doc/fcstring.fncs

   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@
  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> 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@
  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@           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
 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
 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
 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
 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>).
 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@
 167 Returns 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@
 177 Returns the usual &lt;0, 0, &gt;0 result of comparing
 178 <parameter>s1</parameter> and <parameter>s2</parameter>. This test is
 179 case-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@
 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
 191 with 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@
 200 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 @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.
 224 @@
 225
 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 @@