Fix the R6RS exact-integer-sqrt and import into core guile

[bpt/guile.git] / doc / ref / api-data.texi

diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 7fa38d1..760039a 100644 (file)
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -959,6 +959,18 @@ Return @var{n} raised to the integer exponent
 @end lisp
 @end deffn
 
+@deftypefn {Scheme Procedure} {} exact-integer-sqrt @var{k}
+@deftypefnx {C Function} void scm_exact_integer_sqrt (SCM @var{k}, SCM *@var{s}, SCM *@var{r})
+Return two exact non-negative integers @var{s} and @var{r}
+such that @math{@var{k} = @var{s}^2 + @var{r}} and
+@math{@var{s}^2 <= @var{k} < (@var{s} + 1)^2}.
+An error is raised if @var{k} is not an exact non-negative integer.
+
+@lisp
+(exact-integer-sqrt 10) @result{} 3 and 1
+@end lisp
+@end deftypefn
+
 @node Comparison
 @subsubsection Comparison Predicates
 @rnindex zero?
@@ -1308,7 +1320,7 @@ both @var{q} and @var{r}, and is more efficient than computing each
 separately.  Note that @var{r}, if non-zero, will have the same sign
 as @var{y}.
 
-When @var{x} and @var{y} are exact integers, @code{floor-remainder} is
+When @var{x} and @var{y} are integers, @code{floor-remainder} is
 equivalent to the R5RS integer-only operator @code{modulo}.
 
 @lisp
@@ -1365,7 +1377,7 @@ both @var{q} and @var{r}, and is more efficient than computing each
 separately.  Note that @var{r}, if non-zero, will have the same sign
 as @var{x}.
 
-When @var{x} and @var{y} are exact integers, these operators are
+When @var{x} and @var{y} are integers, these operators are
 equivalent to the R5RS integer-only operators @code{quotient} and
 @code{remainder}.
 
@@ -4171,8 +4183,7 @@ using @code{scm_dynwind_free} inside an appropriate dynwind context,
 @deftypefn  {C Function} SCM scm_from_locale_string (const char *str)
 @deftypefnx {C Function} SCM scm_from_locale_stringn (const char *str, size_t len)
 Creates a new Scheme string that has the same contents as @var{str} when
-interpreted in the locale character encoding of the
-@code{current-input-port}.
+interpreted in the character encoding of the current locale.
 
 For @code{scm_from_locale_string}, @var{str} must be null-terminated.
 
@@ -4201,9 +4212,9 @@ can then use @var{str} directly as its internal representation.
 
 @deftypefn  {C Function} {char *} scm_to_locale_string (SCM str)
 @deftypefnx {C Function} {char *} scm_to_locale_stringn (SCM str, size_t *lenp)
-Returns a C string with the same contents as @var{str} in the locale
-encoding of the @code{current-output-port}.  The C string must be freed
-with @code{free} eventually, maybe by using @code{scm_dynwind_free},
+Returns a C string with the same contents as @var{str} in the character
+encoding of the current locale.  The C string must be freed with
+@code{free} eventually, maybe by using @code{scm_dynwind_free},
 @xref{Dynamic Wind}.
 
 For @code{scm_to_locale_string}, the returned string is
@@ -4217,13 +4228,14 @@ returned string will not be null-terminated in this case.  If
 @var{lenp} is @code{NULL}, @code{scm_to_locale_stringn} behaves like
 @code{scm_to_locale_string}.
 
-If a character in @var{str} cannot be represented in the locale encoding
-of the current output port, the port conversion strategy of the current
-output port will determine the result, @xref{Ports}.  If output port's
-conversion strategy is @code{error}, an error will be raised.  If it is
-@code{substitute}, a replacement character, such as a question mark, will
-be inserted in its place.  If it is @code{escape}, a hex escape will be
-inserted in its place.
+If a character in @var{str} cannot be represented in the character
+encoding of the current locale, the default port conversion strategy is
+used.  @xref{Ports}, for more on conversion strategies.
+
+If the conversion strategy is @code{error}, an error will be raised.  If
+it is @code{substitute}, a replacement character, such as a question
+mark, will be inserted in its place.  If it is @code{escape}, a hex
+escape will be inserted in its place.
 @end deftypefn
 
 @deftypefn {C Function} size_t scm_to_locale_stringbuf (SCM str, char *buf, size_t max_len)
@@ -5730,11 +5742,23 @@ Return the keyword with the same name as @var{symbol}.
 Equivalent to @code{scm_is_true (scm_keyword_p (@var{obj}))}.
 @end deftypefn
 
-@deftypefn {C Function} SCM scm_from_locale_keyword (const char *str)
-@deftypefnx {C Function} SCM scm_from_locale_keywordn (const char *str, size_t len)
+@deftypefn {C Function} SCM scm_from_locale_keyword (const char *name)
+@deftypefnx {C Function} SCM scm_from_locale_keywordn (const char *name, size_t len)
 Equivalent to @code{scm_symbol_to_keyword (scm_from_locale_symbol
-(@var{str}))} and @code{scm_symbol_to_keyword (scm_from_locale_symboln
-(@var{str}, @var{len}))}, respectively.
+(@var{name}))} and @code{scm_symbol_to_keyword (scm_from_locale_symboln
+(@var{name}, @var{len}))}, respectively.
+
+Note that these functions should @emph{not} be used when @var{name} is a
+C string constant, because there is no guarantee that the current locale
+will match that of the source code.  In such cases, use
+@code{scm_from_latin1_keyword} or @code{scm_from_utf8_keyword}.
+@end deftypefn
+
+@deftypefn {C Function} SCM scm_from_latin1_keyword (const char *name)
+@deftypefnx {C Function} SCM scm_from_utf8_keyword (const char *name)
+Equivalent to @code{scm_symbol_to_keyword (scm_from_latin1_symbol
+(@var{name}))} and @code{scm_symbol_to_keyword (scm_from_utf8_symbol
+(@var{name}))}, respectively.
 @end deftypefn
 
 @node Other Types