src/string_func.h

   1 /* $Id$ */
   2
   3 /*
   4  * This file is part of OpenTTD.
   5  * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   6  * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   7  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   8  */
   9
  10 /**
  11  * @file string_func.h Functions related to low-level strings.
  12  *
  13  * @note Be aware of "dangerous" string functions; string functions that
  14  * have behaviour that could easily cause buffer overruns and such:
  15  * - strncpy: does not '\0' terminate when input string is longer than
  16  *   the size of the output string. Use strecpy instead.
  17  * - [v]snprintf: returns the length of the string as it would be written
  18  *   when the output is large enough, so it can be more than the size of
  19  *   the buffer and than can underflow size_t (uint-ish) which makes all
  20  *   subsequent snprintf alikes write outside of the buffer. Use
  21  *   [v]seprintf instead; it will return the number of bytes actually
  22  *   added so no [v]seprintf will cause outside of bounds writes.
  23  * - [v]sprintf: does not bounds checking: use [v]seprintf instead.
  24  */
  25
  26 #ifndef STRING_FUNC_H
  27 #define STRING_FUNC_H
  28
  29 #include "core/bitmath_func.hpp"
  30 #include "string_type.h"
  31
  32 void ttd_strlcat(char *dst, const char *src, size_t size);
  33 void ttd_strlcpy(char *dst, const char *src, size_t size);
  34
  35 char *strecat(char *dst, const char *src, const char *last);
  36 char *strecpy(char *dst, const char *src, const char *last);
  37
  38 int CDECL seprintf(char *str, const char *last, const char *format, ...) WARN_FORMAT(3, 4);
  39
  40 char *CDECL str_fmt(const char *str, ...) WARN_FORMAT(1, 2);
  41
  42 void str_validate(char *str, const char *last, StringValidationSettings settings = SVS_REPLACE_WITH_QUESTION_MARK);
  43 void ValidateString(const char *str);
  44
  45 void str_fix_scc_encoded(char *str, const char *last);
  46 void str_strip_colours(char *str);
  47 bool strtolower(char *str);
  48
  49 bool StrValid(const char *str, const char *last);
  50
  51 /**
  52  * Check if a string buffer is empty.
  53  *
  54  * @param s The pointer to the first element of the buffer
  55  * @return true if the buffer starts with the terminating null-character or
  56  *         if the given pointer points to NULL else return false
  57  */
  58 static inline bool StrEmpty(const char *s)
  59 {
  60         return s == NULL || s[0] == '\0';
  61 }
  62
  63 /**
  64  * Get the length of a string, within a limited buffer.
  65  *
  66  * @param str The pointer to the first element of the buffer
  67  * @param maxlen The maximum size of the buffer
  68  * @return The length of the string
  69  */
  70 static inline size_t ttd_strnlen(const char *str, size_t maxlen)
  71 {
  72         const char *t;
  73         for (t = str; (size_t)(t - str) < maxlen && *t != '\0'; t++) {}
  74         return t - str;
  75 }
  76
  77 char *md5sumToString(char *buf, const char *last, const uint8 md5sum[16]);
  78
  79 bool IsValidChar(WChar key, CharSetFilter afilter);
  80
  81 size_t Utf8Decode(WChar *c, const char *s);
  82 size_t Utf8Encode(char *buf, WChar c);
  83 size_t Utf8TrimString(char *s, size_t maxlen);
  84
  85
  86 static inline WChar Utf8Consume(const char **s)
  87 {
  88         WChar c;
  89         *s += Utf8Decode(&c, *s);
  90         return c;
  91 }
  92
  93 /**
  94  * Return the length of a UTF-8 encoded character.
  95  * @param c Unicode character.
  96  * @return Length of UTF-8 encoding for character.
  97  */
  98 static inline int8 Utf8CharLen(WChar c)
  99 {
 100         if (c < 0x80)       return 1;
 101         if (c < 0x800)      return 2;
 102         if (c < 0x10000)    return 3;
 103         if (c < 0x110000)   return 4;
 104
 105         /* Invalid valid, we encode as a '?' */
 106         return 1;
 107 }
 108
 109
 110 /**
 111  * Return the length of an UTF-8 encoded value based on a single char. This
 112  * char should be the first byte of the UTF-8 encoding. If not, or encoding
 113  * is invalid, return value is 0
 114  * @param c char to query length of
 115  * @return requested size
 116  */
 117 static inline int8 Utf8EncodedCharLen(char c)
 118 {
 119         if (GB(c, 3, 5) == 0x1E) return 4;
 120         if (GB(c, 4, 4) == 0x0E) return 3;
 121         if (GB(c, 5, 3) == 0x06) return 2;
 122         if (GB(c, 7, 1) == 0x00) return 1;
 123
 124         /* Invalid UTF8 start encoding */
 125         return 0;
 126 }
 127
 128
 129 /* Check if the given character is part of a UTF8 sequence */
 130 static inline bool IsUtf8Part(char c)
 131 {
 132         return GB(c, 6, 2) == 2;
 133 }
 134
 135 /**
 136  * Retrieve the previous UNICODE character in an UTF-8 encoded string.
 137  * @param s char pointer pointing to (the first char of) the next character
 138  * @return a pointer in 's' to the previous UNICODE character's first byte
 139  * @note The function should not be used to determine the length of the previous
 140  * encoded char because it might be an invalid/corrupt start-sequence
 141  */
 142 static inline char *Utf8PrevChar(char *s)
 143 {
 144         char *ret = s;
 145         while (IsUtf8Part(*--ret)) {}
 146         return ret;
 147 }
 148
 149 static inline const char *Utf8PrevChar(const char *s)
 150 {
 151         const char *ret = s;
 152         while (IsUtf8Part(*--ret)) {}
 153         return ret;
 154 }
 155
 156 size_t Utf8StringLength(const char *s);
 157
 158 /**
 159  * Is the given character a lead surrogate code point?
 160  * @param c The character to test.
 161  * @return True if the character is a lead surrogate code point.
 162  */
 163 static inline bool Utf16IsLeadSurrogate(uint c)
 164 {
 165         return c >= 0xD800 && c <= 0xDBFF;
 166 }
 167
 168 /**
 169  * Is the given character a lead surrogate code point?
 170  * @param c The character to test.
 171  * @return True if the character is a lead surrogate code point.
 172  */
 173 static inline bool Utf16IsTrailSurrogate(uint c)
 174 {
 175         return c >= 0xDC00 && c <= 0xDFFF;
 176 }
 177
 178 /**
 179  * Convert an UTF-16 surrogate pair to the corresponding Unicode character.
 180  * @param lead Lead surrogate code point.
 181  * @param trail Trail surrogate code point.
 182  * @return Decoded Unicode character.
 183  */
 184 static inline WChar Utf16DecodeSurrogate(uint lead, uint trail)
 185 {
 186         return 0x10000 + (((lead - 0xD800) << 10) | (trail - 0xDC00));
 187 }
 188
 189 /**
 190  * Decode an UTF-16 character.
 191  * @param c Pointer to one or two UTF-16 code points.
 192  * @return Decoded Unicode character.
 193  */
 194 static inline WChar Utf16DecodeChar(const uint16 *c)
 195 {
 196         if (Utf16IsLeadSurrogate(c[0])) {
 197                 return Utf16DecodeSurrogate(c[0], c[1]);
 198         } else {
 199                 return *c;
 200         }
 201 }
 202
 203 /**
 204  * Is the given character a text direction character.
 205  * @param c The character to test.
 206  * @return true iff the character is used to influence
 207  *         the text direction.
 208  */
 209 static inline bool IsTextDirectionChar(WChar c)
 210 {
 211         switch (c) {
 212                 case CHAR_TD_LRM:
 213                 case CHAR_TD_RLM:
 214                 case CHAR_TD_LRE:
 215                 case CHAR_TD_RLE:
 216                 case CHAR_TD_LRO:
 217                 case CHAR_TD_RLO:
 218                 case CHAR_TD_PDF:
 219                         return true;
 220
 221                 default:
 222                         return false;
 223         }
 224 }
 225
 226 static inline bool IsPrintable(WChar c)
 227 {
 228         if (c < 0x20)   return false;
 229         if (c < 0xE000) return true;
 230         if (c < 0xE200) return false;
 231         return true;
 232 }
 233
 234 /**
 235  * Check whether UNICODE character is whitespace or not, i.e. whether
 236  * this is a potential line-break character.
 237  * @param c UNICODE character to check
 238  * @return a boolean value whether 'c' is a whitespace character or not
 239  * @see http://www.fileformat.info/info/unicode/category/Zs/list.htm
 240  */
 241 static inline bool IsWhitespace(WChar c)
 242 {
 243         return c == 0x0020 /* SPACE */ || c == 0x3000; /* IDEOGRAPHIC SPACE */
 244 }
 245
 246 /* Needed for NetBSD version (so feature) testing */
 247 #if defined(__NetBSD__) || defined(__FreeBSD__)
 248 #include <sys/param.h>
 249 #endif
 250
 251 /* strndup is a GNU extension */
 252 #if defined(_GNU_SOURCE) || (defined(__NetBSD_Version__) && 400000000 <= __NetBSD_Version__) || (defined(__FreeBSD_version) && 701101 <= __FreeBSD_version) || (defined(__DARWIN_C_LEVEL) && __DARWIN_C_LEVEL >= 200809L)
 253 #       undef DEFINE_STRNDUP
 254 #else
 255 #       define DEFINE_STRNDUP
 256 char *strndup(const char *s, size_t len);
 257 #endif /* strndup is available */
 258
 259 /* strcasestr is available for _GNU_SOURCE, BSD and some Apple */
 260 #if defined(_GNU_SOURCE) || (defined(__BSD_VISIBLE) && __BSD_VISIBLE) || (defined(__APPLE__) && (!defined(_POSIX_C_SOURCE) || defined(_DARWIN_C_SOURCE))) || defined(_NETBSD_SOURCE)
 261 #       undef DEFINE_STRCASESTR
 262 #else
 263 #       define DEFINE_STRCASESTR
 264 char *strcasestr(const char *haystack, const char *needle);
 265 #endif /* strcasestr is available */
 266
 267 int strnatcmp(const char *s1, const char *s2, bool ignore_garbage_at_front = false);
 268
 269 #endif /* STRING_FUNC_H */