[fontconfig.git] / doc / fcstring.fncs

/*
 * fontconfig/doc/fcstring.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.
 */
    <variablelist>

@RET@		int
@FUNC@		FcUtf8ToUcs4 
@TYPE1@		FcChar8 *			@ARG1@		src
@TYPE2@		FcChar32 *			@ARG2@		dst
@TYPE3@		int% 				@ARG3@		len
@PURPOSE@	convert UTF-8 to UCS4
@DESC@
Converts the next Unicode char from <parameter>src</parameter> into
<parameter>dst</parameter> and returns the number of bytes containing the
char.  <parameter>src</parameter> must be at least
<parameter>len</parameter> bytes long.
@@

@RET@		int 
@FUNC@		FcUcs4ToUtf8
@TYPE1@		FcChar32% 			@ARG1@		src	 
@TYPE2@		FcChar8% 			@ARG2@		dst[FC_UTF8_MAX_LEN]
@PURPOSE@	convert UCS4 to UTF-8
@DESC@
Converts the Unicode char from <parameter>src</parameter> into
<parameter>dst</parameter> and returns the number of bytes needed to encode
the char.
@@

@RET@		FcBool 
@FUNC@		FcUtf8Len
@TYPE1@		FcChar8 *			@ARG1@		src
@TYPE2@		int% 				@ARG2@		len
@TYPE3@		int *				@ARG3@		nchar
@TYPE4@		int *				@ARG4@		wchar
@PURPOSE@	count UTF-8 encoded chars
@DESC@
Counts the number of Unicode chars in <parameter>len</parameter> bytes of
<parameter>src</parameter>.  Places that count in
<parameter>nchar</parameter>.  <parameter>wchar</parameter> contains 1, 2 or
4 depending on the number of bytes needed to hold the largest Unicode char
counted.  The return value indicates whether <parameter>src</parameter> is a
well-formed UTF8 string.
@@

@RET@		int 
@FUNC@		FcUtf16ToUcs4
@TYPE1@		FcChar8 *			@ARG1@		src
@TYPE2@		FcEndian% 			@ARG2@		endian
@TYPE3@		FcChar32 *			@ARG3@		dst
@TYPE4@		int% 				@ARG4@		len
@PURPOSE@	convert UTF-16 to UCS4
@DESC@
Converts the next Unicode char from <parameter>src</parameter> into
<parameter>dst</parameter> and returns the number of bytes containing the
char. <parameter>src</parameter> must be at least <parameter>len</parameter>
bytes long.  Bytes of <parameter>src</parameter> are combined into 16-bit
units according to <parameter>endian</parameter>.
@@

@RET@		FcBool
@FUNC@		FcUtf16Len
@TYPE1@		FcChar8 *			@ARG1@		src
@TYPE2@		FcEndian% 			@ARG2@		endian
@TYPE3@		int% 				@ARG3@		len
@TYPE4@		int *				@ARG4@		nchar
@TYPE5@		int *				@ARG5@		wchar
@PURPOSE@	count UTF-16 encoded chars
@DESC@
Counts the number of Unicode chars in <parameter>len</parameter> bytes of
<parameter>src</parameter>.  Bytes of <parameter>src</parameter> are
combined into 16-bit units according to <parameter>endian</parameter>.
Places that count in <parameter>nchar</parameter>.
<parameter>wchar</parameter> contains 1, 2 or 4 depending on the number of
bytes needed to hold the largest Unicode char counted.  The return value
indicates whether <parameter>string</parameter> is a well-formed UTF16
string.
@@

@RET@		FcBool
@FUNC@		FcIsLower
@TYPE1@		FcChar8				@ARG1@		c
@PURPOSE@	check for lower case ASCII character
@DESC@
This macro checks whether <parameter>c</parameter> is an lower case ASCII
letter.
@@

@RET@		FcBool
@FUNC@		FcIsUpper
@TYPE1@		FcChar8				@ARG1@		c
@PURPOSE@	check for upper case ASCII character
@DESC@
This macro checks whether <parameter>c</parameter> is a upper case ASCII
letter.
@@

@RET@		FcChar8
@FUNC@		FcToLower
@TYPE1@		FcChar8				@ARG1@		c
@PURPOSE@	convert upper case ASCII to lower case
@DESC@
This macro converts upper case ASCII <parameter>c</parameter> to the
equivalent lower case letter.
@@

@RET@		FcChar8 *
@FUNC@		FcStrCopy
@TYPE1@		const FcChar8 *			@ARG1@		s
@PURPOSE@	duplicate a string
@DESC@
Allocates memory, copies <parameter>s</parameter> and returns the resulting
buffer.  Yes, this is <function>strdup</function>, but that function isn't
available on every platform.
@@

@RET@		FcChar8 *
@FUNC@		FcStrDowncase
@TYPE1@		const FcChar8 *			@ARG1@		s
@PURPOSE@	create a lower case translation of a string
@DESC@
Allocates memory, copies <parameter>s</parameter>, converting upper case
letters to lower case and returns the allocated buffer.
@@

@RET@		FcChar8 *
@FUNC@		FcStrCopyFilename
@TYPE1@		const FcChar8 *			@ARG1@		s
@PURPOSE@	create a complete path from a filename
@DESC@
<function>FcStrCopyFilename</function> constructs an absolute pathname from
<parameter>s</parameter>. It converts any leading '~' characters in
to the value of the HOME environment variable, and any relative paths are
converted to absolute paths using the current working directory. Sequences
of '/' characters are converted to a single '/', and names containing the
current directory '.' or parent directory '..' are correctly reconstructed.
Returns NULL if '~' is the leading character and HOME is unset or disabled
(see <function>FcConfigEnableHome</function>).
@@

@RET@		int
@FUNC@		FcStrCmp
@TYPE1@		const FcChar8 *			@ARG1@		s1
@TYPE2@		const FcChar8 *			@ARG2@		s2
@PURPOSE@	compare UTF-8 strings
@DESC@
Returns the usual &lt;0, 0, &gt;0 result of comparing
<parameter>s1</parameter> and <parameter>s2</parameter>. 
@@

@RET@		int
@FUNC@		FcStrCmpIgnoreCase
@TYPE1@		const FcChar8 *			@ARG1@		s1
@TYPE2@		const FcChar8 *			@ARG2@		s2
@PURPOSE@	compare UTF-8 strings ignoring case
@DESC@
Returns the usual &lt;0, 0, &gt;0 result of comparing
<parameter>s1</parameter> and <parameter>s2</parameter>. This test is
case-insensitive for all proper UTF-8 encoded strings.
@@

@RET@		FcChar8 *
@FUNC@		FcStrStr
@TYPE1@		const FcChar8 *			@ARG1@		s1
@TYPE2@		const FcChar8 *			@ARG2@		s2
@PURPOSE@	locate UTF-8 substring
@DESC@
Returns the location of <parameter>s2</parameter> in
<parameter>s1</parameter>.  Returns NULL if <parameter>s2</parameter>
is not present in <parameter>s1</parameter>. This test will operate properly
with UTF8 encoded strings.
@@

@RET@		FcChar8 *
@FUNC@		FcStrStrIgnoreCase
@TYPE1@		const FcChar8 *			@ARG1@		s1
@TYPE2@		const FcChar8 *			@ARG2@		s2
@PURPOSE@	locate UTF-8 substring ignoring ASCII case
@DESC@
Returns the location of <parameter>s2</parameter> in 
<parameter>s1</parameter>, ignoring case.  Returns NULL if
<parameter>s2</parameter> is not present in <parameter>s1</parameter>.
This test is case-insensitive for all proper UTF-8 encoded strings.
@@

@RET@		FcChar8 *
@FUNC@		FcStrPlus
@TYPE1@		const FcChar8 *			@ARG1@		s1
@TYPE2@		const FcChar8 *			@ARG2@		s2
@PURPOSE@	concatenate two strings
@DESC@
This function allocates new storage and places the concatenation of
<parameter>s1</parameter> and <parameter>s2</parameter> there, returning the
new string.
@@

@RET@		void
@FUNC@		FcStrFree
@TYPE1@		FcChar8 *			@ARG1@		s
@PURPOSE@	free a string
@DESC@
This is just a wrapper around free(3) which helps track memory usage of
strings within the fontconfig library.
@@

@RET@		FcChar8 *
@FUNC@		FcStrDirname
@TYPE1@		const FcChar8 *			@ARG1@		file
@PURPOSE@	directory part of filename
@DESC@
Returns the directory containing <parameter>file</parameter>.  This
is returned in newly allocated storage which should be freed when no longer
needed.
@@

@RET@		FcChar8 *
@FUNC@		FcStrBasename
@TYPE1@		const FcChar8 *			@ARG1@		file
@PURPOSE@	last component of filename
@DESC@
Returns the filename of <parameter>file</parameter> stripped of any leading
directory names.  This is returned in newly allocated storage which should
be freed when no longer needed.
@@
Commit	Line	Data
39381776	1	/*
e690fbb2	2	* fontconfig/doc/fcstring.fncs
39381776	3	*
46b51147	4	* Copyright © 2003 Keith Packard
39381776 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
39381776	11	* advertising or publicity pertaining to distribution of the software without
5aaf466d	12	* specific, written prior permission. The authors make no
39381776 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,
39381776	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
39381776 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	*/
	24	<variablelist>
	25
	26	@RET@ int
	27	@FUNC@ FcUtf8ToUcs4
	28	@TYPE1@ FcChar8 * @ARG1@ src
	29	@TYPE2@ FcChar32 * @ARG2@ dst
61895ed1	30	@TYPE3@ int% @ARG3@ len
39381776 KP	31	@PURPOSE@ convert UTF-8 to UCS4
	32	@DESC@
	33	Converts the next Unicode char from <parameter>src</parameter> into
	34	<parameter>dst</parameter> and returns the number of bytes containing the
61139cf6	35	char. <parameter>src</parameter> must be at least
39381776 KP	36	<parameter>len</parameter> bytes long.
	37	@@
	38
	39	@RET@ int
	40	@FUNC@ FcUcs4ToUtf8
61895ed1 KP	41	@TYPE1@ FcChar32% @ARG1@ src
61895ed1 KP	42	@TYPE2@ FcChar8% @ARG2@ dst[FC_UTF8_MAX_LEN]
39381776 KP	43	@PURPOSE@ convert UCS4 to UTF-8
	44	@DESC@
	45	Converts the Unicode char from <parameter>src</parameter> into
	46	<parameter>dst</parameter> and returns the number of bytes needed to encode
	47	the char.
	48	@@
	49
	50	@RET@ FcBool
	51	@FUNC@ FcUtf8Len
	52	@TYPE1@ FcChar8 * @ARG1@ src
61895ed1	53	@TYPE2@ int% @ARG2@ len
39381776 KP	54	@TYPE3@ int * @ARG3@ nchar
	55	@TYPE4@ int * @ARG4@ wchar
	56	@PURPOSE@ count UTF-8 encoded chars
	57	@DESC@
	58	Counts the number of Unicode chars in <parameter>len</parameter> bytes of
	59	<parameter>src</parameter>. Places that count in
	60	<parameter>nchar</parameter>. <parameter>wchar</parameter> contains 1, 2 or
7baa20c7	61	4 depending on the number of bytes needed to hold the largest Unicode char
39381776 KP	62	counted. The return value indicates whether <parameter>src</parameter> is a
	63	well-formed UTF8 string.
	64	@@
	65
	66	@RET@ int
	67	@FUNC@ FcUtf16ToUcs4
	68	@TYPE1@ FcChar8 * @ARG1@ src
61895ed1	69	@TYPE2@ FcEndian% @ARG2@ endian
39381776	70	@TYPE3@ FcChar32 * @ARG3@ dst
61895ed1	71	@TYPE4@ int% @ARG4@ len
39381776 KP	72	@PURPOSE@ convert UTF-16 to UCS4
	73	@DESC@
	74	Converts the next Unicode char from <parameter>src</parameter> into
	75	<parameter>dst</parameter> and returns the number of bytes containing the
	76	char. <parameter>src</parameter> must be at least <parameter>len</parameter>
	77	bytes long. Bytes of <parameter>src</parameter> are combined into 16-bit
	78	units according to <parameter>endian</parameter>.
	79	@@
	80
	81	@RET@ FcBool
	82	@FUNC@ FcUtf16Len
	83	@TYPE1@ FcChar8 * @ARG1@ src
61895ed1 KP	84	@TYPE2@ FcEndian% @ARG2@ endian
61895ed1 KP	85	@TYPE3@ int% @ARG3@ len
39381776 KP	86	@TYPE4@ int * @ARG4@ nchar
	87	@TYPE5@ int * @ARG5@ wchar
	88	@PURPOSE@ count UTF-16 encoded chars
	89	@DESC@
	90	Counts the number of Unicode chars in <parameter>len</parameter> bytes of
	91	<parameter>src</parameter>. Bytes of <parameter>src</parameter> are
	92	combined into 16-bit units according to <parameter>endian</parameter>.
	93	Places that count in <parameter>nchar</parameter>.
	94	<parameter>wchar</parameter> contains 1, 2 or 4 depending on the number of
7baa20c7	95	bytes needed to hold the largest Unicode char counted. The return value
39381776 KP	96	indicates whether <parameter>string</parameter> is a well-formed UTF16
	97	string.
	98	@@
	99
a190678e KP	100	@RET@ FcBool
	101	@FUNC@ FcIsLower
	102	@TYPE1@ FcChar8 @ARG1@ c
	103	@PURPOSE@ check for lower case ASCII character
	104	@DESC@
	105	This macro checks whether <parameter>c</parameter> is an lower case ASCII
	106	letter.
	107	@@
	108
	109	@RET@ FcBool
	110	@FUNC@ FcIsUpper
	111	@TYPE1@ FcChar8 @ARG1@ c
	112	@PURPOSE@ check for upper case ASCII character
	113	@DESC@
	114	This macro checks whether <parameter>c</parameter> is a upper case ASCII
	115	letter.
	116	@@
	117
	118	@RET@ FcChar8
	119	@FUNC@ FcToLower
	120	@TYPE1@ FcChar8 @ARG1@ c
	121	@PURPOSE@ convert upper case ASCII to lower case
	122	@DESC@
	123	This macro converts upper case ASCII <parameter>c</parameter> to the
	124	equivalent lower case letter.
	125	@@
	126
39381776 KP	127	@RET@ FcChar8 *
	128	@FUNC@ FcStrCopy
	129	@TYPE1@ const FcChar8 * @ARG1@ s
	130	@PURPOSE@ duplicate a string
	131	@DESC@
	132	Allocates memory, copies <parameter>s</parameter> and returns the resulting
	133	buffer. Yes, this is <function>strdup</function>, but that function isn't
	134	available on every platform.
	135	@@
	136
0c009d2b KP	137	@RET@ FcChar8 *
	138	@FUNC@ FcStrDowncase
	139	@TYPE1@ const FcChar8 * @ARG1@ s
	140	@PURPOSE@ create a lower case translation of a string
	141	@DESC@
	142	Allocates memory, copies <parameter>s</parameter>, converting upper case
	143	letters to lower case and returns the allocated buffer.
	144	@@
	145
39381776 KP	146	@RET@ FcChar8 *
	147	@FUNC@ FcStrCopyFilename
	148	@TYPE1@ const FcChar8 * @ARG1@ s
026fe895	149	@PURPOSE@ create a complete path from a filename
39381776	150	@DESC@
026fe895 KP	151	<function>FcStrCopyFilename</function> constructs an absolute pathname from
	152	<parameter>s</parameter>. It converts any leading '~' characters in
	153	to the value of the HOME environment variable, and any relative paths are
	154	converted to absolute paths using the current working directory. Sequences
	155	of '/' characters are converted to a single '/', and names containing the
	156	current directory '.' or parent directory '..' are correctly reconstructed.
	157	Returns NULL if '~' is the leading character and HOME is unset or disabled
	158	(see <function>FcConfigEnableHome</function>).
39381776 KP	159	@@
39381776 KP	160
a190678e KP	161	@RET@ int
	162	@FUNC@ FcStrCmp
	163	@TYPE1@ const FcChar8 * @ARG1@ s1
	164	@TYPE2@ const FcChar8 * @ARG2@ s2
	165	@PURPOSE@ compare UTF-8 strings
	166	@DESC@
	167	Returns the usual <0, 0, >0 result of comparing
	168	<parameter>s1</parameter> and <parameter>s2</parameter>.
	169	@@
	170
39381776 KP	171	@RET@ int
39381776 KP	172	@FUNC@ FcStrCmpIgnoreCase
0c009d2b KP	173	@TYPE1@ const FcChar8 * @ARG1@ s1
0c009d2b KP	174	@TYPE2@ const FcChar8 * @ARG2@ s2
a190678e	175	@PURPOSE@ compare UTF-8 strings ignoring case
39381776 KP	176	@DESC@
39381776 KP	177	Returns the usual <0, 0, >0 result of comparing
a190678e KP	178	<parameter>s1</parameter> and <parameter>s2</parameter>. This test is
a190678e KP	179	case-insensitive for all proper UTF-8 encoded strings.
39381776 KP	180	@@
39381776 KP	181
0c009d2b KP	182	@RET@ FcChar8 *
0c009d2b KP	183	@FUNC@ FcStrStr
a190678e KP	184	@TYPE1@ const FcChar8 * @ARG1@ s1
a190678e KP	185	@TYPE2@ const FcChar8 * @ARG2@ s2
0c009d2b KP	186	@PURPOSE@ locate UTF-8 substring
	187	@DESC@
	188	Returns the location of <parameter>s2</parameter> in
	189	<parameter>s1</parameter>. Returns NULL if <parameter>s2</parameter>
	190	is not present in <parameter>s1</parameter>. This test will operate properly
a190678e	191	with UTF8 encoded strings.
0c009d2b KP	192	@@
	193
	194	@RET@ FcChar8 *
	195	@FUNC@ FcStrStrIgnoreCase
a190678e KP	196	@TYPE1@ const FcChar8 * @ARG1@ s1
a190678e KP	197	@TYPE2@ const FcChar8 * @ARG2@ s2
0c009d2b KP	198	@PURPOSE@ locate UTF-8 substring ignoring ASCII case
	199	@DESC@
	200	Returns the location of <parameter>s2</parameter> in
a190678e	201	<parameter>s1</parameter>, ignoring case. Returns NULL if
0c009d2b	202	<parameter>s2</parameter> is not present in <parameter>s1</parameter>.
a190678e	203	This test is case-insensitive for all proper UTF-8 encoded strings.
0c009d2b KP	204	@@
0c009d2b KP	205
a190678e KP	206	@RET@ FcChar8 *
	207	@FUNC@ FcStrPlus
	208	@TYPE1@ const FcChar8 * @ARG1@ s1
	209	@TYPE2@ const FcChar8 * @ARG2@ s2
	210	@PURPOSE@ concatenate two strings
	211	@DESC@
	212	This function allocates new storage and places the concatenation of
	213	<parameter>s1</parameter> and <parameter>s2</parameter> there, returning the
	214	new string.
	215	@@
	216
	217	@RET@ void
	218	@FUNC@ FcStrFree
	219	@TYPE1@ FcChar8 * @ARG1@ s
	220	@PURPOSE@ free a string
	221	@DESC@
	222	This is just a wrapper around free(3) which helps track memory usage of
	223	strings within the fontconfig library.
0faca4ff	224	@@
a190678e	225
39381776 KP	226	@RET@ FcChar8 *
	227	@FUNC@ FcStrDirname
	228	@TYPE1@ const FcChar8 * @ARG1@ file
	229	@PURPOSE@ directory part of filename
	230	@DESC@
	231	Returns the directory containing <parameter>file</parameter>. This
	232	is returned in newly allocated storage which should be freed when no longer
	233	needed.
	234	@@
	235
	236	@RET@ FcChar8 *
	237	@FUNC@ FcStrBasename
	238	@TYPE1@ const FcChar8 * @ARG1@ file
	239	@PURPOSE@ last component of filename
	240	@DESC@
	241	Returns the filename of <parameter>file</parameter> stripped of any leading
	242	directory names. This is returned in newly allocated storage which should
	243	be freed when no longer needed.
	244	@@