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)