X-Git-Url: https://git.hcoop.net/bpt/guile.git/blobdiff_plain/fa980bcc0f5b186b98d84fc5d165d35fcbb5d5ec..c5ea75534c683638fb1f3b328efe6ba0d242e485:/doc/ref/api-data.texi diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index 6d8de2bd6..23f3bfc73 100644 --- 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, 2008, 2009, 2010, 2011, 2012 -@c Free Software Foundation, Inc. +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, +@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 @@ -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. +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?} @@ -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 -@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. @@ -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 -@code{#f}. +return @code{#f}. @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{} #t +@result{} #f @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 +@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 @@ -414,6 +434,7 @@ function will always succeed and will always return an exact number. @deftypefnx {C Function} {unsigned long long} scm_to_ulong_long (SCM x) @deftypefnx {C Function} size_t scm_to_size_t (SCM x) @deftypefnx {C Function} ssize_t scm_to_ssize_t (SCM x) +@deftypefnx {C Function} scm_t_ptrdiff scm_to_ptrdiff_t (SCM x) @deftypefnx {C Function} scm_t_int8 scm_to_int8 (SCM x) @deftypefnx {C Function} scm_t_uint8 scm_to_uint8 (SCM x) @deftypefnx {C Function} scm_t_int16 scm_to_int16 (SCM x) @@ -424,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_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 @@ -447,6 +470,7 @@ the corresponding types are. @deftypefnx {C Function} SCM scm_from_ulong_long (unsigned long long x) @deftypefnx {C Function} SCM scm_from_size_t (size_t x) @deftypefnx {C Function} SCM scm_from_ssize_t (ssize_t x) +@deftypefnx {C Function} SCM scm_from_ptrdiff_t (scm_t_ptrdiff x) @deftypefnx {C Function} SCM scm_from_int8 (scm_t_int8 x) @deftypefnx {C Function} SCM scm_from_uint8 (scm_t_uint8 x) @deftypefnx {C Function} SCM scm_from_int16 (scm_t_int16 x) @@ -457,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_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. @@ -1684,19 +1710,15 @@ starts from 0 for the least significant bit. @end lisp @end deffn -@deffn {Scheme Procedure} ash n cnt -@deffnx {C Function} scm_ash (n, cnt) -Return @var{n} shifted left by @var{cnt} bits, or shifted right if -@var{cnt} is negative. This is an ``arithmetic'' shift. +@deffn {Scheme Procedure} ash n count +@deffnx {C Function} scm_ash (n, count) +Return @math{floor(n * 2^count)}. +@var{n} and @var{count} must be exact integers. -This is effectively a multiplication by @m{2^{cnt}, 2^@var{cnt}}, and -when @var{cnt} is negative it's a division, rounded towards negative -infinity. (Note that this is not the same rounding as @code{quotient} -does.) - -With @var{n} viewed as an infinite precision twos complement, -@code{ash} means a left shift introducing zero bits, or a right shift -dropping bits. +With @var{n} viewed as an infinite-precision twos-complement +integer, @code{ash} means a left shift introducing zero bits +when @var{count} is positive, or a right shift dropping bits +when @var{count} is negative. This is an ``arithmetic'' shift. @lisp (number->string (ash #b1 3) 2) @result{} "1000" @@ -1707,6 +1729,28 @@ dropping bits. @end lisp @end deffn +@deffn {Scheme Procedure} round-ash n count +@deffnx {C Function} scm_round_ash (n, count) +Return @math{round(n * 2^count)}. +@var{n} and @var{count} must be exact integers. + +With @var{n} viewed as an infinite-precision twos-complement +integer, @code{round-ash} means a left shift introducing zero +bits when @var{count} is positive, or a right shift rounding +to the nearest integer (with ties going to the nearest even +integer) when @var{count} is negative. This is a rounded +``arithmetic'' shift. + +@lisp +(number->string (round-ash #b1 3) 2) @result{} \"1000\" +(number->string (round-ash #b1010 -1) 2) @result{} \"101\" +(number->string (round-ash #b1010 -2) 2) @result{} \"10\" +(number->string (round-ash #b1011 -2) 2) @result{} \"11\" +(number->string (round-ash #b1101 -2) 2) @result{} \"11\" +(number->string (round-ash #b1110 -2) 2) @result{} \"100\" +@end lisp +@end deffn + @deffn {Scheme Procedure} logcount n @deffnx {C Function} scm_logcount (n) Return the number of bits in integer @var{n}. If @var{n} is @@ -2026,6 +2070,9 @@ name for each character. 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. @@ -2047,7 +2094,7 @@ number of one to eight digits. @rnindex char? @deffn {Scheme Procedure} char? x @deffnx {C Function} scm_char_p (x) -Return @code{#t} iff @var{x} is a character, else @code{#f}. +Return @code{#t} if @var{x} is a character, else @code{#f}. @end deffn Fundamentally, the character comparison operations below are @@ -2055,31 +2102,31 @@ numeric comparisons of the character's code points. @rnindex char=? @deffn {Scheme Procedure} char=? x y -Return @code{#t} iff code point of @var{x} is equal to the code point +Return @code{#t} if code point of @var{x} is equal to the code point of @var{y}, else @code{#f}. @end deffn @rnindex char? @deffn {Scheme Procedure} char>? x y -Return @code{#t} iff the code point of @var{x} is greater than the +Return @code{#t} if the code point of @var{x} is greater than the code point of @var{y}, else @code{#f}. @end deffn @rnindex char>=? @deffn {Scheme Procedure} char>=? x y -Return @code{#t} iff the code point of @var{x} is greater than or +Return @code{#t} if the code point of @var{x} is greater than or equal to the code point of @var{y}, else @code{#f}. @end deffn @@ -2097,32 +2144,32 @@ it cannot cover all cases for all languages. @rnindex char-ci=? @deffn {Scheme Procedure} char-ci=? x y -Return @code{#t} iff the case-folded code point of @var{x} is the same +Return @code{#t} if the case-folded code point of @var{x} is the same as the case-folded code point of @var{y}, else @code{#f}. @end deffn @rnindex char-ci? @deffn {Scheme Procedure} char-ci>? x y -Return @code{#t} iff the case-folded code point of @var{x} is greater +Return @code{#t} if the case-folded code point of @var{x} is greater than the case-folded code point of @var{y}, else @code{#f}. @end deffn @rnindex char-ci>=? @deffn {Scheme Procedure} char-ci>=? x y -Return @code{#t} iff the case-folded code point of @var{x} is greater +Return @code{#t} if the case-folded code point of @var{x} is greater than or equal to the case-folded code point of @var{y}, else @code{#f}. @end deffn @@ -2130,36 +2177,36 @@ than or equal to the case-folded code point of @var{y}, else @rnindex char-alphabetic? @deffn {Scheme Procedure} char-alphabetic? chr @deffnx {C Function} scm_char_alphabetic_p (chr) -Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}. +Return @code{#t} if @var{chr} is alphabetic, else @code{#f}. @end deffn @rnindex char-numeric? @deffn {Scheme Procedure} char-numeric? chr @deffnx {C Function} scm_char_numeric_p (chr) -Return @code{#t} iff @var{chr} is numeric, else @code{#f}. +Return @code{#t} if @var{chr} is numeric, else @code{#f}. @end deffn @rnindex char-whitespace? @deffn {Scheme Procedure} char-whitespace? chr @deffnx {C Function} scm_char_whitespace_p (chr) -Return @code{#t} iff @var{chr} is whitespace, else @code{#f}. +Return @code{#t} if @var{chr} is whitespace, else @code{#f}. @end deffn @rnindex char-upper-case? @deffn {Scheme Procedure} char-upper-case? chr @deffnx {C Function} scm_char_upper_case_p (chr) -Return @code{#t} iff @var{chr} is uppercase, else @code{#f}. +Return @code{#t} if @var{chr} is uppercase, else @code{#f}. @end deffn @rnindex char-lower-case? @deffn {Scheme Procedure} char-lower-case? chr @deffnx {C Function} scm_char_lower_case_p (chr) -Return @code{#t} iff @var{chr} is lowercase, else @code{#f}. +Return @code{#t} if @var{chr} is lowercase, else @code{#f}. @end deffn @deffn {Scheme Procedure} char-is-both? chr @deffnx {C Function} scm_char_is_both_p (chr) -Return @code{#t} iff @var{chr} is either uppercase or lowercase, else +Return @code{#t} if @var{chr} is either uppercase or lowercase, else @code{#f}. @end deffn @@ -2288,6 +2335,24 @@ lowercase, and titlecase forms respectively. The type @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 @@ -2581,8 +2646,8 @@ string is not defined. @deffn {Scheme Procedure} char-set-contains? cs ch @deffnx {C Function} scm_char_set_contains_p (cs, ch) -Return @code{#t} iff the character @var{ch} is contained in the -character set @var{cs}. +Return @code{#t} if the character @var{ch} is contained in the +character set @var{cs}, or @code{#f} otherwise. @end deffn @deffn {Scheme Procedure} char-set-every pred cs @@ -2881,6 +2946,7 @@ Guile provides all procedures of SRFI-13 and a few more. * Reversing and Appending Strings:: Appending strings to form a new string. * Mapping Folding and Unfolding:: Iterating over strings. * Miscellaneous String Operations:: Replicating, insertion, parsing, ... +* Representing Strings as Bytes:: Encoding and decoding strings. * Conversion to/from C:: * String Internals:: The storage strategy for strings. @end menu @@ -2897,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 -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{\\} @@ -2909,6 +2976,9 @@ Backslash character. 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). @@ -3127,7 +3197,7 @@ placed between the strings, and defaults to the symbol @item infix Insert the separator between list elements. An empty string will produce an empty list. -@item string-infix +@item strict-infix Like @code{infix}, but will raise an error if given the empty list. @item suffix @@ -4163,6 +4233,76 @@ a predicate, if it is a character, it is tested for equality and if it is a character set, it is tested for membership. @end deffn +@node Representing Strings as Bytes +@subsubsection Representing Strings as Bytes + +Out in the cold world outside of Guile, not all strings are treated in +the same way. Out there there are only bytes, and there are many ways +of representing a strings (sequences of characters) as binary data +(sequences of bytes). + +As a user, usually you don't have to think about this very much. When +you type on your keyboard, your system encodes your keystrokes as bytes +according to the locale that you have configured on your computer. +Guile uses the locale to decode those bytes back into characters -- +hopefully the same characters that you typed in. + +All is not so clear when dealing with a system with multiple users, such +as a web server. Your web server might get a request from one user for +data encoded in the ISO-8859-1 character set, and then another request +from a different user for UTF-8 data. + +@cindex iconv +@cindex character encoding +Guile provides an @dfn{iconv} module for converting between strings and +sequences of bytes. @xref{Bytevectors}, for more on how Guile +represents raw byte sequences. This module gets its name from the +common @sc{unix} command of the same name. + +Note that often it is sufficient to just read and write strings from +ports instead of using these functions. To do this, specify the port +encoding using @code{set-port-encoding!}. @xref{Ports}, for more on +ports and character encodings. + +Unlike the rest of the procedures in this section, you have to load the +@code{iconv} module before having access to these procedures: + +@example +(use-modules (ice-9 iconv)) +@end example + +@deffn {Scheme Procedure} string->bytevector string encoding [conversion-strategy] +Encode @var{string} as a sequence of bytes. + +The string will be encoded in the character set specified by the +@var{encoding} string. If the string has characters that cannot be +represented in the encoding, by default this procedure raises an +@code{encoding-error}. Pass a @var{conversion-strategy} argument to +specify other behaviors. + +The return value is a bytevector. @xref{Bytevectors}, for more on +bytevectors. @xref{Ports}, for more on character encodings and +conversion strategies. +@end deffn + +@deffn {Scheme Procedure} bytevector->string bytevector encoding [conversion-strategy] +Decode @var{bytevector} into a string. + +The bytes will be decoded from the character set by the @var{encoding} +string. If the bytes do not form a valid encoding, by default this +procedure raises an @code{decoding-error}. As with +@code{string->bytevector}, pass the optional @var{conversion-strategy} +argument to modify this behavior. @xref{Ports}, for more on character +encodings and conversion strategies. +@end deffn + +@deffn {Scheme Procedure} call-with-output-encoded-string encoding proc [conversion-strategy] +Like @code{call-with-output-string}, but instead of returning a string, +returns a encoding of the string according to @var{encoding}, as a +bytevector. This procedure can be more efficient than collecting a +string and then converting it via @code{string->bytevector}. +@end deffn + @node Conversion to/from C @subsubsection Conversion to/from C @@ -4172,9 +4312,9 @@ important. In C, a string is just a sequence of bytes, and the character encoding describes the relation between these bytes and the actual characters -that make up the string. For Scheme strings, character encoding is -not an issue (most of the time), since in Scheme you never get to see -the bytes, only the characters. +that make up the string. For Scheme strings, character encoding is not +an issue (most of the time), since in Scheme you usually treat strings +as character sequences, not byte sequences. Converting to C and converting from C each have their own challenges. @@ -4212,9 +4352,9 @@ If the C string is ill-formed, an error will be raised. Note that these functions should @emph{not} be used to convert C string constants, because there is no guarantee that the current locale will -match that of the source code. To convert C string constants, use -@code{scm_from_latin1_string}, @code{scm_from_utf8_string} or -@code{scm_from_utf32_string}. +match that of the execution character set, used for string and character +constants. Most modern C compilers use UTF-8 by default, so to convert +C string constants we recommend @code{scm_from_utf8_string}. @end deftypefn @deftypefn {C Function} SCM scm_take_locale_string (char *str) @@ -4305,6 +4445,9 @@ into @var{encoding}. If @var{lenp} is @code{NULL}, this function will return a null-terminated C string. It will throw an error if the string contains a null character. + +The Scheme interface to this function is @code{string->bytevector}, from the +@code{ice-9 iconv} module. @xref{Representing Strings as Bytes}. @end deftypefn @deftypefn {C Function} SCM scm_from_stringn (const char *str, size_t len, const char *encoding, scm_t_string_failed_conversion_handler handler) @@ -4313,6 +4456,9 @@ length in bytes of the C string is input as @var{len}. The encoding of the C string is passed as the ASCII, null-terminated C string @code{encoding}. The @var{handler} parameters suggests a strategy for dealing with unconvertable characters. + +The Scheme interface to this function is @code{bytevector->string}. +@xref{Representing Strings as Bytes}. @end deftypefn The following conversion functions are provided as a convenience for the @@ -4351,6 +4497,19 @@ returned is the number of bytes for @code{scm_to_latin1_stringn} and for @code{scm_to_utf32_stringn}. @end deftypefn +It is not often the case, but sometimes when you are dealing with the +implementation details of a port, you need to encode and decode strings +according to the encoding and conversion strategy of the port. There +are some convenience functions for that purpose as well. + +@deftypefn {C Function} SCM scm_from_port_string (const char *str, SCM port) +@deftypefnx {C Function} SCM scm_from_port_stringn (const char *str, size_t len, SCM port) +@deftypefnx {C Function} char* scm_to_port_string (SCM str, SCM port) +@deftypefnx {C Function} char* scm_to_port_stringn (SCM str, size_t *lenp, SCM port) +Like @code{scm_from_stringn} and friends, except they take their +encoding and conversion strategy from a given port object. +@end deftypefn + @node String Internals @subsubsection String Internals @@ -4458,7 +4617,7 @@ R6RS (@pxref{R6RS I/O Ports}). * Bytevectors and Integer Lists:: Converting to/from an integer list. * Bytevectors as Floats:: Interpreting bytes as real numbers. * Bytevectors as Strings:: Interpreting bytes as Unicode strings. -* Bytevectors as Generalized Vectors:: Guile extension to the bytevector API. +* Bytevectors as Arrays:: Guile extension to the bytevector API. * Bytevectors as Uniform Vectors:: Bytevectors and SRFI-4. @end menu @@ -4810,6 +4969,7 @@ the host's native endianness. Bytevector contents can also be interpreted as Unicode strings encoded in one of the most commonly available encoding formats. +@xref{Representing Strings as Bytes}, for a more generic interface. @lisp (utf8->string (u8-list->bytevector '(99 97 102 101))) @@ -4843,25 +5003,27 @@ or UTF-32-decoded contents of bytevector @var{utf}. For UTF-16 and UTF-32, it defaults to big endian. @end deffn -@node Bytevectors as Generalized Vectors -@subsubsection Accessing Bytevectors with the Generalized Vector API +@node Bytevectors as Arrays +@subsubsection Accessing Bytevectors with the Array API As an extension to the R6RS, Guile allows bytevectors to be manipulated -with the @dfn{generalized vector} procedures (@pxref{Generalized -Vectors}). This also allows bytevectors to be accessed using the -generic @dfn{array} procedures (@pxref{Array Procedures}). When using -these APIs, bytes are accessed one at a time as 8-bit unsigned integers: +with the @dfn{array} procedures (@pxref{Arrays}). When using these +APIs, bytes are accessed one at a time as 8-bit unsigned integers: @example (define bv #vu8(0 1 2 3)) -(generalized-vector? bv) +(array? bv) @result{} #t -(generalized-vector-ref bv 2) +(array-rank bv) +@result{} 1 + +(array-ref bv 2) @result{} 2 -(generalized-vector-set! bv 2 77) +;; Note the different argument order on array-set!. +(array-set! bv 77 2) (array-ref bv 2) @result{} 77 @@ -5262,15 +5424,15 @@ When you want to do more from C, you should convert between symbols and strings using @code{scm_symbol_to_string} and @code{scm_string_to_symbol} and work with the strings. -@deftypefn {C Function} scm_from_latin1_symbol (const char *name) -@deftypefnx {C Function} scm_from_utf8_symbol (const char *name) +@deftypefn {C Function} SCM scm_from_latin1_symbol (const char *name) +@deftypefnx {C Function} SCM scm_from_utf8_symbol (const char *name) Construct and return a Scheme symbol whose name is specified by the null-terminated C string @var{name}. These are appropriate when the C string is hard-coded in the source code. @end deftypefn -@deftypefn {C Function} scm_from_locale_symbol (const char *name) -@deftypefnx {C Function} scm_from_locale_symboln (const char *name, size_t len) +@deftypefn {C Function} SCM scm_from_locale_symbol (const char *name) +@deftypefnx {C Function} SCM scm_from_locale_symboln (const char *name, size_t len) Construct and return a Scheme symbol whose name is specified by @var{name}. For @code{scm_from_locale_symbol}, @var{name} must be null terminated; for @code{scm_from_locale_symboln} the length of @var{name} is @@ -5278,8 +5440,9 @@ specified explicitly by @var{len}. 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_symbol} or @code{scm_from_utf8_symbol}. +will match that of the execution character set, used for string and +character constants. Most modern C compilers use UTF-8 by default, so +in such cases we recommend @code{scm_from_utf8_symbol}. @end deftypefn @deftypefn {C Function} SCM scm_take_locale_symbol (char *str) @@ -5398,6 +5561,8 @@ approach to properties, see @ref{Object Properties}. @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{+}, @@ -5447,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. +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 @@ -5679,6 +5864,8 @@ For further details on @code{let-keywords}, @code{define*} and other facilities provided by the @code{(ice-9 optargs)} module, see @ref{Optional Arguments}. +To handle keyword arguments from procedures implemented in C, +use @code{scm_c_bind_keyword_arguments} (@pxref{Keyword Procedures}). @node Keyword Read Syntax @subsubsection Keyword Read Syntax @@ -5770,8 +5957,9 @@ Equivalent to @code{scm_symbol_to_keyword (scm_from_locale_symbol 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}. +will match that of the execution character set, used for string and +character constants. Most modern C compilers use UTF-8 by default, so +in such cases we recommend @code{scm_from_utf8_keyword}. @end deftypefn @deftypefn {C Function} SCM scm_from_latin1_keyword (const char *name) @@ -5781,6 +5969,70 @@ Equivalent to @code{scm_symbol_to_keyword (scm_from_latin1_symbol (@var{name}))}, respectively. @end deftypefn +@deftypefn {C Function} void scm_c_bind_keyword_arguments (const char *subr, @ + SCM rest, scm_t_keyword_arguments_flags flags, @ + SCM keyword1, SCM *argp1, @ + @dots{}, @ + SCM keywordN, SCM *argpN, @ + @nicode{SCM_UNDEFINED}) + +Extract the specified keyword arguments from @var{rest}, which is not +modified. If the keyword argument @var{keyword1} is present in +@var{rest} with an associated value, that value is stored in the +variable pointed to by @var{argp1}, otherwise the variable is left +unchanged. Similarly for the other keywords and argument pointers up to +@var{keywordN} and @var{argpN}. The argument list to +@code{scm_c_bind_keyword_arguments} must be terminated by +@code{SCM_UNDEFINED}. + +Note that since the variables pointed to by @var{argp1} through +@var{argpN} are left unchanged if the associated keyword argument is not +present, they should be initialized to their default values before +calling @code{scm_c_bind_keyword_arguments}. Alternatively, you can +initialize them to @code{SCM_UNDEFINED} before the call, and then use +@code{SCM_UNBNDP} after the call to see which ones were provided. + +If an unrecognized keyword argument is present in @var{rest} and +@var{flags} does not contain @code{SCM_ALLOW_OTHER_KEYS}, or if +non-keyword arguments are present and @var{flags} does not contain +@code{SCM_ALLOW_NON_KEYWORD_ARGUMENTS}, an exception is raised. +@var{subr} should be the name of the procedure receiving the keyword +arguments, for purposes of error reporting. + +For example: + +@example +SCM k_delimiter; +SCM k_grammar; +SCM sym_infix; + +SCM my_string_join (SCM strings, SCM rest) +@{ + SCM delimiter = SCM_UNDEFINED; + SCM grammar = sym_infix; + + scm_c_bind_keyword_arguments ("my-string-join", rest, 0, + k_delimiter, &delimiter, + k_grammar, &grammar, + SCM_UNDEFINED); + + if (SCM_UNBNDP (delimiter)) + delimiter = scm_from_utf8_string (" "); + + return scm_string_join (strings, delimiter, grammar); +@} + +void my_init () +@{ + k_delimiter = scm_from_utf8_keyword ("delimiter"); + k_grammar = scm_from_utf8_keyword ("grammar"); + sym_infix = scm_from_utf8_symbol ("infix"); + scm_c_define_gsubr ("my-string-join", 1, 0, 1, my_string_join); +@} +@end example +@end deftypefn + + @node Other Types @subsection ``Functionality-Centric'' Data Types