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