[fontconfig.git] / doc / fclangset.fncs

/*
 * 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@		FcBool
@FUNC@		FcLangSetDel
@TYPE1@		FcLangSet *			@ARG1@		ls
@TYPE2@		const FcChar8 *			@ARG2@		lang
@PURPOSE@	delete a language from a langset
@DESC@
<parameter>lang</parameter> is removed from <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@		FcLangSet *
@FUNC@		FcLangSetUnion
@TYPE1@		const FcLangSet *		@ARG1@		ls_a
@TYPE2@		const FcLangSet *		@ARG2@		ls_b
@PURPOSE@	Add langsets
@DESC@
Returns a set including only those languages found in either <parameter>ls_a</parameter> or <parameter>ls_b</parameter>.
@@

@RET@		FcLangSet *
@FUNC@		FcLangSetSubtract
@TYPE1@		const FcLangSet *		@ARG1@		ls_a
@TYPE2@		const FcLangSet *		@ARG2@		ls_b
@PURPOSE@	Subtract langsets
@DESC@
Returns a set including only those languages found in <parameter>ls_a</parameter> but not in <parameter>ls_b</parameter>.
@@

@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 FcLangDifferentTerritory. 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</parameter> 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 FcLangDifferentTerritory. If <parameter>ls</parameter> 
has no matching language, this function returns FcLangDifferentLang.
@@

@RET@		FcStrSet *
@FUNC@		FcLangSetGetLangs
@TYPE1@		const FcLangSet *		@ARG1@		ls
@PURPOSE@	get the list of languages in the langset
@DESC@
Returns a string set of all languages in <parameter>langset</parameter>.
@@

@RET@		FcStrSet *
@FUNC@		FcGetLangs
@TYPE1@		void
@PURPOSE@	Get list of languages
@DESC@
Returns a string set of all known languages.
@@

@RET@		const FcCharSet *
@FUNC@		FcLangGetCharSet
@TYPE1@		const FcChar8 *			@ARG1@		lang
@PURPOSE@	Get character map for a language
@DESC@
Returns the FcCharMap for a language.
@@
Commit	Line	Data
a190678e KP	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
fa269cf8 AT	61	@RET@ FcBool
	62	@FUNC@ FcLangSetDel
	63	@TYPE1@ FcLangSet * @ARG1@ ls
	64	@TYPE2@ const FcChar8 * @ARG2@ lang
e63f90ce	65	@PURPOSE@ delete a language from a langset
fa269cf8 AT	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@
e63f90ce	88	Returns a set including only those languages found in <parameter>ls_a</parameter> but not in <parameter>ls_b</parameter>.
fa269cf8 AT	89	@@
fa269cf8 AT	90
a190678e KP	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
7baa20c7	101	function returns FcLangDifferentTerritory. If they share no languages in
a190678e KP	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
dac27f2f	136	<parameter>ls</parameter> will have the same result from
a190678e KP	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
7baa20c7	152	function returns FcLangDifferentTerritory. If <parameter>ls</parameter>
a190678e KP	153	has no matching language, this function returns FcLangDifferentLang.
a190678e KP	154	@@
cf223cc7	155
d62b85af BE	156	@RET@ FcStrSet *
	157	@FUNC@ FcLangSetGetLangs
	158	@TYPE1@ const FcLangSet * @ARG1@ ls
	159	@PURPOSE@ get the list of languages in the langset
	160	@DESC@
	161	Returns a string set of all languages in <parameter>langset</parameter>.
	162	@@
	163
cf223cc7 BE	164	@RET@ FcStrSet *
	165	@FUNC@ FcGetLangs
	166	@TYPE1@ void
	167	@PURPOSE@ Get list of languages
	168	@DESC@
	169	Returns a string set of all known languages.
	170	@@
	171
	172	@RET@ const FcCharSet *
	173	@FUNC@ FcLangGetCharSet
	174	@TYPE1@ const FcChar8 * @ARG1@ lang
	175	@PURPOSE@ Get character map for a language
	176	@DESC@
	177	Returns the FcCharMap for a language.
	178	@@