[fontconfig.git] / doc / fccharset.fncs

/*
 * fontconfig/doc/fccharset.fncs
 *
 * Copyright © 2003 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 author(s) not be used in
 * advertising or publicity pertaining to distribution of the software without
 * specific, written prior permission.  The authors make no
 * representations about the suitability of this software for any purpose.  It
 * is provided "as is" without express or implied warranty.
 *
 * THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 * EVENT SHALL THE AUTHOR(S) 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@		FcCharSet *
@FUNC@		FcCharSetCreate
@TYPE1@		void
@PURPOSE@	Create an empty character set
@DESC@
<function>FcCharSetCreate</function> allocates and initializes a new empty
character set object.
@@

@RET@		void
@FUNC@		FcCharSetDestroy
@TYPE1@		FcCharSet *		@ARG1@		fcs
@PURPOSE@	Destroy a character set
@DESC@
<function>FcCharSetDestroy</function> decrements the reference count 
<parameter>fcs</parameter>.  If the reference count becomes zero, all
memory referenced is freed.
@@

@RET@		FcBool 
@FUNC@		FcCharSetAddChar
@TYPE1@		FcCharSet *		@ARG1@		fcs
@TYPE2@		FcChar32% 		@ARG2@		ucs4 
@PURPOSE@	Add a character to a charset
@DESC@
<function>FcCharSetAddChar</function> adds a single unicode char to the set,
returning FcFalse on failure, either as a result of a constant set or from
running out of memory. 
@@

@RET@		FcBool 
@FUNC@		FcCharSetDelChar
@TYPE1@		FcCharSet *		@ARG1@		fcs
@TYPE2@		FcChar32% 		@ARG2@		ucs4 
@PURPOSE@	Add a character to a charset
@DESC@
<function>FcCharSetDelChar</function> deletes a single unicode char from the set,
returning FcFalse on failure, either as a result of a constant set or from
running out of memory.
@@

@RET@		FcCharSet *
@FUNC@		FcCharSetCopy
@TYPE1@		FcCharSet *		@ARG1@		src
@PURPOSE@	Copy a charset
@DESC@
Makes a copy of <parameter>src</parameter>; note that this may not actually do anything more
than increment the reference count on <parameter>src</parameter>. 
@@

@RET@		FcBool
@FUNC@		FcCharSetEqual
@TYPE1@		const FcCharSet *	@ARG1@		a
@TYPE2@		const FcCharSet *	@ARG2@		b
@PURPOSE@	Compare two charsets
@DESC@
Returns whether <parameter>a</parameter> and <parameter>b</parameter>
contain the same set of unicode chars.
@@

@RET@		FcCharSet *
@FUNC@		FcCharSetIntersect
@TYPE1@		const FcCharSet *	@ARG1@		a
@TYPE2@		const FcCharSet *	@ARG2@		b
@PURPOSE@	Intersect charsets
@DESC@
Returns a set including only those chars found in both
<parameter>a</parameter> and <parameter>b</parameter>. 
@@

@RET@		FcCharSet *
@FUNC@		FcCharSetUnion
@TYPE1@		const FcCharSet *	@ARG1@		a
@TYPE2@		const FcCharSet *	@ARG2@		b
@PURPOSE@	Add charsets
@DESC@
Returns a set including only those chars found in either <parameter>a</parameter> or <parameter>b</parameter>. 
@@

@RET@		FcCharSet *
@FUNC@		FcCharSetSubtract
@TYPE1@		const FcCharSet *	@ARG1@		a
@TYPE2@		const FcCharSet *	@ARG2@		b
@PURPOSE@	Subtract charsets
@DESC@
Returns a set including only those chars found in <parameter>a</parameter> but not <parameter>b</parameter>. 
@@

@RET@		FcBool
@FUNC@		FcCharSetMerge
@TYPE1@		FcCharSet *		@ARG1@		a
@TYPE2@		const FcCharSet *	@ARG2@		b
@TYPE3@		FcBool *		@ARG3@		changed
@PURPOSE@	Merge charsets
@DESC@
Adds all chars in <parameter>b</parameter> to <parameter>a</parameter>.
In other words, this is an in-place version of FcCharSetUnion.
If <parameter>changed</parameter> is not NULL, then it returns whether any new
chars from <parameter>b</parameter> were added to <parameter>a</parameter>.
Returns FcFalse on failure, either when <parameter>a</parameter> is a constant
set or from running out of memory.
@@

@RET@		FcBool 
@FUNC@		FcCharSetHasChar
@TYPE1@		const FcCharSet *	@ARG1@		fcs
@TYPE2@		FcChar32% 		@ARG2@		ucs4
@PURPOSE@	Check a charset for a char
@DESC@
Returns whether <parameter>fcs</parameter> contains the char <parameter>ucs4</parameter>. 
@@

@RET@		FcChar32
@FUNC@		FcCharSetCount
@TYPE1@		const FcCharSet *	@ARG1@		a
@PURPOSE@	Count entries in a charset
@DESC@
Returns the total number of unicode chars in <parameter>a</parameter>. 
@@

@RET@		FcChar32
@FUNC@		FcCharSetIntersectCount
@TYPE1@		const FcCharSet *	@ARG1@		a
@TYPE2@		const FcCharSet *	@ARG2@		b
@PURPOSE@	Intersect and count charsets
@DESC@
Returns the number of chars that are in both <parameter>a</parameter> and <parameter>b</parameter>. 
@@

@RET@		FcChar32
@FUNC@		FcCharSetSubtractCount
@TYPE1@		const FcCharSet *	@ARG1@		a
@TYPE2@		const FcCharSet *	@ARG2@		b
@PURPOSE@	Subtract and count charsets
@DESC@
Returns the number of chars that are in <parameter>a</parameter> but not in <parameter>b</parameter>. 
@@

@RET@		FcBool
@FUNC@		FcCharSetIsSubset
@TYPE1@		const FcCharSet *	@ARG1@		a
@TYPE2@		const FcCharSet *	@ARG2@		b
@PURPOSE@	Test for charset inclusion
@DESC@
Returns whether <parameter>a</parameter> is a subset of <parameter>b</parameter>. 
@@

@RET@		FcChar32
@FUNC@		FcCharSetFirstPage
@TYPE1@		const FcCharSet *	@ARG1@		a
@TYPE2@		FcChar32[FC_CHARSET_MAP_SIZE]%	@ARG2@	map
@TYPE3@		FcChar32 *		@ARG3@		next
@PURPOSE@	Start enumerating charset contents
@DESC@
Builds an array of bits marking the first page of Unicode coverage of
<parameter>a</parameter>. Returns the base of the array. <parameter>next</parameter> contains the next page in the
font.
@@

@RET@		FcChar32
@FUNC@		FcCharSetNextPage
@TYPE1@		const FcCharSet *	@ARG1@		a
@TYPE2@		FcChar32[FC_CHARSET_MAP_SIZE]%	@ARG2@	map
@TYPE3@		FcChar32 *		@ARG3@		next
@PURPOSE@	Continue enumerating charset contents
@DESC@
Builds an array of bits marking the Unicode coverage of <parameter>a</parameter> for page
<parameter>*next</parameter>. Returns the base of the array. <parameter>next</parameter> contains the next page in
the font. 
@@

@RET@		FcChar32
@FUNC@		FcCharSetCoverage
@TYPE1@		const FcCharSet *	@ARG1@		a
@TYPE2@		FcChar32		@ARG2@		page
@TYPE3@		FcChar32[8] 		@ARG3@		result
@PURPOSE@	DEPRECATED return coverage for a Unicode page
@DESC@
DEPRECATED
This function returns a bitmask in <parameter>result</parameter> which
indicates which code points in
<parameter>page</parameter> are included in <parameter>a</parameter>.
<function>FcCharSetCoverage</function> returns the next page in the charset which has any
coverage.
@@

@RET@		FcCharSet *
@FUNC@		FcCharSetNew
@TYPE1@		void
@PURPOSE@	DEPRECATED alias for FcCharSetCreate
@DESC@
<function>FcCharSetNew</function> is a DEPRECATED alias for FcCharSetCreate.
@@
Commit	Line	Data
bfc2dc3a	1	/*
e690fbb2	2	* fontconfig/doc/fccharset.fncs
bfc2dc3a	3	*
46b51147	4	* Copyright © 2003 Keith Packard
bfc2dc3a KP	5	*
	6	* Permission to use, copy, modify, distribute, and sell this software and its
	7	* documentation for any purpose is hereby granted without fee, provided that
	8	* the above copyright notice appear in all copies and that both that
	9	* copyright notice and this permission notice appear in supporting
5aaf466d	10	* documentation, and that the name of the author(s) not be used in
bfc2dc3a	11	* advertising or publicity pertaining to distribution of the software without
5aaf466d	12	* specific, written prior permission. The authors make no
bfc2dc3a KP	13	* representations about the suitability of this software for any purpose. It
	14	* is provided "as is" without express or implied warranty.
	15	*
3074a73b	16	* THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
bfc2dc3a	17	* INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
3074a73b	18	* EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
bfc2dc3a KP	19	* CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
	20	* DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
	21	* TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
	22	* PERFORMANCE OF THIS SOFTWARE.
	23	*/
22671e25 KP	24	@RET@ FcCharSet *
	25	@FUNC@ FcCharSetCreate
	26	@TYPE1@ void
	27	@PURPOSE@ Create an empty character set
	28	@DESC@
	29	<function>FcCharSetCreate</function> allocates and initializes a new empty
	30	character set object.
	31	@@
	32
	33	@RET@ void
	34	@FUNC@ FcCharSetDestroy
	35	@TYPE1@ FcCharSet * @ARG1@ fcs
	36	@PURPOSE@ Destroy a character set
	37	@DESC@
	38	<function>FcCharSetDestroy</function> decrements the reference count
	39	<parameter>fcs</parameter>. If the reference count becomes zero, all
	40	memory referenced is freed.
	41	@@
	42
	43	@RET@ FcBool
	44	@FUNC@ FcCharSetAddChar
	45	@TYPE1@ FcCharSet * @ARG1@ fcs
61895ed1	46	@TYPE2@ FcChar32% @ARG2@ ucs4
22671e25 KP	47	@PURPOSE@ Add a character to a charset
	48	@DESC@
	49	<function>FcCharSetAddChar</function> adds a single unicode char to the set,
	50	returning FcFalse on failure, either as a result of a constant set or from
	51	running out of memory.
	52	@@
	53
52960d05 BE	54	@RET@ FcBool
	55	@FUNC@ FcCharSetDelChar
	56	@TYPE1@ FcCharSet * @ARG1@ fcs
	57	@TYPE2@ FcChar32% @ARG2@ ucs4
	58	@PURPOSE@ Add a character to a charset
	59	@DESC@
	60	<function>FcCharSetDelChar</function> deletes a single unicode char from the set,
	61	returning FcFalse on failure, either as a result of a constant set or from
	62	running out of memory.
	63	@@
	64
22671e25 KP	65	@RET@ FcCharSet *
	66	@FUNC@ FcCharSetCopy
	67	@TYPE1@ FcCharSet * @ARG1@ src
	68	@PURPOSE@ Copy a charset
	69	@DESC@
	70	Makes a copy of <parameter>src</parameter>; note that this may not actually do anything more
	71	than increment the reference count on <parameter>src</parameter>.
	72	@@
	73
	74	@RET@ FcBool
	75	@FUNC@ FcCharSetEqual
	76	@TYPE1@ const FcCharSet * @ARG1@ a
	77	@TYPE2@ const FcCharSet * @ARG2@ b
	78	@PURPOSE@ Compare two charsets
	79	@DESC@
	80	Returns whether <parameter>a</parameter> and <parameter>b</parameter>
	81	contain the same set of unicode chars.
	82	@@
	83
	84	@RET@ FcCharSet *
	85	@FUNC@ FcCharSetIntersect
	86	@TYPE1@ const FcCharSet * @ARG1@ a
	87	@TYPE2@ const FcCharSet * @ARG2@ b
	88	@PURPOSE@ Intersect charsets
	89	@DESC@
	90	Returns a set including only those chars found in both
	91	<parameter>a</parameter> and <parameter>b</parameter>.
	92	@@
	93
	94	@RET@ FcCharSet *
	95	@FUNC@ FcCharSetUnion
	96	@TYPE1@ const FcCharSet * @ARG1@ a
	97	@TYPE2@ const FcCharSet * @ARG2@ b
	98	@PURPOSE@ Add charsets
	99	@DESC@
	100	Returns a set including only those chars found in either <parameter>a</parameter> or <parameter>b</parameter>.
	101	@@
	102
	103	@RET@ FcCharSet *
	104	@FUNC@ FcCharSetSubtract
	105	@TYPE1@ const FcCharSet * @ARG1@ a
	106	@TYPE2@ const FcCharSet * @ARG2@ b
	107	@PURPOSE@ Subtract charsets
	108	@DESC@
	109	Returns a set including only those chars found in <parameter>a</parameter> but not <parameter>b</parameter>.
	110	@@
	111
575ee6cd	112	@RET@ FcBool
d230cf14	113	@FUNC@ FcCharSetMerge
575ee6cd	114	@TYPE1@ FcCharSet * @ARG1@ a
d230cf14	115	@TYPE2@ const FcCharSet * @ARG2@ b
575ee6cd	116	@TYPE3@ FcBool * @ARG3@ changed
d230cf14 BE	117	@PURPOSE@ Merge charsets
d230cf14 BE	118	@DESC@
575ee6cd KT	119	Adds all chars in <parameter>b</parameter> to <parameter>a</parameter>.
	120	In other words, this is an in-place version of FcCharSetUnion.
	121	If <parameter>changed</parameter> is not NULL, then it returns whether any new
	122	chars from <parameter>b</parameter> were added to <parameter>a</parameter>.
	123	Returns FcFalse on failure, either when <parameter>a</parameter> is a constant
	124	set or from running out of memory.
d230cf14 BE	125	@@
d230cf14 BE	126
22671e25 KP	127	@RET@ FcBool
	128	@FUNC@ FcCharSetHasChar
	129	@TYPE1@ const FcCharSet * @ARG1@ fcs
61895ed1	130	@TYPE2@ FcChar32% @ARG2@ ucs4
22671e25 KP	131	@PURPOSE@ Check a charset for a char
	132	@DESC@
	133	Returns whether <parameter>fcs</parameter> contains the char <parameter>ucs4</parameter>.
	134	@@
	135
	136	@RET@ FcChar32
	137	@FUNC@ FcCharSetCount
	138	@TYPE1@ const FcCharSet * @ARG1@ a
	139	@PURPOSE@ Count entries in a charset
	140	@DESC@
	141	Returns the total number of unicode chars in <parameter>a</parameter>.
	142	@@
	143
	144	@RET@ FcChar32
	145	@FUNC@ FcCharSetIntersectCount
	146	@TYPE1@ const FcCharSet * @ARG1@ a
	147	@TYPE2@ const FcCharSet * @ARG2@ b
	148	@PURPOSE@ Intersect and count charsets
	149	@DESC@
	150	Returns the number of chars that are in both <parameter>a</parameter> and <parameter>b</parameter>.
	151	@@
	152
	153	@RET@ FcChar32
	154	@FUNC@ FcCharSetSubtractCount
	155	@TYPE1@ const FcCharSet * @ARG1@ a
	156	@TYPE2@ const FcCharSet * @ARG2@ b
	157	@PURPOSE@ Subtract and count charsets
	158	@DESC@
	159	Returns the number of chars that are in <parameter>a</parameter> but not in <parameter>b</parameter>.
	160	@@
	161
	162	@RET@ FcBool
	163	@FUNC@ FcCharSetIsSubset
	164	@TYPE1@ const FcCharSet * @ARG1@ a
	165	@TYPE2@ const FcCharSet * @ARG2@ b
	166	@PURPOSE@ Test for charset inclusion
	167	@DESC@
	168	Returns whether <parameter>a</parameter> is a subset of <parameter>b</parameter>.
	169	@@
	170
	171	@RET@ FcChar32
	172	@FUNC@ FcCharSetFirstPage
	173	@TYPE1@ const FcCharSet * @ARG1@ a
61895ed1	174	@TYPE2@ FcChar32[FC_CHARSET_MAP_SIZE]% @ARG2@ map
22671e25 KP	175	@TYPE3@ FcChar32 * @ARG3@ next
	176	@PURPOSE@ Start enumerating charset contents
	177	@DESC@
	178	Builds an array of bits marking the first page of Unicode coverage of
	179	<parameter>a</parameter>. Returns the base of the array. <parameter>next</parameter> contains the next page in the
	180	font.
	181	@@
	182
	183	@RET@ FcChar32
	184	@FUNC@ FcCharSetNextPage
	185	@TYPE1@ const FcCharSet * @ARG1@ a
61895ed1	186	@TYPE2@ FcChar32[FC_CHARSET_MAP_SIZE]% @ARG2@ map
22671e25 KP	187	@TYPE3@ FcChar32 * @ARG3@ next
	188	@PURPOSE@ Continue enumerating charset contents
	189	@DESC@
	190	Builds an array of bits marking the Unicode coverage of <parameter>a</parameter> for page
	191	<parameter>*next</parameter>. Returns the base of the array. <parameter>next</parameter> contains the next page in
	192	the font.
	193	@@
a190678e KP	194
	195	@RET@ FcChar32
	196	@FUNC@ FcCharSetCoverage
	197	@TYPE1@ const FcCharSet * @ARG1@ a
	198	@TYPE2@ FcChar32 @ARG2@ page
	199	@TYPE3@ FcChar32[8] @ARG3@ result
	200	@PURPOSE@ DEPRECATED return coverage for a Unicode page
	201	@DESC@
	202	DEPRECATED
	203	This function returns a bitmask in <parameter>result</parameter> which
	204	indicates which code points in
	205	<parameter>page</parameter> are included in <parameter>a</parameter>.
	206	<function>FcCharSetCoverage</function> returns the next page in the charset which has any
	207	coverage.
	208	@@
	209
	210	@RET@ FcCharSet *
	211	@FUNC@ FcCharSetNew
	212	@TYPE1@ void
	213	@PURPOSE@ DEPRECATED alias for FcCharSetCreate
	214	@DESC@
	215	<function>FcCharSetNew</function> is a DEPRECATED alias for FcCharSetCreate.
	216	@@
	217