Branch data     Line data    Source code

       1                 :             : #include "mem.h"
       2                 :             : #include "mem_internal.h"
       3                 :             : 
       4                 :             : /**
       5                 :             :  * @brief Append the visible part of a bounded source string
       6                 :             :  *
       7                 :             :  * Use this helper when you know how many bytes are available in the source,
       8                 :             :  * but you want to append only the visible text before the first terminator.
       9                 :             :  * In other words, the function behaves like a safe bounded append: it never
      10                 :             :  * reads past @p source_limit_bytes, and it always leaves @p destination as a
      11                 :             :  * valid zero-terminated string
      12                 :             :  *
      13                 :             :  * @par Active terminator search within bounds
      14                 :             :  * Unlike @ref mem_concat_fixed_string, this function **actively scans** the
      15                 :             :  * source within the first @p source_limit_bytes bytes looking for `'\0'`. If
      16                 :             :  * a terminator is found earlier, only the visible prefix up to that point is
      17                 :             :  * appended. If no terminator is found within the limit, exactly
      18                 :             :  * @p source_limit_bytes bytes are appended. This is the safe choice when you
      19                 :             :  * cannot guarantee that the source is terminated, but you do know an upper
      20                 :             :  * bound for the search
      21                 :             :  *
      22                 :             :  * If you have absolutely no upper bound and the source is guaranteed to be
      23                 :             :  * a real C-string, use @ref mem_concat_unbounded_string instead. If the
      24                 :             :  * terminator is guaranteed to be exactly the last element, the faster
      25                 :             :  * @ref mem_concat_fixed_string is preferable
      26                 :             :  *
      27                 :             :  * The source is interpreted using the destination element width, so the same
      28                 :             :  * call works for ordinary `char` strings and for wider code units
      29                 :             :  *
      30                 :             :  * Example:
      31                 :             :  * @code
      32                 :             :  * const char suffix[] = {'-','n','e','w','\0','x','x'};
      33                 :             :  * if((TRIUMPH & mem_concat_bounded_string(path,sizeof(suffix),suffix)) == 0) { return FAILURE; }
      34                 :             :  * // "prefix" becomes "prefix-new"
      35                 :             :  * @endcode
      36                 :             :  *
      37                 :             :  * @param destination Destination string descriptor to extend.
      38                 :             :  *        Must already be in string mode
      39                 :             :  * @param source_limit_bytes Maximum number of bytes to scan for a terminator
      40                 :             :  * @param source_string Source string. May or may not be terminated within bounds
      41                 :             :  * @return `SUCCESS` on success; `FAILURE` otherwise
      42                 :             :  */
      43                 :         221 : Return mem_concat_bounded_string(
      44                 :             :         memory            *destination,
      45                 :             :         const size_t      source_limit_bytes,
      46                 :             :         const void *const source_string)
      47                 :             : {
      48                 :             :         /* This function was reviewed line by line by a human and is not AI-generated
      49                 :             :            Any change to this function requires separate explicit approval */
      50                 :             : 
      51                 :         221 :         return(mem_core_string(
      52                 :             :                 SOURCE_BOUNDED_STRING | TRANSFER_APPEND,
      53                 :             :                 destination,
      54                 :             :                 source_limit_bytes,
      55                 :             :                 source_string));
      56                 :             : }