SS8_CSTR(3)                      Ssstr Manual                      SS8_CSTR(3)

NAME
       ss8_cstr,  ss8_mutable_cstr, ss8_cstr_suffix, ss8_mutable_cstr_suffix -
       access the bytes of an ssstr byte  string  as  a  null-terminated  byte
       string

SYNOPSIS
       #include <ss8str.h>

       char const *ss8_cstr(ss8str const *str);
       char       *ss8_mutable_cstr(ss8str *str);
       char const *ss8_cstr_suffix(ss8str const *str, size_t start);
       char       *ss8_mutable_cstr_suffix(ss8str *str, size_t start);

DESCRIPTION
       The  ss8_cstr() family of functions provide direct access to the inter‐
       nal buffer of the ss8str that str points to.

       ss8_cstr() and ss8_mutable_cstr() return the pointer to  the  beginning
       of the string buffer.  A null terminator is always placed after the end
       of  the buffer.  ss8_cstr_suffix() and ss8_mutable_cstr_suffix() return
       a pointer offsetted by start bytes, corresponding to a  suffix  of  the
       string.   Calling  ss8_cstr()  or  ss8_mutable_cstr()  is equivalent to
       calling ss8_cstr_suffix() or  ss8_mutable_cstr_suffix(),  respectively,
       with start set to zero.

       Behavior  is  undefined unless str points to a valid ss8str object, and
       start is less than or equal to the length of the string.

       ss8_cstr() and ss8_cstr_suffix() are suitable for passing the  contents
       of  an  ss8str to a function expecting a read-only null-terminated byte
       string, or a read-only byte string with length at  most  equal  to  the
       length  of str (as determined by ss8_len() and subtracting start in the
       case of ss8_cstr_suffix()).

       ss8_mutable_cstr() and ss8_mutable_cstr_suffix() allow the  use  of  an
       ss8str  as the destination when calling a function that fills a caller-
       provided buffer with a null-terminated  or  bound-length  byte  string.
       The  available  buffer  size can be adjusted with ss8_set_len() before‐
       hand, and the same function, or ss8_set_len_to_cstrlen(), can  be  used
       afterwards  to crop the string to the desired length, if necessary.  In
       the case of ss8_mutable_cstr_suffix(), start must  be  subtracted  from
       the available length.

       It  is permissible to write 1 byte more than the available length, pro‐
       vided that the last byte written is always a null byte.

       See ss8_set_len(3) for examples.

RETURN VALUE
       All 4 functions return a pointer to the internal string buffer  of  the
       ss8str  pointed to by str, offset by start if applicable.  The returned
       pointer remains valid as long as the ss8str at str  remains  valid  and
       unmodified.

SEE ALSO
       ss8_len(3), ss8_set_len(3), ss8_set_len_to_cstrlen(3), ssstr(7)

SSSTR                             2023-12-30                       SS8_CSTR(3)