libctru  v2.4.1
utf.h
Go to the documentation of this file.
1 /**
2  * @file utf.h
3  * @brief UTF conversion functions.
4  */
5 #pragma once
6 
7 #include <stdint.h>
8 #include <sys/types.h>
9 
10 /** Convert a UTF-8 sequence into a UTF-32 codepoint
11  *
12  * @param[out] out Output codepoint
13  * @param[in] in Input sequence
14  *
15  * @returns number of input code units consumed
16  * @returns -1 for error
17  */
18 ssize_t decode_utf8 (uint32_t *out, const uint8_t *in);
19 
20 /** Convert a UTF-16 sequence into a UTF-32 codepoint
21  *
22  * @param[out] out Output codepoint
23  * @param[in] in Input sequence
24  *
25  * @returns number of input code units consumed
26  * @returns -1 for error
27  */
28 ssize_t decode_utf16(uint32_t *out, const uint16_t *in);
29 
30 /** Convert a UTF-32 codepoint into a UTF-8 sequence
31  *
32  * @param[out] out Output sequence
33  * @param[in] in Input codepoint
34  *
35  * @returns number of output code units produced
36  * @returns -1 for error
37  *
38  * @note \a out must be able to store 4 code units
39  */
40 ssize_t encode_utf8 (uint8_t *out, uint32_t in);
41 
42 /** Convert a UTF-32 codepoint into a UTF-16 sequence
43  *
44  * @param[out] out Output sequence
45  * @param[in] in Input codepoint
46  *
47  * @returns number of output code units produced
48  * @returns -1 for error
49  *
50  * @note \a out must be able to store 2 code units
51  */
52 ssize_t encode_utf16(uint16_t *out, uint32_t in);
53 
54 /** Convert a UTF-8 sequence into a UTF-16 sequence
55  *
56  * Fills the output buffer up to \a len code units.
57  * Returns the number of code units that the input would produce;
58  * if it returns greater than \a len, the output has been
59  * truncated.
60  *
61  * @param[out] out Output sequence
62  * @param[in] in Input sequence (null-terminated)
63  * @param[in] len Output length
64  *
65  * @returns number of output code units produced
66  * @returns -1 for error
67  *
68  * @note \a out is not null-terminated
69  */
70 ssize_t utf8_to_utf16(uint16_t *out, const uint8_t *in, size_t len);
71 
72 /** Convert a UTF-8 sequence into a UTF-32 sequence
73  *
74  * Fills the output buffer up to \a len code units.
75  * Returns the number of code units that the input would produce;
76  * if it returns greater than \a len, the output has been
77  * truncated.
78  *
79  * @param[out] out Output sequence
80  * @param[in] in Input sequence (null-terminated)
81  * @param[in] len Output length
82  *
83  * @returns number of output code units produced
84  * @returns -1 for error
85  *
86  * @note \a out is not null-terminated
87  */
88 ssize_t utf8_to_utf32(uint32_t *out, const uint8_t *in, size_t len);
89 
90 /** Convert a UTF-16 sequence into a UTF-8 sequence
91  *
92  * Fills the output buffer up to \a len code units.
93  * Returns the number of code units that the input would produce;
94  * if it returns greater than \a len, the output has been
95  * truncated.
96  *
97  * @param[out] out Output sequence
98  * @param[in] in Input sequence (null-terminated)
99  * @param[in] len Output length
100  *
101  * @returns number of output code units produced
102  * @returns -1 for error
103  *
104  * @note \a out is not null-terminated
105  */
106 ssize_t utf16_to_utf8(uint8_t *out, const uint16_t *in, size_t len);
107 
108 /** Convert a UTF-16 sequence into a UTF-32 sequence
109  *
110  * Fills the output buffer up to \a len code units.
111  * Returns the number of code units that the input would produce;
112  * if it returns greater than \a len, the output has been
113  * truncated.
114  *
115  * @param[out] out Output sequence
116  * @param[in] in Input sequence (null-terminated)
117  * @param[in] len Output length
118  *
119  * @returns number of output code units produced
120  * @returns -1 for error
121  *
122  * @note \a out is not null-terminated
123  */
124 ssize_t utf16_to_utf32(uint32_t *out, const uint16_t *in, size_t len);
125 
126 /** Convert a UTF-32 sequence into a UTF-8 sequence
127  *
128  * Fills the output buffer up to \a len code units.
129  * Returns the number of code units that the input would produce;
130  * if it returns greater than \a len, the output has been
131  * truncated.
132  *
133  * @param[out] out Output sequence
134  * @param[in] in Input sequence (null-terminated)
135  * @param[in] len Output length
136  *
137  * @returns number of output code units produced
138  * @returns -1 for error
139  *
140  * @note \a out is not null-terminated
141  */
142 ssize_t utf32_to_utf8(uint8_t *out, const uint32_t *in, size_t len);
143 
144 /** Convert a UTF-32 sequence into a UTF-16 sequence
145  *
146  * @param[out] out Output sequence
147  * @param[in] in Input sequence (null-terminated)
148  * @param[in] len Output length
149  *
150  * @returns number of output code units produced
151  * @returns -1 for error
152  *
153  * @note \a out is not null-terminated
154  */
155 ssize_t utf32_to_utf16(uint16_t *out, const uint32_t *in, size_t len);
ssize_t encode_utf16(uint16_t *out, uint32_t in)
Convert a UTF-32 codepoint into a UTF-16 sequence.
ssize_t utf8_to_utf16(uint16_t *out, const uint8_t *in, size_t len)
Convert a UTF-8 sequence into a UTF-16 sequence.
ssize_t utf16_to_utf8(uint8_t *out, const uint16_t *in, size_t len)
Convert a UTF-16 sequence into a UTF-8 sequence.
ssize_t decode_utf16(uint32_t *out, const uint16_t *in)
Convert a UTF-16 sequence into a UTF-32 codepoint.
ssize_t decode_utf8(uint32_t *out, const uint8_t *in)
Convert a UTF-8 sequence into a UTF-32 codepoint.
ssize_t utf32_to_utf8(uint8_t *out, const uint32_t *in, size_t len)
Convert a UTF-32 sequence into a UTF-8 sequence.
ssize_t utf8_to_utf32(uint32_t *out, const uint8_t *in, size_t len)
Convert a UTF-8 sequence into a UTF-32 sequence.
ssize_t utf16_to_utf32(uint32_t *out, const uint16_t *in, size_t len)
Convert a UTF-16 sequence into a UTF-32 sequence.
ssize_t utf32_to_utf16(uint16_t *out, const uint32_t *in, size_t len)
Convert a UTF-32 sequence into a UTF-16 sequence.
ssize_t encode_utf8(uint8_t *out, uint32_t in)
Convert a UTF-32 codepoint into a UTF-8 sequence.