When creating a Scheme string from a C string or when converting a Scheme string to a C string, the concept of character encoding becomes 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.
Well, ideally, anyway. Right now, Guile simply equates Scheme characters and bytes, ignoring the possibility of multi-byte encodings completely. This will change in the future, where Guile will use Unicode codepoints as its characters and UTF-8 or some other encoding as its internal encoding. When you exclusively use the functions listed in this section, you are `future-proof'.
Converting a Scheme string to a C string will often allocate fresh
memory to hold the result. You must take care that this memory is
properly freed eventually. In many cases, this can be achieved by
scm_dynwind_free inside an appropriate dynwind context,
See Dynamic Wind.
Creates a new Scheme string that has the same contents as str when interpreted in the current locale character encoding.
scm_from_locale_string, str must be null-terminated.
scm_from_locale_stringn, len specifies the length of str in bytes, and str does not need to be null-terminated. If len is
(size_t)-1, then str does need to be null-terminated and the real length will be found with
scm_from_locale_stringn, respectively, but also frees str with
freeeventually. Thus, you can use this function when you would free str anyway immediately after creating the Scheme string. In certain cases, Guile can then use str directly as its internal representation.
Returns a C string in the current locale encoding with the same contents as str. The C string must be freed with
freeeventually, maybe by using
scm_dynwind_free, See Dynamic Wind.
scm_to_locale_string, the returned string is null-terminated and an error is signalled when str contains
scm_to_locale_stringnand lenp not
NULL, str might contain
#\nulcharacters and the length of the returned string in bytes is stored in
*lenp. The returned string will not be null-terminated in this case. If lenp is
Puts str as a C string in the current locale encoding into the memory pointed to by buf. The buffer at buf has room for max_len bytes and
scm_to_local_stringbufwill never store more than that. No terminating
'\0'will be stored.
The return value of
scm_to_locale_stringbufis the number of bytes that are needed for all of str, regardless of whether buf was large enough to hold them. Thus, when the return value is larger than max_len, only max_len bytes have been stored and you probably need to try again with a larger buffer.