mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-30 15:00:21 +02:00
Code Activity

Clarify the units of returned lengths in string conversion functions

Browse source 
* doc/ref/api-data.texi (Conversion to/from C): In descriptions of
  scm_to_stringn and scm_to_{latin1,utf8,utf32}, clarify that the
  returned length is in units of bytes or code points, not characters.
  Also change NULL to @code{NULL} in a few places.
This commit is contained in:
Mark H Weaver 2011-04-19 23:59:17 -04:00
parent 0fbdbe6c84
commit 68a78738a4
1 changed files with 9 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

15
doc/ref/api-data.texi
View file

@ -4280,13 +4280,13 @@ strings to Scheme.
@deftypefn {C Function} char *scm_to_stringn (SCM str, size_t *lenp, const char *encoding, scm_t_string_failed_conversion_handler handler) @deftypefn {C Function} char *scm_to_stringn (SCM str, size_t *lenp, const char *encoding, scm_t_string_failed_conversion_handler handler)
This function returns a newly allocated C string from the Guile string This function returns a newly allocated C string from the Guile string
@var{str}. The length of the string will be returned in @var{lenp}. @var{str}. The length of the returned string in bytes will be returned in
The character encoding of the C string is passed as the ASCII, @var{lenp}. The character encoding of the C string is passed as the ASCII,
null-terminated C string @var{encoding}. The @var{handler} parameter null-terminated C string @var{encoding}. The @var{handler} parameter
gives a strategy for dealing with characters that cannot be converted gives a strategy for dealing with characters that cannot be converted
into @var{encoding}. into @var{encoding}.
If @var{lenp} is NULL, this function will return a null-terminated C 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 string. It will throw an error if the string contains a null
character. character.
@end deftypefn @end deftypefn
@ -4325,11 +4325,14 @@ in @var{str} in the case of @code{scm_from_utf32_stringn}.
@deftypefnx {C function} scm_t_wchar *scm_to_utf32_stringn (SCM str, size_t *lenp) @deftypefnx {C function} scm_t_wchar *scm_to_utf32_stringn (SCM str, size_t *lenp)
Return a newly allocated, ISO-8859-1-, UTF-8-, or UTF-32-encoded C string Return a newly allocated, ISO-8859-1-, UTF-8-, or UTF-32-encoded C string
from Scheme string @var{str}. An error is thrown when @var{str} from Scheme string @var{str}. An error is thrown when @var{str}
string cannot be converted to the specified encoding. If @var{lenp} is cannot be converted to the specified encoding. If @var{lenp} is
@code{NULL}, the returned C string will be null terminated, and an error @code{NULL}, the returned C string will be null terminated, and an error
will be thrown if the C string would otherwise contain null will be thrown if the C string would otherwise contain null
characters. If @var{lenp} is not NULL, the length of the string is characters. If @var{lenp} is not @code{NULL}, the string is not null terminated,
returned in @var{lenp}, and the string is not null terminated. and the length of the returned string is returned in @var{lenp}. The length
returned is the number of bytes for @code{scm_to_latin1_stringn} and
@code{scm_to_utf8_stringn}; it is the number of elements (code points)
for @code{scm_to_utf32_stringn}.
@end deftypefn @end deftypefn
@node String Internals @node String Internals