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> nust 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@           FcChar8 *
 101 @FUNC@          FcStrCopy
 102 @TYPE1@         const FcChar8 *                 @ARG1@          s
 103 @PURPOSE@       duplicate a string
 104 @DESC@
 105 Allocates memory, copies <parameter>s</parameter> and returns the resulting
 106 buffer.  Yes, this is <function>strdup</function>, but that function isn't
 107 available on every platform.
 108 @@
 109
 110 @RET@           FcChar8 *
 111 @FUNC@          FcStrDowncase
 112 @TYPE1@         const FcChar8 *                 @ARG1@          s
 113 @PURPOSE@       create a lower case translation of a string
 114 @DESC@
 115 Allocates memory, copies <parameter>s</parameter>, converting upper case
 116 letters to lower case and returns the allocated buffer.
 117 @@
 118
 119 @RET@           FcChar8 *
 120 @FUNC@          FcStrCopyFilename
 121 @TYPE1@         const FcChar8 *                 @ARG1@          s
 122 @PURPOSE@       copy a string, expanding '~'
 123 @DESC@
 124 Just like FcStrCopy except that it converts any leading '~' characters in
 125 <parameter>s</parameter> to the value of the HOME environment variable.
 126 Returns NULL if '~' is present in <parameter>s</parameter> and HOME is unset.
 127 @@
 128
 129 @RET@           int
 130 @FUNC@          FcStrCmpIgnoreCase
 131 @TYPE1@         const FcChar8 *                 @ARG1@          s1
 132 @TYPE2@         const FcChar8 *                 @ARG2@          s2
 133 @PURPOSE@       compare UTF-8 strings ignoring ASCII case
 134 @DESC@
 135 Returns the usual &lt;0, 0, &gt;0 result of comparing
 136 <parameter>s1</parameter> and <parameter>s2</parameter>.  This test is
 137 case-insensitive in the ASCII range and will operate properly with UTF8
 138 encoded strings, although it does not check for well formed strings.
 139 @@
 140
 141 @RET@           FcChar8 *
 142 @FUNC@          FcStrStr
 143 @TYPE1@         const char *                    @ARG1@          s1
 144 @TYPE2@         const char *                    @ARG2@          s2
 145 @PURPOSE@       locate UTF-8 substring
 146 @DESC@
 147 Returns the location of <parameter>s2</parameter> in
 148 <parameter>s1</parameter>.  Returns NULL if <parameter>s2</parameter>
 149 is not present in <parameter>s1</parameter>. This test will operate properly
 150 with UTF8 encoded strings, although it does not check for well formed
 151 strings.
 152 @@
 153
 154 @RET@           FcChar8 *
 155 @FUNC@          FcStrStrIgnoreCase
 156 @TYPE1@         const char *                    @ARG1@          s1
 157 @TYPE2@         const char *                    @ARG2@          s2
 158 @PURPOSE@       locate UTF-8 substring ignoring ASCII case
 159 @DESC@
 160 Returns the location of <parameter>s2</parameter> in
 161 <parameter>s1</parameter>, ignoring ASCII case.  Returns NULL if
 162 <parameter>s2</parameter> is not present in <parameter>s1</parameter>.
 163 This test is case-insensitive in the ASCII range and will operate properly
 164 with UTF8 encoded strings, although it does not check for well formed
 165 strings.
 166 @@
 167
 168 @RET@           FcChar8 *
 169 @FUNC@          FcStrDirname
 170 @TYPE1@         const FcChar8 *                 @ARG1@          file
 171 @PURPOSE@       directory part of filename
 172 @DESC@
 173 Returns the directory containing <parameter>file</parameter>.  This
 174 is returned in newly allocated storage which should be freed when no longer
 175 needed.
 176 @@
 177
 178 @RET@           FcChar8 *
 179 @FUNC@          FcStrBasename
 180 @TYPE1@         const FcChar8 *                 @ARG1@          file
 181 @PURPOSE@       last component of filename
 182 @DESC@
 183 Returns the filename of <parameter>file</parameter> stripped of any leading
 184 directory names.  This is returned in newly allocated storage which should
 185 be freed when no longer needed.
 186 @@