| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
Arguments: name state-loc &key get-next-octet unget-octets octets-count-loc oc-eof-macro external-format
name should be a symbol or an external-format. state-loc a place suitable as the first argument to setf. get-next-octet should be a form. external-format should be an external-format or symbol naming an external-format.
The octets-to-char macro
simply expands to the macro stored in the
octets-to-char-macro
slot of the external-format
named by name. The external-format must be a
base external-format or a macro-based composing external-format (which
is, in fact, just a special type of base external-format). The
external-format must not be an encapsulating-based composing
external-format as it will then not have a filled octets-to-char-macro
slot. See the description of def-octets-to-char-macro for descriptions of
the return value of the macro's expansion as well as of the
get-next-octet,
unget-octets,
octets-count-loc, and
external-format arguments.
The oc-eof-macro argument is not described in the
def-octets-to-char-macro
description. This argument is a list consisting of a lambda list
specification designating a required argument, and a macro defining
form. oc-eof-macro can also be nil
, which specifies that no oc-eof-macro is defined.
An oc-eof-macro specifies the action to be taken by the
get-next-octet routine when it hits an
end-of-data situation. When oc-eof-macro is invoked, the
octets-count-loc should hold the number of octets
retrieved.
The argument to oc-eof-macro is a boolean which designates whether the end-of-data situation should be considered 'hard' or not. When the argument is true (designating a 'hard' end-of-data situation), the octet input source is to be considered completely empty and no further attempts to extract octets from the source should be made. The octets-to-char macro may then choose to return an alternate character in this case. When the argument is false, the octet input source is to be considered empty at the current time, but further octets may be available in the future. Thus, if there are not enough octets available at the present time to determine which character should be returned, the octets-to-char macro may choose to unget all unused octets (that is, reset the file position so it points to the first newly ungot octet) and indicate the situation (e.g., by a non-local exit) to octets-to-char's caller.
A composing external-format may trap the end-of-data condition using its own oc-eof-macro so that it can return a valid character.
Users generally do not need to invoke the octets-to-char macro. In most cases, it is more convenient to use octets-to-string.
;; Ensure utf8 conversion macros are available by explicitly loading the ;; external-format definition. This suppresses the macro removal ;; optimizations that may occur when external-format is autoloaded. ;; (let ((*modules* (remove "ef-utf8" *modules* :test #'string-equal))) (require "ef-utf8")) (funcall (compile nil `(lambda () (let ((utf8-vector (make-array 3 :element-type '(unsigned-byte 8) ;; These three octets are utf8 ;; for hiragana letter A. :initial-contents '(227 129 130))) (v 0) (octets-count 1) (state nil)) (declare (ignorable state)) (octets-to-char ,(crlf-base-ef :utf8) state :get-next-octet (prog1 (aref utf8-vector v) (incf v)) :octets-count-loc octets-count :unget-octets (lambda (n) (decf v n)) :oc-eof-macro nil))))) ==> #\hiragana_letter_a
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.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |