[fontconfig.git] / doc / fcpattern.fncs

/*
 * fontconfig/doc/fcpattern.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@		FcPattern *	
@FUNC@		FcPatternCreate
@TYPE1@ 	void
@PURPOSE@	Create a pattern
@DESC@
Creates a pattern with no properties; used to build patterns from scratch.
@@

@RET@		FcPattern *	
@FUNC@		FcPatternDuplicate
@TYPE1@		const FcPattern * 		@ARG1@		 p
@PURPOSE@	Copy a pattern
@DESC@
Copy a pattern, returning a new pattern that matches
<parameter>p</parameter>. Each pattern may be modified without affecting the
other.
@@

@RET@		void
@FUNC@		FcPatternReference
@TYPE1@		FcPattern * 			@ARG1@		 p
@PURPOSE@	Increment pattern reference count
@DESC@
Add another reference to <parameter>p</parameter>. Patterns are freed only
when the reference count reaches zero.
@@

@RET@		void
@FUNC@		FcPatternDestroy
@TYPE1@		FcPattern * 			@ARG1@		 p
@PURPOSE@	Destroy a pattern
@DESC@
Decrement the pattern reference count. If all references are gone, destroys
the pattern, in the process destroying all related values.
@@

@RET@		FcBool
@FUNC@		FcPatternEqual
@TYPE1@ 	const FcPattern *		@ARG1@ 		pa
@TYPE2@		const FcPattern * 		@ARG2@		pb 
@PURPOSE@	Compare patterns
@DESC@
Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> are exactly alike.
@@

@RET@		FcBool
@FUNC@		FcPatternEqualSubset
@TYPE1@		const FcPattern * 		@ARG1@ 		pa
@TYPE2@		const FcPattern *		@ARG2@ 		pb
@TYPE3@ 	const FcObjectSet * 		@ARG3@ 		os 
@PURPOSE@	Compare portions of patterns
@DESC@
Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> have exactly the same values for all of the
objects in <parameter>os</parameter>.
@@

@RET@		FcPattern *
@FUNC@		FcPatternFilter
@TYPE1@		FcPattern * 			@ARG1@		 p
@TYPE2@		const FcObjectSet * 		@ARG1@		 os
@PURPOSE@	Filter the objects of pattern
@DESC@
Returns a new pattern that only has those objects from
<parameter>p</parameter> that are in <parameter>os</parameter>.
If <parameter>os</parameter> is NULL, a duplicate of
<parameter>p</parameter> is returned.
@@

@RET@		FcChar32
@FUNC@		FcPatternHash
@TYPE1@		const FcPattern *		@ARG1@		p
@PURPOSE@	Compute a pattern hash value
@DESC@
Returns a 32-bit number which is the same for any two patterns which are
equal.
@@

@RET@		FcBool
@FUNC@		FcPatternAdd
@TYPE1@		FcPattern * 			@ARG1@ 		p
@TYPE2@ 	const char *			@ARG2@ 		object
@TYPE3@		FcValue%			@ARG3@		value
@TYPE4@		FcBool%				@ARG4@		append 
@PURPOSE@	Add a value to a pattern
@DESC@
Adds a single value to the list of values associated with the property named
`object<parameter>.  If `append</parameter> is FcTrue, the value is added at the end of any
existing list, otherwise it is inserted at the beginning.  `value' is saved
(with FcValueSave) when inserted into the pattern so that the library
retains no reference to any application-supplied data structure.
@@

@RET@		FcBool
@FUNC@		FcPatternAddWeak
@TYPE1@ 	FcPattern * 			@ARG1@ 		p
@TYPE2@ 	const char * 			@ARG2@ 		object
@TYPE3@ 	FcValue%  			@ARG3@ 		value
@TYPE4@ 	FcBool%  			@ARG4@		append 
@PURPOSE@	Add a value to a pattern with weak binding
@DESC@
FcPatternAddWeak is essentially the same as FcPatternAdd except that any
values added to the list have binding <parameter>weak</parameter> instead of <parameter>strong</parameter>.
@@

@TITLE@		FcPatternAdd-Type
@RET@		FcBool
@FUNC@		FcPatternAddInteger
@TYPE1@ 	FcPattern * 			@ARG1@ 		p
@TYPE2@		const char *			@ARG2@		object
@TYPE3@		int%				@ARG3@		i

@PROTOTYPE+@
@RET+@		FcBool
@FUNC+@		FcPatternAddDouble
@TYPE1+@ 	FcPattern * 			@ARG1+@ 	p
@TYPE2+@	const char *			@ARG2+@		object
@TYPE3+@	double%				@ARG3+@		d

@PROTOTYPE++@
@RET++@		FcBool
@FUNC++@	FcPatternAddString
@TYPE1++@ 	FcPattern * 			@ARG1++@ 	p
@TYPE2++@	const char *			@ARG2++@	object
@TYPE3++@	const FcChar8 *			@ARG3++@	s

@PROTOTYPE+++@
@RET+++@	FcBool
@FUNC+++@	FcPatternAddMatrix
@TYPE1+++@ 	FcPattern * 			@ARG1+++@ 	p
@TYPE2+++@	const char *			@ARG2+++@	object
@TYPE3+++@	const FcMatrix *		@ARG3+++@	m

@PROTOTYPE++++@
@RET++++@	FcBool
@FUNC++++@	FcPatternAddCharSet
@TYPE1++++@ 	FcPattern * 			@ARG1++++@ 	p
@TYPE2++++@	const char *			@ARG2++++@	object
@TYPE3++++@	const FcCharSet *		@ARG3++++@	c

@PROTOTYPE+++++@
@RET+++++@	FcBool
@FUNC+++++@	FcPatternAddBool
@TYPE1+++++@ 	FcPattern * 			@ARG1+++++@ 	p
@TYPE2+++++@	const char *			@ARG2+++++@	object
@TYPE3+++++@	FcBool%				@ARG3+++++@	b

@PROTOTYPE++++++@
@RET++++++@	FcBool
@FUNC++++++@	FcPatternAddFTFace
@TYPE1++++++@ 	FcPattern * 			@ARG1++++++@ 	p
@TYPE2++++++@	const char *			@ARG2++++++@	object
@TYPE3++++++@	const FT_Face 			@ARG3++++++@	f

@PROTOTYPE+++++++@
@RET+++++++@	FcBool
@FUNC+++++++@	FcPatternAddLangSet
@TYPE1+++++++@ 	FcPattern * 			@ARG1+++++++@ 	p
@TYPE2+++++++@	const char *			@ARG2+++++++@	object
@TYPE3+++++++@	const FcLangSet *		@ARG3+++++++@	l

@PURPOSE@	Add a typed value to a pattern
@DESC@
These are all convenience functions that insert objects of the specified
type into the pattern.  Use these in preference to FcPatternAdd as they
will provide compile-time typechecking.  These all append values to
any existing list of values.
@@

@RET@		FcResult
@FUNC@		FcPatternGet
@TYPE1@		FcPattern *			@ARG1@		p
@TYPE2@		const char *			@ARG2@		object
@TYPE3@		int%  				@ARG3@ 		id
@TYPE4@		FcValue *			@ARG4@		v 
@PURPOSE@	Return a value from a pattern
@DESC@
Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value
associated with the property <parameter>object</parameter>.
The value returned is not a copy, but rather refers to the data stored
within the pattern directly.  Applications must not free this value.
@@

@TITLE@		FcPatternGet-Type
@PROTOTYPE@
@RET@ 		FcResult
@FUNC@		FcPatternGetInteger
@TYPE1@		FcPattern *			@ARG1@		p
@TYPE2@		const char *			@ARG2@		object
@TYPE3@		int%				@ARG3@		n
@TYPE4@		int *				@ARG4@		i

@PROTOTYPE+@
@RET+@		FcResult
@FUNC+@ 	FcPatternGetDouble
@TYPE1+@	FcPattern *			@ARG1+@		p
@TYPE2+@	const char *			@ARG2+@		object
@TYPE3+@	int%				@ARG3+@		n
@TYPE4+@	double *			@ARG4+@		d 

@PROTOTYPE++@
@RET++@ 	FcResult
@FUNC++@	FcPatternGetString
@TYPE1++@	FcPattern *			@ARG1++@	p
@TYPE2++@	const char *			@ARG2++@	object
@TYPE3++@	int%				@ARG3++@	n
@TYPE4++@	FcChar8 **			@ARG4++@	s

@PROTOTYPE+++@
@RET+++@	FcResult
@FUNC+++@	FcPatternGetMatrix 
@TYPE1+++@ 	FcPattern * 			@ARG1+++@ 	p 
@TYPE2+++@ 	const char * 			@ARG2+++@ 	object 
@TYPE3+++@ 	int%  				@ARG3+++@ 	n 
@TYPE4+++@ 	FcMatrix ** 			@ARG4+++@ 	s 

@PROTOTYPE++++@
@RET++++@ 	FcResult 
@FUNC++++@ 	FcPatternGetCharSet 
@TYPE1++++@ 	FcPattern * 			@ARG1++++@ 	p 
@TYPE2++++@ 	const char * 			@ARG2++++@ 	object 
@TYPE3++++@ 	int%  				@ARG3++++@ 	n 
@TYPE4++++@ 	FcCharSet ** 			@ARG4++++@ 	c 

@PROTOTYPE+++++@
@RET+++++@ 	FcResult 
@FUNC+++++@ 	FcPatternGetBool 		
@TYPE1+++++@ 	FcPattern * 			@ARG1+++++@ 	p
@TYPE2+++++@ 	const char * 			@ARG2+++++@ 	object 
@TYPE3+++++@ 	int%  				@ARG3+++++@ 	n 
@TYPE4+++++@ 	FcBool * 			@ARG4+++++@ 	b 

@PROTOTYPE++++++@
@RET++++++@	FcResult
@FUNC++++++@	FcPatternGetFTFace
@TYPE1++++++@ 	FcPattern * 			@ARG1++++++@ 	p
@TYPE2++++++@	const char *			@ARG2++++++@	object
@TYPE3+++++@ 	int%  				@ARG3+++++@ 	n
@TYPE3++++++@	FT_Face *			@ARG3++++++@	f

@PROTOTYPE+++++++@
@RET+++++++@	FcResult
@FUNC+++++++@	FcPatternGetLangSet
@TYPE1+++++++@ 	FcPattern * 			@ARG1+++++++@ 	p
@TYPE2+++++++@	const char *			@ARG2+++++++@	object
@TYPE3+++++@ 	int%  				@ARG3+++++@ 	n
@TYPE3+++++++@	FcLangSet **			@ARG3+++++++@	l

@PURPOSE@	Return a typed value from a pattern
@DESC@
These are convenience functions that call FcPatternGet and verify that the
returned data is of the expected type. They return FcResultTypeMismatch if
this is not the case.  Note that these (like FcPatternGet) do not make a
copy of any data structure referenced by the return value.  Use these
in preference to FcPatternGet to provide compile-time typechecking.
@@

@RET@		FcPattern *
@FUNC@		FcPatternBuild
@TYPE1@		FcPattern *			@ARG1@		pattern
@TYPE2@ 	...

@PROTOTYPE+@
@RET+@		FcPattern *
@FUNC+@		FcPatternVaBuild
@TYPE1+@	FcPattern *			@ARG1+@		pattern
@TYPE2+@	va_list% 			@ARG2+@		va

@PROTOTYPE++@
@RET++@		void
@FUNC++@	FcPatternVapBuild
@TYPE1++@	FcPattern *			@ARG1++@	result
@TYPE2++@	FcPattern *			@ARG2++@	pattern
@TYPE3++@	va_list%			@ARG3++@	va

@PURPOSE@	Create patterns from arguments
@DESC@
Builds a pattern using a list of objects, types and values.  Each
value to be entered in the pattern is specified with three arguments:
</para>
<orderedlist>
<listitem><para>
Object name, a string describing the property to be added.
</para></listitem><listitem><para>
Object type, one of the FcType enumerated values
</para></listitem><listitem><para>
Value, not an FcValue, but the raw type as passed to any of the
FcPatternAdd&lt;type&gt; functions.  Must match the type of the second
argument.
</para></listitem>
</orderedlist>
<para>
The argument list is terminated by a null object name, no object type nor
value need be passed for this.  The values are added to `pattern', if
`pattern' is null, a new pattern is created.  In either case, the pattern is
returned. Example
</para>
<programlisting>
pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0);
</programlisting>
<para>
FcPatternVaBuild is used when the arguments are already in the form of a
varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild
which returns its result directly in the <parameter>result</parameter>
variable.
@@

@RET@		FcBool
@FUNC@		FcPatternDel
@TYPE1@		FcPattern *			@ARG1@		p
@TYPE2@		const char *			@ARG2@		object 
@PURPOSE@	Delete a property from a pattern
@DESC@
Deletes all values associated with the property `object', returning 
whether the property existed or not.
@@

@RET@		FcBool
@FUNC@		FcPatternRemove
@TYPE1@		FcPattern *			@ARG1@		p
@TYPE2@		const char *			@ARG2@		object 
@TYPE3@		int%				@ARG3@		id
@PURPOSE@	Remove one object of the specified type from the pattern
@DESC@
Removes the value associated with the property `object' at position `id', returning 
whether the property existed and had a value at that position or not.
@@
		
@RET@		void
@FUNC@		FcPatternPrint
@TYPE1@		const FcPattern *		@ARG1@		p 
@PURPOSE@	Print a pattern for debugging
@DESC@
Prints an easily readable version of the pattern to stdout.  There is
no provision for reparsing data in this format, it's just for diagnostics
and debugging.
@@

@RET@		void 	
@FUNC@		FcDefaultSubstitute
@TYPE1@		FcPattern *			@ARG1@		pattern 
@PURPOSE@	Perform default substitutions in a pattern
@DESC@
Supplies default values for underspecified font patterns:
<itemizedlist>
<listitem><para>
Patterns without a specified style or weight are set to Medium
</para></listitem>
<listitem><para>
Patterns without a specified style or slant are set to Roman
</para></listitem>
<listitem><para>
Patterns without a specified pixel size are given one computed from any
specified point size (default 12), dpi (default 75) and scale (default 1).
</para></listitem>
</itemizedlist>
@@

@RET@		FcPattern *
@FUNC@		FcNameParse
@TYPE1@		const FcChar8 *			@ARG1@		name 
@PURPOSE@	Parse a pattern string
@DESC@
Converts <parameter>name</parameter> from the standard text format described above into a pattern.
@@

@RET@		FcChar8 *
@FUNC@		FcNameUnparse
@TYPE1@		FcPattern *			@ARG1@		pat 
@PURPOSE@	Convert a pattern back into a string that can be parsed
@DESC@
Converts the given pattern into the standard text format described above.
The return value is not static, but instead refers to newly allocated memory
which should be freed by the caller using free().
@@
Commit	Line	Data
	1	/*
	2	* fontconfig/doc/fcpattern.fncs
	3	*
	4	* Copyright © 2003 Keith Packard
	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
	10	* documentation, and that the name of the author(s) not be used in
	11	* advertising or publicity pertaining to distribution of the software without
	12	* specific, written prior permission. The authors make no
	13	* representations about the suitability of this software for any purpose. It
	14	* is provided "as is" without express or implied warranty.
	15	*
	16	* THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
	17	* INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
	18	* EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
	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	*/
	24	@RET@ FcPattern *
	25	@FUNC@ FcPatternCreate
	26	@TYPE1@ void
	27	@PURPOSE@ Create a pattern
	28	@DESC@
	29	Creates a pattern with no properties; used to build patterns from scratch.
	30	@@
	31
	32	@RET@ FcPattern *
	33	@FUNC@ FcPatternDuplicate
	34	@TYPE1@ const FcPattern * @ARG1@ p
	35	@PURPOSE@ Copy a pattern
	36	@DESC@
	37	Copy a pattern, returning a new pattern that matches
	38	<parameter>p</parameter>. Each pattern may be modified without affecting the
	39	other.
	40	@@
	41
	42	@RET@ void
	43	@FUNC@ FcPatternReference
	44	@TYPE1@ FcPattern * @ARG1@ p
	45	@PURPOSE@ Increment pattern reference count
	46	@DESC@
	47	Add another reference to <parameter>p</parameter>. Patterns are freed only
	48	when the reference count reaches zero.
	49	@@
	50
	51	@RET@ void
	52	@FUNC@ FcPatternDestroy
	53	@TYPE1@ FcPattern * @ARG1@ p
	54	@PURPOSE@ Destroy a pattern
	55	@DESC@
	56	Decrement the pattern reference count. If all references are gone, destroys
	57	the pattern, in the process destroying all related values.
	58	@@
	59
	60	@RET@ FcBool
	61	@FUNC@ FcPatternEqual
	62	@TYPE1@ const FcPattern * @ARG1@ pa
	63	@TYPE2@ const FcPattern * @ARG2@ pb
	64	@PURPOSE@ Compare patterns
	65	@DESC@
	66	Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> are exactly alike.
	67	@@
	68
	69	@RET@ FcBool
	70	@FUNC@ FcPatternEqualSubset
	71	@TYPE1@ const FcPattern * @ARG1@ pa
	72	@TYPE2@ const FcPattern * @ARG2@ pb
	73	@TYPE3@ const FcObjectSet * @ARG3@ os
	74	@PURPOSE@ Compare portions of patterns
	75	@DESC@
	76	Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> have exactly the same values for all of the
	77	objects in <parameter>os</parameter>.
	78	@@
	79
	80	@RET@ FcPattern *
	81	@FUNC@ FcPatternFilter
	82	@TYPE1@ FcPattern * @ARG1@ p
	83	@TYPE2@ const FcObjectSet * @ARG1@ os
	84	@PURPOSE@ Filter the objects of pattern
	85	@DESC@
	86	Returns a new pattern that only has those objects from
	87	<parameter>p</parameter> that are in <parameter>os</parameter>.
	88	If <parameter>os</parameter> is NULL, a duplicate of
	89	<parameter>p</parameter> is returned.
	90	@@
	91
	92	@RET@ FcChar32
	93	@FUNC@ FcPatternHash
	94	@TYPE1@ const FcPattern * @ARG1@ p
	95	@PURPOSE@ Compute a pattern hash value
	96	@DESC@
	97	Returns a 32-bit number which is the same for any two patterns which are
	98	equal.
	99	@@
	100
	101	@RET@ FcBool
	102	@FUNC@ FcPatternAdd
	103	@TYPE1@ FcPattern * @ARG1@ p
	104	@TYPE2@ const char * @ARG2@ object
	105	@TYPE3@ FcValue% @ARG3@ value
	106	@TYPE4@ FcBool% @ARG4@ append
	107	@PURPOSE@ Add a value to a pattern
	108	@DESC@
	109	Adds a single value to the list of values associated with the property named
	110	`object<parameter>. If `append</parameter> is FcTrue, the value is added at the end of any
	111	existing list, otherwise it is inserted at the beginning. `value' is saved
	112	(with FcValueSave) when inserted into the pattern so that the library
	113	retains no reference to any application-supplied data structure.
	114	@@
	115
	116	@RET@ FcBool
	117	@FUNC@ FcPatternAddWeak
	118	@TYPE1@ FcPattern * @ARG1@ p
	119	@TYPE2@ const char * @ARG2@ object
	120	@TYPE3@ FcValue% @ARG3@ value
	121	@TYPE4@ FcBool% @ARG4@ append
	122	@PURPOSE@ Add a value to a pattern with weak binding
	123	@DESC@
	124	FcPatternAddWeak is essentially the same as FcPatternAdd except that any
	125	values added to the list have binding <parameter>weak</parameter> instead of <parameter>strong</parameter>.
	126	@@
	127
	128	@TITLE@ FcPatternAdd-Type
	129	@RET@ FcBool
	130	@FUNC@ FcPatternAddInteger
	131	@TYPE1@ FcPattern * @ARG1@ p
	132	@TYPE2@ const char * @ARG2@ object
	133	@TYPE3@ int% @ARG3@ i
	134
	135	@PROTOTYPE+@
	136	@RET+@ FcBool
	137	@FUNC+@ FcPatternAddDouble
	138	@TYPE1+@ FcPattern * @ARG1+@ p
	139	@TYPE2+@ const char * @ARG2+@ object
	140	@TYPE3+@ double% @ARG3+@ d
	141
	142	@PROTOTYPE++@
	143	@RET++@ FcBool
	144	@FUNC++@ FcPatternAddString
	145	@TYPE1++@ FcPattern * @ARG1++@ p
	146	@TYPE2++@ const char * @ARG2++@ object
	147	@TYPE3++@ const FcChar8 * @ARG3++@ s
	148
	149	@PROTOTYPE+++@
	150	@RET+++@ FcBool
	151	@FUNC+++@ FcPatternAddMatrix
	152	@TYPE1+++@ FcPattern * @ARG1+++@ p
	153	@TYPE2+++@ const char * @ARG2+++@ object
	154	@TYPE3+++@ const FcMatrix * @ARG3+++@ m
	155
	156	@PROTOTYPE++++@
	157	@RET++++@ FcBool
	158	@FUNC++++@ FcPatternAddCharSet
	159	@TYPE1++++@ FcPattern * @ARG1++++@ p
	160	@TYPE2++++@ const char * @ARG2++++@ object
	161	@TYPE3++++@ const FcCharSet * @ARG3++++@ c
	162
	163	@PROTOTYPE+++++@
	164	@RET+++++@ FcBool
	165	@FUNC+++++@ FcPatternAddBool
	166	@TYPE1+++++@ FcPattern * @ARG1+++++@ p
	167	@TYPE2+++++@ const char * @ARG2+++++@ object
	168	@TYPE3+++++@ FcBool% @ARG3+++++@ b
	169
	170	@PROTOTYPE++++++@
	171	@RET++++++@ FcBool
	172	@FUNC++++++@ FcPatternAddFTFace
	173	@TYPE1++++++@ FcPattern * @ARG1++++++@ p
	174	@TYPE2++++++@ const char * @ARG2++++++@ object
	175	@TYPE3++++++@ const FT_Face @ARG3++++++@ f
	176
	177	@PROTOTYPE+++++++@
	178	@RET+++++++@ FcBool
	179	@FUNC+++++++@ FcPatternAddLangSet
	180	@TYPE1+++++++@ FcPattern * @ARG1+++++++@ p
	181	@TYPE2+++++++@ const char * @ARG2+++++++@ object
	182	@TYPE3+++++++@ const FcLangSet * @ARG3+++++++@ l
	183
	184	@PURPOSE@ Add a typed value to a pattern
	185	@DESC@
	186	These are all convenience functions that insert objects of the specified
	187	type into the pattern. Use these in preference to FcPatternAdd as they
	188	will provide compile-time typechecking. These all append values to
	189	any existing list of values.
	190	@@
	191
	192	@RET@ FcResult
	193	@FUNC@ FcPatternGet
	194	@TYPE1@ FcPattern * @ARG1@ p
	195	@TYPE2@ const char * @ARG2@ object
	196	@TYPE3@ int% @ARG3@ id
	197	@TYPE4@ FcValue * @ARG4@ v
	198	@PURPOSE@ Return a value from a pattern
	199	@DESC@
	200	Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value
	201	associated with the property <parameter>object</parameter>.
	202	The value returned is not a copy, but rather refers to the data stored
	203	within the pattern directly. Applications must not free this value.
	204	@@
	205
	206	@TITLE@ FcPatternGet-Type
	207	@PROTOTYPE@
	208	@RET@ FcResult
	209	@FUNC@ FcPatternGetInteger
	210	@TYPE1@ FcPattern * @ARG1@ p
	211	@TYPE2@ const char * @ARG2@ object
	212	@TYPE3@ int% @ARG3@ n
	213	@TYPE4@ int * @ARG4@ i
	214
	215	@PROTOTYPE+@
	216	@RET+@ FcResult
	217	@FUNC+@ FcPatternGetDouble
	218	@TYPE1+@ FcPattern * @ARG1+@ p
	219	@TYPE2+@ const char * @ARG2+@ object
	220	@TYPE3+@ int% @ARG3+@ n
	221	@TYPE4+@ double * @ARG4+@ d
	222
	223	@PROTOTYPE++@
	224	@RET++@ FcResult
	225	@FUNC++@ FcPatternGetString
	226	@TYPE1++@ FcPattern * @ARG1++@ p
	227	@TYPE2++@ const char * @ARG2++@ object
	228	@TYPE3++@ int% @ARG3++@ n
	229	@TYPE4++@ FcChar8 ** @ARG4++@ s
	230
	231	@PROTOTYPE+++@
	232	@RET+++@ FcResult
	233	@FUNC+++@ FcPatternGetMatrix
	234	@TYPE1+++@ FcPattern * @ARG1+++@ p
	235	@TYPE2+++@ const char * @ARG2+++@ object
	236	@TYPE3+++@ int% @ARG3+++@ n
	237	@TYPE4+++@ FcMatrix ** @ARG4+++@ s
	238
	239	@PROTOTYPE++++@
	240	@RET++++@ FcResult
	241	@FUNC++++@ FcPatternGetCharSet
	242	@TYPE1++++@ FcPattern * @ARG1++++@ p
	243	@TYPE2++++@ const char * @ARG2++++@ object
	244	@TYPE3++++@ int% @ARG3++++@ n
	245	@TYPE4++++@ FcCharSet ** @ARG4++++@ c
	246
	247	@PROTOTYPE+++++@
	248	@RET+++++@ FcResult
	249	@FUNC+++++@ FcPatternGetBool
	250	@TYPE1+++++@ FcPattern * @ARG1+++++@ p
	251	@TYPE2+++++@ const char * @ARG2+++++@ object
	252	@TYPE3+++++@ int% @ARG3+++++@ n
	253	@TYPE4+++++@ FcBool * @ARG4+++++@ b
	254
	255	@PROTOTYPE++++++@
	256	@RET++++++@ FcResult
	257	@FUNC++++++@ FcPatternGetFTFace
	258	@TYPE1++++++@ FcPattern * @ARG1++++++@ p
	259	@TYPE2++++++@ const char * @ARG2++++++@ object
	260	@TYPE3+++++@ int% @ARG3+++++@ n
	261	@TYPE3++++++@ FT_Face * @ARG3++++++@ f
	262
	263	@PROTOTYPE+++++++@
	264	@RET+++++++@ FcResult
	265	@FUNC+++++++@ FcPatternGetLangSet
	266	@TYPE1+++++++@ FcPattern * @ARG1+++++++@ p
	267	@TYPE2+++++++@ const char * @ARG2+++++++@ object
	268	@TYPE3+++++@ int% @ARG3+++++@ n
	269	@TYPE3+++++++@ FcLangSet ** @ARG3+++++++@ l
	270
	271	@PURPOSE@ Return a typed value from a pattern
	272	@DESC@
	273	These are convenience functions that call FcPatternGet and verify that the
	274	returned data is of the expected type. They return FcResultTypeMismatch if
	275	this is not the case. Note that these (like FcPatternGet) do not make a
	276	copy of any data structure referenced by the return value. Use these
	277	in preference to FcPatternGet to provide compile-time typechecking.
	278	@@
	279
	280	@RET@ FcPattern *
	281	@FUNC@ FcPatternBuild
	282	@TYPE1@ FcPattern * @ARG1@ pattern
	283	@TYPE2@ ...
	284
	285	@PROTOTYPE+@
	286	@RET+@ FcPattern *
	287	@FUNC+@ FcPatternVaBuild
	288	@TYPE1+@ FcPattern * @ARG1+@ pattern
	289	@TYPE2+@ va_list% @ARG2+@ va
	290
	291	@PROTOTYPE++@
	292	@RET++@ void
	293	@FUNC++@ FcPatternVapBuild
	294	@TYPE1++@ FcPattern * @ARG1++@ result
	295	@TYPE2++@ FcPattern * @ARG2++@ pattern
	296	@TYPE3++@ va_list% @ARG3++@ va
	297
	298	@PURPOSE@ Create patterns from arguments
	299	@DESC@
	300	Builds a pattern using a list of objects, types and values. Each
	301	value to be entered in the pattern is specified with three arguments:
	302	</para>
	303	<orderedlist>
	304	<listitem><para>
	305	Object name, a string describing the property to be added.
	306	</para></listitem><listitem><para>
	307	Object type, one of the FcType enumerated values
	308	</para></listitem><listitem><para>
	309	Value, not an FcValue, but the raw type as passed to any of the
	310	FcPatternAdd<type> functions. Must match the type of the second
	311	argument.
	312	</para></listitem>
	313	</orderedlist>
	314	<para>
	315	The argument list is terminated by a null object name, no object type nor
	316	value need be passed for this. The values are added to `pattern', if
	317	`pattern' is null, a new pattern is created. In either case, the pattern is
	318	returned. Example
	319	</para>
	320	<programlisting>
	321	pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0);
	322	</programlisting>
	323	<para>
	324	FcPatternVaBuild is used when the arguments are already in the form of a
	325	varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild
	326	which returns its result directly in the <parameter>result</parameter>
	327	variable.
	328	@@
	329
	330	@RET@ FcBool
	331	@FUNC@ FcPatternDel
	332	@TYPE1@ FcPattern * @ARG1@ p
	333	@TYPE2@ const char * @ARG2@ object
	334	@PURPOSE@ Delete a property from a pattern
	335	@DESC@
	336	Deletes all values associated with the property `object', returning
	337	whether the property existed or not.
	338	@@
	339
	340	@RET@ FcBool
	341	@FUNC@ FcPatternRemove
	342	@TYPE1@ FcPattern * @ARG1@ p
	343	@TYPE2@ const char * @ARG2@ object
	344	@TYPE3@ int% @ARG3@ id
	345	@PURPOSE@ Remove one object of the specified type from the pattern
	346	@DESC@
	347	Removes the value associated with the property `object' at position `id', returning
	348	whether the property existed and had a value at that position or not.
	349	@@
	350
	351	@RET@ void
	352	@FUNC@ FcPatternPrint
	353	@TYPE1@ const FcPattern * @ARG1@ p
	354	@PURPOSE@ Print a pattern for debugging
	355	@DESC@
	356	Prints an easily readable version of the pattern to stdout. There is
	357	no provision for reparsing data in this format, it's just for diagnostics
	358	and debugging.
	359	@@
	360
	361	@RET@ void
	362	@FUNC@ FcDefaultSubstitute
	363	@TYPE1@ FcPattern * @ARG1@ pattern
	364	@PURPOSE@ Perform default substitutions in a pattern
	365	@DESC@
	366	Supplies default values for underspecified font patterns:
	367	<itemizedlist>
	368	<listitem><para>
	369	Patterns without a specified style or weight are set to Medium
	370	</para></listitem>
	371	<listitem><para>
	372	Patterns without a specified style or slant are set to Roman
	373	</para></listitem>
	374	<listitem><para>
	375	Patterns without a specified pixel size are given one computed from any
	376	specified point size (default 12), dpi (default 75) and scale (default 1).
	377	</para></listitem>
	378	</itemizedlist>
	379	@@
	380
	381	@RET@ FcPattern *
	382	@FUNC@ FcNameParse
	383	@TYPE1@ const FcChar8 * @ARG1@ name
	384	@PURPOSE@ Parse a pattern string
	385	@DESC@
	386	Converts <parameter>name</parameter> from the standard text format described above into a pattern.
	387	@@
	388
	389	@RET@ FcChar8 *
	390	@FUNC@ FcNameUnparse
	391	@TYPE1@ FcPattern * @ARG1@ pat
	392	@PURPOSE@ Convert a pattern back into a string that can be parsed
	393	@DESC@
	394	Converts the given pattern into the standard text format described above.
	395	The return value is not static, but instead refers to newly allocated memory
	396	which should be freed by the caller using free().
	397	@@