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 @@
  72
  73 @RET@           FcLangSet *
  74 @FUNC@          FcLangSetUnion
  75 @TYPE1@         const FcLangSet *               @ARG1@          ls_a
  76 @TYPE2@         const FcLangSet *               @ARG2@          ls_b
  77 @PURPOSE@       Add langsets
  78 @DESC@
  79 Returns a set including only those languages found in either <parameter>ls_a</parameter> or <parameter>ls_b</parameter>.
  80 @@
  81
  82 @RET@           FcLangSet *
  83 @FUNC@          FcLangSetSubtract
  84 @TYPE1@         const FcLangSet *               @ARG1@          ls_a
  85 @TYPE2@         const FcLangSet *               @ARG2@          ls_b
  86 @PURPOSE@       Subtract langsets
  87 @DESC@
  88 Returns a set including only those languages found in <parameter>ls_a</parameter> but not in <parameter>ls_b</parameter>.
  89 @@
  90
  91 @RET@           FcLangResult
  92 @FUNC@          FcLangSetCompare
  93 @TYPE1@         const FcLangSet *               @ARG1@          ls_a
  94 @TYPE2@         const FcLangSet *               @ARG2@          ls_b
  95 @PURPOSE@       compare language sets
  96 @DESC@
  97 <function>FcLangSetCompare</function> compares language coverage for
  98 <parameter>ls_a</parameter> and <parameter>ls_b</parameter>. If they share
  99 any language and territory pair, this function returns FcLangEqual. If they
 100 share a language but differ in which territory that language is for, this
 101 function returns FcLangDifferentTerritory. If they share no languages in
 102 common, this function returns FcLangDifferentLang.
 103 @@
 104
 105 @RET@           FcBool
 106 @FUNC@          FcLangSetContains
 107 @TYPE1@         const FcLangSet *               @ARG1@          ls_a
 108 @TYPE2@         const FcLangSet *               @ARG2@          ls_b
 109 @PURPOSE@       check langset subset relation
 110 @DESC@
 111 <function>FcLangSetContains</function> returns FcTrue if
 112 <parameter>ls_a</parameter> contains every language in
 113 <parameter>ls_b</parameter>. <parameter>ls_a</parameter> will 'contain' a
 114 language from <parameter>ls_b</parameter> if <parameter>ls_a</parameter>
 115 has exactly the language, or either the language or
 116 <parameter>ls_a</parameter> has no territory.
 117 @@
 118
 119 @RET@           FcBool
 120 @FUNC@          FcLangSetEqual
 121 @TYPE1@         const FcLangSet *               @ARG1@          ls_a
 122 @TYPE2@         const FcLangSet *               @ARG2@          ls_b
 123 @PURPOSE@       test for matching langsets
 124 @DESC@
 125 Returns FcTrue if and only if <parameter>ls_a</parameter> supports precisely
 126 the same language and territory combinations as <parameter>ls_b</parameter>.
 127 @@
 128
 129 @RET@           FcChar32
 130 @FUNC@          FcLangSetHash
 131 @TYPE1@         const FcLangSet *               @ARG1@          ls
 132 @PURPOSE@       return a hash value for a langset
 133 @DESC@
 134 This function returns a value which depends solely on the languages
 135 supported by <parameter>ls</parameter>. Any language which equals
 136 <parameter>ls</parameter> will have the same result from
 137 <function>FcLangSetHash</function>. However, two langsets with the same hash
 138 value may not be equal.
 139 @@
 140
 141 @RET@           FcLangResult
 142 @FUNC@          FcLangSetHasLang
 143 @TYPE1@         const FcLangSet *               @ARG1@          ls
 144 @TYPE2@         const FcChar8 *                 @ARG2@          lang
 145 @PURPOSE@       test langset for language support
 146 @DESC@
 147 <function>FcLangSetHasLang</function> checks whether
 148 <parameter>ls</parameter> supports <parameter>lang</parameter>. If
 149 <parameter>ls</parameter> has a matching language and territory pair,
 150 this function returns FcLangEqual. If <parameter>ls</parameter> has
 151 a matching language but differs in which territory that language is for, this
 152 function returns FcLangDifferentTerritory. If <parameter>ls</parameter>
 153 has no matching language, this function returns FcLangDifferentLang.
 154 @@
 155
 156 @RET@           FcStrSet *
 157 @FUNC@          FcGetDefaultLangs
 158 @TYPE1@         void
 159 @PURPOSE@       Get the default languages list
 160 @DESC@
 161 Returns a string set of the default languages according to the environment variables on the system.
 162 This function looks for them in order of FC_LANG, LC_ALL, LC_CTYPE and LANG then.
 163 If there are no valid values in those environment variables, "en" will be set as fallback.
 164
 165 @RET@           FcStrSet *
 166 @FUNC@          FcLangSetGetLangs
 167 @TYPE1@         const FcLangSet *               @ARG1@          ls
 168 @PURPOSE@       get the list of languages in the langset
 169 @DESC@
 170 Returns a string set of all languages in <parameter>langset</parameter>.
 171 @@
 172
 173 @RET@           FcStrSet *
 174 @FUNC@          FcGetLangs
 175 @TYPE1@         void
 176 @PURPOSE@       Get list of languages
 177 @DESC@
 178 Returns a string set of all known languages.
 179 @@
 180
 181 @RET@           FcChar8 *
 182 @FUNC@          FcLangNormalize
 183 @TYPE1@         const FcChar8 *                 @ARG1@          lang
 184 @PURPOSE@       Normalize the language string
 185 @DESC@
 186 Returns a string to make <parameter>lang</parameter> suitable on fontconfig.
 187 @@
 188
 189 @RET@           const FcCharSet *
 190 @FUNC@          FcLangGetCharSet
 191 @TYPE1@         const FcChar8 *                 @ARG1@          lang
 192 @PURPOSE@       Get character map for a language
 193 @DESC@
 194 Returns the FcCharMap for a language.
 195 @@