fcstring.fncs revision ca08ab68 
1/*
2 * fontconfig/doc/fcstring.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    <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@
33Converts the next Unicode char from <parameter>src</parameter> into
34<parameter>dst</parameter> and returns the number of bytes containing the
35char.  <parameter>src</parameter> must 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@
45Converts the Unicode char from <parameter>src</parameter> into
46<parameter>dst</parameter> and returns the number of bytes needed to encode
47the 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@
58Counts 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
614 depending on the number of bytes needed to hold the largest Unicode char
62counted.  The return value indicates whether <parameter>src</parameter> is a
63well-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@
74Converts the next Unicode char from <parameter>src</parameter> into
75<parameter>dst</parameter> and returns the number of bytes containing the
76char. <parameter>src</parameter> must be at least <parameter>len</parameter>
77bytes long.  Bytes of <parameter>src</parameter> are combined into 16-bit
78units 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@
90Counts the number of Unicode chars in <parameter>len</parameter> bytes of
91<parameter>src</parameter>.  Bytes of <parameter>src</parameter> are
92combined into 16-bit units according to <parameter>endian</parameter>.
93Places that count in <parameter>nchar</parameter>.
94<parameter>wchar</parameter> contains 1, 2 or 4 depending on the number of
95bytes needed to hold the largest Unicode char counted.  The return value
96indicates whether <parameter>string</parameter> is a well-formed UTF16
97string.
98@@
99
100@RET@		FcBool
101@FUNC@		FcIsLower
102@TYPE1@		FcChar8				@ARG1@		c
103@PURPOSE@	check for lower case ASCII character
104@DESC@
105This macro checks whether <parameter>c</parameter> is an lower case ASCII
106letter.
107@@
108
109@RET@		FcBool
110@FUNC@		FcIsUpper
111@TYPE1@		FcChar8				@ARG1@		c
112@PURPOSE@	check for upper case ASCII character
113@DESC@
114This macro checks whether <parameter>c</parameter> is a upper case ASCII
115letter.
116@@
117
118@RET@		FcChar8
119@FUNC@		FcToLower
120@TYPE1@		FcChar8				@ARG1@		c
121@PURPOSE@	convert upper case ASCII to lower case
122@DESC@
123This macro converts upper case ASCII <parameter>c</parameter> to the
124equivalent lower case letter.
125@@
126
127@RET@		FcChar8 *
128@FUNC@		FcStrCopy
129@TYPE1@		const FcChar8 *			@ARG1@		s
130@PURPOSE@	duplicate a string
131@DESC@
132Allocates memory, copies <parameter>s</parameter> and returns the resulting
133buffer.  Yes, this is <function>strdup</function>, but that function isn't
134available on every platform.
135@@
136
137@RET@		FcChar8 *
138@FUNC@		FcStrDowncase
139@TYPE1@		const FcChar8 *			@ARG1@		s
140@PURPOSE@	create a lower case translation of a string
141@DESC@
142Allocates memory, copies <parameter>s</parameter>, converting upper case
143letters to lower case and returns the allocated buffer.
144@@
145
146@RET@		FcChar8 *
147@FUNC@		FcStrCopyFilename
148@TYPE1@		const FcChar8 *			@ARG1@		s
149@PURPOSE@	create a complete path from a filename
150@DESC@
151<function>FcStrCopyFilename</function> constructs an absolute pathname from
152<parameter>s</parameter>. It converts any leading '~' characters in
153to the value of the HOME environment variable, and any relative paths are
154converted to absolute paths using the current working directory. Sequences
155of '/' characters are converted to a single '/', and names containing the
156current directory '.' or parent directory '..' are correctly reconstructed.
157Returns NULL if '~' is the leading character and HOME is unset or disabled
158(see <function>FcConfigEnableHome</function>).
159@@
160
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@
167Returns the usual &lt;0, 0, &gt;0 result of comparing
168<parameter>s1</parameter> and <parameter>s2</parameter>. 
169@@
170
171@RET@		int
172@FUNC@		FcStrCmpIgnoreCase
173@TYPE1@		const FcChar8 *			@ARG1@		s1
174@TYPE2@		const FcChar8 *			@ARG2@		s2
175@PURPOSE@	compare UTF-8 strings ignoring case
176@DESC@
177Returns the usual &lt;0, 0, &gt;0 result of comparing
178<parameter>s1</parameter> and <parameter>s2</parameter>. This test is
179case-insensitive for all proper UTF-8 encoded strings.
180@@
181
182@RET@		FcChar8 *
183@FUNC@		FcStrStr
184@TYPE1@		const FcChar8 *			@ARG1@		s1
185@TYPE2@		const FcChar8 *			@ARG2@		s2
186@PURPOSE@	locate UTF-8 substring
187@DESC@
188Returns the location of <parameter>s2</parameter> in
189<parameter>s1</parameter>.  Returns NULL if <parameter>s2</parameter>
190is not present in <parameter>s1</parameter>. This test will operate properly
191with UTF8 encoded strings.
192@@
193
194@RET@		FcChar8 *
195@FUNC@		FcStrStrIgnoreCase
196@TYPE1@		const FcChar8 *			@ARG1@		s1
197@TYPE2@		const FcChar8 *			@ARG2@		s2
198@PURPOSE@	locate UTF-8 substring ignoring ASCII case
199@DESC@
200Returns the location of <parameter>s2</parameter> in 
201<parameter>s1</parameter>, ignoring case.  Returns NULL if
202<parameter>s2</parameter> is not present in <parameter>s1</parameter>.
203This test is case-insensitive for all proper UTF-8 encoded strings.
204@@
205
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@
212This function allocates new storage and places the concatenation of
213<parameter>s1</parameter> and <parameter>s2</parameter> there, returning the
214new string.
215@@
216
217@RET@		void
218@FUNC@		FcStrFree
219@TYPE1@		FcChar8 *			@ARG1@		s
220@PURPOSE@	free a string
221@DESC@
222This is just a wrapper around free(3) which helps track memory usage of
223strings within the fontconfig library.
224@@
225
226@RET@		FcChar8 *
227@FUNC@		FcStrDirname
228@TYPE1@		const FcChar8 *			@ARG1@		file
229@PURPOSE@	directory part of filename
230@DESC@
231Returns the directory containing <parameter>file</parameter>.  This
232is returned in newly allocated storage which should be freed when no longer
233needed.
234@@
235
236@RET@		FcChar8 *
237@FUNC@		FcStrBasename
238@TYPE1@		const FcChar8 *			@ARG1@		file
239@PURPOSE@	last component of filename
240@DESC@
241Returns the filename of <parameter>file</parameter> stripped of any leading
242directory names.  This is returned in newly allocated storage which should
243be freed when no longer needed.
244@@
245