1 /* 2 Copyright (C) 2015-2021, Dirk Krause 3 SPDX-License-Identifier: BSD-3-Clause 4 */ 5 6 /* 7 WARNING: This file was generated by the dkct program (see 8 http://dktools.sourceforge.net/ for details). 9 Changes you make here will be lost if dkct is run again! 10 You should modify the original source and run dkct on it. 11 Original source: dk4str8.ctr 12 */ 13 14 #ifndef DK4STR8_H_INCLUDED 15 /** Avoid multiple inclusions. */ 16 #define DK4STR8_H_INCLUDED 1 17 18 19 /** @file 20 Additional string functions for 21 8 bit characters. 22 23 Although some of the functions in this module duplicate 24 functionality from string.h functions, you should use 25 the functions from this module. 26 With DK4DK4_WIN_AVOID_CRT or DK4_WIN_DENY_CRT defined to non-zero 27 these functions call Windows API functions like 28 lstrcmpA() ... instead of CRT functions. 29 */ 30 31 #ifndef DK4CONF_H_INCLUDED 32 #if DK4_BUILDING_DKTOOLS4 33 #include "dk4conf.h" 34 #else 35 #include <dktools-4/dk4conf.h> 36 #endif 37 #endif 38 39 #ifndef DK4TYPES_H_INCLUDED 40 #if DK4_BUILDING_DKTOOLS4 41 #include <libdk4base/dk4types.h> 42 #else 43 #include <dktools-4/dk4types.h> 44 #endif 45 #endif 46 47 #ifndef DK4ERROR_H_INCLUDED 48 #if DK4_BUILDING_DKTOOLS4 49 #include <libdk4base/dk4error.h> 50 #else 51 #include <dktools-4/dk4error.h> 52 #endif 53 #endif 54 55 #ifndef STDLIB_H_INCLUDED 56 #include <stdlib.h> 57 #define STDLIB_H_INCLUDED 1 58 #endif 59 60 61 #ifdef __cplusplus 62 extern "C" { 63 #endif 64 65 /** Copy string, check destination buffer size. 66 67 CRT on Windows: Optional. 68 @param dst Destination buffer address. 69 @param sz Destination buffer size. 70 @param src Source string. 71 @param erp Error report, may be NULL. 72 @return 1 on success, 0 on error. 73 74 Error codes: 75 - DK4_E_INVALID_ARGUMENTS<br> 76 if dst or src is NULL or sz is 0, 77 - DK4_E_BUFFER_TOO_SMALL<br> 78 if the dst buffer is too small. 79 */ 80 int 81 82 dk4str8_cpy_s(char *dst, size_t sz, const char *src, dk4_er_t *erp); 83 84 /** Concatenate strings, check destination buffer size. 85 86 CRT on Windows: Optional. 87 @param dst Destination buffer address. 88 @param sz Destination buffer size. 89 @param src Source string. 90 @param erp Error report, may be NULL. 91 @return 1 on success, 0 on error. 92 93 Error codes: 94 - DK4_E_INVALID_ARGUMENTS<br> 95 if dst or src is NULL or sz is 0, 96 - DK4_E_MATH_OVERFLOW<br> 97 if a mathematical overflow occured in size calculation, 98 - DK4_E_BUFFER_TOO_SMALL<br> 99 if the concatenated string doest not fit into the buffer. 100 */ 101 int 102 103 dk4str8_cat_s(char *dst, size_t sz, const char *src, dk4_er_t *erp); 104 105 /** Copy characters within a string from right to left. 106 This copy operation is intended for moving characters within 107 one string from right to left, making the string shorter 108 as is. This function does not check buffer size or report 109 any error. 110 For normal string copy operations, use the dk4str8_cpy_s() 111 function instead. 112 113 CRT on Windows: Not used. 114 @param dst Destination buffer address. 115 @param src Source string. 116 */ 117 void 118 119 dk4str8_cpy_to_left(char *dst, const char *src); 120 121 /** Find string length. 122 123 CRT on Windows: Optional. 124 @param src Source string. 125 @return String length. 126 */ 127 size_t 128 129 dk4str8_len(const char *src); 130 131 /** Compare two strings. 132 133 CRT on Windows: Optional. 134 @param s1 Left string, may be NULL. 135 @param s2 Right string, may be NULL. 136 @return 1 if s1>s2, 0 if s1==s2, -1 if s1<s2. 137 */ 138 int 139 140 dk4str8_cmp(const char *s1, const char *s2); 141 142 /** Compare two strings. 143 144 CRT on Windows: Optional, disabling CRT probably degrades performance. 145 @param s1 Left string, may be NULL. 146 @param s2 Right string, may be NULL. 147 @param n Maximum number of characters to compare. 148 @return 1 if s1>s2, 0 if s1==s2, -1 if s1<s2. 149 */ 150 int 151 152 dk4str8_ncmp(const char *s1, const char *s2, size_t n); 153 154 /** Compare two strings, case-insensitive comparison. 155 156 CRT on Windows: Optional. 157 @param s1 Left string, may be NULL. 158 @param s2 Right string, may be NULL. 159 @return 1 if s1>s2, 0 if s1==s2, -1 if s1<s2. 160 */ 161 int 162 163 dk4str8_casecmp(const char *s1, const char *s2); 164 165 /** Compare two file path names. 166 167 CRT on Windows: Optional. 168 @param s1 Left string, may be NULL. 169 @param s2 Right string, may be NULL. 170 @return 1 if s1>s2, 0 if s1==s2, -1 if s1<s2. 171 */ 172 int 173 174 dk4str8_pathcmp(const char *s1, const char *s2); 175 176 /** Find first occurance of character c in string s. 177 178 CRT on Windows: Optional, disabling CRT degrades performance. 179 @param s String to search for c. 180 @param c Character to find. 181 @return Pointer to first occurance if found, NULL otherwise. 182 */ 183 char * 184 185 dk4str8_chr(const char *s, char c); 186 187 /** Find last occurance of character c in string s. 188 189 CRT on Windows: Optional, disabling CRT degrades performance. 190 @param s String to search for c. 191 @param c Character to find. 192 @return Pointer to last occurance if found, NULL otherwise. 193 */ 194 char * 195 196 dk4str8_rchr(const char *s, char c); 197 198 /** Retrieve first token from *stringp. 199 200 CRT on Windows: Optional, disabling CRT degrades performance. 201 @param stringp Adress of string pointer. 202 @param delim String containing the delimiter set, 203 my be NULL to use the default delimiter 204 set (space, tabulator, carriage return and newline). 205 @return Pointer to first token on success, NULL if no (further) 206 token found. 207 */ 208 char * 209 210 dk4str8_sep(char **stringp, const char *delim); 211 212 /** Find first token in string. 213 214 CRT on Windows: Optional, disabling CRT degrades performance. 215 @param src String to search for tokens. 216 @param delim String containing the delimiter characters, 217 may be NULL to use the default delimiter set. 218 @return Pointer to first token if found, NULL otherwise. 219 */ 220 char * 221 222 dk4str8_start(const char *src, const char *delim); 223 224 /** Cut string after first token, find start of second token in string. 225 226 CRT on Windows: Optional, disabling CRT degrades performance. 227 @param src String to search for tokens, 228 normally the result of dk4str8_start() or a 229 previous dk4str8_next() call. 230 @param delim String containing the delimiter characters, 231 may be NULL to use the default delimiter set. 232 @return Pointer to second token if found, NULL otherwise. 233 */ 234 char * 235 236 dk4str8_next(char *src, const char *delim); 237 238 /** Split a string into tokens. 239 240 CRT on Windows: Optional, disabling CRT degrades performance. 241 @param dpp Pointer to string pointer array. 242 @param szdpp Size of destination string pointer array. 243 @param src Source string to process. 244 @param delim String containing delimiter characters, 245 may be NULL to use the default delimiter set. 246 @param erp Error report, may be NULL. 247 @return Number of tokens found on success, 0 if no token 248 found or on error. 249 250 Error codes: 251 - DK4_E_INVALID_ARGUMENTS<br> 252 for invalid function arguments, 253 - DK4_E_BUFFER_TOO_SMALL<br> 254 with dt.mem.nelem set to the number of tokens in string if the dpp 255 array is too short. 256 */ 257 size_t 258 259 dk4str8_tokenize( 260 char **dpp, size_t szdpp, char *src, const char *delim, dk4_er_t *erp 261 ); 262 263 /** Normalize a string (remove leading and trailing delimiters, 264 replace delimiter sequences by just one delimiter). 265 266 CRT on Windows: Optional, disabling CRT degrades performance. 267 @param src Buffer containing the string to normalize. 268 @param delim String containing delimiter characters, 269 may be NULL to use the default delimiter set. 270 */ 271 void 272 273 dk4str8_normalize(char *src, const char *delim); 274 275 /** Find index of a string in an array of strings. 276 277 CRT on Windows: Optional. 278 @param arr Array of strings. 279 @param str String to find in array. 280 @param cs Flag: Case-sensitive search (0=no, other=yes). 281 @return Non-negative index value on success, -1 on error. 282 */ 283 int 284 285 dk4str8_array_index(const char * const *arr, const char *str, int cs); 286 287 /** Find index of a string in an array of strings. 288 289 CRT on Windows: Optional, disabling CRT degrades performances 290 and reduces to upper-case conversion to characters 'a' to 'z'. 291 @param arr Array of string allowing abbreviations. 292 @param spec Special character indicating start of optional text. 293 @param str String to find in array. 294 @param cs Flag: Case-sensitive search (0=no, other=yes). 295 @return Non-negative index value on success, -1 on error. 296 */ 297 int 298 299 dk4str8_abbr_index(const char * const *arr, char spec, const char *str, int cs); 300 301 /** Check whether a text matches a pattern, the text may be abbreviated. 302 303 CRT on Windows: Optional, disabling CRT degrades performances 304 and reduces to upper-case conversion to characters 'a' to 'z' 305 in case-insensitive comparisons. 306 @param str Text to check. 307 @param pattern Pattern for comparison. 308 @param spec Special character marking the abbreviation in the 309 pattern. 310 @param cs Flag: Case sensitive (1) or not (0). 311 @return 1 for a match, 0 otherwise. 312 */ 313 int 314 315 dk4str8_is_abbr(const char *str, const char *pattern, char spec, int cs); 316 317 /** Check whether a string represents a boolean value. 318 319 CRT on Windows: Optional, disabling CRT degrades performances. 320 @param str String to check. 321 @return 1 if str represents a boolean value, 0 otherwise. 322 */ 323 int 324 325 dk4str8_is_bool(const char *str); 326 327 /** Check whether a string represents the boolean value TRUE. 328 329 CRT on Windows: Optional, disabling CRT degrades performances. 330 @param str String to check. 331 @return 1 if str represents the boolean value TRUE, 0 otherwise. 332 */ 333 int 334 335 dk4str8_is_on(const char *str); 336 337 #if (DK4_ON_WINDOWS) || (DK4_HAVE_MALLOC && DK4_HAVE_FREE) 338 339 /** Duplicate string in dynamically allocated memory. 340 341 CRT on Windows: Optional, disabling CRT reduces functionality 342 to strings with length fitting to int and overall size in 343 bytes - including finalizer - fitting into a DWORD. 344 @param src String to duplicate. 345 @param erp Error report, may be NULL. 346 @return Pointer to string in new memory on succes, NULL on error. 347 Use dk4mem_free() to release the memory after usage. 348 349 Error codes: 350 - DK4_E_INVALID_ARGUMENTS<br> 351 if src is a NULL pointer, 352 - DK4_E_MATH_OVERFLOW<br> 353 on mathematical overflow in size calculation, 354 - DK4_E_MEMORY<br> 355 if no memory is available. 356 */ 357 char * 358 359 dk4str8_dup(const char *src, dk4_er_t *erp); 360 361 #endif 362 363 364 /** Remove trailing white spaces. 365 366 CRT on Windows: Optional, disabling CRT degrades performance. 367 @param str String to remove white spaces from. 368 @param whsp White spaces set. 369 */ 370 void 371 372 dk4str8_rtwh(char *str, const char *whsp); 373 374 /** Convert character to uppercase. 375 376 CRT on Windows: Optional, disabling CRT degrades performances 377 and reduces functionality to characters 'a' to 'z'. 378 @param c Character to convert. 379 @return Conversion result. 380 */ 381 char 382 383 dk4str8_toupper(char c); 384 385 /** Convert character to lowercase. 386 387 CRT on Windows: Optional, disabling CRT degrades performances 388 and reduces functionality to characters 'A' to 'Z'. 389 @param c Character to convert. 390 @return Conversion result. 391 */ 392 char 393 394 dk4str8_tolower(char c); 395 396 /** Remove trailing newline from line. 397 398 CRT on Windows: Not used. 399 @param lptr Line pointer. 400 */ 401 void 402 403 dk4str8_delnl(char *lptr); 404 405 /** Skip the first text words in a line, return pointer to start 406 of next word. 407 408 CRT on Windows: Optional, disabling CRT degrades performance. 409 @param line Line to process. 410 @param skip Number of words to skip. 411 @return Pointer to next word on success, NULL on error. 412 */ 413 const char * 414 415 dk4str8_skip(const char *line, size_t skip); 416 417 /** Sanitize string (overwrite using 0 bytes). 418 419 CRT on Windows: Optional. 420 @param str Address of string to sanitize. 421 @return 1 on success, 0 on error. 422 */ 423 int 424 425 dk4str8_sanitize(char *str); 426 427 /** Sanitize string buffer (overwrite using 0 bytes). 428 429 CRT on Windows: Optional. 430 @param str Address of string buffer. 431 @param sz Size of string buffer (number of elements). 432 @return 1 on success, 0 on error. 433 */ 434 int 435 436 dk4str8_buffer_sanitize(char *str, size_t sz); 437 438 /** Sanitize dynamically allocated memory and release it. 439 440 CRT on Windows: Optional. 441 @param str Address of string to sanitize and release. 442 @return 1 on success, 0 on error. 443 */ 444 int 445 446 dk4str8_free_sanitized(char *str); 447 448 #ifdef __cplusplus 449 } 450 #endif 451 452 453 /** Sanitize string and release it, set pointer to NULL. 454 @param p Pointer to string to release. 455 */ 456 #define dk4str8_release_sanitized(p) \ 457 do { if (NULL != p) { (void)dk4str8_free_sanitized(p); } p = NULL; } while (0) 458 459 460 461 #endif 462