format: Signal an error for ~<~@>
[sbcl.git] / src / code / target-char.lisp
1 ;;;; character functions
2
3 ;;;; This software is part of the SBCL system. See the README file for
4 ;;;; more information.
5 ;;;;
6 ;;;; This software is derived from the CMU CL system, which was
7 ;;;; written at Carnegie Mellon University and released into the
8 ;;;; public domain. The software is in the public domain and is
9 ;;;; provided with absolutely no warranty. See the COPYING and CREDITS
10 ;;;; files for more information.
11
12 (in-package "SB!IMPL")
13
14 ;;; We compile some trivial character operations via inline expansion.
15 #!-sb-fluid
16 (declaim (inline standard-char-p graphic-char-p alpha-char-p
17                  upper-case-p lower-case-p both-case-p alphanumericp
18                  char-int))
19 (declaim (maybe-inline digit-char-p digit-weight))
20
21 (deftype char-code ()
22   `(integer 0 (,char-code-limit)))
23
24 #!+sb-unicode
25 (progn
26  (defvar *unicode-character-name-database*)
27  (defvar *unicode-character-name-huffman-tree*))
28
29 (macrolet
30     ((frob ()
31        (flet ((file (name type)
32                 (merge-pathnames (make-pathname
33                                   :directory
34                                   '(:relative :up :up "output")
35                                   :name name :type type)
36                                  sb!xc:*compile-file-truename*)))
37          (let ((character-database
38                 (with-open-file (stream (file "ucd" "dat")
39                                         :direction :input
40                                         :element-type '(unsigned-byte 8))
41                   (let* ((length (file-length stream))
42                          (array (make-array
43                                  length :element-type '(unsigned-byte 8))))
44                     (read-sequence array stream)
45                     array))))
46            `(progn
47               (declaim (type (simple-array (unsigned-byte 8) (*)) **character-database**))
48               (defglobal **character-database** ,character-database)
49               (defun !character-database-cold-init ()
50                 (setf **character-database** ,character-database))
51               ,(with-open-file (stream (file "ucd-names" "lisp-expr")
52                                        :direction :input
53                                        :element-type 'character)
54                                (let ((names (make-hash-table)))
55                                  #!+sb-unicode
56                                  (loop
57                                        for code-point = (read stream nil nil)
58                                        for char-name = (string-upcase (read stream nil nil))
59                                        while code-point
60                                        do (setf (gethash code-point names) char-name))
61                                  (let ((tree
62                                         #!+sb-unicode
63                                          (make-huffman-tree
64                                           (let (list)
65                                             (maphash (lambda (code name)
66                                                        (declare (ignore code))
67                                                        (push name list))
68                                                      names)
69                                             list)))
70                                        (code->name
71                                         (make-array (hash-table-count names)
72                                                     :fill-pointer 0))
73                                        (name->code nil))
74                                    (maphash (lambda (code name)
75                                               (vector-push
76                                                (cons code (huffman-encode name tree))
77                                                code->name))
78                                             names)
79                                    (setf name->code
80                                          (sort (copy-seq code->name) #'< :key #'cdr))
81                                    (setf code->name
82                                          (sort (copy-seq name->code) #'< :key #'car))
83                                    (setf names nil)
84                                    `(defun !character-name-database-cold-init ()
85                                       #!+sb-unicode
86                                       (setq *unicode-character-name-database*
87                                             (cons ',code->name ',name->code)
88                                             *unicode-character-name-huffman-tree* ',tree))))))))))
89   (frob))
90 #+sb-xc-host (!character-name-database-cold-init)
91
92 (defparameter *base-char-name-alist*
93   ;; Note: The *** markers here indicate character names which are
94   ;; required by the ANSI specification of #'CHAR-NAME. For the others,
95   ;; we prefer the ASCII standard name.
96   '((#x00 "Nul" "Null" "^@")
97     (#x01 "Soh" "^a")
98     (#x02 "Stx" "^b")
99     (#x03 "Etx" "^c")
100     (#x04 "Eot" "^d")
101     (#x05 "Enq" "^e")
102     (#x06 "Ack" "^f")
103     (#x07 "Bel" "Bell" "^g")
104     (#x08 "Backspace" "^h" "Bs") ; *** See Note above
105     (#x09 "Tab" "^i" "Ht") ; *** See Note above
106     (#x0A "Newline" "Linefeed" "^j" "Lf" "Nl") ; *** See Note above
107     (#x0B "Vt" "^k")
108     (#x0C "Page" "^l" "Form" "Formfeed" "Ff" "Np") ; *** See Note above
109     (#x0D "Return" "^m" "Cr") ; *** See Note above
110     (#x0E "So" "^n")
111     (#x0F "Si" "^o")
112     (#x10 "Dle" "^p")
113     (#x11 "Dc1" "^q")
114     (#x12 "Dc2" "^r")
115     (#x13 "Dc3" "^s")
116     (#x14 "Dc4" "^t")
117     (#x15 "Nak" "^u")
118     (#x16 "Syn" "^v")
119     (#x17 "Etb" "^w")
120     (#x18 "Can" "^x")
121     (#x19 "Em" "^y")
122     (#x1A "Sub" "^z")
123     (#x1B "Esc" "Escape" "^[" "Altmode" "Alt")
124     (#x1C "Fs" "^\\")
125     (#x1D "Gs" "^]")
126     (#x1E "Rs" "^^")
127     (#x1F "Us" "^_")
128     (#x20 "Space" "Sp") ; *** See Note above
129     (#x7f "Rubout" "Delete" "Del")
130     (#x80 "C80")
131     (#x81 "C81")
132     (#x82 "Break-Permitted")
133     (#x83 "No-Break-Permitted")
134     (#x84 "C84")
135     (#x85 "Next-Line")
136     (#x86 "Start-Selected-Area")
137     (#x87 "End-Selected-Area")
138     (#x88 "Character-Tabulation-Set")
139     (#x89 "Character-Tabulation-With-Justification")
140     (#x8A "Line-Tabulation-Set")
141     (#x8B "Partial-Line-Forward")
142     (#x8C "Partial-Line-Backward")
143     (#x8D "Reverse-Linefeed")
144     (#x8E "Single-Shift-Two")
145     (#x8F "Single-Shift-Three")
146     (#x90 "Device-Control-String")
147     (#x91 "Private-Use-One")
148     (#x92 "Private-Use-Two")
149     (#x93 "Set-Transmit-State")
150     (#x94 "Cancel-Character")
151     (#x95 "Message-Waiting")
152     (#x96 "Start-Guarded-Area")
153     (#x97 "End-Guarded-Area")
154     (#x98 "Start-String")
155     (#x99 "C99")
156     (#x9A "Single-Character-Introducer")
157     (#x9B "Control-Sequence-Introducer")
158     (#x9C "String-Terminator")
159     (#x9D "Operating-System-Command")
160     (#x9E "Privacy-Message")
161     (#x9F "Application-Program-Command"))) ; *** See Note above
162 \f
163 ;;;; UCD accessor functions
164
165 ;;; The first (* 8 215) => 1720 entries in **CHARACTER-DATABASE**
166 ;;; contain entries for the distinct character attributes:
167 ;;; specifically, indexes into the GC kinds, Bidi kinds, CCC kinds,
168 ;;; the decimal digit property, the digit property and the
169 ;;; bidi-mirrored boolean property.  (There are two spare bytes for
170 ;;; other information, should that become necessary)
171 ;;;
172 ;;; the next (ash #x110000 -8) entries contain single-byte indexes
173 ;;; into a table of 256-element 4-byte-sized entries.  These entries
174 ;;; follow directly on, and are of the form
175 ;;; {attribute-index[1B],transformed-code-point[3B]}x256, where the
176 ;;; attribute index is an index into the miscellaneous information
177 ;;; table, and the transformed code point is the code point of the
178 ;;; simple mapping of the character to its lowercase or uppercase
179 ;;; equivalent, as appropriate and if any.
180 ;;;
181 ;;; I feel the opacity of the above suggests the need for a diagram:
182 ;;;
183 ;;;         C  _______________________________________
184 ;;;           /                                       \
185 ;;;          L                                         \
186 ;;;  [***************|=============================|--------...]
187 ;;;                 (a)      \                       _
188 ;;;                         A \______________________/| B
189 ;;;
190 ;;; To look up information about a character, take the high 13 bits of
191 ;;; its code point, and index the character database with that and a
192 ;;; base of 1720 (going past the miscellaneous information[*], so
193 ;;; treating (a) as the start of the array).  This, labelled A, gives
194 ;;; us another index into the detailed pages[-], which we can use to
195 ;;; look up the details for the character in question: we add the low
196 ;;; 8 bits of the character, shifted twice (because we have four-byte
197 ;;; table entries) to 1024 times the `page' index, with a base of 6072
198 ;;; to skip over everything else.  This gets us to point B.  If we're
199 ;;; after a transformed code point (i.e. an upcase or downcase
200 ;;; operation), we can simply read it off now, beginning with an
201 ;;; offset of 1 byte from point B in some endianness; if we're looking
202 ;;; for miscellaneous information, we take the value at B, and index
203 ;;; the character database once more to get to the relevant
204 ;;; miscellaneous information.
205 ;;;
206 ;;; The moral of all this?  Next time, don't just say "FIXME: document
207 ;;; this"
208 (defun ucd-index (char)
209   (let* ((cp (char-code char))
210          (cp-high (ash cp -8))
211          (page (aref **character-database** (+ 1720 cp-high))))
212     (+ 6072 (ash page 10) (ash (ldb (byte 8 0) cp) 2))))
213
214 (declaim (ftype (sfunction (t) (unsigned-byte 8)) ucd-value-0))
215 (defun ucd-value-0 (char)
216   (aref **character-database** (ucd-index char)))
217
218 (declaim (ftype (sfunction (t) (unsigned-byte 24)) ucd-value-1))
219 (defun ucd-value-1 (char)
220   (let ((index (ucd-index char))
221         (character-database **character-database**))
222     (dpb (aref character-database (+ index 3))
223          (byte 8 16)
224          (dpb (aref character-database (+ index 2))
225               (byte 8 8)
226               (aref character-database (1+ index))))))
227
228 (declaim (ftype (sfunction (t) (unsigned-byte 8)) ucd-general-category))
229 (defun ucd-general-category (char)
230   (aref **character-database** (* 8 (ucd-value-0 char))))
231
232 (defun ucd-decimal-digit (char)
233   (let ((decimal-digit (aref **character-database**
234                              (+ 3 (* 8 (ucd-value-0 char))))))
235     (when (< decimal-digit 10)
236       decimal-digit)))
237
238 (defun char-code (char)
239   #!+sb-doc
240   "Return the integer code of CHAR."
241   (char-code char))
242
243 (defun char-int (char)
244   #!+sb-doc
245   "Return the integer code of CHAR. (In SBCL this is the same as CHAR-CODE, as
246 there are no character bits or fonts.)"
247   (char-code char))
248
249 (defun code-char (code)
250   #!+sb-doc
251   "Return the character with the code CODE."
252   (code-char code))
253
254 (defun character (object)
255   #!+sb-doc
256   "Coerce OBJECT into a CHARACTER if possible. Legal inputs are characters,
257 strings and symbols of length 1."
258   (flet ((do-error (control args)
259            (error 'simple-type-error
260                   :datum object
261                   ;;?? how to express "symbol with name of length 1"?
262                   :expected-type '(or character (string 1))
263                   :format-control control
264                   :format-arguments args)))
265     (typecase object
266       (character object)
267       (string (if (= 1 (length (the string object)))
268                   (char object 0)
269                   (do-error
270                    "String is not of length one: ~S" (list object))))
271       (symbol (if (= 1 (length (symbol-name object)))
272                   (schar (symbol-name object) 0)
273                   (do-error
274                    "Symbol name is not of length one: ~S" (list object))))
275       (t (do-error "~S cannot be coerced to a character." (list object))))))
276
277 (defun char-name (char)
278   #!+sb-doc
279   "Return the name (a STRING) for a CHARACTER object."
280   (let ((char-code (char-code char)))
281     (or (second (assoc char-code *base-char-name-alist*))
282         #!+sb-unicode
283         (let ((h-code (cdr (binary-search char-code
284                                           (car *unicode-character-name-database*)
285                                           :key #'car))))
286           (cond
287             (h-code
288              (huffman-decode h-code *unicode-character-name-huffman-tree*))
289             ((< char-code #x10000)
290              (format nil "U~4,'0X" char-code))
291             (t
292              (format nil "U~8,'0X" char-code)))))))
293
294 (defun name-char (name)
295   #!+sb-doc
296   "Given an argument acceptable to STRING, NAME-CHAR returns a character whose
297 name is that string, if one exists. Otherwise, NIL is returned."
298   (or (let ((char-code (car (rassoc-if (lambda (names)
299                                          (member name names :test #'string-equal))
300                                        *base-char-name-alist*))))
301         (when char-code
302           (code-char char-code)))
303       #!+sb-unicode
304       (let ((encoding (huffman-encode (string-upcase name)
305                                        *unicode-character-name-huffman-tree*)))
306         (when encoding
307           (let* ((char-code
308                   (car (binary-search encoding
309                                       (cdr *unicode-character-name-database*)
310                                       :key #'cdr)))
311                  (name-string (string name))
312                  (name-length (length name-string)))
313             (cond
314               (char-code
315                (code-char char-code))
316               ((and (or (= name-length 9)
317                         (= name-length 5))
318                     (char-equal (char name-string 0) #\U)
319                     (loop for i from 1 below name-length
320                           always (digit-char-p (char name-string i) 16)))
321                (code-char (parse-integer name-string :start 1 :radix 16)))
322               (t
323                nil)))))))
324 \f
325 ;;;; predicates
326
327 (defun standard-char-p (char)
328   #!+sb-doc
329   "The argument must be a character object. STANDARD-CHAR-P returns T if the
330 argument is a standard character -- one of the 95 ASCII printing characters or
331 <return>."
332   (and (typep char 'base-char)
333        (let ((n (char-code (the base-char char))))
334          (or (< 31 n 127)
335              (= n 10)))))
336
337 (defun %standard-char-p (thing)
338   #!+sb-doc
339   "Return T if and only if THING is a standard-char. Differs from
340 STANDARD-CHAR-P in that THING doesn't have to be a character."
341   (and (characterp thing) (standard-char-p thing)))
342
343 (defun graphic-char-p (char)
344   #!+sb-doc
345   "The argument must be a character object. GRAPHIC-CHAR-P returns T if the
346 argument is a printing character (space through ~ in ASCII), otherwise returns
347 NIL."
348   (let ((n (char-code char)))
349     (or (< 31 n 127)
350         (< 159 n))))
351
352 (defun alpha-char-p (char)
353   #!+sb-doc
354   "The argument must be a character object. ALPHA-CHAR-P returns T if the
355 argument is an alphabetic character, A-Z or a-z; otherwise NIL."
356   (< (ucd-general-category char) 5))
357
358 (defun upper-case-p (char)
359   #!+sb-doc
360   "The argument must be a character object; UPPER-CASE-P returns T if the
361 argument is an upper-case character, NIL otherwise."
362   (= (ucd-value-0 char) 0))
363
364 (defun lower-case-p (char)
365   #!+sb-doc
366   "The argument must be a character object; LOWER-CASE-P returns T if the
367 argument is a lower-case character, NIL otherwise."
368   (= (ucd-value-0 char) 1))
369
370 (defun both-case-p (char)
371   #!+sb-doc
372   "The argument must be a character object. BOTH-CASE-P returns T if the
373 argument is an alphabetic character and if the character exists in both upper
374 and lower case. For ASCII, this is the same as ALPHA-CHAR-P."
375   (< (ucd-value-0 char) 2))
376
377 (defun digit-char-p (char &optional (radix 10.))
378   #!+sb-doc
379   "If char is a digit in the specified radix, returns the fixnum for which
380 that digit stands, else returns NIL."
381   (let ((m (- (char-code char) 48)))
382     (declare (fixnum m))
383     (cond ((<= radix 10.)
384            ;; Special-case decimal and smaller radices.
385            (if (and (>= m 0) (< m radix))  m  nil))
386           ;; Digits 0 - 9 are used as is, since radix is larger.
387           ((and (>= m 0) (< m 10)) m)
388           ;; Check for upper case A - Z.
389           ((and (>= (setq m (- m 7)) 10) (< m radix)) m)
390           ;; Also check lower case a - z.
391           ((and (>= (setq m (- m 32)) 10) (< m radix)) m)
392           ;; Else, fail.
393           (t (let ((number (ucd-decimal-digit char)))
394                (when (and number (< number radix))
395                  number))))))
396
397 (defun alphanumericp (char)
398   #!+sb-doc
399   "Given a character-object argument, ALPHANUMERICP returns T if the argument
400 is either numeric or alphabetic."
401   (let ((gc (ucd-general-category char)))
402     (or (< gc 5)
403         (= gc 12))))
404
405 (defun char= (character &rest more-characters)
406   #!+sb-doc
407   "Return T if all of the arguments are the same character."
408   (declare (truly-dynamic-extent more-characters))
409   (dolist (c more-characters t)
410     (declare (type character c))
411     (unless (eq c character) (return nil))))
412
413 (defun char/= (character &rest more-characters)
414   #!+sb-doc
415   "Return T if no two of the arguments are the same character."
416   (declare (truly-dynamic-extent more-characters))
417   (do* ((head character (car list))
418         (list more-characters (cdr list)))
419        ((null list) t)
420     (declare (type character head))
421     (dolist (c list)
422       (declare (type character c))
423       (when (eq head c) (return-from char/= nil)))))
424
425 (defun char< (character &rest more-characters)
426   #!+sb-doc
427   "Return T if the arguments are in strictly increasing alphabetic order."
428   (declare (truly-dynamic-extent more-characters))
429   (do* ((c character (car list))
430         (list more-characters (cdr list)))
431        ((null list) t)
432     (unless (< (char-int c)
433                (char-int (car list)))
434       (return nil))))
435
436 (defun char> (character &rest more-characters)
437   #!+sb-doc
438   "Return T if the arguments are in strictly decreasing alphabetic order."
439   (declare (truly-dynamic-extent more-characters))
440   (do* ((c character (car list))
441         (list more-characters (cdr list)))
442        ((null list) t)
443     (unless (> (char-int c)
444                (char-int (car list)))
445       (return nil))))
446
447 (defun char<= (character &rest more-characters)
448   #!+sb-doc
449   "Return T if the arguments are in strictly non-decreasing alphabetic order."
450   (declare (truly-dynamic-extent more-characters))
451   (do* ((c character (car list))
452         (list more-characters (cdr list)))
453        ((null list) t)
454     (unless (<= (char-int c)
455                 (char-int (car list)))
456       (return nil))))
457
458 (defun char>= (character &rest more-characters)
459   #!+sb-doc
460   "Return T if the arguments are in strictly non-increasing alphabetic order."
461   (declare (truly-dynamic-extent more-characters))
462   (do* ((c character (car list))
463         (list more-characters (cdr list)))
464        ((null list) t)
465     (unless (>= (char-int c)
466                 (char-int (car list)))
467       (return nil))))
468
469 ;;; EQUAL-CHAR-CODE is used by the following functions as a version of CHAR-INT
470 ;;;  which loses font, bits, and case info.
471
472 (defmacro equal-char-code (character)
473   (let ((ch (gensym)))
474     `(let ((,ch ,character))
475       (if (= (ucd-value-0 ,ch) 0)
476           (ucd-value-1 ,ch)
477           (char-code ,ch)))))
478
479 (defun two-arg-char-equal (c1 c2)
480   (= (equal-char-code c1) (equal-char-code c2)))
481
482 (defun char-equal (character &rest more-characters)
483   #!+sb-doc
484   "Return T if all of the arguments are the same character.
485 Case is ignored."
486   (declare (truly-dynamic-extent more-characters))
487   (do ((clist more-characters (cdr clist)))
488       ((null clist) t)
489     (unless (two-arg-char-equal (car clist) character)
490       (return nil))))
491
492 (defun two-arg-char-not-equal (c1 c2)
493   (/= (equal-char-code c1) (equal-char-code c2)))
494
495 (defun char-not-equal (character &rest more-characters)
496   #!+sb-doc
497   "Return T if no two of the arguments are the same character.
498 Case is ignored."
499   (declare (truly-dynamic-extent more-characters))
500   (do* ((head character (car list))
501         (list more-characters (cdr list)))
502        ((null list) t)
503     (unless (do* ((l list (cdr l)))
504                  ((null l) t)
505               (if (two-arg-char-equal head (car l))
506                   (return nil)))
507       (return nil))))
508
509 (defun two-arg-char-lessp (c1 c2)
510   (< (equal-char-code c1) (equal-char-code c2)))
511
512 (defun char-lessp (character &rest more-characters)
513   #!+sb-doc
514   "Return T if the arguments are in strictly increasing alphabetic order.
515 Case is ignored."
516   (declare (truly-dynamic-extent more-characters))
517   (do* ((c character (car list))
518         (list more-characters (cdr list)))
519        ((null list) t)
520     (unless (two-arg-char-lessp c (car list))
521       (return nil))))
522
523 (defun two-arg-char-greaterp (c1 c2)
524   (> (equal-char-code c1) (equal-char-code c2)))
525
526 (defun char-greaterp (character &rest more-characters)
527   #!+sb-doc
528   "Return T if the arguments are in strictly decreasing alphabetic order.
529 Case is ignored."
530   (declare (truly-dynamic-extent more-characters))
531   (do* ((c character (car list))
532         (list more-characters (cdr list)))
533        ((null list) t)
534     (unless (two-arg-char-greaterp c (car list))
535       (return nil))))
536
537 (defun two-arg-char-not-greaterp (c1 c2)
538   (<= (equal-char-code c1) (equal-char-code c2)))
539
540 (defun char-not-greaterp (character &rest more-characters)
541   #!+sb-doc
542   "Return T if the arguments are in strictly non-decreasing alphabetic order.
543 Case is ignored."
544   (declare (truly-dynamic-extent more-characters))
545   (do* ((c character (car list))
546         (list more-characters (cdr list)))
547        ((null list) t)
548     (unless (two-arg-char-not-greaterp c (car list))
549       (return nil))))
550
551 (defun two-arg-char-not-lessp (c1 c2)
552   (>= (equal-char-code c1) (equal-char-code c2)))
553
554 (defun char-not-lessp (character &rest more-characters)
555   #!+sb-doc
556   "Return T if the arguments are in strictly non-increasing alphabetic order.
557 Case is ignored."
558   (declare (truly-dynamic-extent more-characters))
559   (do* ((c character (car list))
560         (list more-characters (cdr list)))
561        ((null list) t)
562     (unless (two-arg-char-not-lessp c (car list))
563       (return nil))))
564 \f
565 ;;;; miscellaneous functions
566
567 (defun char-upcase (char)
568   #!+sb-doc
569   "Return CHAR converted to upper-case if that is possible. Don't convert
570 lowercase eszet (U+DF)."
571   (if (= (ucd-value-0 char) 1)
572       (code-char (ucd-value-1 char))
573       char))
574
575 (defun char-downcase (char)
576   #!+sb-doc
577   "Return CHAR converted to lower-case if that is possible."
578   (if (= (ucd-value-0 char) 0)
579       (code-char (ucd-value-1 char))
580       char))
581
582 (defun digit-char (weight &optional (radix 10))
583   #!+sb-doc
584   "All arguments must be integers. Returns a character object that represents
585 a digit of the given weight in the specified radix. Returns NIL if no such
586 character exists."
587   (and (typep weight 'fixnum)
588        (>= weight 0) (< weight radix) (< weight 36)
589        (code-char (if (< weight 10) (+ 48 weight) (+ 55 weight)))))