def-external-format

Arguments: name &key nicknames nulls width

In releases prior to 6.1, there was a size keyword argument but no width or nulls arguments. The size argument confounded the width and nulls values. It is no longer accepted.

The arguments are:

• name should be a symbol. ef-name accesses the name slot of an external format.
• nicknames should be a list of symbols which can be used interchangeably with name.
• width specifies how many octets it takes to build a character. It may have an integer value, or else the value character, which is the default value. The width slot is used to optimize listen techniques in a stream; by default listen requires at least width octets to be available before returning true. Normally this means having to go through the process of building a character, but in simple formats, like latin1, availability of a single octet can allow a true return from listen. ef-width accesses the width slot of an external format.
• nulls specifies how many 0 octets must trail a string. It defaults to 1 and is only ever different in :fat and :unicode formats (where the value is 2). ef-nulls accesses the nulls slot of an external format.

This macro defines name as an external-format. If name already names an existing external-format, then that external-format is modified to have its nicknames, width, and nulls slots set to the values specified in the call to def-external-format. A slot is only modified in this call if it is specified in the call to def-external-format.

An error is signaled if any of the symbols specified in nicknames is a nickname to an external-format other than that being defined or modified.

Example:

(def-external-format :utf-8 :nicknames '(:utf8))

Here is an overview of how external-formats are used:

The main purpose for the external-format object is as a place to store Lisp coded procedures for translating octets in external representation to/from lisp strings. In order to use these routines as efficiently as possible, the translation procedures are defined as macros. The effect is that with these macros, the code to translate octets to and from characters is directly mixed in with the code to retrieve/store octets/characters. The macros themselves take as arguments expressions to get/put the next octet or character to translate. The return value of the macros' expansions are the number of octets or characters translated. (See def-char-to-octets-macro and def-octets-to-char-macro.)

Some external-formats may be composed with other external-formats to form new external-formats. For example, a wrapper external-format may be defined which combines external bytes representing 'f' and 'i' to create #\latin_small_ligature_fi. This wrapper external-format could be composed with the utf8 external-format to create a ligature-utf8 external-format. The wrapper external-format could also be composed with the euc external-format to create a ligature-euc external-format. Wrapped or composed external-formats are created using the compose-external-formats operator.

See iacl.htm for more information on international character support in Allegro CL.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.