Branch data     Line data    Source code

       1                 :             : #include "mem.h"
       2                 :             : #include "mem_internal.h"
       3                 :             : 
       4                 :             : /**
       5                 :             :  * @brief Append the visible prefix of one bounded source string as a new inline element in a descriptor-backed string array
       6                 :             :  *
       7                 :             :  * This is the thin bounded wrapper for @ref m_string_array_append. Use it when
       8                 :             :  * the source byte range is known in advance, but only the visible prefix before
       9                 :             :  * the first zero-valued terminator element inside that range should be copied
      10                 :             :  * into the appended inline descriptor
      11                 :             :  *
      12                 :             :  * Small example:
      13                 :             :  * @code
      14                 :             :  * const char source[] = {'e','p','s','i','l','o','n','\0','x'};
      15                 :             :  * m_create(memory,string_array);
      16                 :             :  *
      17                 :             :  * if((TRIUMPH & m_string_array_append(string_array,char,sizeof(source),source)) == 0) { return FAILURE; }
      18                 :             :  * @endcode
      19                 :             :  *
      20                 :             :  * @param descriptor_array Root data-mode descriptor that stores `memory` elements
      21                 :             :  * @param single_element_size Element width in bytes for the appended string descriptor
      22                 :             :  * @param source_limit_bytes Maximum byte count to inspect in @p source_text
      23                 :             :  * @param source_text Bounded source string interpreted with @p single_element_size
      24                 :             :  * @return `SUCCESS` on success; `FAILURE` otherwise
      25                 :             :  */
      26                 :           2 : Return mem_string_array_append_bounded(
      27                 :             :         memory            *descriptor_array,
      28                 :             :         size_t            single_element_size,
      29                 :             :         const size_t      source_limit_bytes,
      30                 :             :         const void *const source_text)
      31                 :             : {
      32                 :           2 :         return(mem_string_array_core(
      33                 :             :                 SOURCE_BOUNDED_STRING,
      34                 :             :                 descriptor_array,
      35                 :             :                 single_element_size,
      36                 :             :                 source_limit_bytes,
      37                 :             :                 source_text));
      38                 :             : }