doc/fcstring.fncs

   1 /*
   2  * $Id$
   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 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> 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@       copy a string, expanding '~'
 150 @DESC@
 151 Just like FcStrCopy except that it converts any leading '~' characters in
 152 <parameter>s</parameter> to the value of the HOME environment variable.
 153 Returns NULL if '~' is present in <parameter>s</parameter> and HOME is unset.
 154 @@
 155
 156 @RET@           int
 157 @FUNC@          FcStrCmp
 158 @TYPE1@         const FcChar8 *                 @ARG1@          s1
 159 @TYPE2@         const FcChar8 *                 @ARG2@          s2
 160 @PURPOSE@       compare UTF-8 strings
 161 @DESC@
 162 Returns the usual &lt;0, 0, &gt;0 result of comparing
 163 <parameter>s1</parameter> and <parameter>s2</parameter>.
 164 @@
 165
 166 @RET@           int
 167 @FUNC@          FcStrCmpIgnoreCase
 168 @TYPE1@         const FcChar8 *                 @ARG1@          s1
 169 @TYPE2@         const FcChar8 *                 @ARG2@          s2
 170 @PURPOSE@       compare UTF-8 strings ignoring case
 171 @DESC@
 172 Returns the usual &lt;0, 0, &gt;0 result of comparing
 173 <parameter>s1</parameter> and <parameter>s2</parameter>. This test is
 174 case-insensitive for all proper UTF-8 encoded strings.
 175 @@
 176
 177 @RET@           FcChar8 *
 178 @FUNC@          FcStrStr
 179 @TYPE1@         const FcChar8 *                 @ARG1@          s1
 180 @TYPE2@         const FcChar8 *                 @ARG2@          s2
 181 @PURPOSE@       locate UTF-8 substring
 182 @DESC@
 183 Returns the location of <parameter>s2</parameter> in
 184 <parameter>s1</parameter>.  Returns NULL if <parameter>s2</parameter>
 185 is not present in <parameter>s1</parameter>. This test will operate properly
 186 with UTF8 encoded strings.
 187 @@
 188
 189 @RET@           FcChar8 *
 190 @FUNC@          FcStrStrIgnoreCase
 191 @TYPE1@         const FcChar8 *                 @ARG1@          s1
 192 @TYPE2@         const FcChar8 *                 @ARG2@          s2
 193 @PURPOSE@       locate UTF-8 substring ignoring ASCII case
 194 @DESC@
 195 Returns the location of <parameter>s2</parameter> in
 196 <parameter>s1</parameter>, ignoring case.  Returns NULL if
 197 <parameter>s2</parameter> is not present in <parameter>s1</parameter>.
 198 This test is case-insensitive for all proper UTF-8 encoded strings.
 199 @@
 200
 201 @RET@           FcChar8 *
 202 @FUNC@          FcStrPlus
 203 @TYPE1@         const FcChar8 *                 @ARG1@          s1
 204 @TYPE2@         const FcChar8 *                 @ARG2@          s2
 205 @PURPOSE@       concatenate two strings
 206 @DESC@
 207 This function allocates new storage and places the concatenation of
 208 <parameter>s1</parameter> and <parameter>s2</parameter> there, returning the
 209 new string.
 210 @@
 211
 212 @RET@           void
 213 @FUNC@          FcStrFree
 214 @TYPE1@         FcChar8 *                       @ARG1@          s
 215 @PURPOSE@       free a string
 216 @DESC@
 217 This is just a wrapper around free(3) which helps track memory usage of
 218 strings within the fontconfig library.
 219
 220 @RET@           FcChar8 *
 221 @FUNC@          FcStrDirname
 222 @TYPE1@         const FcChar8 *                 @ARG1@          file
 223 @PURPOSE@       directory part of filename
 224 @DESC@
 225 Returns the directory containing <parameter>file</parameter>.  This
 226 is returned in newly allocated storage which should be freed when no longer
 227 needed.
 228 @@
 229
 230 @RET@           FcChar8 *
 231 @FUNC@          FcStrBasename
 232 @TYPE1@         const FcChar8 *                 @ARG1@          file
 233 @PURPOSE@       last component of filename
 234 @DESC@
 235 Returns the filename of <parameter>file</parameter> stripped of any leading
 236 directory names.  This is returned in newly allocated storage which should
 237 be freed when no longer needed.
 238 @@