doc/fccharset.fncs

   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
  30 character 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
  40 memory 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,
  50 returning FcFalse on failure, either as a result of a constant set or from
  51 running out of memory.
  52 @@
  53
  54 @RET@           FcBool
  55 @FUNC@          FcCharSetDelChar
  56 @TYPE1@         FcCharSet *             @ARG1@          fcs
  57 @TYPE2@         FcChar32%               @ARG2@          ucs4
  58 @PURPOSE@       Add a character to a charset
  59 @DESC@
  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.
  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@
  71 Makes a copy of <parameter>src</parameter>; note that this may not actually do anything more
  72 than 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@
  81 Returns whether <parameter>a</parameter> and <parameter>b</parameter>
  82 contain 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@
  91 Returns 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@
 101 Returns 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@
 110 Returns 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@
 120 Adds all chars in <parameter>b</parameter> to <parameter>a</parameter>.
 121 In other words, this is an in-place version of FcCharSetUnion.
 122 If <parameter>changed</parameter> is not NULL, then it returns whether any new
 123 chars from <parameter>b</parameter> were added to <parameter>a</parameter>.
 124 Returns FcFalse on failure, either when <parameter>a</parameter> is a constant
 125 set 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@
 134 Returns 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@
 142 Returns 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@
 151 Returns 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@
 160 Returns 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@
 169 Returns 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@
 179 Builds an array of bits in <parameter>map</parameter> marking the
 180 first page of Unicode coverage of <parameter>a</parameter>.
 181 <parameter>*next</parameter> is set to contains the base code point
 182 for the next page in <parameter>a</parameter>.  Returns the base code
 183 point 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">
 188 0xffffffff 0xffffffff 0x01000008 0x44300002 0xffffd7f0 0xfffffffb 0xffff7fff 0xffff0003
 189 </literallayout>
 190 Then the page contains code points <literal>0x300</literal> through
 191 <literal>0x33f</literal> (the first 64 code points on the page)
 192 because <parameter>map[0]</parameter> and
 193 <parameter>map[1]</parameter> both have all their bits set.  It also
 194 contains code points <literal>0x343</literal> (<parameter>0x300 + 32*2
 195 + (4-1)</parameter>) and <literal>0x35e</literal> (<parameter>0x300 +
 196 32*2 + (31-1)</parameter>) because <parameter>map[2]</parameter> has
 197 the 4th and 31st bits set.  The code points represented by
 198 <literal>map[3]</literal> and later are left as an excercise for the
 199 reader ;).
 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@
 209 Builds an array of bits in <parameter>map</parameter> marking the
 210 Unicode 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
 214 for the next page in <parameter>a</parameter>.  Returns the base of
 215 code 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@
 227 DEPRECATED
 228 This function returns a bitmask in <parameter>result</parameter> which
 229 indicates 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
 232 coverage.
 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