Branch data     Line data    Source code

       1                 :             : #include "mem.h"
       2                 :             : #include "mem_internal.h"
       3                 :             : 
       4                 :             : /**
       5                 :             :  * @brief Replace destination contents with a zero-terminated source string
       6                 :             :  *
       7                 :             :  * Use this helper when the source is already terminated and you want the
       8                 :             :  * visible source payload to become the whole destination string. The source is
       9                 :             :  * scanned until its first zero-valued terminator element, and the destination
      10                 :             :  * ends with exactly one trailing terminator after replacement
      11                 :             :  *
      12                 :             :  * @par Unbounded terminator search
      13                 :             :  * This function **actively scans** the source for `'\0'` with **no upper
      14                 :             :  * bound**. The caller must be absolutely certain that the source is a real
      15                 :             :  * zero-terminated C-string somewhere in memory; otherwise the scan will read
      16                 :             :  * past the buffer end and trigger undefined behavior
      17                 :             :  *
      18                 :             :  * If you only have an upper bound on where the terminator could be, use
      19                 :             :  * @ref mem_copy_bounded_string — it bounds the scan and is the safer choice.
      20                 :             :  * If the terminator is guaranteed to be exactly the last element of a
      21                 :             :  * fixed-size buffer, the faster @ref mem_copy_fixed_string is preferable
      22                 :             :  *
      23                 :             :  * The destination element width defines how the source is read, so this works
      24                 :             :  * for byte strings and for wider string element types. Passing `NULL` means
      25                 :             :  * "replace with an empty string"
      26                 :             :  *
      27                 :             :  * Example:
      28                 :             :  * @code
      29                 :             :  * if((TRIUMPH & m_copy_string(title,"draft")) == 0) { return FAILURE; }
      30                 :             :  * @endcode
      31                 :             :  *
      32                 :             :  * @param destination Destination descriptor that will receive the new string.
      33                 :             :  *        Must already be in string mode
      34                 :             :  * @param source_string Zero-terminated source string, or `NULL` for an empty string
      35                 :             :  * @return `SUCCESS` on success; `FAILURE` otherwise
      36                 :             :  */
      37                 :        1513 : Return mem_copy_unbounded_string(
      38                 :             :         memory            *destination,
      39                 :             :         const void *const source_string)
      40                 :             : {
      41                 :        1513 :         return(mem_core_string(
      42                 :             :                 SOURCE_UNBOUNDED_STRING | TRANSFER_REPLACE,
      43                 :             :                 destination,
      44                 :             :                 0,
      45                 :             :                 source_string));
      46                 :             : }