Xtypes: Documentation

[libucw.git] / ucw / unicode.h

diff --git a/ucw/unicode.h b/ucw/unicode.h
index 2bbbc5170635a4fa3c6c275bd42a1c2603467f76..55532495004e6e21f3f9f21c1c7394457157b636 100644 (file)
--- a/ucw/unicode.h
+++ b/ucw/unicode.h
@@ -12,7 +12,12 @@
 #ifndef _UCW_UNICODE_H
 #define _UCW_UNICODE_H
 
-#include "ucw/unaligned.h"
+#include <ucw/unaligned.h>
+
+#ifdef CONFIG_UCW_CLEAN_ABI
+#define utf8_strlen ucw_utf8_strlen
+#define utf8_strnlen ucw_utf8_strnlen
+#endif
 
 /* Macros for handling UTF-8 */
 
@@ -22,7 +27,7 @@
  * Encode a value from the range `[0, 0xFFFF]`
  * (basic multilingual plane); up to 3 bytes needed (RFC2279).
  **/
-static inline byte *utf8_put(byte *p, uns u)
+static inline byte *utf8_put(byte *p, uint u)
 {
   if (u < 0x80)
     *p++ = u;
@@ -45,7 +50,7 @@ static inline byte *utf8_put(byte *p, uns u)
  * Encode a value from the range `[0, 0x7FFFFFFF]`;
  * (superset of Unicode 4.0) up to 6 bytes needed (RFC2279).
  **/
-static inline byte *utf8_32_put(byte *p, uns u)
+static inline byte *utf8_32_put(byte *p, uint u)
 {
   if (u < 0x80)
     *p++ = u;
@@ -89,9 +94,9 @@ put1: *p++ = 0x80 | (u & 0x3f);
  * Decode a value from the range `[0, 0xFFFF]` (basic multilingual plane)
  * or return @repl if the encoding has been corrupted.
  **/
-static inline byte *utf8_get_repl(const byte *p, uns *uu, uns repl)
+static inline byte *utf8_get_repl(const byte *p, uint *uu, uint repl)
 {
-  uns u = *p++;
+  uint u = *p++;
   if (u < 0x80)
     ;
   else if (unlikely(u < 0xc0))
@@ -121,9 +126,9 @@ static inline byte *utf8_get_repl(const byte *p, uns *uu, uns repl)
  * Decode a value from the range `[0, 0x7FFFFFFF]`
  * or return @repl if the encoding has been corrupted.
  **/
-static inline byte *utf8_32_get_repl(const byte *p, uns *uu, uns repl)
+static inline byte *utf8_32_get_repl(const byte *p, uint *uu, uint repl)
 {
-  uns u = *p++;
+  uint u = *p++;
   if (u < 0x80)
     ;
   else if (unlikely(u < 0xc0))
@@ -168,10 +173,10 @@ get1: UTF8_GET_NEXT;
 }
 
 /**
- * Decode a value from the range `[0, 0xFFFF]` (basic multilignual plane)
+ * Decode a value from the range `[0, 0xFFFF]` (basic multilingual plane)
  * or return `UNI_REPLACEMENT` if the encoding has been corrupted.
  **/
-static inline byte *utf8_get(const byte *p, uns *uu)
+static inline byte *utf8_get(const byte *p, uint *uu)
 {
   return utf8_get_repl(p, uu, UNI_REPLACEMENT);
 }
@@ -180,13 +185,13 @@ static inline byte *utf8_get(const byte *p, uns *uu)
  * Decode a value from the range `[0, 0x7FFFFFFF]`
  * or return `UNI_REPLACEMENT` if the encoding has been corrupted.
  **/
-static inline byte *utf8_32_get(const byte *p, uns *uu)
+static inline byte *utf8_32_get(const byte *p, uint *uu)
 {
   return utf8_32_get_repl(p, uu, UNI_REPLACEMENT);
 }
 
 #define UTF8_SKIP(p) do {                              \
-    uns c = *p++;                                      \
+    uint c = *p++;                                     \
     if (c >= 0xc0)                                     \
       while (c & 0x40 && *p >= 0x80 && *p < 0xc0)      \
         p++, c <<= 1;                                  \
@@ -197,7 +202,7 @@ static inline byte *utf8_32_get(const byte *p, uns *uu)
 /**
  * Return the number of bytes needed to encode a given value from the range `[0, 0x7FFFFFFF]` to UTF-8.
  **/
-static inline uns utf8_space(uns u)
+static inline uint utf8_space(uint u)
 {
   if (u < 0x80)
     return 1;
@@ -213,9 +218,9 @@ static inline uns utf8_space(uns u)
 }
 
 /**
- * Compute the length of a single UTF-8 character from it's first byte. The encoding must be valid.
+ * Compute the length of a single UTF-8 character from its first byte. The encoding must be valid.
  **/
-static inline uns utf8_encoding_len(uns c)
+static inline uint utf8_encoding_len(uint c)
 {
   if (c < 0x80)
     return 1;
@@ -235,7 +240,7 @@ static inline uns utf8_encoding_len(uns c)
  * Encode an UTF-16LE character from the range `[0, 0xD7FF]` or `[0xE000,0x11FFFF]`;
  * up to 4 bytes needed.
  **/
-static inline void *utf16_le_put(void *p, uns u)
+static inline void *utf16_le_put(void *p, uint u)
 {
   if (u < 0xd800 || (u < 0x10000 && u >= 0xe000))
     {
@@ -253,10 +258,10 @@ static inline void *utf16_le_put(void *p, uns u)
 }
 
 /**
- * Encode an UTF-16BE character from the range `[0, 0xD7FF]` or `[0xE000,0x11FFFF]`;
+ * Encode a UTF-16BE character from the range `[0, 0xD7FF]` or `[0xE000,0x11FFFF]`;
  * up to 4 bytes needed.
  **/
-static inline void *utf16_be_put(void *p, uns u)
+static inline void *utf16_be_put(void *p, uint u)
 {
   if (u < 0xd800 || (u < 0x10000 && u >= 0xe000))
     {
@@ -274,12 +279,12 @@ static inline void *utf16_be_put(void *p, uns u)
 }
 
 /**
- * Decode an UTF-16LE character from the range `[0, 0xD7FF]` or `[0xE000,11FFFF]`
+ * Decode a UTF-16LE character from the range `[0, 0xD7FF]` or `[0xE000,11FFFF]`
  * or return @repl if the encoding has been corrupted.
  **/
-static inline void *utf16_le_get_repl(const void *p, uns *uu, uns repl)
+static inline void *utf16_le_get_repl(const void *p, uint *uu, uint repl)
 {
-  uns u = get_u16_le(p), x, y;
+  uint u = get_u16_le(p), x, y;
   x = u - 0xd800;
   if (x < 0x800)
     if (x < 0x400 && (y = get_u16_le(p + 2) - 0xdc00) < 0x400)
@@ -294,12 +299,12 @@ static inline void *utf16_le_get_repl(const void *p, uns *uu, uns repl)
 }
 
 /**
- * Decode an UTF-16BE character from the range `[0, 0xD7FF]` or `[0xE000,11FFFF]`
+ * Decode a UTF-16BE character from the range `[0, 0xD7FF]` or `[0xE000,11FFFF]`
  * or return @repl if the encoding has been corrupted.
  **/
-static inline void *utf16_be_get_repl(const void *p, uns *uu, uns repl)
+static inline void *utf16_be_get_repl(const void *p, uint *uu, uint repl)
 {
-  uns u = get_u16_be(p), x, y;
+  uint u = get_u16_be(p), x, y;
   x = u - 0xd800;
   if (x < 0x800)
     if (x < 0x400 && (y = get_u16_be(p + 2) - 0xdc00) < 0x400)
@@ -314,27 +319,29 @@ static inline void *utf16_be_get_repl(const void *p, uns *uu, uns repl)
 }
 
 /**
- * Decode an UTF-16LE  character from the range `[0, 0xD7FF]` or `[0xE000,11FFFF]`
+ * Decode a UTF-16LE  character from the range `[0, 0xD7FF]` or `[0xE000,11FFFF]`
  * or return `UNI_REPLACEMENT` if the encoding has been corrupted.
  **/
-static inline void *utf16_le_get(const void *p, uns *uu)
+static inline void *utf16_le_get(const void *p, uint *uu)
 {
   return utf16_le_get_repl(p, uu, UNI_REPLACEMENT);
 }
 
 /**
- * Decode an UTF-16BE  character from the range `[0, 0xD7FF]` or `[0xE000,11FFFF]`
+ * Decode a UTF-16BE  character from the range `[0, 0xD7FF]` or `[0xE000,11FFFF]`
  * or return `UNI_REPLACEMENT` if the encoding has been corrupted.
  **/
-static inline void *utf16_be_get(const void *p, uns *uu)
+static inline void *utf16_be_get(const void *p, uint *uu)
 {
   return utf16_be_get_repl(p, uu, UNI_REPLACEMENT);
 }
 
 /**
- * Check an Unicode value and if it seems to be useless (defined by Ucwlib; it may change in future) return `UNI_REPLACEMENT` instead.
+ * Basic sanity check on Unicode characters. Return `UNI_REPLACEMENT` if the input
+ * character is a surrogate, ASCII or Latin-1 control character different from the tab,
+ * or if it lies outside the basic plane. In all other cases, it acts as an identity.
  **/
-static inline uns unicode_sanitize_char(uns u)
+static inline uint unicode_sanitize_char(uint u)
 {
   if (u >= 0x10000 ||                  // We don't accept anything outside the basic plane
       u >= 0xd800 && u < 0xf900 ||     // neither we do surrogates
@@ -347,14 +354,14 @@ static inline uns unicode_sanitize_char(uns u)
 /* unicode-utf8.c */
 
 /**
- * Count the number of Unicode character in a zero-terminated UTF-8 string.
+ * Count the number of Unicode characters in a zero-terminated UTF-8 string.
  * Returned value for corrupted encoding is undefined, but is never greater than strlen().
  **/
-uns utf8_strlen(const byte *str);
+size_t utf8_strlen(const byte *str);
 
 /**
  * Same as @utf8_strlen(), but returns at most @n characters.
  **/
-uns utf8_strnlen(const byte *str, uns n);
+size_t utf8_strnlen(const byte *str, size_t n);
 
 #endif