Changes from arch/CVS synchronization

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

diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 61847e3..abcb28d 100755 (executable)
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -227,8 +227,8 @@ rational is also real, and every real number is also a complex number
 In addition to the classification into integers, rationals, reals and
 complex numbers, Scheme also distinguishes between whether a number is
 represented exactly or not.  For example, the result of
-@m{2\sin(\pi/4),sin(pi/4)} is exactly @m{\sqrt{2},2^(1/2)} but Guile
-can neither represent @m{\pi/4,pi/4} nor @m{\sqrt{2},2^(1/2)} exactly.
+@m{2\sin(\pi/4),2*sin(pi/4)} is exactly @m{\sqrt{2},2^(1/2)}, but Guile
+can represent neither @m{\pi/4,pi/4} nor @m{\sqrt{2},2^(1/2)} exactly.
 Instead, it stores an inexact approximation, using the C type
 @code{double}.
 
@@ -477,7 +477,7 @@ the occupied space must be freed with @code{mpz_clear}.
 @xref{Initializing Integers,,, gmp, GNU MP Manual}, for details.
 @end deftypefn
 
-@deftypefn {C Function} SCM scm_from_mpz_t (mpz_t val)
+@deftypefn {C Function} SCM scm_from_mpz (mpz_t val)
 Return the @code{SCM} value that represents @var{val}.
 @end deftypefn
 
@@ -1012,6 +1012,12 @@ zero.
 @rnindex number->string
 @rnindex string->number
 
+The following procedures read and write numbers according to their
+external representation as defined by R5RS (@pxref{Lexical structure,
+R5RS Lexical Structure,, r5rs, The Revised^5 Report on the Algorithmic
+Language Scheme}).  @xref{The ice-9 i18n Module, the @code{(ice-9
+i18n)} module}, for locale-dependent number parsing.
+
 @deffn {Scheme Procedure} number->string n [radix]
 @deffnx {C Function} scm_number_to_string (n, radix)
 Return a string holding the external representation of the
@@ -1031,6 +1037,13 @@ syntactically valid notation for a number, then
 @code{string->number} returns @code{#f}.
 @end deffn
 
+@deftypefn {C Function} SCM scm_c_locale_stringn_to_number (const char *string, size_t len, unsigned radix)
+As per @code{string->number} above, but taking a C string, as pointer
+and length.  The string characters should be in the current locale
+encoding (@code{locale} in the name refers only to that, there's no
+locale-dependent parsing).
+@end deftypefn
+
 
 @node Complex
 @subsubsection Complex Number Operations
@@ -1207,7 +1220,16 @@ including complex numbers.
 @rnindex sqrt
 @c begin (texi-doc-string "guile" "sqrt")
 @deffn {Scheme Procedure} sqrt z
-Return the square root of @var{z}.
+Return the square root of @var{z}.  Of the two possible roots
+(positive and negative), the one with the a positive real part is
+returned, or if that's zero then a positive imaginary part.  Thus,
+
+@example
+(sqrt 9.0)       @result{} 3.0
+(sqrt -9.0)      @result{} 0.0+3.0i
+(sqrt 1.0+1.0i)  @result{} 1.09868411346781+0.455089860562227i
+(sqrt -1.0-1.0i) @result{} 0.455089860562227-1.09868411346781i
+@end example
 @end deffn
 
 @rnindex expt
@@ -2292,6 +2314,17 @@ character sets.
 In order to make the use of the character set data type and procedures
 useful, several predefined character set variables exist.
 
+@cindex codeset
+@cindex charset
+@cindex locale
+
+Currently, the contents of these character sets are recomputed upon a
+successful @code{setlocale} call (@pxref{Locales}) in order to reflect
+the characters available in the current locale's codeset.  For
+instance, @code{char-set:letter} contains 52 characters under an ASCII
+locale (e.g., the default @code{C} locale) and 117 characters under an
+ISO-8859-1 (``Latin-1'') locale.
+
 @defvr {Scheme Variable} char-set:lower-case
 @defvrx {C Variable} scm_char_set_lower_case
 All lower-case characters.
@@ -2916,7 +2949,8 @@ predicates (@pxref{Characters}), but are defined on character sequences.
 The first set is specified in R5RS and has names that end in @code{?}.
 The second set is specified in SRFI-13 and the names have no ending
 @code{?}.  The predicates ending in @code{-ci} ignore the character case
-when comparing strings.
+when comparing strings.  @xref{The ice-9 i18n Module, the @code{(ice-9
+i18n)} module}, for locale-dependent string comparison.
 
 @rnindex string=?
 @deffn {Scheme Procedure} string=? s1 s2
@@ -4656,10 +4690,8 @@ see @code{symbol-property}.
 @end deffn
 
 Support for these extra slots may be removed in a future release, and it
-is probably better to avoid using them.  (In release 1.6, Guile itself
-uses the property list slot sparingly, and the function slot not at
-all.)  For a more modern and Schemely approach to properties, see
-@ref{Object Properties}.
+is probably better to avoid using them.  For a more modern and Schemely
+approach to properties, see @ref{Object Properties}.
 
 
 @node Symbol Read Syntax