Add (ice-9 unicode) module

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

diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 7603180..23f3bfc 100644 (file)
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007,
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007,

-@c   2008, 2009, 2010, 2011, 2012, 2013  Free Software Foundation, Inc.
+@c   2008, 2009, 2010, 2011, 2012, 2013, 2014  Free Software Foundation, Inc.

 @c See the file guile.texi for copying conditions.
 
 @node Simple Data Types
 @c See the file guile.texi for copying conditions.
 
 @node Simple Data Types


@@ -56,6 +56,7 @@ For the documentation of such @dfn{compound} data types, see
 @tpindex Booleans
 
 The two boolean values are @code{#t} for true and @code{#f} for false.
 @tpindex Booleans
 
 The two boolean values are @code{#t} for true and @code{#f} for false.

+They can also be written as @code{#true} and @code{#false}, as per R7RS.

 
 Boolean values are returned by predicate procedures, such as the general
 equality predicates @code{eq?}, @code{eqv?} and @code{equal?}
 
 Boolean values are returned by predicate procedures, such as the general
 equality predicates @code{eq?}, @code{eqv?} and @code{equal?}


@@ -318,7 +319,8 @@ Scheme integers can be exact and inexact.  For example, a number
 written as @code{3.0} with an explicit decimal-point is inexact, but
 it is also an integer.  The functions @code{integer?} and
 @code{scm_is_integer} report true for such a number, but the functions
 written as @code{3.0} with an explicit decimal-point is inexact, but
 it is also an integer.  The functions @code{integer?} and
 @code{scm_is_integer} report true for such a number, but the functions

-@code{scm_is_signed_integer} and @code{scm_is_unsigned_integer} only
+@code{exact-integer?}, @code{scm_is_exact_integer},
+@code{scm_is_signed_integer}, and @code{scm_is_unsigned_integer} only

 allow exact integers and thus report false.  Likewise, the conversion
 functions like @code{scm_to_signed_integer} only accept exact
 integers.
 allow exact integers and thus report false.  Likewise, the conversion
 functions like @code{scm_to_signed_integer} only accept exact
 integers.


@@ -333,7 +335,7 @@ will become exact fractions.)
 @deffn {Scheme Procedure} integer? x
 @deffnx {C Function} scm_integer_p (x)
 Return @code{#t} if @var{x} is an exact or inexact integer number, else
 @deffn {Scheme Procedure} integer? x
 @deffnx {C Function} scm_integer_p (x)
 Return @code{#t} if @var{x} is an exact or inexact integer number, else

-@code{#f}.
+return @code{#f}.

 
 @lisp
 (integer? 487)
 
 @lisp
 (integer? 487)


@@ -346,7 +348,7 @@ Return @code{#t} if @var{x} is an exact or inexact integer number, else
 @result{} #f
 
 (integer? +inf.0)
 @result{} #f
 
 (integer? +inf.0)

-@result{} #t
+@result{} #f

 @end lisp
 @end deffn
 
 @end lisp
 @end deffn
 


@@ -354,6 +356,24 @@ Return @code{#t} if @var{x} is an exact or inexact integer number, else
 This is equivalent to @code{scm_is_true (scm_integer_p (x))}.
 @end deftypefn
 
 This is equivalent to @code{scm_is_true (scm_integer_p (x))}.
 @end deftypefn
 

+@deffn {Scheme Procedure} exact-integer? x
+@deffnx {C Function} scm_exact_integer_p (x)
+Return @code{#t} if @var{x} is an exact integer number, else
+return @code{#f}.
+
+@lisp
+(exact-integer? 37)
+@result{} #t
+
+(exact-integer? 3.0)
+@result{} #f
+@end lisp
+@end deffn
+
+@deftypefn {C Function} int scm_is_exact_integer (SCM x)
+This is equivalent to @code{scm_is_true (scm_exact_integer_p (x))}.
+@end deftypefn
+

 @defvr  {C Type} scm_t_int8
 @defvrx {C Type} scm_t_uint8
 @defvrx {C Type} scm_t_int16
 @defvr  {C Type} scm_t_int8
 @defvrx {C Type} scm_t_uint8
 @defvrx {C Type} scm_t_int16


@@ -425,6 +445,8 @@ function will always succeed and will always return an exact number.
 @deftypefnx {C Function} scm_t_uint64 scm_to_uint64 (SCM x)
 @deftypefnx {C Function} scm_t_intmax scm_to_intmax (SCM x)
 @deftypefnx {C Function} scm_t_uintmax scm_to_uintmax (SCM x)
 @deftypefnx {C Function} scm_t_uint64 scm_to_uint64 (SCM x)
 @deftypefnx {C Function} scm_t_intmax scm_to_intmax (SCM x)
 @deftypefnx {C Function} scm_t_uintmax scm_to_uintmax (SCM x)

+@deftypefnx {C Function} scm_t_intptr scm_to_intptr_t (SCM x)
+@deftypefnx {C Function} scm_t_uintptr scm_to_uintptr_t (SCM x)

 When @var{x} represents an exact integer that fits into the indicated
 C type, return that integer.  Else signal an error, either a
 `wrong-type' error when @var{x} is not an exact integer, or an
 When @var{x} represents an exact integer that fits into the indicated
 C type, return that integer.  Else signal an error, either a
 `wrong-type' error when @var{x} is not an exact integer, or an


@@ -459,6 +481,8 @@ the corresponding types are.
 @deftypefnx {C Function} SCM scm_from_uint64 (scm_t_uint64 x)
 @deftypefnx {C Function} SCM scm_from_intmax (scm_t_intmax x)
 @deftypefnx {C Function} SCM scm_from_uintmax (scm_t_uintmax x)
 @deftypefnx {C Function} SCM scm_from_uint64 (scm_t_uint64 x)
 @deftypefnx {C Function} SCM scm_from_intmax (scm_t_intmax x)
 @deftypefnx {C Function} SCM scm_from_uintmax (scm_t_uintmax x)

+@deftypefnx {C Function} SCM scm_from_intptr_t (scm_t_intptr x)
+@deftypefnx {C Function} SCM scm_from_uintptr_t (scm_t_uintptr x)

 Return the @code{SCM} value that represents the integer @var{x}.
 These functions will always succeed and will always return an exact
 number.
 Return the @code{SCM} value that represents the integer @var{x}.
 These functions will always succeed and will always return an exact
 number.


@@ -2046,6 +2070,9 @@ name for each character.
 The short name for the ``delete'' character (code point U+007F) is
 @code{#\del}.
 
 The short name for the ``delete'' character (code point U+007F) is
 @code{#\del}.
 

+The R7RS name for the ``escape'' character (code point U+001B) is
+@code{#\escape}.
+

 There are also a few alternative names left over for compatibility with
 previous versions of Guile.
 
 There are also a few alternative names left over for compatibility with
 previous versions of Guile.
 


@@ -2308,6 +2335,24 @@ lowercase, and titlecase forms respectively.  The type
 @code{scm_t_wchar} is a signed, 32-bit integer.
 @end deftypefn
 
 @code{scm_t_wchar} is a signed, 32-bit integer.
 @end deftypefn
 

+Characters also have ``formal names'', which are defined by Unicode.
+These names can be accessed in Guile from the @code{(ice-9 unicode)}
+module:
+
+@example
+(use-modules (ice-9 unicode))
+@end example
+
+@deffn {Scheme Procedure} char->formal-name chr
+Return the formal all-upper-case Unicode name of @var{ch},
+as a string, or @code{#f} if the character has no name.
+@end deffn
+
+@deffn {Scheme Procedure} formal-name->char name
+Return the character whose formal all-upper-case Unicode name is
+@var{name}, or @code{#f} if no such character is known.
+@end deffn
+

 @node Character Sets
 @subsection Character Sets
 
 @node Character Sets
 @subsection Character Sets
 


@@ -2918,9 +2963,10 @@ The read syntax for strings is an arbitrarily long sequence of
 characters enclosed in double quotes (@nicode{"}).
 
 Backslash is an escape character and can be used to insert the following
 characters enclosed in double quotes (@nicode{"}).
 
 Backslash is an escape character and can be used to insert the following

-special characters.  @nicode{\"} and @nicode{\\} are R5RS standard, the
-next seven are R6RS standard --- notice they follow C syntax --- and the
-remaining four are Guile extensions.
+special characters.  @nicode{\"} and @nicode{\\} are R5RS standard,
+@nicode{\|} is R7RS standard, the next seven are R6RS standard ---
+notice they follow C syntax --- and the remaining four are Guile
+extensions.

 
 @table @asis
 @item @nicode{\\}
 
 @table @asis
 @item @nicode{\\}


@@ -2930,6 +2976,9 @@ Backslash character.
 Double quote character (an unescaped @nicode{"} is otherwise the end
 of the string).
 
 Double quote character (an unescaped @nicode{"} is otherwise the end
 of the string).
 

+@item @nicode{\|}
+Vertical bar character.
+

 @item @nicode{\a}
 Bell character (ASCII 7).
 
 @item @nicode{\a}
 Bell character (ASCII 7).
 


@@ -5512,6 +5561,8 @@ approach to properties, see @ref{Object Properties}.
 @node Symbol Read Syntax
 @subsubsection Extended Read Syntax for Symbols
 
 @node Symbol Read Syntax
 @subsubsection Extended Read Syntax for Symbols
 

+@cindex r7rs-symbols
+

 The read syntax for a symbol is a sequence of letters, digits, and
 @dfn{extended alphabetic characters}, beginning with a character that
 cannot begin a number.  In addition, the special cases of @code{+},
 The read syntax for a symbol is a sequence of letters, digits, and
 @dfn{extended alphabetic characters}, beginning with a character that
 cannot begin a number.  In addition, the special cases of @code{+},


@@ -5561,6 +5612,26 @@ Although Guile provides this extended read syntax for symbols,
 widespread usage of it is discouraged because it is not portable and not
 very readable.
 
 widespread usage of it is discouraged because it is not portable and not
 very readable.
 

+Alternatively, if you enable the @code{r7rs-symbols} read option (see
+@pxref{Scheme Read}), you can write arbitrary symbols using the same
+notation used for strings, except delimited by vertical bars instead of
+double quotes.
+
+@example
+|foo bar|
+|\x3BB; is a greek lambda|
+|\| is a vertical bar|
+@end example
+
+Note that there's also an @code{r7rs-symbols} print option
+(@pxref{Scheme Write}).  To enable the use of this notation, evaluate
+one or both of the following expressions:
+
+@example
+(read-enable  'r7rs-symbols)
+(print-enable 'r7rs-symbols)
+@end example
+

 
 @node Symbol Uninterned
 @subsubsection Uninterned Symbols
 
 @node Symbol Uninterned
 @subsubsection Uninterned Symbols