utf8proc
annotate utf8proc.h @ 1:61a89ecc2fb9
Version 0.2
- changed behaviour of PostgreSQL function to return NULL in case of invalid input, rather than raising an exceptional condition
- improved efficiency of PostgreSQL function (no transformation to C string is done)
- added -fpic compiler flag in Makefile
- fixed bug in the C code for the ruby library (usage of non-existent function)
- changed behaviour of PostgreSQL function to return NULL in case of invalid input, rather than raising an exceptional condition
- improved efficiency of PostgreSQL function (no transformation to C string is done)
- added -fpic compiler flag in Makefile
- fixed bug in the C code for the ruby library (usage of non-existent function)
author | jbe |
---|---|
date | Tue Jun 20 12:00:00 2006 +0200 (2006-06-20) |
parents | a0368662434c |
children | aaad485d5335 |
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@1 | 45 * Version: 0.2 |
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 |