[Guile-commits] GNU Guile branch, stable-2.0, updated. v2.0.0-88-gce3ce21

[Mark H Weaver]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Guile".

http://git.savannah.gnu.org/cgit/guile.git/commit/?id=ce3ce21c623771ecafdf80c98519e80048cfedb7

The branch, stable-2.0 has been updated
       via  ce3ce21c623771ecafdf80c98519e80048cfedb7 (commit)
      from  ddf134cfec0d82ea9f39ddd69948c08feecb9576 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit ce3ce21c623771ecafdf80c98519e80048cfedb7
Author: Mark H Weaver <address@hidden>
Date:   Tue Mar 8 13:13:54 2011 -0500

    Improve docs of string and symbol conversions from C strings
    
    * doc/ref/api-data.texi (Conversion to/from C): Document
      scm_from_latin1_string, scm_from_utf8_string, and
      scm_from_utf32_string.  Remind readers that these functions should be
      used to convert C string constants, and that scm_from_locale_string is
      _not_ appropriate for that purpose.
    
      (Symbol Primitives): Document scm_from_latin1_symbol and
      scm_from_utf8_symbol.  Remind readers that these functions should be
      used when the specified names are C string constants, and that
      scm_from_locale_symbol is _not_ appropriate for that purpose.

-----------------------------------------------------------------------

Summary of changes:
 doc/ref/api-data.texi |   32 ++++++++++++++++++++++++++++----
 1 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 5bef926..7fa38d1 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -4182,6 +4182,12 @@ If @var{len} is @code{(size_t)-1}, then @var{str} does 
need to be
 null-terminated and the real length will be found with @code{strlen}.
 
 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
address@hidden, @code{scm_from_utf8_string} or
address@hidden
 @end deftypefn
 
 @deftypefn  {C Function} SCM scm_take_locale_string (char *str)
@@ -4281,10 +4287,16 @@ The @var{handler} parameters suggests a strategy for 
dealing with
 unconvertable characters.
 @end deftypefn
 
-ISO-8859-1 is the most common 8-bit character encoding.  This encoding
-is also referred to as the Latin-1 encoding.  The following two
-conversion functions are provided to convert between Latin-1 C strings
-and Guile strings.
+The following conversion functions are provided as a convenience for the
+most commonly used encodings.
+
address@hidden {C Function} SCM scm_from_latin1_string (const char *str)
address@hidden {C Function} SCM scm_from_utf8_string (const char *str)
address@hidden {C Function} SCM scm_from_utf32_string (const scm_t_wchar *str)
+Return a scheme string from the null-terminated C string @var{str},
+which is ISO-8859-1-, UTF-8-, or UTF-32-encoded.  These functions should
+be used to convert hard-coded C string constants into Scheme strings.
address@hidden deftypefn
 
 @deftypefn {C Function} SCM scm_from_latin1_stringn (const char *str, size_t 
len)
 @deftypefnx {C Function} SCM scm_from_utf8_stringn (const char *str, size_t 
len)
@@ -5218,12 +5230,24 @@ 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.
 
address@hidden {C Function} scm_from_latin1_symbol (const char *name)
address@hidden {C Function} 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.
address@hidden deffn
+
 @deffn {C Function} scm_from_locale_symbol (const char *name)
 @deffnx {C Function} 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
 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
address@hidden or @code{scm_from_utf8_symbol}.
 @end deffn
 
 @deftypefn  {C Function} SCM scm_take_locale_symbol (char *str)


hooks/post-receive
-- 
GNU Guile