1/* 2 * fontconfig/doc/fccharset.fncs 3 * 4 * Copyright © 2003 Keith Packard 5 * 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. 15 * 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. 23 */ 24@RET@ FcCharSet * 25@FUNC@ FcCharSetCreate 26@TYPE1@ void 27@PURPOSE@ Create an empty character set 28@DESC@ 29<function>FcCharSetCreate</function> allocates and initializes a new empty 30character set object. 31@@ 32 33@RET@ void 34@FUNC@ FcCharSetDestroy 35@TYPE1@ FcCharSet * @ARG1@ fcs 36@PURPOSE@ Destroy a character set 37@DESC@ 38<function>FcCharSetDestroy</function> decrements the reference count 39<parameter>fcs</parameter>. If the reference count becomes zero, all 40memory referenced is freed. 41@@ 42 43@RET@ FcBool 44@FUNC@ FcCharSetAddChar 45@TYPE1@ FcCharSet * @ARG1@ fcs 46@TYPE2@ FcChar32% @ARG2@ ucs4 47@PURPOSE@ Add a character to a charset 48@DESC@ 49<function>FcCharSetAddChar</function> adds a single Unicode char to the set, 50returning FcFalse on failure, either as a result of a constant set or from 51running out of memory. 52@@ 53 54@RET@ FcBool 55@FUNC@ FcCharSetDelChar 56@TYPE1@ FcCharSet * @ARG1@ fcs 57@TYPE2@ FcChar32% @ARG2@ ucs4 58@PURPOSE@ Delete a character from a charset 59@DESC@ 60<function>FcCharSetDelChar</function> deletes a single Unicode char from the set, 61returning FcFalse on failure, either as a result of a constant set or from 62running out of memory. 63@SINCE@ 2.9.0 64@@ 65 66@RET@ FcCharSet * 67@FUNC@ FcCharSetCopy 68@TYPE1@ FcCharSet * @ARG1@ src 69@PURPOSE@ Copy a charset 70@DESC@ 71Makes a copy of <parameter>src</parameter>; note that this may not actually do anything more 72than increment the reference count on <parameter>src</parameter>. 73@@ 74 75@RET@ FcBool 76@FUNC@ FcCharSetEqual 77@TYPE1@ const FcCharSet * @ARG1@ a 78@TYPE2@ const FcCharSet * @ARG2@ b 79@PURPOSE@ Compare two charsets 80@DESC@ 81Returns whether <parameter>a</parameter> and <parameter>b</parameter> 82contain the same set of Unicode chars. 83@@ 84 85@RET@ FcCharSet * 86@FUNC@ FcCharSetIntersect 87@TYPE1@ const FcCharSet * @ARG1@ a 88@TYPE2@ const FcCharSet * @ARG2@ b 89@PURPOSE@ Intersect charsets 90@DESC@ 91Returns a set including only those chars found in both 92<parameter>a</parameter> and <parameter>b</parameter>. 93@@ 94 95@RET@ FcCharSet * 96@FUNC@ FcCharSetUnion 97@TYPE1@ const FcCharSet * @ARG1@ a 98@TYPE2@ const FcCharSet * @ARG2@ b 99@PURPOSE@ Add charsets 100@DESC@ 101Returns a set including only those chars found in either <parameter>a</parameter> or <parameter>b</parameter>. 102@@ 103 104@RET@ FcCharSet * 105@FUNC@ FcCharSetSubtract 106@TYPE1@ const FcCharSet * @ARG1@ a 107@TYPE2@ const FcCharSet * @ARG2@ b 108@PURPOSE@ Subtract charsets 109@DESC@ 110Returns a set including only those chars found in <parameter>a</parameter> but not <parameter>b</parameter>. 111@@ 112 113@RET@ FcBool 114@FUNC@ FcCharSetMerge 115@TYPE1@ FcCharSet * @ARG1@ a 116@TYPE2@ const FcCharSet * @ARG2@ b 117@TYPE3@ FcBool * @ARG3@ changed 118@PURPOSE@ Merge charsets 119@DESC@ 120Adds all chars in <parameter>b</parameter> to <parameter>a</parameter>. 121In other words, this is an in-place version of FcCharSetUnion. 122If <parameter>changed</parameter> is not NULL, then it returns whether any new 123chars from <parameter>b</parameter> were added to <parameter>a</parameter>. 124Returns FcFalse on failure, either when <parameter>a</parameter> is a constant 125set or from running out of memory. 126@@ 127 128@RET@ FcBool 129@FUNC@ FcCharSetHasChar 130@TYPE1@ const FcCharSet * @ARG1@ fcs 131@TYPE2@ FcChar32% @ARG2@ ucs4 132@PURPOSE@ Check a charset for a char 133@DESC@ 134Returns whether <parameter>fcs</parameter> contains the char <parameter>ucs4</parameter>. 135@@ 136 137@RET@ FcChar32 138@FUNC@ FcCharSetCount 139@TYPE1@ const FcCharSet * @ARG1@ a 140@PURPOSE@ Count entries in a charset 141@DESC@ 142Returns the total number of Unicode chars in <parameter>a</parameter>. 143@@ 144 145@RET@ FcChar32 146@FUNC@ FcCharSetIntersectCount 147@TYPE1@ const FcCharSet * @ARG1@ a 148@TYPE2@ const FcCharSet * @ARG2@ b 149@PURPOSE@ Intersect and count charsets 150@DESC@ 151Returns the number of chars that are in both <parameter>a</parameter> and <parameter>b</parameter>. 152@@ 153 154@RET@ FcChar32 155@FUNC@ FcCharSetSubtractCount 156@TYPE1@ const FcCharSet * @ARG1@ a 157@TYPE2@ const FcCharSet * @ARG2@ b 158@PURPOSE@ Subtract and count charsets 159@DESC@ 160Returns the number of chars that are in <parameter>a</parameter> but not in <parameter>b</parameter>. 161@@ 162 163@RET@ FcBool 164@FUNC@ FcCharSetIsSubset 165@TYPE1@ const FcCharSet * @ARG1@ a 166@TYPE2@ const FcCharSet * @ARG2@ b 167@PURPOSE@ Test for charset inclusion 168@DESC@ 169Returns whether <parameter>a</parameter> is a subset of <parameter>b</parameter>. 170@@ 171 172@RET@ FcChar32 173@FUNC@ FcCharSetFirstPage 174@TYPE1@ const FcCharSet * @ARG1@ a 175@TYPE2@ FcChar32[FC_CHARSET_MAP_SIZE]% @ARG2@ map 176@TYPE3@ FcChar32 * @ARG3@ next 177@PURPOSE@ Start enumerating charset contents 178@DESC@ 179Builds an array of bits in <parameter>map</parameter> marking the 180first page of Unicode coverage of <parameter>a</parameter>. 181<parameter>*next</parameter> is set to contains the base code point 182for the next page in <parameter>a</parameter>. Returns the base code 183point for the page, or <constant>FC_CHARSET_DONE</constant> if 184<parameter>a</parameter> contains no pages. As an example, if 185<function>FcCharSetFirstPage</function> returns 186<literal>0x300</literal> and fills <parameter>map</parameter> with 187<literallayout class="monospaced"> 1880xffffffff 0xffffffff 0x01000008 0x44300002 0xffffd7f0 0xfffffffb 0xffff7fff 0xffff0003 189</literallayout> 190Then the page contains code points <literal>0x300</literal> through 191<literal>0x33f</literal> (the first 64 code points on the page) 192because <parameter>map[0]</parameter> and 193<parameter>map[1]</parameter> both have all their bits set. It also 194contains code points <literal>0x343</literal> (<parameter>0x300 + 32*2 195+ (4-1)</parameter>) and <literal>0x35e</literal> (<parameter>0x300 + 19632*2 + (31-1)</parameter>) because <parameter>map[2]</parameter> has 197the 4th and 31st bits set. The code points represented by 198<literal>map[3]</literal> and later are left as an exercise for the 199reader ;). 200@@ 201 202@RET@ FcChar32 203@FUNC@ FcCharSetNextPage 204@TYPE1@ const FcCharSet * @ARG1@ a 205@TYPE2@ FcChar32[FC_CHARSET_MAP_SIZE]% @ARG2@ map 206@TYPE3@ FcChar32 * @ARG3@ next 207@PURPOSE@ Continue enumerating charset contents 208@DESC@ 209Builds an array of bits in <parameter>map</parameter> marking the 210Unicode coverage of <parameter>a</parameter> for page containing 211<parameter>*next</parameter> (see the 212<function>FcCharSetFirstPage</function> description for details). 213<parameter>*next</parameter> is set to contains the base code point 214for the next page in <parameter>a</parameter>. Returns the base of 215code point for the page, or <constant>FC_CHARSET_DONE</constant> if 216<parameter>a</parameter> does not contain 217<parameter>*next</parameter>. 218@@ 219 220@RET@ FcChar32 221@FUNC@ FcCharSetCoverage 222@TYPE1@ const FcCharSet * @ARG1@ a 223@TYPE2@ FcChar32 @ARG2@ page 224@TYPE3@ FcChar32[8] @ARG3@ result 225@PURPOSE@ DEPRECATED return coverage for a Unicode page 226@DESC@ 227DEPRECATED 228This function returns a bitmask in <parameter>result</parameter> which 229indicates which code points in 230<parameter>page</parameter> are included in <parameter>a</parameter>. 231<function>FcCharSetCoverage</function> returns the next page in the charset which has any 232coverage. 233@@ 234 235@RET@ FcCharSet * 236@FUNC@ FcCharSetNew 237@TYPE1@ void 238@PURPOSE@ DEPRECATED alias for FcCharSetCreate 239@DESC@ 240<function>FcCharSetNew</function> is a DEPRECATED alias for FcCharSetCreate. 241@@ 242 243