Branch data     Line data    Source code

       1                 :             : #include "mem.h"
       2                 :             : #include "mem_internal.h"
       3                 :             : 
       4                 :             : /**
       5                 :             :  * @brief Append a zero-terminated source string without a separate size limit
       6                 :             :  *
       7                 :             :  * Use this helper when the source really is terminated and you want familiar
       8                 :             :  * `strcat`-style behavior for this library's typed string descriptors. The
       9                 :             :  * function scans the source up to its first zero-valued terminator, appends
      10                 :             :  * only the visible payload, and leaves @p destination with exactly one
      11                 :             :  * trailing terminator
      12                 :             :  *
      13                 :             :  * @par Unbounded terminator search
      14                 :             :  * This function **actively scans** the source for `'\0'` with **no upper
      15                 :             :  * bound**. The caller must be absolutely certain that the source is a real
      16                 :             :  * zero-terminated C-string somewhere in memory; otherwise the scan will read
      17                 :             :  * past the buffer end and trigger undefined behavior
      18                 :             :  *
      19                 :             :  * If you only have an upper bound on where the terminator could be, use
      20                 :             :  * @ref mem_concat_bounded_string — it bounds the scan and is the safer
      21                 :             :  * choice. If the terminator is guaranteed to be exactly the last element of
      22                 :             :  * a fixed-size buffer, the faster @ref mem_concat_fixed_string is preferable
      23                 :             :  *
      24                 :             :  * The destination element width defines how the source is read, so the helper
      25                 :             :  * works for `char`, `wchar_t`, `char16_t`, `char32_t`, `uint16_t`, `uint32_t`,
      26                 :             :  * and similar element types. Passing `NULL` as @p source_string means "append
      27                 :             :  * nothing"
      28                 :             :  *
      29                 :             :  * Example:
      30                 :             :  * @code
      31                 :             :  * if((TRIUMPH & mem_concat_unbounded_string(title," draft")) == 0) { return FAILURE; }
      32                 :             :  * // "Report" becomes "Report draft"
      33                 :             :  * @endcode
      34                 :             :  *
      35                 :             :  * @param destination Destination string descriptor to extend.
      36                 :             :  *        Must already be in string mode
      37                 :             :  * @param source_string Zero-terminated source string, or `NULL` for an empty append
      38                 :             :  * @return `SUCCESS` on success; `FAILURE` otherwise
      39                 :             :  */
      40                 :       12474 : Return mem_concat_unbounded_string(
      41                 :             :         memory            *destination,
      42                 :             :         const void *const source_string)
      43                 :             : {
      44                 :       12474 :         return(mem_core_string(
      45                 :             :                 SOURCE_UNBOUNDED_STRING | TRANSFER_APPEND,
      46                 :             :                 destination,
      47                 :             :                 0,
      48                 :             :                 source_string));
      49                 :             : }