README.md 5.13 KB
Newer Older
Gábor Melis's avatar
Gábor Melis committed
1
<a id="x-28TRIVIAL-UTF-8-3A-40TRIVIAL-UTF-8-MANUAL-20MGL-PAX-3ASECTION-29"></a>
2
3
4
5
# Trivial UTF-8 Manual

## Table of Contents

Gábor Melis's avatar
Gábor Melis committed
6
- [1 `TRIVIAL-UTF-8` ASDF System][d9f2]
Gábor Melis's avatar
Gábor Melis committed
7
8
9
- [2 Introduction][e14a]
- [3 Links][3c3e]
- [4 Reference][a043]
10
11

###### \[in package TRIVIAL-UTF-8\]
Gábor Melis's avatar
Gábor Melis committed
12
<a id="x-28-22trivial-utf-8-22-20ASDF-2FSYSTEM-3ASYSTEM-29"></a>
Gábor Melis's avatar
Gábor Melis committed
13
## 1 `TRIVIAL-UTF-8` ASDF System
14
15
16
17
18
19
20
21
22

- Description: A small library for doing UTF-8-based input and output.
- Licence: ZLIB
- Author: Marijn Haverbeke <marijnh@gmail.com>
- Maintainer: Gábor Melis <mega@retes.hu>
- Homepage: [https://common-lisp.net/project/trivial-utf-8/](https://common-lisp.net/project/trivial-utf-8/)
- Bug tracker: [https://gitlab.common-lisp.net/trivial-utf-8/trivial-utf-8/-/issues](https://gitlab.common-lisp.net/trivial-utf-8/trivial-utf-8/-/issues)
- Source control: [GIT](https://gitlab.common-lisp.net/trivial-utf-8/trivial-utf-8.git)

Gábor Melis's avatar
Gábor Melis committed
23
<a id="x-28TRIVIAL-UTF-8-3A-40TRIVIAL-UTF-8-INTRODUCTION-20MGL-PAX-3ASECTION-29"></a>
24
25
26
27
## 2 Introduction

Trivial UTF-8 is a small library for doing UTF-8-based in- and
output on a Lisp implementation that already supports Unicode -
Gábor Melis's avatar
Gábor Melis committed
28
meaning [`CHAR-CODE`][7e2c] and [`CODE-CHAR`][d796] deal with Unicode character codes.
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

The rationale for the existence of this library is that while
Unicode-enabled implementations usually do provide some kind of
interface to dealing with character encodings, these are typically
not terribly flexible or uniform.

The [Babel][babel] library solves a similar problem while
understanding more encodings. Trivial UTF-8 was written before Babel
existed, but for new projects you might be better off going with
Babel. The one plus that Trivial UTF-8 has is that it doesn't depend
on any other libraries.

[babel]: https://common-lisp.net/project/babel/ 


Gábor Melis's avatar
Gábor Melis committed
44
<a id="x-28TRIVIAL-UTF-8-3A-40TRIVIAL-UTF-8-LINKS-20MGL-PAX-3ASECTION-29"></a>
45
46
47
48
49
50
51
52
53
54
## 3 Links

Here is the [official repository][trivial-utf-8-repo] and the
[HTML documentation][trivial-utf-8-doc] for the latest version.

[trivial-utf-8-repo]: https://gitlab.common-lisp.net/trivial-utf-8/trivial-utf-8 

[trivial-utf-8-doc]: http://melisgl.github.io/mgl-pax-world/trivial-utf-8-manual.html 


Gábor Melis's avatar
Gábor Melis committed
55
<a id="x-28TRIVIAL-UTF-8-3A-40TRIVIAL-UTF-8-REFERENCE-20MGL-PAX-3ASECTION-29"></a>
56
57
## 4 Reference

Gábor Melis's avatar
Gábor Melis committed
58
<a id="x-28TRIVIAL-UTF-8-3AUTF-8-BYTE-LENGTH-20FUNCTION-29"></a>
59
60
61
62
- [function] **UTF-8-BYTE-LENGTH** *STRING*

    Calculate the amount of bytes needed to encode `STRING`.

Gábor Melis's avatar
Gábor Melis committed
63
<a id="x-28TRIVIAL-UTF-8-3ASTRING-TO-UTF-8-BYTES-20FUNCTION-29"></a>
64
65
66
67
68
- [function] **STRING-TO-UTF-8-BYTES** *STRING &KEY NULL-TERMINATE*

    Convert `STRING` into an array of unsigned bytes containing its UTF-8
    representation. If `NULL-TERMINATE`, add an extra 0 byte at the end.

Gábor Melis's avatar
Gábor Melis committed
69
<a id="x-28TRIVIAL-UTF-8-3AUTF-8-GROUP-SIZE-20FUNCTION-29"></a>
70
71
72
- [function] **UTF-8-GROUP-SIZE** *BYTE*

    Determine the amount of bytes that are part of the character whose
Gábor Melis's avatar
Gábor Melis committed
73
    encoding starts with `BYTE`. May signal [`UTF-8-DECODING-ERROR`][ad1e].
74

Gábor Melis's avatar
Gábor Melis committed
75
<a id="x-28TRIVIAL-UTF-8-3AUTF-8-BYTES-TO-STRING-20FUNCTION-29"></a>
76
77
78
- [function] **UTF-8-BYTES-TO-STRING** *BYTES &KEY (START 0) (END (LENGTH BYTES))*

    Convert the `START`, `END` subsequence of the array of `BYTES` containing
Gábor Melis's avatar
Gábor Melis committed
79
80
81
    UTF-8 encoded characters to a [`STRING`][4267]. The element type of
    `BYTES` may be anything as long as it can be [`COERCE`][7959]d into
    an `(UNSIGNED-BYTES 8)` array. May signal [`UTF-8-DECODING-ERROR`][ad1e].
82

Gábor Melis's avatar
Gábor Melis committed
83
<a id="x-28TRIVIAL-UTF-8-3AREAD-UTF-8-STRING-20FUNCTION-29"></a>
84
85
86
87
88
- [function] **READ-UTF-8-STRING** *INPUT &KEY NULL-TERMINATED STOP-AT-EOF (CHAR-LENGTH -1) (BYTE-LENGTH -1)*

    Read UTF-8 encoded data from `INPUT`, a byte stream, and construct a
    string with the characters found. When `NULL-TERMINATED` is given,
    stop reading at a null character. If `STOP-AT-EOF`, then stop at
Gábor Melis's avatar
Gábor Melis committed
89
    [`END-OF-FILE`][cc17] without raising an error. The `CHAR-LENGTH` and
90
91
    `BYTE-LENGTH` parameters can be used to specify the max amount of
    characters or bytes to read, where -1 means no limit. May signal
Gábor Melis's avatar
Gábor Melis committed
92
    [`UTF-8-DECODING-ERROR`][ad1e].
93

Gábor Melis's avatar
Gábor Melis committed
94
<a id="x-28TRIVIAL-UTF-8-3AUTF-8-DECODING-ERROR-20CONDITION-29"></a>
95
96
- [condition] **UTF-8-DECODING-ERROR** *SIMPLE-ERROR*

Gábor Melis's avatar
Gábor Melis committed
97
  [3c3e]: #x-28TRIVIAL-UTF-8-3A-40TRIVIAL-UTF-8-LINKS-20MGL-PAX-3ASECTION-29 "Links"
Gábor Melis's avatar
Gábor Melis committed
98
99
100
  [4267]: http://www.lispworks.com/documentation/HyperSpec/Body/t_string.htm "STRING TYPE"
  [7959]: http://www.lispworks.com/documentation/HyperSpec/Body/f_coerce.htm "COERCE FUNCTION"
  [7e2c]: http://www.lispworks.com/documentation/HyperSpec/Body/f_char_c.htm "CHAR-CODE FUNCTION"
Gábor Melis's avatar
Gábor Melis committed
101
102
  [a043]: #x-28TRIVIAL-UTF-8-3A-40TRIVIAL-UTF-8-REFERENCE-20MGL-PAX-3ASECTION-29 "Reference"
  [ad1e]: #x-28TRIVIAL-UTF-8-3AUTF-8-DECODING-ERROR-20CONDITION-29 "TRIVIAL-UTF-8:UTF-8-DECODING-ERROR CONDITION"
Gábor Melis's avatar
Gábor Melis committed
103
104
  [cc17]: http://www.lispworks.com/documentation/HyperSpec/Body/e_end_of.htm "END-OF-FILE CONDITION"
  [d796]: http://www.lispworks.com/documentation/HyperSpec/Body/f_code_c.htm "CODE-CHAR FUNCTION"
Gábor Melis's avatar
Gábor Melis committed
105
106
  [d9f2]: #x-28-22trivial-utf-8-22-20ASDF-2FSYSTEM-3ASYSTEM-29 '"trivial-utf-8" ASDF/SYSTEM:SYSTEM'
  [e14a]: #x-28TRIVIAL-UTF-8-3A-40TRIVIAL-UTF-8-INTRODUCTION-20MGL-PAX-3ASECTION-29 "Introduction"
107
108
109

* * *
###### \[generated by [MGL-PAX](https://github.com/melisgl/mgl-pax)\]