/* * fontconfig/doc/fcstring.fncs * * Copyright © 2003 Keith Packard * * 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 * documentation, and that the name of Keith Packard not be used in * advertising or publicity pertaining to distribution of the software without * specific, written prior permission. Keith Packard makes no * representations about the suitability of this software for any purpose. It * is provided "as is" without express or implied warranty. * * THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO * EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR * 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 @TYPE3@ int% @ARG3@ len @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 char. <parameter>src</parameter> must be at least <parameter>len</parameter> bytes long. @@ @RET@ int @FUNC@ FcUcs4ToUtf8 @TYPE1@ FcChar32% @ARG1@ src @TYPE2@ FcChar8% @ARG2@ dst[FC_UTF8_MAX_LEN] @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 @TYPE2@ int% @ARG2@ len @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 4 depending on the number of bytes needed to hold the largest unicode char counted. The return value indicates whether <parameter>src</parameter> is a well-formed UTF8 string. @@ @RET@ int @FUNC@ FcUtf16ToUcs4 @TYPE1@ FcChar8 * @ARG1@ src @TYPE2@ FcEndian% @ARG2@ endian @TYPE3@ FcChar32 * @ARG3@ dst @TYPE4@ int% @ARG4@ len @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 @TYPE2@ FcEndian% @ARG2@ endian @TYPE3@ int% @ARG3@ len @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 bytes needed to hold the largest unicode char counted. The return value indicates whether <parameter>string</parameter> is a well-formed UTF16 string. @@ @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. @@ @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. @@ @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. @@ @RET@ FcChar8 * @FUNC@ FcStrCopyFilename @TYPE1@ const FcChar8 * @ARG1@ s @PURPOSE@ create a complete path from a filename @DESC@ <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>). @@ @RET@ int @FUNC@ FcStrCmp @TYPE1@ const FcChar8 * @ARG1@ s1 @TYPE2@ const FcChar8 * @ARG2@ s2 @PURPOSE@ compare UTF-8 strings @DESC@ Returns the usual <0, 0, >0 result of comparing <parameter>s1</parameter> and <parameter>s2</parameter>. @@ @RET@ int @FUNC@ FcStrCmpIgnoreCase @TYPE1@ const FcChar8 * @ARG1@ s1 @TYPE2@ const FcChar8 * @ARG2@ s2 @PURPOSE@ compare UTF-8 strings ignoring case @DESC@ Returns the usual <0, 0, >0 result of comparing <parameter>s1</parameter> and <parameter>s2</parameter>. This test is case-insensitive for all proper UTF-8 encoded strings. @@ @RET@ FcChar8 * @FUNC@ FcStrStr @TYPE1@ const FcChar8 * @ARG1@ s1 @TYPE2@ const FcChar8 * @ARG2@ s2 @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 with UTF8 encoded strings. @@ @RET@ FcChar8 * @FUNC@ FcStrStrIgnoreCase @TYPE1@ const FcChar8 * @ARG1@ s1 @TYPE2@ const FcChar8 * @ARG2@ s2 @PURPOSE@ locate UTF-8 substring ignoring ASCII case @DESC@ Returns the location of <parameter>s2</parameter> in <parameter>s1</parameter>, ignoring case. Returns NULL if <parameter>s2</parameter> is not present in <parameter>s1</parameter>. This test is case-insensitive for all proper UTF-8 encoded strings. @@ @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. @@ @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. @@