doc/fclangset.fncs

   1 /*
   2  * Copyright © 2007 Keith Packard
   3  *
   4  * Permission to use, copy, modify, distribute, and sell this software and its
   5  * documentation for any purpose is hereby granted without fee, provided that
   6  * the above copyright notice appear in all copies and that both that copyright
   7  * notice and this permission notice appear in supporting documentation, and
   8  * that the name of the copyright holders not be used in advertising or
   9  * publicity pertaining to distribution of the software without specific,
  10  * written prior permission.  The copyright holders make no representations
  11  * about the suitability of this software for any purpose.  It is provided "as
  12  * is" without express or implied warranty.
  13  *
  14  * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  15  * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  16  * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  17  * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
  18  * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  19  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  20  * OF THIS SOFTWARE.
  21  */
  22
  23 @RET@           FcLangSet *
  24 @FUNC@          FcLangSetCreate
  25 @TYPE1@         void
  26 @PURPOSE@       create a langset object
  27 @DESC@
  28 <function>FcLangSetCreate</function> creates a new FcLangSet object.
  29 @@
  30
  31 @RET@           void
  32 @FUNC@          FcLangSetDestroy
  33 @TYPE1@         FcLangSet *                     @ARG1@          ls
  34 @PURPOSE@       destroy a langset object
  35 @DESC@
  36 <function>FcLangSetDestroy</function> destroys a FcLangSet object, freeing
  37 all memory associated with it.
  38 @@
  39
  40 @RET@           FcLangSet *
  41 @FUNC@          FcLangSetCopy
  42 @TYPE1@         const FcLangSet *               @ARG1@          ls
  43 @PURPOSE@       copy a langset object
  44 @DESC@
  45 <function>FcLangSetCopy</function> creates a new FcLangSet object and
  46 populates it with the contents of <parameter>ls</parameter>.
  47 @@
  48
  49 @RET@           FcBool
  50 @FUNC@          FcLangSetAdd
  51 @TYPE1@         FcLangSet *                     @ARG1@          ls
  52 @TYPE2@         const FcChar8 *                 @ARG2@          lang
  53 @PURPOSE@       add a language to a langset
  54 @DESC@
  55 <parameter>lang</parameter> is added to <parameter>ls</parameter>.
  56 <parameter>lang</parameter> should be of the form Ll-Tt where Ll is a
  57 two or three letter language from ISO 639 and Tt is a territory from ISO
  58 3166.
  59 @@
  60
  61 @RET@           FcBool
  62 @FUNC@          FcLangSetDel
  63 @TYPE1@         FcLangSet *                     @ARG1@          ls
  64 @TYPE2@         const FcChar8 *                 @ARG2@          lang
  65 @PURPOSE@       delete a language from a langset
  66 @DESC@
  67 <parameter>lang</parameter> is removed from <parameter>ls</parameter>.
  68 <parameter>lang</parameter> should be of the form Ll-Tt where Ll is a
  69 two or three letter language from ISO 639 and Tt is a territory from ISO
  70 3166.
  71 @SINCE@         2.9.0
  72 @@
  73
  74 @RET@           FcLangSet *
  75 @FUNC@          FcLangSetUnion
  76 @TYPE1@         const FcLangSet *               @ARG1@          ls_a
  77 @TYPE2@         const FcLangSet *               @ARG2@          ls_b
  78 @PURPOSE@       Add langsets
  79 @DESC@
  80 Returns a set including only those languages found in either <parameter>ls_a</parameter> or <parameter>ls_b</parameter>.
  81 @SINCE@         2.9.0
  82 @@
  83
  84 @RET@           FcLangSet *
  85 @FUNC@          FcLangSetSubtract
  86 @TYPE1@         const FcLangSet *               @ARG1@          ls_a
  87 @TYPE2@         const FcLangSet *               @ARG2@          ls_b
  88 @PURPOSE@       Subtract langsets
  89 @DESC@
  90 Returns a set including only those languages found in <parameter>ls_a</parameter> but not in <parameter>ls_b</parameter>.
  91 @SINCE@         2.9.0
  92 @@
  93
  94 @RET@           FcLangResult
  95 @FUNC@          FcLangSetCompare
  96 @TYPE1@         const FcLangSet *               @ARG1@          ls_a
  97 @TYPE2@         const FcLangSet *               @ARG2@          ls_b
  98 @PURPOSE@       compare language sets
  99 @DESC@
 100 <function>FcLangSetCompare</function> compares language coverage for
 101 <parameter>ls_a</parameter> and <parameter>ls_b</parameter>. If they share
 102 any language and territory pair, this function returns FcLangEqual. If they
 103 share a language but differ in which territory that language is for, this
 104 function returns FcLangDifferentTerritory. If they share no languages in
 105 common, this function returns FcLangDifferentLang.
 106 @@
 107
 108 @RET@           FcBool
 109 @FUNC@          FcLangSetContains
 110 @TYPE1@         const FcLangSet *               @ARG1@          ls_a
 111 @TYPE2@         const FcLangSet *               @ARG2@          ls_b
 112 @PURPOSE@       check langset subset relation
 113 @DESC@
 114 <function>FcLangSetContains</function> returns FcTrue if
 115 <parameter>ls_a</parameter> contains every language in
 116 <parameter>ls_b</parameter>. <parameter>ls_a</parameter> will 'contain' a
 117 language from <parameter>ls_b</parameter> if <parameter>ls_a</parameter>
 118 has exactly the language, or either the language or
 119 <parameter>ls_a</parameter> has no territory.
 120 @@
 121
 122 @RET@           FcBool
 123 @FUNC@          FcLangSetEqual
 124 @TYPE1@         const FcLangSet *               @ARG1@          ls_a
 125 @TYPE2@         const FcLangSet *               @ARG2@          ls_b
 126 @PURPOSE@       test for matching langsets
 127 @DESC@
 128 Returns FcTrue if and only if <parameter>ls_a</parameter> supports precisely
 129 the same language and territory combinations as <parameter>ls_b</parameter>.
 130 @@
 131
 132 @RET@           FcChar32
 133 @FUNC@          FcLangSetHash
 134 @TYPE1@         const FcLangSet *               @ARG1@          ls
 135 @PURPOSE@       return a hash value for a langset
 136 @DESC@
 137 This function returns a value which depends solely on the languages
 138 supported by <parameter>ls</parameter>. Any language which equals
 139 <parameter>ls</parameter> will have the same result from
 140 <function>FcLangSetHash</function>. However, two langsets with the same hash
 141 value may not be equal.
 142 @@
 143
 144 @RET@           FcLangResult
 145 @FUNC@          FcLangSetHasLang
 146 @TYPE1@         const FcLangSet *               @ARG1@          ls
 147 @TYPE2@         const FcChar8 *                 @ARG2@          lang
 148 @PURPOSE@       test langset for language support
 149 @DESC@
 150 <function>FcLangSetHasLang</function> checks whether
 151 <parameter>ls</parameter> supports <parameter>lang</parameter>. If
 152 <parameter>ls</parameter> has a matching language and territory pair,
 153 this function returns FcLangEqual. If <parameter>ls</parameter> has
 154 a matching language but differs in which territory that language is for, this
 155 function returns FcLangDifferentTerritory. If <parameter>ls</parameter>
 156 has no matching language, this function returns FcLangDifferentLang.
 157 @@
 158
 159 @RET@           FcStrSet *
 160 @FUNC@          FcGetDefaultLangs
 161 @TYPE1@         void
 162 @PURPOSE@       Get the default languages list
 163 @DESC@
 164 Returns a string set of the default languages according to the environment variables on the system.
 165 This function looks for them in order of FC_LANG, LC_ALL, LC_CTYPE and LANG then.
 166 If there are no valid values in those environment variables, "en" will be set as fallback.
 167 @SINCE@         2.9.91
 168 @@
 169
 170 @RET@           FcStrSet *
 171 @FUNC@          FcLangSetGetLangs
 172 @TYPE1@         const FcLangSet *               @ARG1@          ls
 173 @PURPOSE@       get the list of languages in the langset
 174 @DESC@
 175 Returns a string set of all languages in <parameter>langset</parameter>.
 176 @@
 177
 178 @RET@           FcStrSet *
 179 @FUNC@          FcGetLangs
 180 @TYPE1@         void
 181 @PURPOSE@       Get list of languages
 182 @DESC@
 183 Returns a string set of all known languages.
 184 @@
 185
 186 @RET@           FcChar8 *
 187 @FUNC@          FcLangNormalize
 188 @TYPE1@         const FcChar8 *                 @ARG1@          lang
 189 @PURPOSE@       Normalize the language string
 190 @DESC@
 191 Returns a string to make <parameter>lang</parameter> suitable on fontconfig.
 192 @SINCE@         2.10.91
 193 @@
 194
 195 @RET@           const FcCharSet *
 196 @FUNC@          FcLangGetCharSet
 197 @TYPE1@         const FcChar8 *                 @ARG1@          lang
 198 @PURPOSE@       Get character map for a language
 199 @DESC@
 200 Returns the FcCharMap for a language.
 201 @@