2.14 Strings

2.14.1 String types & Unicode

The ECL implementation of strings is ANSI Common-Lisp compliant. There are basically four string types as shown in Table 2.7. As explained in Characters, when Unicode support is disabled, character and base-character are the same type and the last two string types are equivalent to the first two.

It is important to remember that strings with unicode characters can only be printed readably when the external format supports those characters. If this is not the case, ECL will signal a serious-condition. This condition will abort your program if not properly handled.

2.14.2 C reference

2.14.2.1 Base string constructors

Building strings of C data

Functions

Function: cl_object ecl_alloc_adjustable_base_string (cl_index length);

Function: cl_object ecl_alloc_simple_base_string (cl_index length);

Function: cl_object ecl_make_simple_base_string (const char* data, cl_fixnum length);

Function: cl_object ecl_make_constant_base_string (const char* data, cl_fixnum length);

Description

These are different ways to create a base string, which is a string that holds a small subset of characters, the base-char, with codes ranging from 0 to 255.

ecl_alloc_simple_base_string creates an empty string with that much space for characters and a fixed length. The string does not have a fill pointer and cannot be resized, and the initial data is unspecified

ecl_alloc_adjustable_base_string is similar to the previous function, but creates an adjustable string with a fill pointer. This means that the length of the string can be changed and the string itself can be resized to accommodate more data.

The other constructors create strings but use some preexisting data. ecl_make_simple_base_string creates a string copying the data that the user supplies, and using freshly allocated memory. ecl_make_constant_base_string on the other hand, does not allocate memory, but simply uses the supplied pointer as buffer for the string. This last function should be used with care, ensuring that the supplied buffer is not deallocated. If the length argument of these functions is -1, the length is determined by strlen.

2.14.2.2 String accessors

Reading and writing characters into a string

Functions

Function: ecl_character ecl_char (cl_object string, cl_index index);

Function: ecl_character ecl_char_set (cl_object string, cl_index index, ecl_character c);

Description

Access to string information should be done using these two functions. The first one implements the equivalent of the char function from Common Lisp, returning the character that is at position index in the string string.

The counterpart of the previous function is ecl_char_set, which implements (setf char) and stores character c at the position index in the given string.

Both functions check the type of their arguments and verify that the indices do not exceed the string boundaries. Otherwise they signal a serious-condition.

2.14.2.3 ANSI dictionary

Common Lisp and C equivalence