fontconfig/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 Keith Packard not be used in
 * advertising or publicity pertaining to distribution of the software without
 * specific, written prior permission.  Keith Packard makes no
 * representations about the suitability of this software for any purpose.  It
 * is provided "as is" without express or implied warranty.
 *
 * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 * EVENT SHALL KEITH PACKARD 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@		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@		FcCharSet *
@FUNC@		FcCharSetMerge
@TYPE1@		const FcCharSet *	@ARG1@		a
@TYPE2@		const FcCharSet *	@ARG2@		b
@PURPOSE@	Merge charsets
@DESC@
If <parameter>a</parameter> is NULL, returns a copy of <parameter>b</parameter>.
If <parameter>a</parameter> is an FcCharSet object owned by fontconfig that
cannot be modified, it returns the union of <parameter>a</parameter> and
<parameter>b</parameter> in a newly-created FcCharSet object.
Otherwise, adds all chars in <parameter>b</parameter> to <parameter>a</parameter> and returns <parameter>a</parameter>.  In other words, this is an in-place versionof FcCharSetUnion.
@@

@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.
@@
Add lots more function documentation 2003-03-07 09:44:32 +01:00			`/*`
Get rid of $Id$ tags 2008-08-13 09:30:23 +02:00			`* fontconfig/doc/fccharset.fncs`
Add lots more function documentation 2003-03-07 09:44:32 +01:00			`*`
Change files from ISO-Latin-1 to UTF-8 2004-12-07 02:14:46 +01:00			`* Copyright © 2003 Keith Packard`
Add lots more function documentation 2003-03-07 09:44:32 +01:00			`*`
			`* 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 Keith Packard not be used in`
			`* advertising or publicity pertaining to distribution of the software without`
			`* specific, written prior permission. Keith Packard makes no`
			`* representations about the suitability of this software for any purpose. It`
			`* is provided "as is" without express or implied warranty.`
			`*`
			`* KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,`
			`* INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO`
			`* EVENT SHALL KEITH PACKARD 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.`
			`*/`
Rework documentation to build man pages for each function 2003-03-07 08:12:51 +01:00			`@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`
Add space between type and formal in devel man pages (bug 8935) Most parameters are pointers and have '*' in the type; for those which do not, use '%' to mark where a space needs to be inserted. 2006-12-03 00:06:13 +01:00			`@TYPE2@ FcChar32% @ARG2@ ucs4`
Rework documentation to build man pages for each function 2003-03-07 08:12:51 +01:00			`@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@ 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>.`
			`@@`

Make FcCharSetMerge() public That's needed for apps to be abled to do pruning themselves without the performance penalty of recreating new charsets all the time. 2009-01-08 02:15:20 +01:00			`@RET@ FcCharSet *`
			`@FUNC@ FcCharSetMerge`
			`@TYPE1@ const FcCharSet * @ARG1@ a`
			`@TYPE2@ const FcCharSet * @ARG2@ b`
			`@PURPOSE@ Merge charsets`
			`@DESC@`
			`If <parameter>a</parameter> is NULL, returns a copy of <parameter>b</parameter>.`
			`If <parameter>a</parameter> is an FcCharSet object owned by fontconfig that`
			`cannot be modified, it returns the union of <parameter>a</parameter> and`
			`<parameter>b</parameter> in a newly-created FcCharSet object.`
			`Otherwise, adds all chars in <parameter>b</parameter> to <parameter>a</parameter> and returns <parameter>a</parameter>. In other words, this is an in-place versionof FcCharSetUnion.`
			`@@`

Rework documentation to build man pages for each function 2003-03-07 08:12:51 +01:00			`@RET@ FcBool`
			`@FUNC@ FcCharSetHasChar`
			`@TYPE1@ const FcCharSet * @ARG1@ fcs`
Add space between type and formal in devel man pages (bug 8935) Most parameters are pointers and have '*' in the type; for those which do not, use '%' to mark where a space needs to be inserted. 2006-12-03 00:06:13 +01:00			`@TYPE2@ FcChar32% @ARG2@ ucs4`
Rework documentation to build man pages for each function 2003-03-07 08:12:51 +01:00			`@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`
Add space between type and formal in devel man pages (bug 8935) Most parameters are pointers and have '*' in the type; for those which do not, use '%' to mark where a space needs to be inserted. 2006-12-03 00:06:13 +01:00			`@TYPE2@ FcChar32[FC_CHARSET_MAP_SIZE]% @ARG2@ map`
Rework documentation to build man pages for each function 2003-03-07 08:12:51 +01:00			`@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`
Add space between type and formal in devel man pages (bug 8935) Most parameters are pointers and have '*' in the type; for those which do not, use '%' to mark where a space needs to be inserted. 2006-12-03 00:06:13 +01:00			`@TYPE2@ FcChar32[FC_CHARSET_MAP_SIZE]% @ARG2@ map`
Rework documentation to build man pages for each function 2003-03-07 08:12:51 +01:00			`@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.`
			`@@`
Document previously undocumented functions. (bug 12963) 2007-11-04 06:23:28 +01:00
			`@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.`
			`@@`