Branch data     Line data    Source code

       1                 :             : #include "mem.h"
       2                 :             : #include "mem_internal.h"
       3                 :             : 
       4                 :             : /**
       5                 :             :  * @brief Append a fixed-size string source whose final element is already the terminator
       6                 :             :  *
       7                 :             :  * Use this helper when you already know the full source size and that the
       8                 :             :  * last logical element inside that size is the terminator. This wrapper does
       9                 :             :  * not need `strlen(...)` or any other terminator search. It simply forwards
      10                 :             :  * the fixed-size string contract to the shared string-transfer core
      11                 :             :  *
      12                 :             :  * @par Trust mode — no terminator search
      13                 :             :  * This is the "trust mode" variant: the source is **not scanned** for an
      14                 :             :  * embedded `'\0'`. The function simply trusts that the last element within
      15                 :             :  * @p source_size_bytes is the terminator and appends the entire range as-is. If you
      16                 :             :  * are not certain that the terminator is exactly at the end of the source
      17                 :             :  * buffer, do not use this function — use @ref mem_concat_bounded_string or
      18                 :             :  * @ref mem_concat_unbounded_string instead, which actively search for the
      19                 :             :  * terminator
      20                 :             :  *
      21                 :             :  * This works for ordinary byte strings and for wider fixed-size string arrays
      22                 :             :  * as long as the destination element width matches the source element width
      23                 :             :  *
      24                 :             :  * @par Convenience for string literals
      25                 :             :  * For C string literals, prefer the @ref m_concat_literal macro, which derives
      26                 :             :  * the size automatically via `sizeof` and avoids manual size arithmetic
      27                 :             :  *
      28                 :             :  * Example:
      29                 :             :  * @code
      30                 :             :  * const char suffix[] = {' ','w','o','r','l','d','\0'};
      31                 :             :  * if((TRIUMPH & m_concat_fixed_string(title,sizeof(suffix),suffix)) == 0) { return FAILURE; }
      32                 :             :  * @endcode
      33                 :             :  *
      34                 :             :  * @param destination Destination string descriptor to extend.
      35                 :             :  *        Must already be in string mode
      36                 :             :  * @param source_size_bytes Total source size in bytes, including the terminator
      37                 :             :  * @param source Source string whose last logical element is the terminator
      38                 :             :  * @return `SUCCESS` on success; `FAILURE` otherwise
      39                 :             :  */
      40                 :       13821 : Return mem_concat_fixed_string(
      41                 :             :         memory            *destination,
      42                 :             :         const size_t      source_size_bytes,
      43                 :             :         const void *const source)
      44                 :             : {
      45                 :       13821 :         return(mem_core_string(
      46                 :             :                 SOURCE_FIXED_STRING | TRANSFER_APPEND,
      47                 :             :                 destination,
      48                 :             :                 source_size_bytes,
      49                 :             :                 source));
      50                 :             : }