octets-to-char

Macro

Package: excl

Arguments: name state-loc &key get-next-octet unget-octets octets-count-loc oc-eof-macro external-format

name should be a symbol. state-loc a place suitable as the fist 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. See the description of def-octets-to-char-macro for descriptions the return value of the 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 and indicate the situation (eg, 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.

Example:

(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 :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.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.