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@           FcLangResult
  62 @FUNC@          FcLangSetCompare
  63 @TYPE1@         const FcLangSet *               @ARG1@          ls_a
  64 @TYPE2@         const FcLangSet *               @ARG2@          ls_b
  65 @PURPOSE@       compare language sets
  66 @DESC@
  67 <function>FcLangSetCompare</function> compares language coverage for
  68 <parameter>ls_a</parameter> and <parameter>ls_b</parameter>. If they share
  69 any language and territory pair, this function returns FcLangEqual. If they
  70 share a language but differ in which territory that language is for, this
  71 function returns FcLangDiffentTerritory. If they share no languages in
  72 common, this function returns FcLangDifferentLang.
  73 @@
  74
  75 @RET@           FcBool
  76 @FUNC@          FcLangSetContains
  77 @TYPE1@         const FcLangSet *               @ARG1@          ls_a
  78 @TYPE2@         const FcLangSet *               @ARG2@          ls_b
  79 @PURPOSE@       check langset subset relation
  80 @DESC@
  81 <function>FcLangSetContains</function> returns FcTrue if
  82 <parameter>ls_a</parameter> contains every language in
  83 <parameter>ls_b</parameter>. <parameter>ls_a</parameter> will 'contain' a
  84 language from <parameter>ls_b</parameter> if <parameter>ls_a</parameter>
  85 has exactly the language, or either the language or
  86 <parameter>ls_a</parameter> has no territory.
  87 @@
  88
  89 @RET@           FcBool
  90 @FUNC@          FcLangSetEqual
  91 @TYPE1@         const FcLangSet *               @ARG1@          ls_a
  92 @TYPE2@         const FcLangSet *               @ARG2@          ls_b
  93 @PURPOSE@       test for matching langsets
  94 @DESC@
  95 Returns FcTrue if and only if <parameter>ls_a</parameter> supports precisely
  96 the same language and territory combinations as <parameter>ls_b</parameter>.
  97 @@
  98
  99 @RET@           FcChar32
 100 @FUNC@          FcLangSetHash
 101 @TYPE1@         const FcLangSet *               @ARG1@          ls
 102 @PURPOSE@       return a hash value for a langset
 103 @DESC@
 104 This function returns a value which depends solely on the languages
 105 supported by <parameter>ls</parameter>. Any language which equals
 106 <parameter>ls</function> will have the same result from
 107 <function>FcLangSetHash</function>. However, two langsets with the same hash
 108 value may not be equal.
 109 @@
 110
 111 @RET@           FcLangResult
 112 @FUNC@          FcLangSetHasLang
 113 @TYPE1@         const FcLangSet *               @ARG1@          ls
 114 @TYPE2@         const FcChar8 *                 @ARG2@          lang
 115 @PURPOSE@       test langset for language support
 116 @DESC@
 117 <function>FcLangSetHasLang</function> checks whether
 118 <parameter>ls</parameter> supports <parameter>lang</parameter>. If
 119 <parameter>ls</parameter> has a matching language and territory pair,
 120 this function returns FcLangEqual. If <parameter>ls</parameter> has
 121 a matching language but differs in which territory that language is for, this
 122 function returns FcLangDiffentTerritory. If <parameter>ls</parameter>
 123 has no matching language, this function returns FcLangDifferentLang.
 124 @@