fcstring.fncs 8.42 KB
Newer Older
1
/*
Behdad Esfahbod's avatar
Behdad Esfahbod committed
2
 * fontconfig/doc/fcstring.fncs
3
 *
4
 * Copyright © 2003 Keith Packard
5 6 7 8 9
 *
 * 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
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 14 15
 * representations about the suitability of this software for any purpose.  It
 * is provided "as is" without express or implied warranty.
 *
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 20 21 22 23 24 25 26 27 28 29
 * 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
30
@TYPE3@		int% 				@ARG3@		len
31 32 33 34
@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
35
char.  <parameter>src</parameter> must be at least
36 37 38 39 40
<parameter>len</parameter> bytes long.
@@

@RET@		int 
@FUNC@		FcUcs4ToUtf8
41 42
@TYPE1@		FcChar32% 			@ARG1@		src	 
@TYPE2@		FcChar8% 			@ARG2@		dst[FC_UTF8_MAX_LEN]
43 44 45 46 47 48 49 50 51 52
@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
53
@TYPE2@		int% 				@ARG2@		len
54 55 56 57 58 59 60
@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
Brad Hards's avatar
Brad Hards committed
61
4 depending on the number of bytes needed to hold the largest Unicode char
62 63 64 65 66 67 68
counted.  The return value indicates whether <parameter>src</parameter> is a
well-formed UTF8 string.
@@

@RET@		int 
@FUNC@		FcUtf16ToUcs4
@TYPE1@		FcChar8 *			@ARG1@		src
69
@TYPE2@		FcEndian% 			@ARG2@		endian
70
@TYPE3@		FcChar32 *			@ARG3@		dst
71
@TYPE4@		int% 				@ARG4@		len
72 73 74 75 76 77 78 79 80 81 82 83
@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
84 85
@TYPE2@		FcEndian% 			@ARG2@		endian
@TYPE3@		int% 				@ARG3@		len
86 87 88 89 90 91 92 93 94
@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
Brad Hards's avatar
Brad Hards committed
95
bytes needed to hold the largest Unicode char counted.  The return value
96 97 98 99
indicates whether <parameter>string</parameter> is a well-formed UTF16
string.
@@

100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126
@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.
@@

127 128 129 130 131 132 133 134 135 136
@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.
@@

137 138 139 140 141 142 143 144 145
@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.
@@

146 147 148
@RET@		FcChar8 *
@FUNC@		FcStrCopyFilename
@TYPE1@		const FcChar8 *			@ARG1@		s
149
@PURPOSE@	create a complete path from a filename
150
@DESC@
151 152 153 154 155 156 157 158
<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>).
159 160
@@

161 162 163 164 165 166 167 168 169 170
@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>. 
@@

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

182 183
@RET@		FcChar8 *
@FUNC@		FcStrStr
184 185
@TYPE1@		const FcChar8 *			@ARG1@		s1
@TYPE2@		const FcChar8 *			@ARG2@		s2
186 187 188 189 190
@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
191
with UTF8 encoded strings.
192 193 194 195
@@

@RET@		FcChar8 *
@FUNC@		FcStrStrIgnoreCase
196 197
@TYPE1@		const FcChar8 *			@ARG1@		s1
@TYPE2@		const FcChar8 *			@ARG2@		s2
198
@PURPOSE@	locate UTF-8 substring ignoring case
199 200
@DESC@
Returns 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>.
203
This test is case-insensitive for all proper UTF-8 encoded strings.
204 205
@@

206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223
@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.
224
@@
225

226 227 228 229 230 231 232 233 234 235 236 237
@RET@		FcChar8 *
@FUNC@		FcStrBuildFilename
@TYPE1@		const FcChar8 *			@ARG1@		path
@TYPE2@		...
@PURPOSE@	Concatenate strings as a file path
@DESC@
Creates a filename from the given elements of strings as file paths
and concatenate them with the appropriate file separator.
Arguments must be null-terminated.
This returns a newly-allocated memory which should be freed when no longer needed.
@@

238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256
@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.
@@