/*

 * 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.

@SINCE@		2.9.0

@@

@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 in <parameter>map</parameter> marking the

first page of Unicode coverage of <parameter>a</parameter>.

<parameter>*next</parameter> is set to contains the base code point

for the next page in <parameter>a</parameter>.  Returns the base code

point for the page, or <constant>FC_CHARSET_DONE</constant> if

<parameter>a</parameter> contains no pages.  As an example, if

<function>FcCharSetFirstPage</function> returns

<literal>0x300</literal> and fills <parameter>map</parameter> with

<literallayout class="monospaced">

0xffffffff 0xffffffff 0x01000008 0x44300002 0xffffd7f0 0xfffffffb 0xffff7fff 0xffff0003

</literallayout>

Then the page contains code points <literal>0x300</literal> through

<literal>0x33f</literal> (the first 64 code points on the page)

because <parameter>map[0]</parameter> and

<parameter>map[1]</parameter> both have all their bits set.  It also

contains code points <literal>0x343</literal> (<parameter>0x300 + 32*2

+ (4-1)</parameter>) and <literal>0x35e</literal> (<parameter>0x300 +

32*2 + (31-1)</parameter>) because <parameter>map[2]</parameter> has

the 4th and 31st bits set.  The code points represented by

<literal>map[3]</literal> and later are left as an excercise for the

reader ;).

@@

@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 in <parameter>map</parameter> marking the

Unicode coverage of <parameter>a</parameter> for page containing

<parameter>*next</parameter> (see the

<function>FcCharSetFirstPage</function> description for details).

<parameter>*next</parameter> is set to contains the base code point

for the next page in <parameter>a</parameter>.  Returns the base of

code point for the page, or <constant>FC_CHARSET_DONE</constant> if

<parameter>a</parameter> does not contain

<parameter>*next</parameter>.

@@

@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.

@@