Next: , Previous: , Up: Miscellaneous   [Contents][Index]


13.3.7.2 Utilities

Function: stream:set-system-external-format terminal &optional filenames

This function changes the external format used for *standard-input*, *standard-output*, and *standard-error* to the external format specified by terminal. Additionally, the Unix file name encoding can be set to the value specified by filenames if non-nil.

Function: extensions:list-all-external-formats

list all of the vailable external formats. A list is returned where each element is a list of the external format name and a list of aliases for the format. No distinction is made between external formats and composing external formats.

Function: extensions:describe-external-format external-format

Print a description of the given external-format. This may cause the external format to be loaded (silently) if it is not already loaded.

Since strings are UTF-16 and hence may contain surrogate pairs, some utility functions are provided to make access easier.

Function: lisp:codepoint string i &optional end

Return the codepoint value from string at position i. If code unit at that position is a surrogate value, it is combined with either the previous or following code unit (when possible) to compute the codepoint. The first return value is the codepoint itself. The second return value is nil if the position is not a surrogate pair. Otherwise, +1 or -1 is returned if the position is the high (leading) or low (trailing) surrogate value, respectively.

This is useful for iterating through a string in codepoint sequence.

Function: lisp:surrogates-to-codepoint hi lo

Convert the given hi and lo surrogate characters to the corresponding codepoint value

Function: lisp:surrogates codepoint

Convert the given codepoint value to the corresponding high and low surrogate characters. If the codepoint is less than 65536, the second value is nil since the codepoint does not need to be represented as a surrogate pair.

Macro: lisp:with-string-codepoint-iterator (next string) &body body

with-string-codepoint-iterator provides a method of looping through a string from the beginning to the end of the string prodcucing successive codepoints from the string. next is bound to a generator macro that, within the scope of the invocation, returns one or two values. The first value tells whether any objects remain in the string. When the first value is non-NIL, the second value is the codepoint of the next object.

Macro: lisp:with-string-glpyh-iterator (next string) &body body

with-string-glyph-iterator provides a method of looping through a string from the beginning to the end of the string prodcucing successive glyphs from the string. next is bound to a generator macro that, within the scope of the invocation, returns one or three values. The first value tells whether any objects remain in the string. When the first value is non-NIL, the second value is the index into the string of the glyph and the third value is index of the next glyph.

Function: stream:string-encode string external-format &optional (start 0) end

string-encode encodes string using the format external-format, producing an array of octets. Each octet is converted to a character via code-char and the resulting string is returned.

The optional argument start, defaulting to 0, specifies the starting index and end, defaulting to the length of the string, is the end of the string.

Function: stream:string-decode string external-format &optional (start 0) end

string-decode decodes string using the format external-format and produces a new string. Each character of string is converted to octet (by char-code) and the resulting array of octets is used by the external format to produce a string. This is the inverse of string-encode.

The optional argument start, defaulting to 0, specifies the starting index and end, defaulting to the length of the string, is the end of the string.

string must consist of characters whose char-code is less than 256.

Function: string-to-octets string &key :start :end :external-format :buffer :buffer-start :error

string-to-octets converts string to a sequence of octets according to the external format specified by external-format. The string to be converted is bounded by start, which defaults to 0, and end, which defaults to the length of the string. If buffer is specified, the octets are placed in buffer. If buffer is not specified, a new array is allocated to hold the octets. buffer-start specifies where in the buffer the first octet will be placed.

An error method may also be specified by error. Any errors encountered while converting the string to octets will be handled according to error. If nil, a replacement character is converted to octets in place of the error. Otherwise, error should be a symbol or function that will be called when the error occurs. The function takes two arguments: an error string and the character that caused the error. It should return a replacement character.

Three values are returned: The buffer, the number of valid octets written, and the number of characters converted. Note that the actual number of octets written may be greater than the returned value, These represent the partial octets of the next character to be converted, but there was not enough room to hold the complete set of octets.

Function: octets-to-string octets &key :start :end :external-format :string :s-start :s-end :state

octets-to-string converts the sequence of octets in octets to a string. octets must be a (simple-array (unsigned-byte 8) (*)). The octets to be converted are bounded by start and end, which default to 0 and the length of the array, respectively. The conversion is performed according to the external format specified by external-format. If string is specified, the octets are converted and stored in string, starting at s-start (defaulting to 0) and ending just before s-end (defaulting to the end of string. string must be simple-string. If the bounded string is not large enough to hold all of the characters, then some octets will not be converted. If string is not specified, a new string is created.

The state is used as the initial state of for the external format. This is useful when converting buffers of octets where the buffers are not on character boundaries, and state information is needed between buffers.

Four values are returned: the string, the number of characters written to the string, and the number of octets consumed to produce the characters, and the final state of external format after converting the octets.


Next: Loop Extensions, Previous: Files, Up: Miscellaneous   [Contents][Index]