:orphan: .. index:: pair: group; Substring manipulation API .. _doxid-group__te__tools__te__substring: Substring manipulation API ========================== .. toctree:: :hidden: enum_te_substring_mod_op.rst struct_te_substring_t.rst Overview ~~~~~~~~ .. ref-code-block:: cpp :class: doxyrest-overview-code-block // typedefs typedef struct :ref:`te_substring_t` :ref:`te_substring_t`; typedef enum :ref:`te_substring_mod_op` :ref:`te_substring_mod_op`; // enums enum :ref:`te_substring_mod_op`; // structs struct :ref:`te_substring_t`; // global functions static void :ref:`te_substring_invalidate`(:ref:`te_substring_t`* substr); static bool :ref:`te_substring_is_valid`(const :ref:`te_substring_t`* substr); static bool :ref:`te_substring_past_end`(const :ref:`te_substring_t`* substr); static void :ref:`te_substring_till_end`(:ref:`te_substring_t`* substr); static bool :ref:`te_substring_extract_buf`(char* dst, const :ref:`te_substring_t`* src); static bool :ref:`te_substring_extract`(:ref:`te_string`* dst, const :ref:`te_substring_t`* src); int :ref:`te_substring_compare`(const :ref:`te_substring_t`* substr1, const :ref:`te_substring_t`* substr2); int :ref:`te_substring_compare_str`(const :ref:`te_substring_t`* substr, const char* str); bool :ref:`te_substring_find`(:ref:`te_substring_t`* substr, const char* str); char :ref:`te_substring_span`(:ref:`te_substring_t`* substr, const char* cset, bool inverted); size_t :ref:`te_substring_skip`(:ref:`te_substring_t`* substr, char skip, size_t at_most); bool :ref:`te_substring_strip_prefix`(:ref:`te_substring_t`* substr, const char* prefix); bool :ref:`te_substring_strip_suffix`(:ref:`te_substring_t`* substr, const char* suffix); bool :ref:`te_substring_strip_uint_suffix`(:ref:`te_substring_t`* str, uintmax_t* suffix_val); size_t :ref:`te_substring_modify`(:ref:`te_substring_t`* substr, :ref:`te_substring_mod_op` op, const char* fmt, ...); size_t size_t :ref:`te_substring_modify_va`(:ref:`te_substring_t`* substr, :ref:`te_substring_mod_op` op, const char* fmt, va_list args); size_t :ref:`te_substring_replace`(:ref:`te_substring_t`* substr, const char* fmt, ...); size_t size_t :ref:`te_substring_replace_va`(:ref:`te_substring_t`* substr, const char* fmt, va_list args); bool :ref:`te_substring_insert_sep`(:ref:`te_substring_t`* substr, char sep, bool at_bol); bool :ref:`te_substring_copy`(:ref:`te_substring_t`* dst, const :ref:`te_substring_t`* src, :ref:`te_substring_mod_op` op); bool :ref:`te_substring_advance`(:ref:`te_substring_t`* substr); bool :ref:`te_substring_limit`(:ref:`te_substring_t`* substr, const :ref:`te_substring_t`* limit); size_t :ref:`te_string_replace_all_substrings`(:ref:`te_string`* str, const char* new, const char* old); bool :ref:`te_string_replace_substring`(:ref:`te_string`* str, const char* new, const char* old); // macros #define :ref:`TE_SUBSTRING_INIT`(base_) .. _details-group__te__tools__te__substring: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Typedefs -------- .. index:: pair: typedef; te_substring_t .. _doxid-group__te__tools__te__substring_1gaad61d17007089da720d9d0b428de3476: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`te_substring_t` te_substring_t Structure for describing a piece of string .. index:: pair: typedef; te_substring_mod_op .. _doxid-group__te__tools__te__substring_1ga8ff2703cc6b3de45d020a9d9f1e711dc: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef enum :ref:`te_substring_mod_op` te_substring_mod_op The mode of operation for substring modifications. Global Functions ---------------- .. index:: pair: function; te_substring_invalidate .. _doxid-group__te__tools__te__substring_1ga487b80151d7952196dec99c3cae5252e: .. ref-code-block:: cpp :class: doxyrest-title-code-block static void te_substring_invalidate(:ref:`te_substring_t`* substr) Invalidate the substring so that it would be treated as pointing nowhere. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. .. index:: pair: function; te_substring_is_valid .. _doxid-group__te__tools__te__substring_1gaff2ae7d38f9062d40f5029b24ce6405e: .. ref-code-block:: cpp :class: doxyrest-title-code-block static bool te_substring_is_valid(const :ref:`te_substring_t`* substr) Check that substring is valid. The substring is considered valid if it is completely contained within its base string or if it has a length of zero and points right after the end of its base string. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. .. rubric:: Returns: ``true`` if the substring is valid. .. index:: pair: function; te_substring_past_end .. _doxid-group__te__tools__te__substring_1ga6dd622bf8caee0d94e948bb72faeafc9: .. ref-code-block:: cpp :class: doxyrest-title-code-block static bool te_substring_past_end(const :ref:`te_substring_t`* substr) Check whether a substring points past the end of its base string. If it is true, replacing a substring would effectively append data to the base string. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. .. rubric:: Returns: ``true`` if the substring is valid and points past the end of its base string. .. index:: pair: function; te_substring_till_end .. _doxid-group__te__tools__te__substring_1gac38ccead30bc9f141f7ad2170bebf774: .. ref-code-block:: cpp :class: doxyrest-title-code-block static void te_substring_till_end(:ref:`te_substring_t`* substr) Extend the length of the substring to reach the end of its base string. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. .. index:: pair: function; te_substring_extract_buf .. _doxid-group__te__tools__te__substring_1ga8d8da66b57315c64b303aea86634a9d2: .. ref-code-block:: cpp :class: doxyrest-title-code-block static bool te_substring_extract_buf(char* dst, const :ref:`te_substring_t`* src) Copy the content of a substring into the C array. The terminating ``'\0'`` is added to the array, so it should have enough space to hold ``src->len`` + 1 bytes. If the substring is not valid, a single ``'\0'`` is written to the buffer. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - dst - Target buffer. * - src - Substring. .. rubric:: Returns: ``true`` if ``src`` is a valid substring. .. index:: pair: function; te_substring_extract .. _doxid-group__te__tools__te__substring_1ga9cd47311209c2ae03c6c6af7f09c8be0: .. ref-code-block:: cpp :class: doxyrest-title-code-block static bool te_substring_extract(:ref:`te_string`* dst, const :ref:`te_substring_t`* src) Copy the content of a substring into the target string. If the substring is not valid, nothing happens. .. note:: The function returns true if the substring is valid but empty, so nothing is actually copied. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - dst - Target string. * - src - Substring. .. rubric:: Returns: ``true`` if ``src`` is a valid substring. .. index:: pair: function; te_substring_compare .. _doxid-group__te__tools__te__substring_1ga492d10ddffd2a7d38bb48ab7b8a23aaf: .. ref-code-block:: cpp :class: doxyrest-title-code-block int te_substring_compare(const :ref:`te_substring_t`* substr1, const :ref:`te_substring_t`* substr2) Compare two substrings like ``strcmp()``. An invalid substring always compares equal to another invalid substring and is considered less than any valid substring. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr1 - First substring. * - substr2 - Second substring. .. rubric:: Returns: 0, -1 or 1 depending on whether ``substr1`` is equal, less or greater than ``substr2``. .. index:: pair: function; te_substring_compare_str .. _doxid-group__te__tools__te__substring_1ga0a4a1c9aa5627283e6bfb4e3ee641d7d: .. ref-code-block:: cpp :class: doxyrest-title-code-block int te_substring_compare_str(const :ref:`te_substring_t`* substr, const char* str) Compare a substring to a C string like ``strcmp()``. An invalid substring compares equal to ``NULL`` and is less than any non-null string. A valid substring is always greater than ``NULL``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. * - str - C string to compare (may be ``NULL``). .. rubric:: Returns: 0, -1 or 1 depending on whether ``substr`` is equal, less or greater than ``str``. .. index:: pair: function; te_substring_find .. _doxid-group__te__tools__te__substring_1ga804308753427e30e3a598217951a3c7d: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool te_substring_find(:ref:`te_substring_t`* substr, const char* str) Find a ``str`` starting at ``substr`` position and update it accordingly. .. note:: If ``str`` has not been found, :ref:`te_substring_is_valid() ` will also return ``false`` after this call. .. note:: If :ref:`te_substring_find() ` is called the second time without calling :ref:`te_substring_advance() `, it will effectively do nothing. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. * - str - The string to find. .. rubric:: Returns: ``true`` if ``str`` has been found. .. index:: pair: function; te_substring_span .. _doxid-group__te__tools__te__substring_1ga4d6245775a210cd167a559a2ec1a2036: .. ref-code-block:: cpp :class: doxyrest-title-code-block char te_substring_span(:ref:`te_substring_t`* substr, const char* cset, bool inverted) Make the substring cover the longset segment of characters entirely from ``cset`` (or entirely *not* from ``cset`` if ``inverted`` is ``true``). The starting point of the substring is not changed. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. * - cset - Set of characters. * - inverted - If ``true``, consider characters not in ``cset``. .. rubric:: Returns: The first character after the initial segment, may be ``'\0'``. .. index:: pair: function; te_substring_skip .. _doxid-group__te__tools__te__substring_1gaa102a4556f335ecce82daf1e34d16db3: .. ref-code-block:: cpp :class: doxyrest-title-code-block size_t te_substring_skip(:ref:`te_substring_t`* substr, char skip, size_t at_most) Skip at most ``at_most`` characters ``skip`` in ``substr``. Unlike :ref:`te_substring_span() `, this function does move the starting point and the length is decreased if it's not zero. .. rubric:: Returns: The number of characters actually skipped. .. index:: pair: function; te_substring_strip_prefix .. _doxid-group__te__tools__te__substring_1gaa0700c60e6b089a9d6f0a2e818421631: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool te_substring_strip_prefix(:ref:`te_substring_t`* substr, const char* prefix) Strip a prefix from a substring. If ``substr`` starts with ``prefix``, its starting point is moved to skip that prefix. The underlying string is not modified. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. * - prefix - Prefix to strip. .. rubric:: Returns: ``true`` if ``prefix`` has been stripped. .. rubric:: See also: :ref:`te_str_strip_prefix() ` .. index:: pair: function; te_substring_strip_suffix .. _doxid-group__te__tools__te__substring_1gabb27b7e9a7082b71b3db4a92201eb33a: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool te_substring_strip_suffix(:ref:`te_substring_t`* substr, const char* suffix) Strip a suffix from a subsstring. If ``substr`` ends with ``suffix``, the length of the suffix is substracted from the length of the substring. The underlying string is not modified. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. * - suffix - Suffix to strip. .. rubric:: Returns: ``true`` if ``suffix`` has been stripped. .. index:: pair: function; te_substring_strip_uint_suffix .. _doxid-group__te__tools__te__substring_1ga0db3087d7c27e7c3db3f9513b3aa3526: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool te_substring_strip_uint_suffix(:ref:`te_substring_t`* str, uintmax_t* suffix_val) Strip a sequence of digits from the end of ``substring``. If the sequence is not empty, the resulting number is stored in ``suffix_val`` and the length of ``substr`` is diminished to exclude the numeric suffix. Otherwise, ``substr`` is untouched and ``0`` is stored in ``suffix_val``. If the numeric suffix represent a number that does not fit into ``uintmax_t``, it won't be stripped. The underlying string is never modified. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. * - suffix_val - Place to store the numeric value of a suffix or zero (may be ``NULL``). .. rubric:: Returns: ``true`` if any digits have been stripped off. .. index:: pair: function; te_substring_modify .. _doxid-group__te__tools__te__substring_1ga191663364e7416d06783b99742c06b38: .. ref-code-block:: cpp :class: doxyrest-title-code-block size_t te_substring_modify(:ref:`te_substring_t`* substr, :ref:`te_substring_mod_op` op, const char* fmt, ...) Modify a substring at a given position, changing the underlying :ref:`te_string ` in place. If the substring is not valid, nothing happens. The exact behaviour depends on the value of ``op:`` * :ref:`TE_SUBSTRING_MOD_OP_PREPEND ` : the replacement string is inserted at the beginning of the substring; * :ref:`TE_SUBSTRING_MOD_OP_APPEND ` : the replacement string is inserted after the end of the substring; * :ref:`TE_SUBSTRING_MOD_OP_REPLACE ` : the replacement string is inserted in place of the whole substring. The replacement string is constructed by applying ``printf()`` format to the arguments. If ``fmt`` is ``NULL``, the content of the substring is deleted (if ``op`` is :ref:`TE_SUBSTRING_MOD_OP_REPLACE `, otherwise it's a no-op). No variadic arguments shall be present in this case. The starting point of the substring remains the same in all cases and the length is adjusted according to the operation and the length of the replacement string (in contrast to :ref:`te_substring_replace() `). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. * - op - Mode of operation. * - fmt - Replacement format (may be ``NULL``). * - ... - Format arguments. .. rubric:: Returns: The length of the replacement string. Note that this does *not* include the length of the old substring in case of appending/prepending. .. index:: pair: function; te_substring_modify_va .. _doxid-group__te__tools__te__substring_1ga00daf2a59f73876869df4fae1205d0f5: .. ref-code-block:: cpp :class: doxyrest-title-code-block size_t size_t te_substring_modify_va(:ref:`te_substring_t`* substr, :ref:`te_substring_mod_op` op, const char* fmt, va_list args) Same as :ref:`te_substring_modify() ` but accepts a variadic list argument. If ``fmt`` is ``NULL``, the content of the substring is deleted (when ``op`` is :ref:`TE_SUBSTRING_MOD_OP_REPLACE `). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. * - op - Mode of operation. * - fmt - Replacement format (may be ``NULL``). * - ... - Format arguments. .. rubric:: Returns: The length of the replacement string. .. index:: pair: function; te_substring_replace .. _doxid-group__te__tools__te__substring_1ga398bb5b67926a0634c7adf7409cda427: .. ref-code-block:: cpp :class: doxyrest-title-code-block size_t te_substring_replace(:ref:`te_substring_t`* substr, const char* fmt, ...) Like :ref:`te_substring_modify() `, but the operation is always :ref:`TE_SUBSTRING_MOD_OP_REPLACE `. Unlike :ref:`te_substring_modify() `, this function moves the starting point past the end of the replaced string and sets the substring length to zero, so it's basically equivalent to calling :ref:`te_substring_advance() ` after :ref:`te_substring_modify() `. 1.45.0. Before that version, it accepted a fixed replacement string, not a format. It also used to return a pretty uninformative status code instead of the length. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. * - fmt - Replacement format (may be ``NULL``). * - ... - Format arguments. .. rubric:: Returns: The length of the replacement string. .. index:: pair: function; te_substring_replace_va .. _doxid-group__te__tools__te__substring_1ga6524618efc41c0a9060a43aef59398c9: .. ref-code-block:: cpp :class: doxyrest-title-code-block size_t size_t te_substring_replace_va(:ref:`te_substring_t`* substr, const char* fmt, va_list args) Same as :ref:`te_substring_replace() ` but accepts a variadic list argument. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. * - fmt - Replacement format (may be ``NULL``). * - ... - Format arguments. .. rubric:: Returns: The length of the replacement string. .. index:: pair: function; te_substring_insert_sep .. _doxid-group__te__tools__te__substring_1gae651c9174a2f3bd9ad3eae9d0c58d82f: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool te_substring_insert_sep(:ref:`te_substring_t`* substr, char sep, bool at_bol) Inserts a separator at the start of the substring if there is no one already. The function checks the character immediately preceding the substring. If ``at_bol`` is true, the separator is also inserted if there is no preceding character at all. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. * - sep - Separator. * - at_bol - If true, insert at the start of the string. .. rubric:: Returns: ``true`` if the separator has been .. index:: pair: function; te_substring_copy .. _doxid-group__te__tools__te__substring_1gaefb63ebdb25f7f091e259d7d25bb237b: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool te_substring_copy(:ref:`te_substring_t`* dst, const :ref:`te_substring_t`* src, :ref:`te_substring_mod_op` op) Copy the content of a substring into another substring. If ``dst`` is invalid, no copying is done. If ``src`` is invalid, the content of ``dst`` is deleted. ``dst`` and ``src`` must have *different* base strings. The mode of operation is the same as for :ref:`te_substring_modify() `. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - dst - Target substring. * - src - Source substring. * - op - Modification mode. * - :ref:`TE_FATAL_ERROR ` - if ``dst`` and ``src`` refer to the same string. This may change in the future. .. rubric:: Returns: ``true`` if copying took place. .. index:: pair: function; te_substring_advance .. _doxid-group__te__tools__te__substring_1ga480141da18011a990f042384d83ef65e: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool te_substring_advance(:ref:`te_substring_t`* substr) Move the position of a substring by its length. In other words, after this call the substring will point after the point where the substring ended initially. If the string was not valid initially, nothing happens. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. .. rubric:: Returns: ``true`` if the substring has been advanced. .. index:: pair: function; te_substring_limit .. _doxid-group__te__tools__te__substring_1ga30273a9a5c264ef4d6d156386115280a: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool te_substring_limit(:ref:`te_substring_t`* substr, const :ref:`te_substring_t`* limit) Limit the length of the ``substr`` so that it would end right before the start of ``limit``. If any of the substrings is not valid of if they have different base strings or if ``limit`` starts before ``substr``, nothing happens. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - substr - Substring. * - limit - Limiting substring. .. rubric:: Returns: ``true`` if the substring has been limited. .. index:: pair: function; te_string_replace_all_substrings .. _doxid-group__te__tools__te__substring_1ga1446d5b41614206d649a9a8cc4df6d0e: .. ref-code-block:: cpp :class: doxyrest-title-code-block size_t te_string_replace_all_substrings(:ref:`te_string`* str, const char* new, const char* old) Replace all occurrences of a substring in a string. 1.45.0. Before that version the function returned a meaningless status code instead of the count. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - str - The string in which to replace. * - new - The replacement string (may be ``NULL``). * - old - The substring to be replaced. .. rubric:: Returns: The number of performed replacements. .. index:: pair: function; te_string_replace_substring .. _doxid-group__te__tools__te__substring_1ga159238b1f238f54ac9d0134956a4454c: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool te_string_replace_substring(:ref:`te_string`* str, const char* new, const char* old) Replace the first occurrence of substring in a string. 1.45.0. Before that version the function returned a meaningless status code instead of the success flag. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - str - The string in which to replace. * - new - The replacement (may be ``NULL``). * - old - The substring to be replaced. .. rubric:: Returns: ``true`` if a substring has been replaced. Macros ------ .. index:: pair: define; TE_SUBSTRING_INIT .. _doxid-group__te__tools__te__substring_1gacd69274a078c208f5576c35952c2eaf2: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_SUBSTRING_INIT(base_) Substring initializer Bug ``base_`` may be a pointer to const :ref:`te_string ` without a warning from the compiler, but in this case a user shall not call :ref:`te_substring_replace() ` on it and currenly this is not enforced but that may be fixed later. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - base\_ - Pointer to the base string.