[fontconfig.git] / doc / fcstring.fncs

/*
 * $Id$
 *
 * 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.
 */
    <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> nust 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@		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@		FcStrCopyFilename
@TYPE1@		const FcChar8 *			@ARG1@		s
@PURPOSE@	copy a string, expanding '~'
@DESC@
Just like FcStrCopy except that it converts any leading '~' characters in
<parameter>s</parameter> to the value of the HOME environment variable.
Returns NULL if '~' is present in <parameter>s</parameter> and HOME is unset.
@@

@RET@		int
@FUNC@		FcStrCmpIgnoreCase
@TYPE1@		const char *			@ARG1@		s1
@TYPE2@		const char *			@ARG2@		s2
@PURPOSE@	compare UTF-8 strings ignoring ASCII 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 in the ASCII range and will operate properly with UTF8
encoded strings, although it does not check for well formed strings.
@@

@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 KP	1	/*
	2	* $Id$
	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
	10	* documentation, and that the name of Keith Packard not be used in
	11	* advertising or publicity pertaining to distribution of the software without
	12	* specific, written prior permission. Keith Packard makes 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	* KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
	17	* INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
	18	* EVENT SHALL KEITH PACKARD 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	<variablelist>
	25
	26	@RET@ int
	27	@FUNC@ FcUtf8ToUcs4
	28	@TYPE1@ FcChar8 * @ARG1@ src
	29	@TYPE2@ FcChar32 * @ARG2@ dst
	30	@TYPE3@ int @ARG3@ len
	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
	35	char. <parameter>src</parameter> nust be at least
	36	<parameter>len</parameter> bytes long.
	37	@@
	38
	39	@RET@ int
	40	@FUNC@ FcUcs4ToUtf8
	41	@TYPE1@ FcChar32 @ARG1@ src
	42	@TYPE2@ FcChar8 @ARG2@ dst[FC_UTF8_MAX_LEN]
	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
	53	@TYPE2@ int @ARG2@ len
	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
	61	4 depending on the number of bytes needed to hold the largest unicode char
	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
69	@TYPE2@ FcEndian @ARG2@ endian
70	@TYPE3@ FcChar32 * @ARG3@ dst
71	@TYPE4@ int @ARG4@ len
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
84	@TYPE2@ FcEndian @ARG2@ endian
85	@TYPE3@ int @ARG3@ len
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
95	bytes needed to hold the largest unicode char counted. The return value
96	indicates whether <parameter>string</parameter> is a well-formed UTF16
97	string.
98	@@
99
100	@RET@ FcChar8 *
101	@FUNC@ FcStrCopy
102	@TYPE1@ const FcChar8 * @ARG1@ s
103	@PURPOSE@ duplicate a string
104	@DESC@
105	Allocates memory, copies <parameter>s</parameter> and returns the resulting
106	buffer. Yes, this is <function>strdup</function>, but that function isn't
107	available on every platform.
108	@@
109
110	@RET@ FcChar8 *
111	@FUNC@ FcStrCopyFilename
112	@TYPE1@ const FcChar8 * @ARG1@ s
113	@PURPOSE@ copy a string, expanding '~'
114	@DESC@
115	Just like FcStrCopy except that it converts any leading '~' characters in
116	<parameter>s</parameter> to the value of the HOME environment variable.
117	Returns NULL if '~' is present in <parameter>s</parameter> and HOME is unset.
118	@@
119
120	@RET@ int
121	@FUNC@ FcStrCmpIgnoreCase
122	@TYPE1@ const char * @ARG1@ s1
123	@TYPE2@ const char * @ARG2@ s2
124	@PURPOSE@ compare UTF-8 strings ignoring ASCII case
125	@DESC@
126	Returns the usual <0, 0, >0 result of comparing
127	<parameter>s1</parameter> and <parameter>s2</parameter>. This test is
128	case-insensitive in the ASCII range and will operate properly with UTF8
129	encoded strings, although it does not check for well formed strings.
130	@@
131
132	@RET@ FcChar8 *
133	@FUNC@ FcStrDirname
134	@TYPE1@ const FcChar8 * @ARG1@ file
135	@PURPOSE@ directory part of filename
136	@DESC@
137	Returns the directory containing <parameter>file</parameter>. This
138	is returned in newly allocated storage which should be freed when no longer
139	needed.
140	@@
141
142	@RET@ FcChar8 *
143	@FUNC@ FcStrBasename
144	@TYPE1@ const FcChar8 * @ARG1@ file
145	@PURPOSE@ last component of filename
146	@DESC@
147	Returns the filename of <parameter>file</parameter> stripped of any leading
148	directory names. This is returned in newly allocated storage which should
149	be freed when no longer needed.
150	@@