utf8proc

annotate utf8proc.h @ 0:a0368662434c

find changesets by author, revision, files, or words in the commit message
Version 0.1
author jbe
date Fri Jun 02 12:00:00 2006 +0200 (2006-06-02)
parents
children 61a89ecc2fb9
rev   line source
jbe@0 1 /*
jbe@0 2 * Copyright (c) 2006, FlexiGuided GmbH, Berlin, Germany
jbe@0 3 * Author: Jan Behrens <jan.behrens@flexiguided.de>
jbe@0 4 * All rights reserved.
jbe@0 5 *
jbe@0 6 * Redistribution and use in source and binary forms, with or without
jbe@0 7 * modification, are permitted provided that the following conditions are
jbe@0 8 * met:
jbe@0 9 *
jbe@0 10 * 1. Redistributions of source code must retain the above copyright
jbe@0 11 * notice, this list of conditions and the following disclaimer.
jbe@0 12 * 2. Redistributions in binary form must reproduce the above copyright
jbe@0 13 * notice, this list of conditions and the following disclaimer in the
jbe@0 14 * documentation and/or other materials provided with the distribution.
jbe@0 15 * 3. Neither the name of the FlexiGuided GmbH nor the names of its
jbe@0 16 * contributors may be used to endorse or promote products derived from
jbe@0 17 * this software without specific prior written permission.
jbe@0 18 *
jbe@0 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
jbe@0 20 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
jbe@0 21 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
jbe@0 22 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
jbe@0 23 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
jbe@0 24 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
jbe@0 25 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
jbe@0 26 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
jbe@0 27 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
jbe@0 28 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
jbe@0 29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
jbe@0 30 *
jbe@0 31 *
jbe@0 32 * This library contains derived data from a modified version of the
jbe@0 33 * Unicode data files.
jbe@0 34 *
jbe@0 35 * The original data files are available at
jbe@0 36 * http://www.unicode.org/Public/UNIDATA/
jbe@0 37 *
jbe@0 38 * Please notice the copyright statement in the file "utf8proc_data.c".
jbe@0 39 *
jbe@0 40 */
jbe@0 41
jbe@0 42
jbe@0 43 /*
jbe@0 44 * File name: utf8proc.h
jbe@0 45 * Version: 0.1
jbe@0 46 * Last changed: 2006-05-31
jbe@0 47 *
jbe@0 48 * Description:
jbe@0 49 * Header files for libutf8proc, which is a mapping tool for UTF-8 strings
jbe@0 50 * with following features:
jbe@0 51 * - decomposing and composing of strings
jbe@0 52 * - replacing compatibility characters with their equivalents
jbe@0 53 * - stripping of "default ignorable characters"
jbe@0 54 * like SOFT-HYPHEN or ZERO-WIDTH-SPACE
jbe@0 55 * - optional rejection of strings containing non-assigned code points
jbe@0 56 * - stripping of control characters
jbe@0 57 * - transformation of LF, CRLF, CR and NEL to line-feed (LF)
jbe@0 58 * or to the unicode chararacters for paragraph separation (PS)
jbe@0 59 * or line separation (LS).
jbe@0 60 * - unicode case folding (for case insensitive string comparisons)
jbe@0 61 * - rejection of illegal UTF-8 data (i.e. UTF-8 encoded UTF-16 surrogates)
jbe@0 62 * - support for korean hangul characters
jbe@0 63 * Unicode Version 4.1.0 is supported.
jbe@0 64 */
jbe@0 65
jbe@0 66
jbe@0 67 #ifndef UTF8PROC_H
jbe@0 68 #define UTF8PROC_H
jbe@0 69
jbe@0 70
jbe@0 71 #include <stdlib.h>
jbe@0 72 #include <stdbool.h>
jbe@0 73 #include <sys/types.h>
jbe@0 74 #include <inttypes.h>
jbe@0 75 #include <limits.h>
jbe@0 76
jbe@0 77 #ifndef SSIZE_MAX
jbe@0 78 #define SSIZE_MAX (SIZE_MAX/2)
jbe@0 79 #endif
jbe@0 80
jbe@0 81 #define UTF8PROC_NULLTERM (1<<0)
jbe@0 82 #define UTF8PROC_STABLE (1<<1)
jbe@0 83 #define UTF8PROC_COMPAT (1<<2)
jbe@0 84 #define UTF8PROC_COMPOSE (1<<3)
jbe@0 85 #define UTF8PROC_IGNORE (1<<4)
jbe@0 86 #define UTF8PROC_REJECTNA (1<<5)
jbe@0 87 #define UTF8PROC_NLF2LS (1<<6)
jbe@0 88 #define UTF8PROC_NLF2PS (1<<7)
jbe@0 89 #define UTF8PROC_NLF2LF (UTF8PROC_NLF2LS | UTF8PROC_NLF2PS)
jbe@0 90 #define UTF8PROC_STRIPCC (1<<8)
jbe@0 91 #define UTF8PROC_CASEFOLD (1<<9)
jbe@0 92 /*
jbe@0 93 * Flags being regarded by several functions in the library:
jbe@0 94 * NULLTERM: The given UTF-8 input is NULL terminated.
jbe@0 95 * STABLE: Unicode Versioning Stability has to be respected.
jbe@0 96 * COMPAT: Compatiblity decomposition (i.e. formatting information is lost)
jbe@0 97 * COMPOSE: Return a result with composed characters, instead of decomposed.
jbe@0 98 * IGNORE: Strip "default ignorable characters"
jbe@0 99 * REJECTNA: Return an error, if the input contains unassigned code points.
jbe@0 100 * NLF2LS: Indicating that NLF-sequences (LF, CRLF, CR, NEL) are
jbe@0 101 * representing a line break, and should be converted to the
jbe@0 102 * unicode character for line separation (LS).
jbe@0 103 * NLF2PS: Indicating that NLF-sequences are representing a paragraph
jbe@0 104 * break, and should be converted to the unicode character for
jbe@0 105 * paragraph separation (PS).
jbe@0 106 * NLF2LF: Indicating that the meaning of NLF-sequences is unknown.
jbe@0 107 * STRIPCC: Strips and/or convers control characters.
jbe@0 108 * NLF-sequences are transformed into space, except if one of the
jbe@0 109 * NLF2LS/PS/LF options is given.
jbe@0 110 * HorizontalTab (HT) and FormFeed (FF) are treated as a
jbe@0 111 * NLF-sequence in this case.
jbe@0 112 * All other control characters are simply removed.
jbe@0 113 * CASEFOLD: Performs unicode case folding, to be able to do a
jbe@0 114 * case-insensitive string comparison.
jbe@0 115 */
jbe@0 116
jbe@0 117 #define UTF8PROC_ERROR_NOMEM -1
jbe@0 118 #define UTF8PROC_ERROR_OVERFLOW -2
jbe@0 119 #define UTF8PROC_ERROR_INVALIDUTF8 -3
jbe@0 120 #define UTF8PROC_ERROR_NOTASSIGNED -4
jbe@0 121 /*
jbe@0 122 * Error codes being returned by almost all functions:
jbe@0 123 * ERROR_NOMEM: Memory could not be allocated.
jbe@0 124 * ERROR_OVERFLOW: The given string is too long to be processed.
jbe@0 125 * ERROR_INVALIDUTF8: The given string is not a legal UTF-8 string.
jbe@0 126 * ERROR_NOTASSIGNED: The REJECTNA flag was set,
jbe@0 127 * and an unassigned code point was found.
jbe@0 128 */
jbe@0 129
jbe@0 130 typedef struct utf8proc_property_struct {
jbe@0 131 const char *category;
jbe@0 132 const int16_t combining_class;
jbe@0 133 const char *bidi_class;
jbe@0 134 const char *decomp_type;
jbe@0 135 const int32_t *decomp_mapping;
jbe@0 136 const unsigned bidi_mirrored:1;
jbe@0 137 const int32_t uppercase_mapping;
jbe@0 138 const int32_t lowercase_mapping;
jbe@0 139 const int32_t titlecase_mapping;
jbe@0 140 const int32_t comb1st_index;
jbe@0 141 const int32_t comb2nd_index;
jbe@0 142 const unsigned comp_exclusion:1;
jbe@0 143 const unsigned ignorable:1;
jbe@0 144 const int32_t *casefold_mapping;
jbe@0 145 } utf8proc_property_t;
jbe@0 146
jbe@0 147 extern const int8_t utf8proc_utf8class[256];
jbe@0 148
jbe@0 149 const char *utf8proc_errmsg(ssize_t errcode);
jbe@0 150 /*
jbe@0 151 * Returns a static error string for the given error code.
jbe@0 152 */
jbe@0 153
jbe@0 154 ssize_t utf8proc_iterate(uint8_t *str, ssize_t strlen, int32_t *dst);
jbe@0 155 /*
jbe@0 156 * Reads a single char from the UTF-8 sequence being pointed to by 'str'.
jbe@0 157 * The maximum number of bytes read is 'strlen', unless 'strlen' is
jbe@0 158 * negative.
jbe@0 159 * If a valid unicode char could be read, it is stored in the variable
jbe@0 160 * being pointed to by 'dst', otherwise that variable will be set to -1.
jbe@0 161 * In case of success the number of bytes read is returned, otherwise a
jbe@0 162 * negative error code is returned.
jbe@0 163 */
jbe@0 164
jbe@0 165 ssize_t utf8proc_encode_char(int32_t uc, uint8_t *dst);
jbe@0 166 /*
jbe@0 167 * Encodes the unicode char with the code point 'uc' as an UTF-8 string in
jbe@0 168 * the byte array being pointed to by 'dst'. This array has to be at least
jbe@0 169 * 4 bytes long.
jbe@0 170 * In case of success the number of bytes written is returned, otherwise 0.
jbe@0 171 * This function does not check if 'uc' is a valid unicode code point.
jbe@0 172 */
jbe@0 173
jbe@0 174 const utf8proc_property_t *utf8proc_get_property(int32_t uc);
jbe@0 175 /*
jbe@0 176 * Returns a pointer to a (constant) struct containing information about
jbe@0 177 * the unicode char with the given code point 'uc'.
jbe@0 178 * If the character is not existent a pointer to a special struct is
jbe@0 179 * returned, where 'category' is a NULL pointer.
jbe@0 180 * WARNING: The parameter 'uc' has to be in the range of 0x0000 to
jbe@0 181 * 0x10FFFF, otherwise the program might crash!
jbe@0 182 */
jbe@0 183
jbe@0 184 ssize_t utf8proc_decompose_char(int32_t uc, int32_t *dst, ssize_t bufsize,
jbe@0 185 int options);
jbe@0 186 /*
jbe@0 187 * Writes a decomposition of the unicode char 'uc' into the array being
jbe@0 188 * pointed to by 'dst'.
jbe@0 189 * Following flags in the 'options' field are regarded:
jbe@0 190 * REJECTNA: an unassigned unicode code point leads to an error
jbe@0 191 * IGNORE: "default ignorable" chars are stripped
jbe@0 192 * CASEFOLD: unicode casefolding is applied
jbe@0 193 * COMPAT: replace certain characters with their
jbe@0 194 * compatibility decomposition
jbe@0 195 * In case of success the number of chars written is returned,
jbe@0 196 * in case of an error, a negative error code is returned.
jbe@0 197 * If the number of written chars would be bigger than 'bufsize',
jbe@0 198 * the buffer (up to 'bufsize') has inpredictable data, and the needed
jbe@0 199 * buffer size is returned.
jbe@0 200 * WARNING: The parameter 'uc' has to be in the range of 0x0000 to
jbe@0 201 * 0x10FFFF, otherwise the program might crash!
jbe@0 202 */
jbe@0 203
jbe@0 204 ssize_t utf8proc_decompose(uint8_t *str, ssize_t strlen,
jbe@0 205 int32_t *buffer, ssize_t bufsize, int options);
jbe@0 206 /*
jbe@0 207 * Does the same as 'utf8proc_decompose_char', but acts on a whole UTF-8
jbe@0 208 * string, and orders the decomposed sequences correctly.
jbe@0 209 * If the NULLTERM flag in 'options' is set, processing will be stopped,
jbe@0 210 * when a NULL byte is encounted, otherwise 'strlen' bytes are processed.
jbe@0 211 * The result in form of unicode code points is written into the buffer
jbe@0 212 * being pointed to by 'buffer', having the length of 'bufsize' entries.
jbe@0 213 * In case of success the number of chars written is returned,
jbe@0 214 * in case of an error, a negative error code is returned.
jbe@0 215 * If the number of written chars would be bigger than 'bufsize',
jbe@0 216 * the buffer (up to 'bufsize') has inpredictable data, and the needed
jbe@0 217 * buffer size is returned.
jbe@0 218 */
jbe@0 219
jbe@0 220 ssize_t utf8proc_reencode(int32_t *buffer, ssize_t length, int options);
jbe@0 221 /*
jbe@0 222 * Reencodes the sequence of unicode characters given by the pointer
jbe@0 223 * 'buffer' and 'length' as UTF-8.
jbe@0 224 * The result is stored in the same memory area where the data is read.
jbe@0 225 * Following flags in the 'options' field are regarded:
jbe@0 226 * NLF2LS: converts LF, CRLF, CR and NEL into LS
jbe@0 227 * NLF2PS: converts LF, CRLF, CR and NEL into PS
jbe@0 228 * NLF2LF: converts LF, CRLF, CR and NEL into LF
jbe@0 229 * STRIPCC: strips or converts all non-affected control characters
jbe@0 230 * COMPOSE: tries to combine decomposed characters into composite characters
jbe@0 231 * STABLE: prohibits combining characters which would violate
jbe@0 232 * the unicode versioning stability
jbe@0 233 * In case of success the length of the resulting UTF-8 string is returned,
jbe@0 234 * otherwise a negative error code is returned.
jbe@0 235 * WARNING: The amount of free space being pointed to by 'buffer', has to
jbe@0 236 * exceed the amount of the input data by one byte, and the
jbe@0 237 * entries of the array pointed to by 'str' have to be in the
jbe@0 238 * range of 0x0000 to 0x10FFFF, otherwise the program might crash!
jbe@0 239 */
jbe@0 240
jbe@0 241 ssize_t utf8proc_map(uint8_t *str, ssize_t strlen, uint8_t **dstptr,
jbe@0 242 int options);
jbe@0 243 /*
jbe@0 244 * Maps the given UTF-8 string being pointed to by 'str' to a new UTF-8
jbe@0 245 * string, which is allocated dynamically, and afterwards pointed to by the
jbe@0 246 * pointer being pointed to by 'dstptr'.
jbe@0 247 * If the NULLTERM flag in the 'options' field is set, the length is
jbe@0 248 * determined by a NULL terminator, otherwise the parameter 'strlen' is
jbe@0 249 * evaluated to determine the string length, but in any case the result
jbe@0 250 * will be NULL terminated (though it might contain NULL characters before).
jbe@0 251 * Other flags in the 'options' field are passed to the functions defined
jbe@0 252 * above, and regarded as described.
jbe@0 253 * In case of success the length of the new string is returned,
jbe@0 254 * otherwise a negative error code is returned.
jbe@0 255 * NOTICE: The memory of the new UTF-8 string will have been allocated with
jbe@0 256 * 'malloc', and has theirfore to be freed with 'free'.
jbe@0 257 */
jbe@0 258
jbe@0 259 uint8_t *utf8proc_NFD(uint8_t *str);
jbe@0 260 uint8_t *utf8proc_NFC(uint8_t *str);
jbe@0 261 uint8_t *utf8proc_NFKD(uint8_t *str);
jbe@0 262 uint8_t *utf8proc_NFKC(uint8_t *str);
jbe@0 263 /*
jbe@0 264 * Returns a pointer to newly allocated memory of a NFD, NFC, NFKD or NFKC
jbe@0 265 * normalized version of the null-terminated string 'str'.
jbe@0 266 */
jbe@0 267
jbe@0 268
jbe@0 269 #endif
jbe@0 270
jbe@0 271

Impressum / About Us