[Guile-commits] GNU Guile branch, master, updated. release_1-9-15-135-g139851f

[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=139851f28b3aa8a605240017ded9286fd32d7c0f

The branch, master has been updated
       via  139851f28b3aa8a605240017ded9286fd32d7c0f (commit)
      from  4324bf9a961f0ed57376db752b67dba1a6344748 (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 139851f28b3aa8a605240017ded9286fd32d7c0f
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