Document previously undocumented functions. (bug 12963)

[fontconfig.git] / doc / fclangset.fncs

diff --git a/doc/fclangset.fncs b/doc/fclangset.fncs
new file mode 100644 (file)
index 0000000..eb4a937
--- /dev/null
+++ b/doc/fclangset.fncs
@@ -0,0 +1,124 @@
+/*
+ * Copyright © 2007 Keith Packard
+ *
+ * Permission to use, copy, modify, distribute, and sell this software and its
+ * documentation for any purpose is hereby granted without fee, provided that
+ * the above copyright notice appear in all copies and that both that copyright
+ * notice and this permission notice appear in supporting documentation, and
+ * that the name of the copyright holders not be used in advertising or
+ * publicity pertaining to distribution of the software without specific,
+ * written prior permission.  The copyright holders make no representations
+ * about the suitability of this software for any purpose.  It is provided "as
+ * is" without express or implied warranty.
+ *
+ * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+ * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+ * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+ * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+ * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
+ * OF THIS SOFTWARE.
+ */
+
+@RET@          FcLangSet *
+@FUNC@         FcLangSetCreate
+@TYPE1@                void
+@PURPOSE@      create a langset object
+@DESC@
+<function>FcLangSetCreate</function> creates a new FcLangSet object.
+@@
+
+@RET@          void
+@FUNC@         FcLangSetDestroy
+@TYPE1@                FcLangSet *                     @ARG1@          ls
+@PURPOSE@      destroy a langset object
+@DESC@
+<function>FcLangSetDestroy</function> destroys a FcLangSet object, freeing
+all memory associated with it.
+@@
+
+@RET@          FcLangSet *
+@FUNC@         FcLangSetCopy
+@TYPE1@                const FcLangSet *               @ARG1@          ls
+@PURPOSE@      copy a langset object
+@DESC@
+<function>FcLangSetCopy</function> creates a new FcLangSet object and
+populates it with the contents of <parameter>ls</parameter>.
+@@
+
+@RET@          FcBool
+@FUNC@         FcLangSetAdd
+@TYPE1@                FcLangSet *                     @ARG1@          ls
+@TYPE2@                const FcChar8 *                 @ARG2@          lang
+@PURPOSE@      add a language to a langset
+@DESC@
+<parameter>lang</parameter> is added to <parameter>ls</parameter>.
+<parameter>lang</parameter> should be of the form Ll-Tt where Ll is a
+two or three letter language from ISO 639 and Tt is a territory from ISO
+3166.
+@@
+
+@RET@          FcLangResult
+@FUNC@         FcLangSetCompare
+@TYPE1@                const FcLangSet *               @ARG1@          ls_a
+@TYPE2@                const FcLangSet *               @ARG2@          ls_b
+@PURPOSE@      compare language sets
+@DESC@
+<function>FcLangSetCompare</function> compares language coverage for
+<parameter>ls_a</parameter> and <parameter>ls_b</parameter>. If they share
+any language and territory pair, this function returns FcLangEqual. If they
+share a language but differ in which territory that language is for, this
+function returns FcLangDiffentTerritory. If they share no languages in
+common, this function returns FcLangDifferentLang.
+@@
+
+@RET@          FcBool
+@FUNC@         FcLangSetContains
+@TYPE1@                const FcLangSet *               @ARG1@          ls_a
+@TYPE2@                const FcLangSet *               @ARG2@          ls_b
+@PURPOSE@      check langset subset relation
+@DESC@
+<function>FcLangSetContains</function> returns FcTrue if
+<parameter>ls_a</parameter> contains every language in
+<parameter>ls_b</parameter>. <parameter>ls_a</parameter> will 'contain' a
+language from <parameter>ls_b</parameter> if <parameter>ls_a</parameter>
+has exactly the language, or either the language or
+<parameter>ls_a</parameter> has no territory.
+@@
+
+@RET@          FcBool
+@FUNC@         FcLangSetEqual
+@TYPE1@                const FcLangSet *               @ARG1@          ls_a
+@TYPE2@                const FcLangSet *               @ARG2@          ls_b
+@PURPOSE@      test for matching langsets
+@DESC@
+Returns FcTrue if and only if <parameter>ls_a</parameter> supports precisely
+the same language and territory combinations as <parameter>ls_b</parameter>.
+@@
+
+@RET@          FcChar32
+@FUNC@         FcLangSetHash
+@TYPE1@                const FcLangSet *               @ARG1@          ls
+@PURPOSE@      return a hash value for a langset
+@DESC@
+This function returns a value which depends solely on the languages
+supported by <parameter>ls</parameter>. Any language which equals
+<parameter>ls</function> will have the same result from
+<function>FcLangSetHash</function>. However, two langsets with the same hash
+value may not be equal.
+@@
+
+@RET@          FcLangResult
+@FUNC@         FcLangSetHasLang
+@TYPE1@                const FcLangSet *               @ARG1@          ls
+@TYPE2@                const FcChar8 *                 @ARG2@          lang
+@PURPOSE@      test langset for language support
+@DESC@
+<function>FcLangSetHasLang</function> checks whether
+<parameter>ls</parameter> supports <parameter>lang</parameter>. If 
+<parameter>ls</parameter> has a matching language and territory pair,
+this function returns FcLangEqual. If <parameter>ls</parameter> has
+a matching language but differs in which territory that language is for, this
+function returns FcLangDiffentTerritory. If <parameter>ls</parameter> 
+has no matching language, this function returns FcLangDifferentLang.
+@@