Previous: Miscellaneous String Operations, Up: Strings

5.5.5.13 Conversion to/from C

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 using scm_dynwind_free inside an appropriate dynwind context, See Dynamic Wind.

— C Function: SCM scm_from_locale_string (const char *str)
— C Function: SCM scm_from_locale_stringn (const char *str, size_t len)

Creates a new Scheme string that has the same contents as str when interpreted in the current locale character encoding.

For scm_from_locale_string, str must be null-terminated.

For 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 strlen.

— C Function: SCM scm_take_locale_string (char *str)
— C Function: SCM scm_take_locale_stringn (char *str, size_t len)

Like scm_from_locale_string and scm_from_locale_stringn, respectively, but also frees str with free eventually. 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.

— C Function: char * scm_to_locale_string (SCM str)
— C Function: char * scm_to_locale_stringn (SCM str, size_t *lenp)

Returns a C string in the current locale encoding with the same contents as str. The C string must be freed with free eventually, maybe by using scm_dynwind_free, See Dynamic Wind.

For scm_to_locale_string, the returned string is null-terminated and an error is signalled when str contains #\nul characters.

For scm_to_locale_stringn and lenp not NULL, str might contain #\nul characters 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 NULL, scm_to_locale_stringn behaves like scm_to_locale_string.

— C Function: size_t scm_to_locale_stringbuf (SCM str, char *buf, size_t max_len)

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_stringbuf will never store more than that. No terminating '\0' will be stored.

The return value of scm_to_locale_stringbuf is 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.