[Guile-commits] GNU Guile branch, master, updated. release_1-9-6-169-gd85ae24

[Michael Gran]

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=d85ae24dfb96997ce50ece2eb06a33a997313640

The branch, master has been updated
       via  d85ae24dfb96997ce50ece2eb06a33a997313640 (commit)
      from  7beae9f15ac49f144a15d3ebfe80c2f29e43b3ff (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 d85ae24dfb96997ce50ece2eb06a33a997313640
Author: Michael Gran <address@hidden>
Date:   Sun Jan 17 15:25:40 2010 -0800

    Document string-bytes-per-char and %string-dump
    
    * doc/ref/api-data.texi (String Internals): new subsubsection.  Document
      string-bytes-per-char and %string-dump.

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

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

diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 44d2ee9..8528014 100755
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -2601,6 +2601,7 @@ If you want to prevent modifications, use 
@code{substring/read-only}.
 Guile provides all procedures of SRFI-13 and a few more.
 
 @menu
+* String Internals::                The storage strategy for strings.
 * String Syntax::                   Read syntax for strings.
 * String Predicates::               Testing strings for certain properties.
 * String Constructors::             Creating new string objects.
@@ -2616,6 +2617,71 @@ Guile provides all procedures of SRFI-13 and a few more.
 * Conversion to/from C::       
 @end menu
 
address@hidden String Internals
address@hidden String Internals
+
+Guile stores each string in memory as a contiguous array of Unicode code
+points along with an associated set of attributes.  If all of the code
+points of a string have an integer range between 0 and 255 inclusive,
+the code point array is stored as one byte per code point: it is stored
+as an ISO-8859-1 (aka Latin-1) string.  If any of the code points of the
+string has an integer value greater that 255, the code point array is
+stored as four bytes per code point: it is stored as a UTF-32 string.
+
+Conversion between the one-byte-per-code-point and
+four-bytes-per-code-point representations happens automatically as
+necessary.
+
+No API is provided to set the internal representation of strings;
+however, there are pair of procedures available to query it.  These are
+debugging procedures.  Using them in production code is discouraged,
+since the details of Guile's internal representation of strings may
+change from release to release.
+
address@hidden {Scheme Procedure} string-bytes-per-char str
address@hidden {C Function} scm_string_bytes_per_char (str)
+Return the number of bytes used to encode a Unicode code point in string
address@hidden  The result is one or four.
address@hidden deffn
+
address@hidden {Scheme Procedure} %string-dump str
address@hidden {C Function} scm_sys_string_dump (str)
+Returns an association list containing debugging information for
address@hidden The association list has the following entries.
address@hidden @code 
+
address@hidden string 
+The string itself.
+
address@hidden start 
+The start index of the string into its stringbuf 
+
address@hidden length 
+The length of the string 
+
address@hidden shared 
+If this string is a substring, it returns its
+parent string.  Otherwise, it returns @code{#f} 
+
address@hidden read-only
address@hidden if the string is read-only 
+
address@hidden stringbuf-chars 
+A new string containing this string's stringbuf's characters 
+
address@hidden stringbuf-length
+The number of characters in this stringbuf 
+
address@hidden stringbuf-shared
address@hidden if this stringbuf is shared 
+
address@hidden stringbuf-wide 
address@hidden if this stringbuf's characters are stored in a 32-bit buffer,
+or @code{#f} if they are stored in an 8-bit buffer
address@hidden table
address@hidden deffn
+
+
 @node String Syntax
 @subsubsection String Read Syntax
 


hooks/post-receive
-- 
GNU Guile