1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
|
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="libenca-Charsets-and-Surfaces">
<refmeta>
<refentrytitle role="top_of_page" id="libenca-Charsets-and-Surfaces.top_of_page">Charsets and Surfaces</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBENCA Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Charsets and Surfaces</refname>
<refpurpose>Functions and macros for getting something sensible from <link linkend="EncaEncoding"><type>EncaEncoding</type></link>.</refpurpose>
</refnamediv>
<refsynopsisdiv id="libenca-Charsets-and-Surfaces.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>
<synopsis>
const <link linkend="char">char</link>* <link linkend="enca-charset-name">enca_charset_name</link> (<link linkend="int">int</link> charset,
<link linkend="EncaNameStyle">EncaNameStyle</link> whatname);
const <link linkend="char">char</link>** <link linkend="enca-get-charset-aliases">enca_get_charset_aliases</link> (<link linkend="int">int</link> charset,
<link linkend="size-t">size_t</link> *n);
<link linkend="char">char</link>* <link linkend="enca-get-surface-name">enca_get_surface_name</link> (<link linkend="EncaSurface">EncaSurface</link> surface,
<link linkend="EncaNameStyle">EncaNameStyle</link> whatname);
<link linkend="EncaEncoding">EncaEncoding</link> <link linkend="enca-parse-encoding-name">enca_parse_encoding_name</link> (const <link linkend="char">char</link> *name);
<link linkend="EncaSurface">EncaSurface</link> <link linkend="enca-charset-natural-surface">enca_charset_natural_surface</link> (<link linkend="int">int</link> charset);
<link linkend="EncaCharsetFlags">EncaCharsetFlags</link> <link linkend="enca-charset-properties">enca_charset_properties</link> (<link linkend="int">int</link> charset);
#define <link linkend="enca-charset-is-7bit">enca_charset_is_7bit</link> (cs)
#define <link linkend="enca-charset-is-8bit">enca_charset_is_8bit</link> (cs)
#define <link linkend="enca-charset-is-16bit">enca_charset_is_16bit</link> (cs)
#define <link linkend="enca-charset-is-32bit">enca_charset_is_32bit</link> (cs)
#define <link linkend="enca-charset-is-fixed">enca_charset_is_fixed</link> (cs)
#define <link linkend="enca-charset-is-variable">enca_charset_is_variable</link> (cs)
#define <link linkend="enca-charset-is-binary">enca_charset_is_binary</link> (cs)
#define <link linkend="enca-charset-is-regular">enca_charset_is_regular</link> (cs)
#define <link linkend="enca-charset-is-multibyte">enca_charset_is_multibyte</link> (cs)
#define <link linkend="enca-charset-is-known">enca_charset_is_known</link> (cs)
</synopsis>
</refsynopsisdiv>
<refsect1 id="libenca-Charsets-and-Surfaces.description" role="desc">
<title role="desc.title">Description</title>
<para>
</para>
</refsect1>
<refsect1 id="libenca-Charsets-and-Surfaces.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="enca-charset-name" role="function">
<title>enca_charset_name ()</title>
<indexterm zone="enca-charset-name"><primary sortas="enca_charset_name">enca_charset_name</primary></indexterm><programlisting>const <link linkend="char">char</link>* enca_charset_name (<link linkend="int">int</link> charset,
<link linkend="EncaNameStyle">EncaNameStyle</link> whatname);</programlisting>
<para>
Translates numeric charset id <parameter>charset</parameter> to some kind of name.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>charset</parameter> :</term>
<listitem><simpara> A charset id.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>whatname</parameter> :</term>
<listitem><simpara> Teh type of name you request.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The requested charset name; <link linkend="NULL--CAPS"><type>NULL</type></link> for invalid <parameter>whatname</parameter> or
<parameter>charset</parameter>, or when <parameter>whatname</parameter> name doesn't exist for charset <parameter>charset</parameter>
(<link linkend="ENCA-CS-UNKNOWN--CAPS"><type>ENCA_CS_UNKNOWN</type></link> is OK).
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="enca-get-charset-aliases" role="function">
<title>enca_get_charset_aliases ()</title>
<indexterm zone="enca-get-charset-aliases"><primary sortas="enca_get_charset_aliases">enca_get_charset_aliases</primary></indexterm><programlisting>const <link linkend="char">char</link>** enca_get_charset_aliases (<link linkend="int">int</link> charset,
<link linkend="size-t">size_t</link> *n);</programlisting>
<para>
Returns list of accepted aliases for charset <parameter>charset</parameter>.
</para>
<para>
The list of aliases has to be freed by caller; the strings themselves
must be considered constant and must NOT be freed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>charset</parameter> :</term>
<listitem><simpara> A charset id.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n</parameter> :</term>
<listitem><simpara> The number of aliases will be stored here.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The list of aliases, storing their number into *<parameter>n</parameter>; <link linkend="NULL--CAPS"><type>NULL</type></link> for
invalid <parameter>charset</parameter> (*<parameter>n</parameter> is zero then).
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="enca-get-surface-name" role="function">
<title>enca_get_surface_name ()</title>
<indexterm zone="enca-get-surface-name"><primary sortas="enca_get_surface_name">enca_get_surface_name</primary></indexterm><programlisting><link linkend="char">char</link>* enca_get_surface_name (<link linkend="EncaSurface">EncaSurface</link> surface,
<link linkend="EncaNameStyle">EncaNameStyle</link> whatname);</programlisting>
<para>
Constructs surface name from surface flags <parameter>surface</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> A surface.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>whatname</parameter> :</term>
<listitem><simpara> The type of name you request.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The requested surface name; <link linkend="NULL--CAPS"><type>NULL</type></link> for invalid <parameter>whatname</parameter>; empty
string for naming style not supporting surfaces. In all cases, the
returned string must be freed by caller when no longer used.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="enca-parse-encoding-name" role="function">
<title>enca_parse_encoding_name ()</title>
<indexterm zone="enca-parse-encoding-name"><primary sortas="enca_parse_encoding_name">enca_parse_encoding_name</primary></indexterm><programlisting><link linkend="EncaEncoding">EncaEncoding</link> enca_parse_encoding_name (const <link linkend="char">char</link> *name);</programlisting>
<para>
Transofrms encoding specification charset/surface into numeric <link linkend="EncaEncoding"><type>EncaEncoding</type></link>.
</para>
<para>
When the charset name is not recognized, surfaces are not parsed at all and
<link linkend="ENCA-CS-UNKNOWN--CAPS"><type>ENCA_CS_UNKNOWN</type></link> is returned as charset. However, unrecognized surfaces are
considered only a minor problem causing <link linkend="ENCA-SURFACE-UNKNOWN--CAPS"><literal>ENCA_SURFACE_UNKNOWN</literal></link> flag to be
set in the result, beside recognized surface flags.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>name</parameter> :</term>
<listitem><simpara> An encoding specification.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The charset/surface pair.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="enca-charset-natural-surface" role="function">
<title>enca_charset_natural_surface ()</title>
<indexterm zone="enca-charset-natural-surface"><primary sortas="enca_charset_natural_surface">enca_charset_natural_surface</primary></indexterm><programlisting><link linkend="EncaSurface">EncaSurface</link> enca_charset_natural_surface (<link linkend="int">int</link> charset);</programlisting>
<para>
Returns natural surface of a charset.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>charset</parameter> :</term>
<listitem><simpara> A charset.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The requested charset natural surface (called `implied' in recode),
zero for invalid <parameter>charset</parameter> or for charsets with no natural surface.
Natrual surface is the surface one expects for a given charset --
e.g. CRLF EOLs for IBM/Microsoft charsets, CR EOLs for Macintosh
charsets and LF EOLs for ISO/Unix charsets.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="enca-charset-properties" role="function">
<title>enca_charset_properties ()</title>
<indexterm zone="enca-charset-properties"><primary sortas="enca_charset_properties">enca_charset_properties</primary></indexterm><programlisting><link linkend="EncaCharsetFlags">EncaCharsetFlags</link> enca_charset_properties (<link linkend="int">int</link> charset);</programlisting>
<para>
Returns charset properties.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>charset</parameter> :</term>
<listitem><simpara> A charset.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The requested charset properties; zero for invalid <parameter>charset</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="enca-charset-is-7bit" role="macro">
<title>enca_charset_is_7bit()</title>
<indexterm zone="enca-charset-is-7bit"><primary sortas="enca_charset_is_7bit">enca_charset_is_7bit</primary></indexterm><programlisting>#define enca_charset_is_7bit(cs)</programlisting>
<para>
Expands to nonzero when characters are represented with 7bit characters.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>cs</parameter> :</term>
<listitem><simpara> Charset id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="enca-charset-is-8bit" role="macro">
<title>enca_charset_is_8bit()</title>
<indexterm zone="enca-charset-is-8bit"><primary sortas="enca_charset_is_8bit">enca_charset_is_8bit</primary></indexterm><programlisting>#define enca_charset_is_8bit(cs)</programlisting>
<para>
Expands to nonzero when characters are represented with bytes.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>cs</parameter> :</term>
<listitem><simpara> Charset id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="enca-charset-is-16bit" role="macro">
<title>enca_charset_is_16bit()</title>
<indexterm zone="enca-charset-is-16bit"><primary sortas="enca_charset_is_16bit">enca_charset_is_16bit</primary></indexterm><programlisting>#define enca_charset_is_16bit(cs)</programlisting>
<para>
Expands to nonzero when characters are represented with 2byte words.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>cs</parameter> :</term>
<listitem><simpara> Charset id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="enca-charset-is-32bit" role="macro">
<title>enca_charset_is_32bit()</title>
<indexterm zone="enca-charset-is-32bit"><primary sortas="enca_charset_is_32bit">enca_charset_is_32bit</primary></indexterm><programlisting>#define enca_charset_is_32bit(cs)</programlisting>
<para>
Expands to nonzero when characters are represented with 4byte words.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>cs</parameter> :</term>
<listitem><simpara> Charset id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="enca-charset-is-fixed" role="macro">
<title>enca_charset_is_fixed()</title>
<indexterm zone="enca-charset-is-fixed"><primary sortas="enca_charset_is_fixed">enca_charset_is_fixed</primary></indexterm><programlisting>#define enca_charset_is_fixed(cs)</programlisting>
<para>
Expands to nonzero when one characters consists of one fundamental piece.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>cs</parameter> :</term>
<listitem><simpara> Charset id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="enca-charset-is-variable" role="macro">
<title>enca_charset_is_variable()</title>
<indexterm zone="enca-charset-is-variable"><primary sortas="enca_charset_is_variable">enca_charset_is_variable</primary></indexterm><programlisting>#define enca_charset_is_variable(cs)</programlisting>
<para>
Expands to nonzero when one character consists of variable number of
fundamental pieces.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>cs</parameter> :</term>
<listitem><simpara> Charset id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="enca-charset-is-binary" role="macro">
<title>enca_charset_is_binary()</title>
<indexterm zone="enca-charset-is-binary"><primary sortas="enca_charset_is_binary">enca_charset_is_binary</primary></indexterm><programlisting>#define enca_charset_is_binary(cs)</programlisting>
<para>
Expands to nonzero when charset is binary from ASCII viewpoint.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>cs</parameter> :</term>
<listitem><simpara> Charset id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="enca-charset-is-regular" role="macro">
<title>enca_charset_is_regular()</title>
<indexterm zone="enca-charset-is-regular"><primary sortas="enca_charset_is_regular">enca_charset_is_regular</primary></indexterm><programlisting>#define enca_charset_is_regular(cs)</programlisting>
<para>
Expands to nonzero when charset is language dependent (8bit) charset.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>cs</parameter> :</term>
<listitem><simpara> Charset id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="enca-charset-is-multibyte" role="macro">
<title>enca_charset_is_multibyte()</title>
<indexterm zone="enca-charset-is-multibyte"><primary sortas="enca_charset_is_multibyte">enca_charset_is_multibyte</primary></indexterm><programlisting>#define enca_charset_is_multibyte(cs)</programlisting>
<para>
Expands to nonzero when charset is multibyte.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>cs</parameter> :</term>
<listitem><simpara> Charset id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="enca-charset-is-known" role="macro">
<title>enca_charset_is_known()</title>
<indexterm zone="enca-charset-is-known"><primary sortas="enca_charset_is_known">enca_charset_is_known</primary></indexterm><programlisting>#define enca_charset_is_known(cs)</programlisting>
<para>
Expands to nonzero when the charset is known (i.e. it's not
ENCA_CS_UNKNOWN).</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>cs</parameter> :</term>
<listitem><simpara> Charset id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
</refentry>
|
