octets-to-char

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.

Example:

;; 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.