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 <0, 0, >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 <0, 0, >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 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@ FcStrBuildFilename 228@TYPE1@ const FcChar8 * @ARG1@ path 229@TYPE2@ ... 230@PURPOSE@ Concatenate strings as a file path 231@DESC@ 232Creates a filename from the given elements of strings as file paths 233and concatenate them with the appropriate file separator. 234Arguments must be null-terminated. 235This returns a newly-allocated memory which should be freed when no longer needed. 236@@ 237 238@RET@ FcChar8 * 239@FUNC@ FcStrDirname 240@TYPE1@ const FcChar8 * @ARG1@ file 241@PURPOSE@ directory part of filename 242@DESC@ 243Returns the directory containing <parameter>file</parameter>. This 244is returned in newly allocated storage which should be freed when no longer 245needed. 246@@ 247 248@RET@ FcChar8 * 249@FUNC@ FcStrBasename 250@TYPE1@ const FcChar8 * @ARG1@ file 251@PURPOSE@ last component of filename 252@DESC@ 253Returns the filename of <parameter>file</parameter> stripped of any leading 254directory names. This is returned in newly allocated storage which should 255be freed when no longer needed. 256@@ 257