2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4
<refentry id="libidn-punycode">
6
<refentrytitle role="top_of_page" id="libidn-punycode.top_of_page">punycode</refentrytitle>
7
<manvolnum>3</manvolnum>
8
<refmiscinfo>LIBIDN Library</refmiscinfo>
12
<refname>punycode</refname>
13
<refpurpose></refpurpose>
16
<refsynopsisdiv id="libidn-punycode.synopsis" role="synopsis">
17
<title role="synopsis.title">Synopsis</title>
20
#define <link linkend="IDNAPI--CAPS">IDNAPI</link>
21
enum <link linkend="Punycode-status">Punycode_status</link>;
22
const <link linkend="char">char</link> * <link linkend="punycode-strerror">punycode_strerror</link> (<link linkend="Punycode-status">Punycode_status</link> rc);
23
typedef <link linkend="punycode-uint">punycode_uint</link>;
24
<link linkend="int">int</link> <link linkend="punycode-encode">punycode_encode</link> (<link linkend="size-t">size_t</link> input_length,
25
const <link linkend="punycode-uint">punycode_uint</link> input[],
26
unsigned <link linkend="char">char</link> case_flags[],
27
<link linkend="size-t">size_t</link> *output_length,
28
<link linkend="char">char</link> output[]);
29
<link linkend="int">int</link> <link linkend="punycode-decode">punycode_decode</link> (<link linkend="size-t">size_t</link> input_length,
30
const <link linkend="char">char</link> input[],
31
<link linkend="size-t">size_t</link> *output_length,
32
<link linkend="punycode-uint">punycode_uint</link> output[],
33
unsigned <link linkend="char">char</link> case_flags[]);
45
<refsect1 id="libidn-punycode.description" role="desc">
46
<title role="desc.title">Description</title>
51
<refsect1 id="libidn-punycode.details" role="details">
52
<title role="details.title">Details</title>
53
<refsect2 id="IDNAPI--CAPS" role="macro">
55
<indexterm zone="IDNAPI--CAPS"><primary sortas="IDNAPI">IDNAPI</primary></indexterm><programlisting>#define IDNAPI</programlisting>
58
<refsect2 id="Punycode-status" role="enum">
59
<title>enum Punycode_status</title>
60
<indexterm zone="Punycode-status"><primary sortas="Punycode_status">Punycode_status</primary></indexterm><programlisting> typedef enum
62
PUNYCODE_SUCCESS = punycode_success,
63
PUNYCODE_BAD_INPUT = punycode_bad_input,
64
PUNYCODE_BIG_OUTPUT = punycode_big_output,
65
PUNYCODE_OVERFLOW = punycode_overflow
69
Enumerated return codes of <link linkend="punycode-encode"><function>punycode_encode()</function></link> and <link linkend="punycode-decode"><function>punycode_decode()</function></link>.
70
The value 0 is guaranteed to always correspond to success.</para>
72
</para><variablelist role="enum">
73
<varlistentry id="PUNYCODE-SUCCESS--CAPS" role="constant">
74
<term><literal>PUNYCODE_SUCCESS</literal></term>
75
<listitem><simpara> Successful operation. This value is guaranteed
76
to always be zero, the remaining ones are only guaranteed to hold
77
non-zero values, for logical comparison purposes.
80
<varlistentry id="PUNYCODE-BAD-INPUT--CAPS" role="constant">
81
<term><literal>PUNYCODE_BAD_INPUT</literal></term>
82
<listitem><simpara> Input is invalid.
85
<varlistentry id="PUNYCODE-BIG-OUTPUT--CAPS" role="constant">
86
<term><literal>PUNYCODE_BIG_OUTPUT</literal></term>
87
<listitem><simpara> Output would exceed the space provided.
90
<varlistentry id="PUNYCODE-OVERFLOW--CAPS" role="constant">
91
<term><literal>PUNYCODE_OVERFLOW</literal></term>
92
<listitem><simpara> Input needs wider integers to process.
95
</variablelist></refsect2>
96
<refsect2 id="punycode-strerror" role="function">
97
<title>punycode_strerror ()</title>
98
<indexterm zone="punycode-strerror"><primary sortas="punycode_strerror">punycode_strerror</primary></indexterm><programlisting>const <link linkend="char">char</link> * punycode_strerror (<link linkend="Punycode-status">Punycode_status</link> rc);</programlisting>
100
Convert a return code integer to a text string. This string can be
101
used to output a diagnostic message to the user.
104
PUNYCODE_SUCCESS: Successful operation. This value is guaranteed
105
to always be zero, the remaining ones are only guaranteed to hold
106
non-zero values, for logical comparison purposes.
107
PUNYCODE_BAD_INPUT: Input is invalid.
108
PUNYCODE_BIG_OUTPUT: Output would exceed the space provided.
109
PUNYCODE_OVERFLOW: Input needs wider integers to process.</para>
111
</para><variablelist role="params">
112
<varlistentry><term><parameter>rc</parameter> :</term>
113
<listitem><simpara> an <link linkend="Punycode-status"><type>Punycode_status</type></link> return code.
114
</simpara></listitem></varlistentry>
115
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Returns a pointer to a statically allocated string
116
containing a description of the error with the return code <parameter>rc</parameter>.
117
</simpara></listitem></varlistentry>
118
</variablelist></refsect2>
119
<refsect2 id="punycode-uint" role="typedef">
120
<title>punycode_uint</title>
121
<indexterm zone="punycode-uint"><primary sortas="punycode_uint">punycode_uint</primary></indexterm><programlisting> typedef uint32_t punycode_uint;
124
Unicode code point data type, this is always a 32 bit unsigned
128
<refsect2 id="punycode-encode" role="function">
129
<title>punycode_encode ()</title>
130
<indexterm zone="punycode-encode"><primary sortas="punycode_encode">punycode_encode</primary></indexterm><programlisting><link linkend="int">int</link> punycode_encode (<link linkend="size-t">size_t</link> input_length,
131
const <link linkend="punycode-uint">punycode_uint</link> input[],
132
unsigned <link linkend="char">char</link> case_flags[],
133
<link linkend="size-t">size_t</link> *output_length,
134
<link linkend="char">char</link> output[]);</programlisting>
136
Converts a sequence of code points (presumed to be Unicode code
137
points) to Punycode.</para>
139
</para><variablelist role="params">
140
<varlistentry><term><parameter>input_length</parameter> :</term>
141
<listitem><simpara> The number of code points in the <parameter>input</parameter> array and
142
the number of flags in the <parameter>case_flags</parameter> array.
143
</simpara></listitem></varlistentry>
144
<varlistentry><term><parameter>input</parameter> :</term>
145
<listitem><simpara> An array of code points. They are presumed to be Unicode
146
code points, but that is not strictly REQUIRED. The array
147
contains code points, not code units. UTF-16 uses code units
148
D800 through DFFF to refer to code points 10000..10FFFF. The
149
code points D800..DFFF do not occur in any valid Unicode string.
150
The code points that can occur in Unicode strings (0..D7FF and
151
E000..10FFFF) are also called Unicode scalar values.
152
</simpara></listitem></varlistentry>
153
<varlistentry><term><parameter>case_flags</parameter> :</term>
154
<listitem><simpara> A <link linkend="NULL--CAPS"><literal>NULL</literal></link> pointer or an array of boolean values parallel
155
to the <parameter>input</parameter> array. Nonzero (true, flagged) suggests that the
156
corresponding Unicode character be forced to uppercase after
157
being decoded (if possible), and zero (false, unflagged) suggests
158
that it be forced to lowercase (if possible). ASCII code points
159
(0..7F) are encoded literally, except that ASCII letters are
160
forced to uppercase or lowercase according to the corresponding
161
case flags. If <parameter>case_flags</parameter> is a <link linkend="NULL--CAPS"><literal>NULL</literal></link> pointer then ASCII letters
162
are left as they are, and other code points are treated as
164
</simpara></listitem></varlistentry>
165
<varlistentry><term><parameter>output_length</parameter> :</term>
166
<listitem><simpara> The caller passes in the maximum number of ASCII
167
code points that it can receive. On successful return it will
168
contain the number of ASCII code points actually output.
169
</simpara></listitem></varlistentry>
170
<varlistentry><term><parameter>output</parameter> :</term>
171
<listitem><simpara> An array of ASCII code points. It is *not*
172
null-terminated; it will contain zeros if and only if the <parameter>input</parameter>
173
contains zeros. (Of course the caller can leave room for a
174
terminator and add one if needed.)
175
</simpara></listitem></varlistentry>
176
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The return value can be any of the <link linkend="Punycode-status"><type>Punycode_status</type></link>
177
values defined above except <link linkend="PUNYCODE-BAD-INPUT--CAPS"><literal>PUNYCODE_BAD_INPUT</literal></link>. If not
178
<link linkend="PUNYCODE-SUCCESS--CAPS"><literal>PUNYCODE_SUCCESS</literal></link>, then <parameter>output_size</parameter> and <parameter>output</parameter> might contain
180
</simpara></listitem></varlistentry>
181
</variablelist></refsect2>
182
<refsect2 id="punycode-decode" role="function">
183
<title>punycode_decode ()</title>
184
<indexterm zone="punycode-decode"><primary sortas="punycode_decode">punycode_decode</primary></indexterm><programlisting><link linkend="int">int</link> punycode_decode (<link linkend="size-t">size_t</link> input_length,
185
const <link linkend="char">char</link> input[],
186
<link linkend="size-t">size_t</link> *output_length,
187
<link linkend="punycode-uint">punycode_uint</link> output[],
188
unsigned <link linkend="char">char</link> case_flags[]);</programlisting>
190
Converts Punycode to a sequence of code points (presumed to be
191
Unicode code points).</para>
193
</para><variablelist role="params">
194
<varlistentry><term><parameter>input_length</parameter> :</term>
195
<listitem><simpara> The number of ASCII code points in the <parameter>input</parameter> array.
196
</simpara></listitem></varlistentry>
197
<varlistentry><term><parameter>input</parameter> :</term>
198
<listitem><simpara> An array of ASCII code points (0..7F).
199
</simpara></listitem></varlistentry>
200
<varlistentry><term><parameter>output_length</parameter> :</term>
201
<listitem><simpara> The caller passes in the maximum number of code
202
points that it can receive into the <parameter>output</parameter> array (which is also
203
the maximum number of flags that it can receive into the
204
<parameter>case_flags</parameter> array, if <parameter>case_flags</parameter> is not a <link linkend="NULL--CAPS"><literal>NULL</literal></link> pointer). On
205
successful return it will contain the number of code points
206
actually output (which is also the number of flags actually
207
output, if case_flags is not a null pointer). The decoder will
208
never need to output more code points than the number of ASCII
209
code points in the input, because of the way the encoding is
210
defined. The number of code points output cannot exceed the
211
maximum possible value of a punycode_uint, even if the supplied
212
<parameter>output_length</parameter> is greater than that.
213
</simpara></listitem></varlistentry>
214
<varlistentry><term><parameter>output</parameter> :</term>
215
<listitem><simpara> An array of code points like the input argument of
216
<link linkend="punycode-encode"><function>punycode_encode()</function></link> (see above).
217
</simpara></listitem></varlistentry>
218
<varlistentry><term><parameter>case_flags</parameter> :</term>
219
<listitem><simpara> A <link linkend="NULL--CAPS"><literal>NULL</literal></link> pointer (if the flags are not needed by the
220
caller) or an array of boolean values parallel to the <parameter>output</parameter>
221
array. Nonzero (true, flagged) suggests that the corresponding
222
Unicode character be forced to uppercase by the caller (if
223
possible), and zero (false, unflagged) suggests that it be forced
224
to lowercase (if possible). ASCII code points (0..7F) are output
225
already in the proper case, but their flags will be set
226
appropriately so that applying the flags would be harmless.
227
</simpara></listitem></varlistentry>
228
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The return value can be any of the <link linkend="Punycode-status"><type>Punycode_status</type></link>
229
values defined above. If not <link linkend="PUNYCODE-SUCCESS--CAPS"><literal>PUNYCODE_SUCCESS</literal></link>, then
230
<parameter>output_length</parameter>, <parameter>output</parameter>, and <parameter>case_flags</parameter> might contain garbage.
232
</simpara></listitem></varlistentry>
233
</variablelist></refsect2>
added
removed
doc/reference/xml/punycode.xml
