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: dk4strw.ctr 12 */ 13 14 #ifndef DK4STRW_H_INCLUDED 15 /** Avoid multiple inclusions. */ 16 #define DK4STRW_H_INCLUDED 1 17 18 19 /** @file 20 Additional string functions for 21 wchar_t strings. 22 23 Although some of the functions in this module duplicate 24 functionality from the C runtime library on Windows, 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 lstrcmpW() ... 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 #if DK4_HAVE_WCHAR_H 61 #ifndef WCHAR_H_INCLUDED 62 #include <wchar.h> 63 #define WCHAR_H_INCLUDED 1 64 #endif 65 #endif 66 67 68 #ifdef __cplusplus 69 extern "C" { 70 #endif 71 72 /** Copy string, check destination buffer size. 73 74 CRT on Windows: Optional. 75 @param dst Destination buffer address. 76 @param sz Destination buffer size. 77 @param src Source string. 78 @param erp Error report, may be NULL. 79 @return 1 on success, 0 on error. 80 81 Error codes: 82 - DK4_E_INVALID_ARGUMENTS<br> 83 if dst or src is NULL or sz is 0, 84 - DK4_E_BUFFER_TOO_SMALL<br> 85 if the dst buffer is too small. 86 */ 87 int 88 89 dk4strw_cpy_s(wchar_t *dst, size_t sz, const wchar_t *src, dk4_er_t *erp); 90 91 /** Concatenate strings, check destination buffer size. 92 93 CRT on Windows: Optional. 94 @param dst Destination buffer address. 95 @param sz Destination buffer size. 96 @param src Source string. 97 @param erp Error report, may be NULL. 98 @return 1 on success, 0 on error. 99 100 Error codes: 101 - DK4_E_INVALID_ARGUMENTS<br> 102 if dst or src is NULL or sz is 0, 103 - DK4_E_MATH_OVERFLOW<br> 104 if a mathematical overflow occured in size calculation, 105 - DK4_E_BUFFER_TOO_SMALL<br> 106 if the concatenated string doest not fit into the buffer. 107 */ 108 int 109 110 dk4strw_cat_s(wchar_t *dst, size_t sz, const wchar_t *src, dk4_er_t *erp); 111 112 /** Copy characters within a string from right to left. 113 This copy operation is intended for moving characters within 114 one string from right to left, making the string shorter 115 as is. This function does not check buffer size or report 116 any error. 117 For normal string copy operations, use the dk4strw_cpy_s() 118 function instead. 119 120 CRT on Windows: Not used. 121 @param dst Destination buffer address. 122 @param src Source string. 123 */ 124 void 125 126 dk4strw_cpy_to_left(wchar_t *dst, const wchar_t *src); 127 128 /** Find string length. 129 130 CRT on Windows: Optional, disabling CRT reduces functionality 131 to strings with length fitting to int. 132 @param src Source string. 133 @return String length. 134 */ 135 size_t 136 137 dk4strw_len(const wchar_t *src); 138 139 /** Compare two strings. 140 141 CRT on Windows: Optional. 142 @param s1 Left string, may be NULL. 143 @param s2 Right string, may be NULL. 144 @return 1 if s1>s2, 0 if s1==s2, -1 if s1<s2. 145 */ 146 int 147 148 dk4strw_cmp(const wchar_t *s1, const wchar_t *s2); 149 150 /** Compare two strings. 151 152 CRT on Windows: Optional. 153 @param s1 Left string, may be NULL. 154 @param s2 Right string, may be NULL. 155 @param n Maximum number of characters to compare. 156 @return 1 if s1>s2, 0 if s1==s2, -1 if s1<s2. 157 */ 158 int 159 160 dk4strw_ncmp(const wchar_t *s1, const wchar_t *s2, size_t n); 161 162 /** Compare two strings, case-insensitive comparison. 163 164 CRT on Windows: Optional. 165 @param s1 Left string, may be NULL. 166 @param s2 Right string, may be NULL. 167 @return 1 if s1>s2, 0 if s1==s2, -1 if s1<s2. 168 */ 169 int 170 171 dk4strw_casecmp(const wchar_t *s1, const wchar_t *s2); 172 173 /** Compare two file path names. 174 175 CRT on Windows: Optional. 176 @param s1 Left string, may be NULL. 177 @param s2 Right string, may be NULL. 178 @return 1 if s1>s2, 0 if s1==s2, -1 if s1<s2. 179 */ 180 int 181 182 dk4strw_pathcmp(const wchar_t *s1, const wchar_t *s2); 183 184 /** Find first occurance of character c in string s. 185 186 CRT on Windows: Optional, disabling CRT degrades performance. 187 @param s String to search for c. 188 @param c Character to find. 189 @return Pointer to first occurance if found, NULL otherwise. 190 */ 191 wchar_t * 192 193 dk4strw_chr(const wchar_t *s, wchar_t c); 194 195 /** Find last occurance of character c in string s. 196 197 CRT on Windows: Optional, disabling CRT degrades performance. 198 @param s String to search for c. 199 @param c Character to find. 200 @return Pointer to last occurance if found, NULL otherwise. 201 */ 202 wchar_t * 203 204 dk4strw_rchr(const wchar_t *s, wchar_t c); 205 206 /** Convert character to upper-case character. 207 208 CRT on windows: Optional, disabling CRT degrades performance. 209 @param c Character to convert. 210 @return Conversion result. 211 */ 212 wchar_t 213 214 dk4strw_toupper(wchar_t c); 215 216 /** Convert character to lower-case character. 217 218 CRT on windows: Optional, disabling CRT degrades performance. 219 @param c Character to convert. 220 @return Conversion result. 221 */ 222 wchar_t 223 224 dk4strw_tolower(wchar_t c); 225 226 /** Retrieve first token from *stringp. 227 CRT on Windows: Optional, disabling CRT degrades performance. 228 @param stringp Adress of string pointer. 229 @param delim String containing the delimiter set, 230 my be NULL to use the default delimiter 231 set (space, tabulator, carriage return and newline). 232 @return Pointer to first token on success, NULL if no (further) 233 token found. 234 */ 235 wchar_t * 236 237 dk4strw_sep(wchar_t **stringp, const wchar_t *delim); 238 239 /** Find first token in string. 240 241 CRT on Windows: Optional, disabling CRT degrades performance. 242 @param src String to search for tokens. 243 @param delim String containing the delimiter characters, 244 may be NULL to use the default delimiter set. 245 @return Pointer to first token if found, NULL otherwise. 246 */ 247 wchar_t * 248 249 dk4strw_start(const wchar_t *src, const wchar_t *delim); 250 251 /** Cut string after first token, find start of second token in string. 252 253 CRT on Windows: Optional, disabling CRT degrades performance. 254 @param src String to search for tokens, 255 normally the result of dk4strw_start() or a 256 previous dk4strw_next() call. 257 @param delim String containing the delimiter characters, 258 may be NULL to use the default delimiter set. 259 @return Pointer to second token if found, NULL otherwise. 260 */ 261 wchar_t * 262 263 dk4strw_next(wchar_t *src, const wchar_t *delim); 264 265 /** Split a string into tokens. 266 CRT on Windows: Optional, disabling CRT degrades performance. 267 @param dpp Pointer to string pointer array. 268 @param szdpp Size of destination string pointer array. 269 @param src Source string to process. 270 @param delim String containing delimiter characters, 271 may be NULL to use the default delimiter set. 272 @param erp Error report, may be NULL. 273 @return Number of tokens found on success, 0 if no token 274 found or on error. 275 276 Error codes: 277 - DK4_E_INVALID_ARGUMENTS<br> 278 for invalid function arguments, 279 - DK4_E_BUFFER_TOO_SMALL<br> 280 with dt.mem.nelem set to the number of tokens in string if the dpp 281 array is too short. 282 */ 283 size_t 284 285 dk4strw_tokenize( 286 wchar_t **dpp, size_t szdpp, wchar_t *src, const wchar_t *delim, dk4_er_t *erp 287 ); 288 289 /** Normalize a string (remove leading and trailing delimiters, 290 replace delimiter sequences by just one delimiter). 291 292 CRT on Windows: Optional, disabling CRT degrades performance. 293 @param src Buffer containing the string to normalize. 294 @param delim String containing delimiter characters, 295 may be NULL to use the default delimiter set. 296 */ 297 void 298 299 dk4strw_normalize(wchar_t *src, const wchar_t *delim); 300 301 /** Find index of a string in an array of strings. 302 303 CRT on Windows: Optional. 304 @param arr Array of strings. 305 @param str String to find in array. 306 @param cs Flag: Case-sensitive search (0=no, other=yes). 307 @return Non-negative index value on success, -1 on error. 308 */ 309 int 310 311 dk4strw_array_index(const wchar_t * const *arr, const wchar_t *str, int cs); 312 313 /** Find index of a string in an array of strings. 314 315 CRT on windows: Optional, disabling CRT degrades performance 316 for case-insensitive comparisons. 317 @param arr Array of strings allowing abbreviation. 318 @param spec Special character indicating start of optional text. 319 @param str String to find in array. 320 @param cs Flag: Case-sensitive search (0=no, other=yes). 321 @return Non-negative index value on success, -1 on error. 322 */ 323 int 324 325 dk4strw_abbr_index( 326 const wchar_t * const *arr, 327 wchar_t spec, 328 const wchar_t *str, 329 int cs 330 ); 331 332 /** Check whether a text matches a pattern, the text may be abbreviated. 333 334 CRT on windows: Optional, disabling CRT degrades performance 335 for case-insensitive comparisons. 336 @param str Text to check. 337 @param pattern Pattern for comparison. 338 @param spec Special character marking the abbreviation in the 339 pattern. 340 @param cs Flag: Case sensitive (1) or not (0). 341 @return 1 for a match, 0 otherwise. 342 */ 343 int 344 345 dk4strw_is_abbr(const wchar_t *str,const wchar_t *pattern,wchar_t spec,int cs); 346 347 /** Check whether a string represents a boolean value. 348 349 CRT on windows: Optional, disabling CRT degrades performance. 350 @param str String to check. 351 @return 1 if str represents a boolean value, 0 otherwise. 352 */ 353 int 354 355 dk4strw_is_bool(const wchar_t *str); 356 357 /** Check whether a string represents the boolean value TRUE. 358 359 CRT on windows: Optional, disabling CRT degrades performance. 360 @param str String to check. 361 @return 1 if str represents the boolean value TRUE, 0 otherwise. 362 */ 363 int 364 365 dk4strw_is_on(const wchar_t *str); 366 367 #if (DK4_ON_WINDOWS) || (DK4_HAVE_MALLOC && DK4_HAVE_FREE) 368 369 /** Duplicate string in dynamically allocated memory. 370 371 CRT on Windows: Optional, disabling CRT reduces functionality 372 to strings with length fitting to int and overall size in 373 bytes - including finalizer - fitting into a DWORD. 374 @param src String to duplicate. 375 @param erp Error report, may be NULL. 376 @return Pointer to string in new memory on succes, NULL on error. 377 Use dk4mem_free() to release the memory after usage. 378 379 Error codes: 380 - DK4_E_INVALID_ARGUMENTS<br> 381 if src is a NULL pointer, 382 - DK4_E_MATH_OVERFLOW<br> 383 on mathematical overflow in size calculation, 384 - DK4_E_MEMORY<br> 385 if no memory is available. 386 */ 387 wchar_t * 388 389 dk4strw_dup(const wchar_t *src, dk4_er_t *erp); 390 391 #endif 392 393 394 395 /** Remove trailing white spaces. 396 397 CRT on Windows: Optional, disabling CRT degrades performance. 398 @param str String to remove white spaces from. 399 @param whsp White spaces set. 400 */ 401 void 402 403 dk4strw_rtwh(wchar_t *str, const wchar_t *whsp); 404 405 /** Remove trailing newline from line. 406 407 CRT on Windows: Not used. 408 @param lptr Line pointer. 409 */ 410 void 411 412 dk4strw_delnl(wchar_t *lptr); 413 414 /** Skip the first text words in a line, return pointer to start 415 of next word. 416 417 CRT on Windows: Optional, disabling CRT degrades performance. 418 @param line Line to process. 419 @param skip Number of words to skip. 420 @return Pointer to next word on success, NULL on error. 421 */ 422 const wchar_t * 423 424 dk4strw_skip(const wchar_t *line, size_t skip); 425 426 /** Sanitize string (overwrite using 0). 427 428 CRT on Windows: Optional. 429 @param str Address of string to sanitize. 430 @return 1 on success, 0 on error. 431 */ 432 int 433 434 dk4strw_sanitize(wchar_t *str); 435 436 /** Sanitize string buffer (overwrite using 0 bytes). 437 438 CRT on Windows: Optional. 439 @param str Address of string buffer. 440 @param sz Size of string buffer (number of wchar_t). 441 @return 1 on success, 0 on error. 442 */ 443 int 444 445 dk4strw_buffer_sanitize(wchar_t *str, size_t sz); 446 447 /** Sanitize dynamically allocated memory and release it. 448 449 CRT on Windows: Optional. 450 @param str Address of string to sanitize and release. 451 @return 1 on success, 0 on error. 452 */ 453 int 454 455 dk4strw_free_sanitized(wchar_t *str); 456 457 #ifdef __cplusplus 458 } 459 #endif 460 461 462 /** Sanitize string and release it, set pointer to NULL. 463 @param p Pointer to string to release. 464 */ 465 #define dk4strw_release_sanitized(p) \ 466 do { if (NULL != p) { (void)dk4strw_free_sanitized(p); } p = NULL; } while (0) 467 468 469 #endif 470