Branch data     Line data    Source code

       1                 :             : #include "mem.h"
       2                 :             : #include "mem_internal.h"
       3                 :             : 
       4                 :             : /**
       5                 :             :  * @brief Replace destination contents with the visible part of a bounded source string
       6                 :             :  *
       7                 :             :  * Use this helper when the source byte range is known, but only the visible
       8                 :             :  * prefix before the first terminator should become the new destination text.
       9                 :             :  * The function never reads past @p source_limit_bytes and still guarantees
      10                 :             :  * exactly one trailing terminator in the destination after replacement
      11                 :             :  *
      12                 :             :  * @par Active terminator search within bounds
      13                 :             :  * Unlike @ref mem_copy_fixed_string, this function **actively scans** the
      14                 :             :  * source within the first @p source_limit_bytes bytes looking for `'\0'`. If
      15                 :             :  * a terminator is found earlier, only the visible prefix up to that point is
      16                 :             :  * copied. If no terminator is found within the limit, exactly
      17                 :             :  * @p source_limit_bytes bytes are copied. This is the safe choice when you
      18                 :             :  * cannot guarantee that the source is terminated, but you do know an upper
      19                 :             :  * bound for the search
      20                 :             :  *
      21                 :             :  * If you have absolutely no upper bound and the source is guaranteed to be
      22                 :             :  * a real C-string, use @ref mem_copy_unbounded_string instead. If the
      23                 :             :  * terminator is guaranteed to be exactly the last element, the faster
      24                 :             :  * @ref mem_copy_fixed_string is preferable
      25                 :             :  *
      26                 :             :  * The source is interpreted using the destination element width, so the same
      27                 :             :  * call works for ordinary `char` strings and for wider code units
      28                 :             :  *
      29                 :             :  * Example:
      30                 :             :  * @code
      31                 :             :  * const char source[] = {'n','e','w','\0','x'};
      32                 :             :  * if((TRIUMPH & m_copy_string(path,sizeof(source),source)) == 0) { return FAILURE; }
      33                 :             :  * @endcode
      34                 :             :  *
      35                 :             :  * @param destination Destination descriptor that will receive the new string.
      36                 :             :  *        Must already be in string mode
      37                 :             :  * @param source_limit_bytes Maximum number of bytes to scan for a terminator
      38                 :             :  * @param source_string Source string. May or may not be terminated within bounds
      39                 :             :  * @return `SUCCESS` on success; `FAILURE` otherwise
      40                 :             :  */
      41                 :       12967 : Return mem_copy_bounded_string(
      42                 :             :         memory            *destination,
      43                 :             :         const size_t      source_limit_bytes,
      44                 :             :         const void *const source_string)
      45                 :             : {
      46                 :       12967 :         return(mem_core_string(
      47                 :             :                 SOURCE_BOUNDED_STRING | TRANSFER_REPLACE,
      48                 :             :                 destination,
      49                 :             :                 source_limit_bytes,
      50                 :             :                 source_string));
      51                 :             : }