1.1 --- a/src/ucx/string.h Mon Dec 30 09:54:10 2019 +0100
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,1201 +0,0 @@
1.4 -/*
1.5 - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
1.6 - *
1.7 - * Copyright 2017 Mike Becker, Olaf Wintermann All rights reserved.
1.8 - *
1.9 - * Redistribution and use in source and binary forms, with or without
1.10 - * modification, are permitted provided that the following conditions are met:
1.11 - *
1.12 - * 1. Redistributions of source code must retain the above copyright
1.13 - * notice, this list of conditions and the following disclaimer.
1.14 - *
1.15 - * 2. Redistributions in binary form must reproduce the above copyright
1.16 - * notice, this list of conditions and the following disclaimer in the
1.17 - * documentation and/or other materials provided with the distribution.
1.18 - *
1.19 - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
1.20 - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1.21 - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
1.22 - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
1.23 - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
1.24 - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
1.25 - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
1.26 - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
1.27 - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
1.28 - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
1.29 - * POSSIBILITY OF SUCH DAMAGE.
1.30 - */
1.31 -/**
1.32 - * Bounded string implementation.
1.33 - *
1.34 - * The UCX strings (<code>sstr_t</code>) provide an alternative to C strings.
1.35 - * The main difference to C strings is, that <code>sstr_t</code> does <b>not
1.36 - * need to be <code>NULL</code>-terminated</b>. Instead the length is stored
1.37 - * within the structure.
1.38 - *
1.39 - * When using <code>sstr_t</code>, developers must be full aware of what type
1.40 - * of string (<code>NULL</code>-terminated) or not) they are using, when
1.41 - * accessing the <code>char* ptr</code> directly.
1.42 - *
1.43 - * The UCX string module provides some common string functions, known from
1.44 - * standard libc, working with <code>sstr_t</code>.
1.45 - *
1.46 - * @file string.h
1.47 - * @author Mike Becker
1.48 - * @author Olaf Wintermann
1.49 - */
1.50 -
1.51 -#ifndef UCX_STRING_H
1.52 -#define UCX_STRING_H
1.53 -
1.54 -#include "ucx.h"
1.55 -#include "allocator.h"
1.56 -#include <stddef.h>
1.57 -
1.58 -/*
1.59 - * Use this macro to disable the shortcuts if you experience macro collision.
1.60 - */
1.61 -#ifndef UCX_NO_SSTR_SHORTCUTS
1.62 -/**
1.63 - * Shortcut for a <code>sstr_t struct</code>
1.64 - * or <code>scstr_t struct</code> literal.
1.65 - */
1.66 -#define ST(s) { s, sizeof(s)-1 }
1.67 -
1.68 -/** Shortcut for the conversion of a C string to a <code>sstr_t</code>. */
1.69 -#define S(s) sstrn(s, sizeof(s)-1)
1.70 -
1.71 -/** Shortcut for the conversion of a C string to a <code>scstr_t</code>. */
1.72 -#define SC(s) scstrn(s, sizeof(s)-1)
1.73 -#endif /* UCX_NO_SSTR_SHORTCUTS */
1.74 -
1.75 -/*
1.76 - * Use this macro to disable the format macros.
1.77 - */
1.78 -#ifndef UCX_NO_SSTR_FORMAT_MACROS
1.79 -/** Expands a sstr_t or scstr_t to printf arguments. */
1.80 -#define SFMT(s) (int) (s).length, (s).ptr
1.81 -
1.82 -/** Format specifier for a sstr_t or scstr_t. */
1.83 -#define PRIsstr ".*s"
1.84 -#endif /* UCX_NO_SSTR_FORMAT_MACROS */
1.85 -
1.86 -#ifdef __cplusplus
1.87 -extern "C" {
1.88 -#endif
1.89 -
1.90 -/**
1.91 - * The UCX string structure.
1.92 - */
1.93 -typedef struct {
1.94 - /** A pointer to the string
1.95 - * (<b>not necessarily <code>NULL</code>-terminated</b>) */
1.96 - char *ptr;
1.97 - /** The length of the string */
1.98 - size_t length;
1.99 -} sstr_t;
1.100 -
1.101 -/**
1.102 - * The UCX string structure for immutable (constant) strings.
1.103 - */
1.104 -typedef struct {
1.105 - /** A constant pointer to the immutable string
1.106 - * (<b>not necessarily <code>NULL</code>-terminated</b>) */
1.107 - const char *ptr;
1.108 - /** The length of the string */
1.109 - size_t length;
1.110 -} scstr_t;
1.111 -
1.112 -#ifdef __cplusplus
1.113 -}
1.114 -#endif
1.115 -
1.116 -
1.117 -#ifdef __cplusplus
1.118 -/**
1.119 - * One of two type adjustment functions that return an scstr_t.
1.120 - *
1.121 - * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
1.122 - *
1.123 - * <b>Do not use this function manually.</b>
1.124 - *
1.125 - * @param str some sstr_t
1.126 - * @return an immutable (scstr_t) version of the provided string.
1.127 - */
1.128 -inline scstr_t s2scstr(sstr_t s) {
1.129 - scstr_t c;
1.130 - c.ptr = s.ptr;
1.131 - c.length = s.length;
1.132 - return c;
1.133 -}
1.134 -
1.135 -/**
1.136 - * One of two type adjustment functions that return an scstr_t.
1.137 - *
1.138 - * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
1.139 - * This variant is used, when the string is already immutable and no operation
1.140 - * needs to be performed.
1.141 - *
1.142 - * <b>Do not use this function manually.</b>
1.143 - *
1.144 - * @param str some scstr_t
1.145 - * @return the argument itself
1.146 - */
1.147 -inline scstr_t s2scstr(scstr_t str) {
1.148 - return str;
1.149 -}
1.150 -
1.151 -/**
1.152 - * Converts a UCX string to an immutable UCX string (scstr_t).
1.153 - * @param str some UCX string
1.154 - * @return an immutable version of the provided string
1.155 - */
1.156 -#define SCSTR(s) s2scstr(s)
1.157 -#else
1.158 -
1.159 -/**
1.160 - * One of two type adjustment functions that return an scstr_t.
1.161 - *
1.162 - * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
1.163 - * This variant is used, when the string is already immutable and no operation
1.164 - * needs to be performed.
1.165 - *
1.166 - * <b>Do not use this function manually.</b>
1.167 - *
1.168 - * @param str some scstr_t
1.169 - * @return the argument itself
1.170 - */
1.171 -scstr_t ucx_sc2sc(scstr_t str);
1.172 -
1.173 -/**
1.174 - * One of two type adjustment functions that return an scstr_t.
1.175 - *
1.176 - * Used <b>internally</b> to convert a UCX string to an immutable UCX string.
1.177 - *
1.178 - * <b>Do not use this function manually.</b>
1.179 - *
1.180 - * @param str some sstr_t
1.181 - * @return an immutable (scstr_t) version of the provided string.
1.182 - */
1.183 -scstr_t ucx_ss2sc(sstr_t str);
1.184 -
1.185 -#if __STDC_VERSION__ >= 201112L
1.186 -/**
1.187 - * Converts a UCX string to an immutable UCX string (scstr_t).
1.188 - * @param str some UCX string
1.189 - * @return an immutable version of the provided string
1.190 - */
1.191 -#define SCSTR(str) _Generic(str, sstr_t: ucx_ss2sc, scstr_t: ucx_sc2sc)(str)
1.192 -
1.193 -#elif defined(__GNUC__) || defined(__clang__)
1.194 -
1.195 -/**
1.196 - * Converts a UCX string to an immutable UCX string (scstr_t).
1.197 - * @param str some UCX string
1.198 - * @return an immutable version of the provided string
1.199 - */
1.200 -#define SCSTR(str) __builtin_choose_expr( \
1.201 - __builtin_types_compatible_p(typeof(str), sstr_t), \
1.202 - ucx_ss2sc, \
1.203 - ucx_sc2sc)(str)
1.204 -
1.205 -#elif defined(__sun)
1.206 -
1.207 -/**
1.208 - * Converts a UCX string to an immutable UCX string (scstr_t).
1.209 - * @param str some UCX string
1.210 - * @return the an immutable version of the provided string
1.211 - */
1.212 -#define SCSTR(str) ({typeof(str) ucx_tmp_var_str = str; \
1.213 - scstr_t ucx_tmp_var_c; \
1.214 - ucx_tmp_var_c.ptr = ucx_tmp_var_str.ptr;\
1.215 - ucx_tmp_var_c.length = ucx_tmp_var_str.length;\
1.216 - ucx_tmp_var_c; })
1.217 -#else /* no generics and no builtins */
1.218 -
1.219 -/**
1.220 - * Converts a UCX string to an immutable UCX string (scstr_t).
1.221 - *
1.222 - * This <b>internal</b> function (ab)uses the C standard an expects one single
1.223 - * argument which is then implicitly converted to scstr_t without a warning.
1.224 - *
1.225 - * <b>Do not use this function manually.</b>
1.226 - *
1.227 - * @return the an immutable version of the provided string
1.228 - */
1.229 -scstr_t ucx_ss2c_s();
1.230 -
1.231 -/**
1.232 - * Converts a UCX string to an immutable UCX string (scstr_t).
1.233 - * @param str some UCX string
1.234 - * @return the an immutable version of the provided string
1.235 - */
1.236 -#define SCSTR(str) ucx_ss2c_s(str)
1.237 -#endif /* C11 feature test */
1.238 -
1.239 -#endif /* C++ */
1.240 -
1.241 -#ifdef __cplusplus
1.242 -extern "C" {
1.243 -#endif
1.244 -
1.245 -
1.246 -/**
1.247 - * Creates a new sstr_t based on a C string.
1.248 - *
1.249 - * The length is implicitly inferred by using a call to <code>strlen()</code>.
1.250 - *
1.251 - * <b>Note:</b> the sstr_t will share the specified pointer to the C string.
1.252 - * If you do want a copy, use sstrdup() on the return value of this function.
1.253 - *
1.254 - * If you need to wrap a constant string, use scstr().
1.255 - *
1.256 - * @param cstring the C string to wrap
1.257 - * @return a new sstr_t containing the C string
1.258 - *
1.259 - * @see sstrn()
1.260 - */
1.261 -sstr_t sstr(char *cstring);
1.262 -
1.263 -/**
1.264 - * Creates a new sstr_t of the specified length based on a C string.
1.265 - *
1.266 - * <b>Note:</b> the sstr_t will share the specified pointer to the C string.
1.267 - * If you do want a copy, use sstrdup() on the return value of this function.
1.268 - *
1.269 - * If you need to wrap a constant string, use scstrn().
1.270 - *
1.271 - * @param cstring the C string to wrap
1.272 - * @param length the length of the string
1.273 - * @return a new sstr_t containing the C string
1.274 - *
1.275 - * @see sstr()
1.276 - * @see S()
1.277 - */
1.278 -sstr_t sstrn(char *cstring, size_t length);
1.279 -
1.280 -/**
1.281 - * Creates a new scstr_t based on a constant C string.
1.282 - *
1.283 - * The length is implicitly inferred by using a call to <code>strlen()</code>.
1.284 - *
1.285 - * <b>Note:</b> the scstr_t will share the specified pointer to the C string.
1.286 - * If you do want a copy, use scstrdup() on the return value of this function.
1.287 - *
1.288 - * @param cstring the C string to wrap
1.289 - * @return a new scstr_t containing the C string
1.290 - *
1.291 - * @see scstrn()
1.292 - */
1.293 -scstr_t scstr(const char *cstring);
1.294 -
1.295 -
1.296 -/**
1.297 - * Creates a new scstr_t of the specified length based on a constant C string.
1.298 - *
1.299 - * <b>Note:</b> the scstr_t will share the specified pointer to the C string.
1.300 - * If you do want a copy, use scstrdup() on the return value of this function. *
1.301 - *
1.302 - * @param cstring the C string to wrap
1.303 - * @param length the length of the string
1.304 - * @return a new scstr_t containing the C string
1.305 - *
1.306 - * @see scstr()
1.307 - */
1.308 -scstr_t scstrn(const char *cstring, size_t length);
1.309 -
1.310 -/**
1.311 - * Returns the accumulated length of all specified strings.
1.312 - *
1.313 - * <b>Attention:</b> if the count argument is larger than the count of the
1.314 - * specified strings, the behavior is undefined.
1.315 - *
1.316 - * @param count the total number of specified strings
1.317 - * @param ... all strings
1.318 - * @return the accumulated length of all strings
1.319 - */
1.320 -size_t scstrnlen(size_t count, ...);
1.321 -
1.322 -/**
1.323 - * Returns the accumulated length of all specified strings.
1.324 - *
1.325 - * <b>Attention:</b> if the count argument is larger than the count of the
1.326 - * specified strings, the behavior is undefined.
1.327 - *
1.328 - * @param count the total number of specified strings
1.329 - * @param ... all strings
1.330 - * @return the cumulated length of all strings
1.331 - */
1.332 -#define sstrnlen(count, ...) scstrnlen(count, __VA_ARGS__)
1.333 -
1.334 -/**
1.335 - * Concatenates two or more strings.
1.336 - *
1.337 - * The resulting string will be allocated by standard <code>malloc()</code>.
1.338 - * So developers <b>MUST</b> pass the sstr_t.ptr to <code>free()</code>.
1.339 - *
1.340 - * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
1.341 - * terminated.
1.342 - *
1.343 - * @param count the total number of strings to concatenate
1.344 - * @param s1 first string
1.345 - * @param ... all remaining strings
1.346 - * @return the concatenated string
1.347 - */
1.348 -sstr_t scstrcat(size_t count, scstr_t s1, ...);
1.349 -
1.350 -/**
1.351 - * Concatenates two or more strings.
1.352 - *
1.353 - * The resulting string will be allocated by standard <code>malloc()</code>.
1.354 - * So developers <b>MUST</b> pass the sstr_t.ptr to <code>free()</code>.
1.355 - *
1.356 - * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
1.357 - * terminated.
1.358 - *
1.359 - * @param count the total number of strings to concatenate
1.360 - * @param s1 first string
1.361 - * @param ... all remaining strings
1.362 - * @return the concatenated string
1.363 - */
1.364 -#define sstrcat(count, s1, ...) scstrcat(count, SCSTR(s1), __VA_ARGS__)
1.365 -
1.366 -/**
1.367 - * Concatenates two or more strings using a UcxAllocator.
1.368 - *
1.369 - * The resulting string must be freed by the allocators <code>free()</code>
1.370 - * implementation.
1.371 - *
1.372 - * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
1.373 - * terminated.
1.374 - *
1.375 - * @param alloc the allocator to use
1.376 - * @param count the total number of strings to concatenate
1.377 - * @param s1 first string
1.378 - * @param ... all remaining strings
1.379 - * @return the concatenated string
1.380 - *
1.381 - * @see scstrcat()
1.382 - */
1.383 -sstr_t scstrcat_a(UcxAllocator *alloc, size_t count, scstr_t s1, ...);
1.384 -
1.385 -/**
1.386 - * Concatenates two or more strings using a UcxAllocator.
1.387 - *
1.388 - * The resulting string must be freed by the allocators <code>free()</code>
1.389 - * implementation.
1.390 - *
1.391 - * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
1.392 - * terminated.
1.393 - *
1.394 - * @param alloc the allocator to use
1.395 - * @param count the total number of strings to concatenate
1.396 - * @param s1 first string
1.397 - * @param ... all remaining strings
1.398 - * @return the concatenated string
1.399 - *
1.400 - * @see sstrcat()
1.401 - */
1.402 -#define sstrcat_a(alloc, count, s1, ...) \
1.403 - scstrcat_a(alloc, count, SCSTR(s1), __VA_ARGS__)
1.404 -
1.405 -/**
1.406 - * Returns a substring starting at the specified location.
1.407 - *
1.408 - * <b>Attention:</b> the new string references the same memory area as the
1.409 - * input string and is <b>NOT</b> required to be <code>NULL</code>-terminated.
1.410 - * Use sstrdup() to get a copy.
1.411 - *
1.412 - * @param string input string
1.413 - * @param start start location of the substring
1.414 - * @return a substring of <code>string</code> starting at <code>start</code>
1.415 - *
1.416 - * @see sstrsubsl()
1.417 - * @see sstrchr()
1.418 - */
1.419 -sstr_t sstrsubs(sstr_t string, size_t start);
1.420 -
1.421 -/**
1.422 - * Returns a substring with the given length starting at the specified location.
1.423 - *
1.424 - * <b>Attention:</b> the new string references the same memory area as the
1.425 - * input string and is <b>NOT</b> required to be <code>NULL</code>-terminated.
1.426 - * Use sstrdup() to get a copy.
1.427 - *
1.428 - * @param string input string
1.429 - * @param start start location of the substring
1.430 - * @param length the maximum length of the substring
1.431 - * @return a substring of <code>string</code> starting at <code>start</code>
1.432 - * with a maximum length of <code>length</code>
1.433 - *
1.434 - * @see sstrsubs()
1.435 - * @see sstrchr()
1.436 - */
1.437 -sstr_t sstrsubsl(sstr_t string, size_t start, size_t length);
1.438 -
1.439 -/**
1.440 - * Returns a substring of an immutable string starting at the specified
1.441 - * location.
1.442 - *
1.443 - * <b>Attention:</b> the new string references the same memory area as the
1.444 -* input string and is <b>NOT</b> required to be <code>NULL</code>-terminated.
1.445 - * Use scstrdup() to get a copy.
1.446 - *
1.447 - * @param string input string
1.448 - * @param start start location of the substring
1.449 - * @return a substring of <code>string</code> starting at <code>start</code>
1.450 - *
1.451 - * @see scstrsubsl()
1.452 - * @see scstrchr()
1.453 - */
1.454 -scstr_t scstrsubs(scstr_t string, size_t start);
1.455 -
1.456 -/**
1.457 - * Returns a substring of an immutable string with a maximum length starting
1.458 - * at the specified location.
1.459 - *
1.460 - * <b>Attention:</b> the new string references the same memory area as the
1.461 - * input string and is <b>NOT</b> required to be <code>NULL</code>-terminated.
1.462 - * Use scstrdup() to get a copy.
1.463 - *
1.464 - * @param string input string
1.465 - * @param start start location of the substring
1.466 - * @param length the maximum length of the substring
1.467 - * @return a substring of <code>string</code> starting at <code>start</code>
1.468 - * with a maximum length of <code>length</code>
1.469 - *
1.470 - * @see scstrsubs()
1.471 - * @see scstrchr()
1.472 - */
1.473 -scstr_t scstrsubsl(scstr_t string, size_t start, size_t length);
1.474 -
1.475 -/**
1.476 - * Returns a substring starting at the location of the first occurrence of the
1.477 - * specified character.
1.478 - *
1.479 - * If the string does not contain the character, an empty string is returned.
1.480 - *
1.481 - * @param string the string where to locate the character
1.482 - * @param chr the character to locate
1.483 - * @return a substring starting at the first location of <code>chr</code>
1.484 - *
1.485 - * @see sstrsubs()
1.486 - */
1.487 -sstr_t sstrchr(sstr_t string, int chr);
1.488 -
1.489 -/**
1.490 - * Returns a substring starting at the location of the last occurrence of the
1.491 - * specified character.
1.492 - *
1.493 - * If the string does not contain the character, an empty string is returned.
1.494 - *
1.495 - * @param string the string where to locate the character
1.496 - * @param chr the character to locate
1.497 - * @return a substring starting at the last location of <code>chr</code>
1.498 - *
1.499 - * @see sstrsubs()
1.500 - */
1.501 -sstr_t sstrrchr(sstr_t string, int chr);
1.502 -
1.503 -/**
1.504 - * Returns an immutable substring starting at the location of the first
1.505 - * occurrence of the specified character.
1.506 - *
1.507 - * If the string does not contain the character, an empty string is returned.
1.508 - *
1.509 - * @param string the string where to locate the character
1.510 - * @param chr the character to locate
1.511 - * @return a substring starting at the first location of <code>chr</code>
1.512 - *
1.513 - * @see scstrsubs()
1.514 - */
1.515 -scstr_t scstrchr(scstr_t string, int chr);
1.516 -
1.517 -/**
1.518 - * Returns an immutable substring starting at the location of the last
1.519 - * occurrence of the specified character.
1.520 - *
1.521 - * If the string does not contain the character, an empty string is returned.
1.522 - *
1.523 - * @param string the string where to locate the character
1.524 - * @param chr the character to locate
1.525 - * @return a substring starting at the last location of <code>chr</code>
1.526 - *
1.527 - * @see scstrsubs()
1.528 - */
1.529 -scstr_t scstrrchr(scstr_t string, int chr);
1.530 -
1.531 -/**
1.532 - * Returns a substring starting at the location of the first occurrence of the
1.533 - * specified string.
1.534 - *
1.535 - * If the string does not contain the other string, an empty string is returned.
1.536 - *
1.537 - * If <code>match</code> is an empty string, the complete <code>string</code> is
1.538 - * returned.
1.539 - *
1.540 - * @param string the string to be scanned
1.541 - * @param match string containing the sequence of characters to match
1.542 - * @return a substring starting at the first occurrence of
1.543 - * <code>match</code>, or an empty string, if the sequence is not
1.544 - * present in <code>string</code>
1.545 - */
1.546 -sstr_t scstrsstr(sstr_t string, scstr_t match);
1.547 -
1.548 -/**
1.549 - * Returns a substring starting at the location of the first occurrence of the
1.550 - * specified string.
1.551 - *
1.552 - * If the string does not contain the other string, an empty string is returned.
1.553 - *
1.554 - * If <code>match</code> is an empty string, the complete <code>string</code> is
1.555 - * returned.
1.556 - *
1.557 - * @param string the string to be scanned
1.558 - * @param match string containing the sequence of characters to match
1.559 - * @return a substring starting at the first occurrence of
1.560 - * <code>match</code>, or an empty string, if the sequence is not
1.561 - * present in <code>string</code>
1.562 - */
1.563 -#define sstrstr(string, match) scstrsstr(string, SCSTR(match))
1.564 -
1.565 -/**
1.566 - * Returns an immutable substring starting at the location of the
1.567 - * first occurrence of the specified immutable string.
1.568 - *
1.569 - * If the string does not contain the other string, an empty string is returned.
1.570 - *
1.571 - * If <code>match</code> is an empty string, the complete <code>string</code> is
1.572 - * returned.
1.573 - *
1.574 - * @param string the string to be scanned
1.575 - * @param match string containing the sequence of characters to match
1.576 - * @return a substring starting at the first occurrence of
1.577 - * <code>match</code>, or an empty string, if the sequence is not
1.578 - * present in <code>string</code>
1.579 - */
1.580 -scstr_t scstrscstr(scstr_t string, scstr_t match);
1.581 -
1.582 -/**
1.583 - * Returns an immutable substring starting at the location of the
1.584 - * first occurrence of the specified immutable string.
1.585 - *
1.586 - * If the string does not contain the other string, an empty string is returned.
1.587 - *
1.588 - * If <code>match</code> is an empty string, the complete <code>string</code> is
1.589 - * returned.
1.590 - *
1.591 - * @param string the string to be scanned
1.592 - * @param match string containing the sequence of characters to match
1.593 - * @return a substring starting at the first occurrence of
1.594 - * <code>match</code>, or an empty string, if the sequence is not
1.595 - * present in <code>string</code>
1.596 - */
1.597 -#define sstrscstr(string, match) scstrscstr(string, SCSTR(match))
1.598 -
1.599 -/**
1.600 - * Splits a string into parts by using a delimiter string.
1.601 - *
1.602 - * This function will return <code>NULL</code>, if one of the following happens:
1.603 - * <ul>
1.604 - * <li>the string length is zero</li>
1.605 - * <li>the delimeter length is zero</li>
1.606 - * <li>the string equals the delimeter</li>
1.607 - * <li>memory allocation fails</li>
1.608 - * </ul>
1.609 - *
1.610 - * The integer referenced by <code>count</code> is used as input and determines
1.611 - * the maximum size of the resulting array, i.e. the maximum count of splits to
1.612 - * perform + 1.
1.613 - *
1.614 - * The integer referenced by <code>count</code> is also used as output and is
1.615 - * set to
1.616 - * <ul>
1.617 - * <li>-2, on memory allocation errors</li>
1.618 - * <li>-1, if either the string or the delimiter is an empty string</li>
1.619 - * <li>0, if the string equals the delimiter</li>
1.620 - * <li>1, if the string does not contain the delimiter</li>
1.621 - * <li>the count of array items, otherwise</li>
1.622 - * </ul>
1.623 - *
1.624 - * If the string starts with the delimiter, the first item of the resulting
1.625 - * array will be an empty string.
1.626 - *
1.627 - * If the string ends with the delimiter and the maximum list size is not
1.628 - * exceeded, the last array item will be an empty string.
1.629 - * In case the list size would be exceeded, the last array item will be the
1.630 - * remaining string after the last split, <i>including</i> the terminating
1.631 - * delimiter.
1.632 - *
1.633 - * <b>Attention:</b> The array pointer <b>AND</b> all sstr_t.ptr of the array
1.634 - * items must be manually passed to <code>free()</code>. Use scstrsplit_a() with
1.635 - * an allocator to managed memory, to avoid this.
1.636 - *
1.637 - * @param string the string to split
1.638 - * @param delim the delimiter string
1.639 - * @param count IN: the maximum size of the resulting array (0 = no limit),
1.640 - * OUT: the actual size of the array
1.641 - * @return a sstr_t array containing the split strings or
1.642 - * <code>NULL</code> on error
1.643 - *
1.644 - * @see scstrsplit_a()
1.645 - */
1.646 -sstr_t* scstrsplit(scstr_t string, scstr_t delim, ssize_t *count);
1.647 -
1.648 -/**
1.649 - * Splits a string into parts by using a delimiter string.
1.650 - *
1.651 - * This function will return <code>NULL</code>, if one of the following happens:
1.652 - * <ul>
1.653 - * <li>the string length is zero</li>
1.654 - * <li>the delimeter length is zero</li>
1.655 - * <li>the string equals the delimeter</li>
1.656 - * <li>memory allocation fails</li>
1.657 - * </ul>
1.658 - *
1.659 - * The integer referenced by <code>count</code> is used as input and determines
1.660 - * the maximum size of the resulting array, i.e. the maximum count of splits to
1.661 - * perform + 1.
1.662 - *
1.663 - * The integer referenced by <code>count</code> is also used as output and is
1.664 - * set to
1.665 - * <ul>
1.666 - * <li>-2, on memory allocation errors</li>
1.667 - * <li>-1, if either the string or the delimiter is an empty string</li>
1.668 - * <li>0, if the string equals the delimiter</li>
1.669 - * <li>1, if the string does not contain the delimiter</li>
1.670 - * <li>the count of array items, otherwise</li>
1.671 - * </ul>
1.672 - *
1.673 - * If the string starts with the delimiter, the first item of the resulting
1.674 - * array will be an empty string.
1.675 - *
1.676 - * If the string ends with the delimiter and the maximum list size is not
1.677 - * exceeded, the last array item will be an empty string.
1.678 - * In case the list size would be exceeded, the last array item will be the
1.679 - * remaining string after the last split, <i>including</i> the terminating
1.680 - * delimiter.
1.681 - *
1.682 - * <b>Attention:</b> The array pointer <b>AND</b> all sstr_t.ptr of the array
1.683 - * items must be manually passed to <code>free()</code>. Use sstrsplit_a() with
1.684 - * an allocator to managed memory, to avoid this.
1.685 - *
1.686 - * @param string the string to split
1.687 - * @param delim the delimiter string
1.688 - * @param count IN: the maximum size of the resulting array (0 = no limit),
1.689 - * OUT: the actual size of the array
1.690 - * @return a sstr_t array containing the split strings or
1.691 - * <code>NULL</code> on error
1.692 - *
1.693 - * @see sstrsplit_a()
1.694 - */
1.695 -#define sstrsplit(string, delim, count) \
1.696 - scstrsplit(SCSTR(string), SCSTR(delim), count)
1.697 -
1.698 -/**
1.699 - * Performing scstrsplit() using a UcxAllocator.
1.700 - *
1.701 - * <i>Read the description of scstrsplit() for details.</i>
1.702 - *
1.703 - * The memory for the sstr_t.ptr pointers of the array items and the memory for
1.704 - * the sstr_t array itself are allocated by using the UcxAllocator.malloc()
1.705 - * function.
1.706 - *
1.707 - * @param allocator the UcxAllocator used for allocating memory
1.708 - * @param string the string to split
1.709 - * @param delim the delimiter string
1.710 - * @param count IN: the maximum size of the resulting array (0 = no limit),
1.711 - * OUT: the actual size of the array
1.712 - * @return a sstr_t array containing the split strings or
1.713 - * <code>NULL</code> on error
1.714 - *
1.715 - * @see scstrsplit()
1.716 - */
1.717 -sstr_t* scstrsplit_a(UcxAllocator *allocator, scstr_t string, scstr_t delim,
1.718 - ssize_t *count);
1.719 -
1.720 -/**
1.721 - * Performing sstrsplit() using a UcxAllocator.
1.722 - *
1.723 - * <i>Read the description of sstrsplit() for details.</i>
1.724 - *
1.725 - * The memory for the sstr_t.ptr pointers of the array items and the memory for
1.726 - * the sstr_t array itself are allocated by using the UcxAllocator.malloc()
1.727 - * function.
1.728 - *
1.729 - * @param allocator the UcxAllocator used for allocating memory
1.730 - * @param string the string to split
1.731 - * @param delim the delimiter string
1.732 - * @param count IN: the maximum size of the resulting array (0 = no limit),
1.733 - * OUT: the actual size of the array
1.734 - * @return a sstr_t array containing the split strings or
1.735 - * <code>NULL</code> on error
1.736 - *
1.737 - * @see sstrsplit()
1.738 - */
1.739 -#define sstrsplit_a(allocator, string, delim, count) \
1.740 - scstrsplit_a(allocator, SCSTR(string), SCSTR(delim), count)
1.741 -
1.742 -/**
1.743 - * Compares two UCX strings with standard <code>memcmp()</code>.
1.744 - *
1.745 - * At first it compares the scstr_t.length attribute of the two strings. The
1.746 - * <code>memcmp()</code> function is called, if and only if the lengths match.
1.747 - *
1.748 - * @param s1 the first string
1.749 - * @param s2 the second string
1.750 - * @return -1, if the length of s1 is less than the length of s2 or 1, if the
1.751 - * length of s1 is greater than the length of s2 or the result of
1.752 - * <code>memcmp()</code> otherwise (i.e. 0 if the strings match)
1.753 - */
1.754 -int scstrcmp(scstr_t s1, scstr_t s2);
1.755 -
1.756 -/**
1.757 - * Compares two UCX strings with standard <code>memcmp()</code>.
1.758 - *
1.759 - * At first it compares the sstr_t.length attribute of the two strings. The
1.760 - * <code>memcmp()</code> function is called, if and only if the lengths match.
1.761 - *
1.762 - * @param s1 the first string
1.763 - * @param s2 the second string
1.764 - * @return -1, if the length of s1 is less than the length of s2 or 1, if the
1.765 - * length of s1 is greater than the length of s2 or the result of
1.766 - * <code>memcmp()</code> otherwise (i.e. 0 if the strings match)
1.767 - */
1.768 -#define sstrcmp(s1, s2) scstrcmp(SCSTR(s1), SCSTR(s2))
1.769 -
1.770 -/**
1.771 - * Compares two UCX strings ignoring the case.
1.772 - *
1.773 - * At first it compares the scstr_t.length attribute of the two strings. If and
1.774 - * only if the lengths match, both strings are compared char by char ignoring
1.775 - * the case.
1.776 - *
1.777 - * @param s1 the first string
1.778 - * @param s2 the second string
1.779 - * @return -1, if the length of s1 is less than the length of s2 or 1, if the
1.780 - * length of s1 is greater than the length of s2 or the result of the platform
1.781 - * specific string comparison function ignoring the case.
1.782 - */
1.783 -int scstrcasecmp(scstr_t s1, scstr_t s2);
1.784 -
1.785 -/**
1.786 - * Compares two UCX strings ignoring the case.
1.787 - *
1.788 - * At first it compares the sstr_t.length attribute of the two strings. If and
1.789 - * only if the lengths match, both strings are compared char by char ignoring
1.790 - * the case.
1.791 - *
1.792 - * @param s1 the first string
1.793 - * @param s2 the second string
1.794 - * @return -1, if the length of s1 is less than the length of s2 or 1, if the
1.795 - * length of s1 is greater than the length of s2 or the result of the platform
1.796 - * specific string comparison function ignoring the case.
1.797 - */
1.798 -#define sstrcasecmp(s1, s2) scstrcasecmp(SCSTR(s1), SCSTR(s2))
1.799 -
1.800 -/**
1.801 - * Creates a duplicate of the specified string.
1.802 - *
1.803 - * The new sstr_t will contain a copy allocated by standard
1.804 - * <code>malloc()</code>. So developers <b>MUST</b> pass the sstr_t.ptr to
1.805 - * <code>free()</code>.
1.806 - *
1.807 - * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
1.808 - * terminated and mutable, regardless of the argument.
1.809 - *
1.810 - * @param string the string to duplicate
1.811 - * @return a duplicate of the string
1.812 - * @see scstrdup_a()
1.813 - */
1.814 -sstr_t scstrdup(scstr_t string);
1.815 -
1.816 -/**
1.817 - * Creates a duplicate of the specified string.
1.818 - *
1.819 - * The new sstr_t will contain a copy allocated by standard
1.820 - * <code>malloc()</code>. So developers <b>MUST</b> pass the sstr_t.ptr to
1.821 - * <code>free()</code>.
1.822 - *
1.823 - * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
1.824 - * terminated, regardless of the argument.
1.825 - *
1.826 - * @param string the string to duplicate
1.827 - * @return a duplicate of the string
1.828 - * @see sstrdup_a()
1.829 - */
1.830 -#define sstrdup(string) scstrdup(SCSTR(string))
1.831 -
1.832 -/**
1.833 - * Creates a duplicate of the specified string using a UcxAllocator.
1.834 - *
1.835 - * The new sstr_t will contain a copy allocated by the allocators
1.836 - * UcxAllocator.malloc() function. So it is implementation depended, whether the
1.837 - * returned sstr_t.ptr pointer must be passed to the allocators
1.838 - * UcxAllocator.free() function manually.
1.839 - *
1.840 - * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
1.841 - * terminated and mutable, regardless of the argument.
1.842 - *
1.843 - * @param allocator a valid instance of a UcxAllocator
1.844 - * @param string the string to duplicate
1.845 - * @return a duplicate of the string
1.846 - * @see scstrdup()
1.847 - */
1.848 -sstr_t scstrdup_a(UcxAllocator *allocator, scstr_t string);
1.849 -
1.850 -/**
1.851 - * Creates a duplicate of the specified string using a UcxAllocator.
1.852 - *
1.853 - * The new sstr_t will contain a copy allocated by the allocators
1.854 - * UcxAllocator.malloc() function. So it is implementation depended, whether the
1.855 - * returned sstr_t.ptr pointer must be passed to the allocators
1.856 - * UcxAllocator.free() function manually.
1.857 - *
1.858 - * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
1.859 - * terminated, regardless of the argument.
1.860 - *
1.861 - * @param allocator a valid instance of a UcxAllocator
1.862 - * @param string the string to duplicate
1.863 - * @return a duplicate of the string
1.864 - * @see scstrdup()
1.865 - */
1.866 -#define sstrdup_a(allocator, string) scstrdup_a(allocator, SCSTR(string))
1.867 -
1.868 -
1.869 -/**
1.870 - * Omits leading and trailing spaces.
1.871 - *
1.872 - * This function returns a new sstr_t containing a trimmed version of the
1.873 - * specified string.
1.874 - *
1.875 - * <b>Note:</b> the new sstr_t references the same memory, thus you
1.876 - * <b>MUST NOT</b> pass the sstr_t.ptr of the return value to
1.877 - * <code>free()</code>. It is also highly recommended to avoid assignments like
1.878 - * <code>mystr = sstrtrim(mystr);</code> as you lose the reference to the
1.879 - * source string. Assignments of this type are only permitted, if the
1.880 - * sstr_t.ptr of the source string does not need to be freed or if another
1.881 - * reference to the source string exists.
1.882 - *
1.883 - * @param string the string that shall be trimmed
1.884 - * @return a new sstr_t containing the trimmed string
1.885 - */
1.886 -sstr_t sstrtrim(sstr_t string);
1.887 -
1.888 -/**
1.889 - * Omits leading and trailing spaces.
1.890 - *
1.891 - * This function returns a new scstr_t containing a trimmed version of the
1.892 - * specified string.
1.893 - *
1.894 - * <b>Note:</b> the new scstr_t references the same memory, thus you
1.895 - * <b>MUST NOT</b> pass the scstr_t.ptr of the return value to
1.896 - * <code>free()</code>. It is also highly recommended to avoid assignments like
1.897 - * <code>mystr = scstrtrim(mystr);</code> as you lose the reference to the
1.898 - * source string. Assignments of this type are only permitted, if the
1.899 - * scstr_t.ptr of the source string does not need to be freed or if another
1.900 - * reference to the source string exists.
1.901 - *
1.902 - * @param string the string that shall be trimmed
1.903 - * @return a new scstr_t containing the trimmed string
1.904 - */
1.905 -scstr_t scstrtrim(scstr_t string);
1.906 -
1.907 -/**
1.908 - * Checks, if a string has a specific prefix.
1.909 - *
1.910 - * @param string the string to check
1.911 - * @param prefix the prefix the string should have
1.912 - * @return 1, if and only if the string has the specified prefix, 0 otherwise
1.913 - */
1.914 -int scstrprefix(scstr_t string, scstr_t prefix);
1.915 -
1.916 -/**
1.917 - * Checks, if a string has a specific prefix.
1.918 - *
1.919 - * @param string the string to check
1.920 - * @param prefix the prefix the string should have
1.921 - * @return 1, if and only if the string has the specified prefix, 0 otherwise
1.922 - */
1.923 -#define sstrprefix(string, prefix) scstrprefix(SCSTR(string), SCSTR(prefix))
1.924 -
1.925 -/**
1.926 - * Checks, if a string has a specific suffix.
1.927 - *
1.928 - * @param string the string to check
1.929 - * @param suffix the suffix the string should have
1.930 - * @return 1, if and only if the string has the specified suffix, 0 otherwise
1.931 - */
1.932 -int scstrsuffix(scstr_t string, scstr_t suffix);
1.933 -
1.934 -/**
1.935 - * Checks, if a string has a specific suffix.
1.936 - *
1.937 - * @param string the string to check
1.938 - * @param suffix the suffix the string should have
1.939 - * @return 1, if and only if the string has the specified suffix, 0 otherwise
1.940 - */
1.941 -#define sstrsuffix(string, suffix) scstrsuffix(SCSTR(string), SCSTR(suffix))
1.942 -
1.943 -/**
1.944 - * Checks, if a string has a specific prefix, ignoring the case.
1.945 - *
1.946 - * @param string the string to check
1.947 - * @param prefix the prefix the string should have
1.948 - * @return 1, if and only if the string has the specified prefix, 0 otherwise
1.949 - */
1.950 -int scstrcaseprefix(scstr_t string, scstr_t prefix);
1.951 -
1.952 -/**
1.953 - * Checks, if a string has a specific prefix, ignoring the case.
1.954 - *
1.955 - * @param string the string to check
1.956 - * @param prefix the prefix the string should have
1.957 - * @return 1, if and only if the string has the specified prefix, 0 otherwise
1.958 - */
1.959 -#define sstrcaseprefix(string, prefix) \
1.960 - scstrcaseprefix(SCSTR(string), SCSTR(prefix))
1.961 -
1.962 -/**
1.963 - * Checks, if a string has a specific suffix, ignoring the case.
1.964 - *
1.965 - * @param string the string to check
1.966 - * @param suffix the suffix the string should have
1.967 - * @return 1, if and only if the string has the specified suffix, 0 otherwise
1.968 - */
1.969 -int scstrcasesuffix(scstr_t string, scstr_t suffix);
1.970 -
1.971 -/**
1.972 - * Checks, if a string has a specific suffix, ignoring the case.
1.973 - *
1.974 - * @param string the string to check
1.975 - * @param suffix the suffix the string should have
1.976 - * @return 1, if and only if the string has the specified suffix, 0 otherwise
1.977 - */
1.978 -#define sstrcasesuffix(string, suffix) \
1.979 - scstrcasesuffix(SCSTR(string), SCSTR(suffix))
1.980 -
1.981 -/**
1.982 - * Returns a lower case version of a string.
1.983 - *
1.984 - * This function creates a duplicate of the input string, first
1.985 - * (see scstrdup()).
1.986 - *
1.987 - * @param string the input string
1.988 - * @return the resulting lower case string
1.989 - * @see scstrdup()
1.990 - */
1.991 -sstr_t scstrlower(scstr_t string);
1.992 -
1.993 -/**
1.994 - * Returns a lower case version of a string.
1.995 - *
1.996 - * This function creates a duplicate of the input string, first
1.997 - * (see sstrdup()).
1.998 - *
1.999 - * @param string the input string
1.1000 - * @return the resulting lower case string
1.1001 - */
1.1002 -#define sstrlower(string) scstrlower(SCSTR(string))
1.1003 -
1.1004 -/**
1.1005 - * Returns a lower case version of a string.
1.1006 - *
1.1007 - * This function creates a duplicate of the input string, first
1.1008 - * (see scstrdup_a()).
1.1009 - *
1.1010 - * @param allocator the allocator used for duplicating the string
1.1011 - * @param string the input string
1.1012 - * @return the resulting lower case string
1.1013 - * @see scstrdup_a()
1.1014 - */
1.1015 -sstr_t scstrlower_a(UcxAllocator *allocator, scstr_t string);
1.1016 -
1.1017 -
1.1018 -/**
1.1019 - * Returns a lower case version of a string.
1.1020 - *
1.1021 - * This function creates a duplicate of the input string, first
1.1022 - * (see sstrdup_a()).
1.1023 - *
1.1024 - * @param allocator the allocator used for duplicating the string
1.1025 - * @param string the input string
1.1026 - * @return the resulting lower case string
1.1027 - */
1.1028 -#define sstrlower_a(allocator, string) scstrlower_a(allocator, SCSTR(string))
1.1029 -
1.1030 -/**
1.1031 - * Returns a upper case version of a string.
1.1032 - *
1.1033 - * This function creates a duplicate of the input string, first
1.1034 - * (see scstrdup()).
1.1035 - *
1.1036 - * @param string the input string
1.1037 - * @return the resulting upper case string
1.1038 - * @see scstrdup()
1.1039 - */
1.1040 -sstr_t scstrupper(scstr_t string);
1.1041 -
1.1042 -/**
1.1043 - * Returns a upper case version of a string.
1.1044 - *
1.1045 - * This function creates a duplicate of the input string, first
1.1046 - * (see sstrdup()).
1.1047 - *
1.1048 - * @param string the input string
1.1049 - * @return the resulting upper case string
1.1050 - */
1.1051 -#define sstrupper(string) scstrupper(SCSTR(string))
1.1052 -
1.1053 -/**
1.1054 - * Returns a upper case version of a string.
1.1055 - *
1.1056 - * This function creates a duplicate of the input string, first
1.1057 - * (see scstrdup_a()).
1.1058 - *
1.1059 - * @param allocator the allocator used for duplicating the string
1.1060 - * @param string the input string
1.1061 - * @return the resulting upper case string
1.1062 - * @see scstrdup_a()
1.1063 - */
1.1064 -sstr_t scstrupper_a(UcxAllocator *allocator, scstr_t string);
1.1065 -
1.1066 -/**
1.1067 - * Returns a upper case version of a string.
1.1068 - *
1.1069 - * This function creates a duplicate of the input string, first
1.1070 - * (see sstrdup_a()).
1.1071 - *
1.1072 - * @param allocator the allocator used for duplicating the string
1.1073 - * @param string the input string
1.1074 - * @return the resulting upper case string
1.1075 - */
1.1076 -#define sstrupper_a(allocator, string) scstrupper_a(allocator, string)
1.1077 -
1.1078 -
1.1079 -/**
1.1080 - * Replaces a pattern in a string with another string.
1.1081 - *
1.1082 - * The pattern is taken literally and is no regular expression.
1.1083 - * Replaces at most <code>replmax</code> occurrences.
1.1084 - *
1.1085 - * The resulting string is allocated by the specified allocator. I.e. it
1.1086 - * depends on the used allocator, whether the sstr_t.ptr must be freed
1.1087 - * manually.
1.1088 - *
1.1089 - * If allocation fails, the sstr_t.ptr of the return value is NULL.
1.1090 - *
1.1091 - * @param allocator the allocator to use
1.1092 - * @param str the string where replacements should be applied
1.1093 - * @param pattern the pattern to search for
1.1094 - * @param replacement the replacement string
1.1095 - * @param replmax maximum number of replacements
1.1096 - * @return the resulting string after applying the replacements
1.1097 - */
1.1098 -sstr_t scstrreplacen_a(UcxAllocator *allocator, scstr_t str,
1.1099 - scstr_t pattern, scstr_t replacement, size_t replmax);
1.1100 -
1.1101 -/**
1.1102 - * Replaces a pattern in a string with another string.
1.1103 - *
1.1104 - * The pattern is taken literally and is no regular expression.
1.1105 - * Replaces at most <code>replmax</code> occurrences.
1.1106 - *
1.1107 - * The sstr_t.ptr of the resulting string must be freed manually.
1.1108 - *
1.1109 - * If allocation fails, the sstr_t.ptr of the return value is NULL.
1.1110 - *
1.1111 - * @param str the string where replacements should be applied
1.1112 - * @param pattern the pattern to search for
1.1113 - * @param replacement the replacement string
1.1114 - * @param replmax maximum number of replacements
1.1115 - * @return the resulting string after applying the replacements
1.1116 - */
1.1117 -sstr_t scstrreplacen(scstr_t str, scstr_t pattern,
1.1118 - scstr_t replacement, size_t replmax);
1.1119 -
1.1120 -/**
1.1121 - * Replaces a pattern in a string with another string.
1.1122 - *
1.1123 - * The pattern is taken literally and is no regular expression.
1.1124 - * Replaces at most <code>replmax</code> occurrences.
1.1125 - *
1.1126 - * The resulting string is allocated by the specified allocator. I.e. it
1.1127 - * depends on the used allocator, whether the sstr_t.ptr must be freed
1.1128 - * manually.
1.1129 - *
1.1130 - * @param allocator the allocator to use
1.1131 - * @param str the string where replacements should be applied
1.1132 - * @param pattern the pattern to search for
1.1133 - * @param replacement the replacement string
1.1134 - * @param replmax maximum number of replacements
1.1135 - * @return the resulting string after applying the replacements
1.1136 - */
1.1137 -#define sstrreplacen_a(allocator, str, pattern, replacement, replmax) \
1.1138 - scstrreplacen_a(allocator, SCSTR(str), SCSTR(pattern), \
1.1139 - SCSTR(replacement), replmax)
1.1140 -
1.1141 -/**
1.1142 - * Replaces a pattern in a string with another string.
1.1143 - *
1.1144 - * The pattern is taken literally and is no regular expression.
1.1145 - * Replaces at most <code>replmax</code> occurrences.
1.1146 - *
1.1147 - * The sstr_t.ptr of the resulting string must be freed manually.
1.1148 - *
1.1149 - * If allocation fails, the sstr_t.ptr of the return value is NULL.
1.1150 - *
1.1151 - * @param str the string where replacements should be applied
1.1152 - * @param pattern the pattern to search for
1.1153 - * @param replacement the replacement string
1.1154 - * @param replmax maximum number of replacements
1.1155 - * @return the resulting string after applying the replacements
1.1156 - */
1.1157 -#define sstrreplacen(str, pattern, replacement, replmax) \
1.1158 - scstrreplacen(SCSTR(str), SCSTR(pattern), SCSTR(replacement), replmax)
1.1159 -
1.1160 -/**
1.1161 - * Replaces a pattern in a string with another string.
1.1162 - *
1.1163 - * The pattern is taken literally and is no regular expression.
1.1164 - * Replaces at most <code>replmax</code> occurrences.
1.1165 - *
1.1166 - * The resulting string is allocated by the specified allocator. I.e. it
1.1167 - * depends on the used allocator, whether the sstr_t.ptr must be freed
1.1168 - * manually.
1.1169 - *
1.1170 - * If allocation fails, the sstr_t.ptr of the return value is NULL.
1.1171 - *
1.1172 - * @param allocator the allocator to use
1.1173 - * @param str the string where replacements should be applied
1.1174 - * @param pattern the pattern to search for
1.1175 - * @param replacement the replacement string
1.1176 - * @return the resulting string after applying the replacements
1.1177 - */
1.1178 -#define sstrreplace_a(allocator, str, pattern, replacement) \
1.1179 - scstrreplacen_a(allocator, SCSTR(str), SCSTR(pattern), \
1.1180 - SCSTR(replacement), SIZE_MAX)
1.1181 -
1.1182 -/**
1.1183 - * Replaces a pattern in a string with another string.
1.1184 - *
1.1185 - * The pattern is taken literally and is no regular expression.
1.1186 - * Replaces at most <code>replmax</code> occurrences.
1.1187 - *
1.1188 - * The sstr_t.ptr of the resulting string must be freed manually.
1.1189 - *
1.1190 - * If allocation fails, the sstr_t.ptr of the return value is NULL.
1.1191 - *
1.1192 - * @param str the string where replacements should be applied
1.1193 - * @param pattern the pattern to search for
1.1194 - * @param replacement the replacement string
1.1195 - * @return the resulting string after applying the replacements
1.1196 - */
1.1197 -#define sstrreplace(str, pattern, replacement) \
1.1198 - scstrreplacen(SCSTR(str), SCSTR(pattern), SCSTR(replacement), SIZE_MAX)
1.1199 -
1.1200 -#ifdef __cplusplus
1.1201 -}
1.1202 -#endif
1.1203 -
1.1204 -#endif /* UCX_STRING_H */
