2 * fontconfig/doc/fccharset.fncs
4 * Copyright © 2003 Keith Packard
6 * Permission to use, copy, modify, distribute, and sell this software and its
7 * documentation for any purpose is hereby granted without fee, provided that
8 * the above copyright notice appear in all copies and that both that
9 * copyright notice and this permission notice appear in supporting
10 * documentation, and that the name of the author(s) not be used in
11 * advertising or publicity pertaining to distribution of the software without
12 * specific, written prior permission. The authors make no
13 * representations about the suitability of this software for any purpose. It
14 * is provided "as is" without express or implied warranty.
16 * THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
17 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
18 * EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
19 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
20 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
21 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
22 * PERFORMANCE OF THIS SOFTWARE.
25 @FUNC@ FcCharSetCreate
27 @PURPOSE@ Create an empty character set
29 <function>FcCharSetCreate</function> allocates and initializes a new empty
34 @FUNC@ FcCharSetDestroy
35 @TYPE1@ FcCharSet * @ARG1@ fcs
36 @PURPOSE@ Destroy a character set
38 <function>FcCharSetDestroy</function> decrements the reference count
39 <parameter>fcs</parameter>. If the reference count becomes zero, all
40 memory referenced is freed.
44 @FUNC@ FcCharSetAddChar
45 @TYPE1@ FcCharSet * @ARG1@ fcs
46 @TYPE2@ FcChar32% @ARG2@ ucs4
47 @PURPOSE@ Add a character to a charset
49 <function>FcCharSetAddChar</function> adds a single Unicode char to the set,
50 returning FcFalse on failure, either as a result of a constant set or from
51 running out of memory.
55 @FUNC@ FcCharSetDelChar
56 @TYPE1@ FcCharSet * @ARG1@ fcs
57 @TYPE2@ FcChar32% @ARG2@ ucs4
58 @PURPOSE@ Add a character to a charset
60 <function>FcCharSetDelChar</function> deletes a single Unicode char from the set,
61 returning FcFalse on failure, either as a result of a constant set or from
62 running out of memory.
67 @TYPE1@ FcCharSet * @ARG1@ src
68 @PURPOSE@ Copy a charset
70 Makes a copy of <parameter>src</parameter>; note that this may not actually do anything more
71 than increment the reference count on <parameter>src</parameter>.
76 @TYPE1@ const FcCharSet * @ARG1@ a
77 @TYPE2@ const FcCharSet * @ARG2@ b
78 @PURPOSE@ Compare two charsets
80 Returns whether <parameter>a</parameter> and <parameter>b</parameter>
81 contain the same set of Unicode chars.
85 @FUNC@ FcCharSetIntersect
86 @TYPE1@ const FcCharSet * @ARG1@ a
87 @TYPE2@ const FcCharSet * @ARG2@ b
88 @PURPOSE@ Intersect charsets
90 Returns a set including only those chars found in both
91 <parameter>a</parameter> and <parameter>b</parameter>.
96 @TYPE1@ const FcCharSet * @ARG1@ a
97 @TYPE2@ const FcCharSet * @ARG2@ b
98 @PURPOSE@ Add charsets
100 Returns a set including only those chars found in either <parameter>a</parameter> or <parameter>b</parameter>.
104 @FUNC@ FcCharSetSubtract
105 @TYPE1@ const FcCharSet * @ARG1@ a
106 @TYPE2@ const FcCharSet * @ARG2@ b
107 @PURPOSE@ Subtract charsets
109 Returns a set including only those chars found in <parameter>a</parameter> but not <parameter>b</parameter>.
113 @FUNC@ FcCharSetMerge
114 @TYPE1@ FcCharSet * @ARG1@ a
115 @TYPE2@ const FcCharSet * @ARG2@ b
116 @TYPE3@ FcBool * @ARG3@ changed
117 @PURPOSE@ Merge charsets
119 Adds all chars in <parameter>b</parameter> to <parameter>a</parameter>.
120 In other words, this is an in-place version of FcCharSetUnion.
121 If <parameter>changed</parameter> is not NULL, then it returns whether any new
122 chars from <parameter>b</parameter> were added to <parameter>a</parameter>.
123 Returns FcFalse on failure, either when <parameter>a</parameter> is a constant
124 set or from running out of memory.
128 @FUNC@ FcCharSetHasChar
129 @TYPE1@ const FcCharSet * @ARG1@ fcs
130 @TYPE2@ FcChar32% @ARG2@ ucs4
131 @PURPOSE@ Check a charset for a char
133 Returns whether <parameter>fcs</parameter> contains the char <parameter>ucs4</parameter>.
137 @FUNC@ FcCharSetCount
138 @TYPE1@ const FcCharSet * @ARG1@ a
139 @PURPOSE@ Count entries in a charset
141 Returns the total number of Unicode chars in <parameter>a</parameter>.
145 @FUNC@ FcCharSetIntersectCount
146 @TYPE1@ const FcCharSet * @ARG1@ a
147 @TYPE2@ const FcCharSet * @ARG2@ b
148 @PURPOSE@ Intersect and count charsets
150 Returns the number of chars that are in both <parameter>a</parameter> and <parameter>b</parameter>.
154 @FUNC@ FcCharSetSubtractCount
155 @TYPE1@ const FcCharSet * @ARG1@ a
156 @TYPE2@ const FcCharSet * @ARG2@ b
157 @PURPOSE@ Subtract and count charsets
159 Returns the number of chars that are in <parameter>a</parameter> but not in <parameter>b</parameter>.
163 @FUNC@ FcCharSetIsSubset
164 @TYPE1@ const FcCharSet * @ARG1@ a
165 @TYPE2@ const FcCharSet * @ARG2@ b
166 @PURPOSE@ Test for charset inclusion
168 Returns whether <parameter>a</parameter> is a subset of <parameter>b</parameter>.
172 @FUNC@ FcCharSetFirstPage
173 @TYPE1@ const FcCharSet * @ARG1@ a
174 @TYPE2@ FcChar32[FC_CHARSET_MAP_SIZE]% @ARG2@ map
175 @TYPE3@ FcChar32 * @ARG3@ next
176 @PURPOSE@ Start enumerating charset contents
178 Builds an array of bits in <parameter>map</parameter> marking the
179 first page of Unicode coverage of <parameter>a</parameter>.
180 <parameter>*next</parameter> is set to contains the base code point
181 for the next page in <parameter>a</parameter>. Returns the base code
182 point for the page, or <constant>FC_CHARSET_DONE</constant> if
183 <parameter>a</parameter> contains no pages. As an example, if
184 <function>FcCharSetFirstPage</function> returns
185 <literal>0x300</literal> and fills <parameter>map</parameter> with
186 <literallayout class="monospaced">
187 0xffffffff 0xffffffff 0x01000008 0x44300002 0xffffd7f0 0xfffffffb 0xffff7fff 0xffff0003
189 Then the page contains code points <literal>0x300</literal> through
190 <literal>0x33f</literal> (the first 64 code points on the page)
191 because <parameter>map[0]</parameter> and
192 <parameter>map[1]</parameter> both have all their bits set. It also
193 contains code points <literal>0x343</literal> (<parameter>0x300 + 32*2
194 + (4-1)</parameter>) and <literal>0x35e</literal> (<parameter>0x300 +
195 32*2 + (31-1)</parameter>) because <parameter>map[2]</parameter> has
196 the 4th and 31st bits set. The code points represented by
197 <literal>map[3]</literal> and later are left as an excercise for the
202 @FUNC@ FcCharSetNextPage
203 @TYPE1@ const FcCharSet * @ARG1@ a
204 @TYPE2@ FcChar32[FC_CHARSET_MAP_SIZE]% @ARG2@ map
205 @TYPE3@ FcChar32 * @ARG3@ next
206 @PURPOSE@ Continue enumerating charset contents
208 Builds an array of bits in <parameter>map</parameter> marking the
209 Unicode coverage of <parameter>a</parameter> for page containing
210 <parameter>*next</parameter> (see the
211 <function>FcCharSetFirstPage</function> description for details).
212 <parameter>*next</parameter> is set to contains the base code point
213 for the next page in <parameter>a</parameter>. Returns the base of
214 code point for the page, or <constant>FC_CHARSET_DONE</constant> if
215 <parameter>a</parameter> does not contain
216 <parameter>*next</parameter>.
220 @FUNC@ FcCharSetCoverage
221 @TYPE1@ const FcCharSet * @ARG1@ a
222 @TYPE2@ FcChar32 @ARG2@ page
223 @TYPE3@ FcChar32[8] @ARG3@ result
224 @PURPOSE@ DEPRECATED return coverage for a Unicode page
227 This function returns a bitmask in <parameter>result</parameter> which
228 indicates which code points in
229 <parameter>page</parameter> are included in <parameter>a</parameter>.
230 <function>FcCharSetCoverage</function> returns the next page in the charset which has any
237 @PURPOSE@ DEPRECATED alias for FcCharSetCreate
239 <function>FcCharSetNew</function> is a DEPRECATED alias for FcCharSetCreate.