SS8_CAPACITY(3)                  Ssstr Manual                  SS8_CAPACITY(3)



NAME
       ss8_capacity,  ss8_reserve, ss8_shrink_to_fit - query and modify buffer
       capacity of ssstr byte strings

SYNOPSIS
       #include <ss8str.h>

       size_t  ss8_capacity(ss8str const *str);
       ss8str *ss8_reserve(ss8str *str, size_t capacity);
       ss8str *ss8_shrink_to_fit(ss8str *str);

DESCRIPTION
       ss8_capacity() queries the ss8str at str for its capacity, which is the
       maximum  length of the byte string that it can hold without the need to
       allocate additional (or any) dynamic storage.

       ss8_reserve() ensures that the ss8str at str has at least the given ca‐
       pacity  by  enlarging its buffer if necessary.  The length and contents
       of the string do not change.  ss8_reserve() never lessens the capacity.

       Reserving capacity ahead of time can improve efficiency  when  a  large
       number  of  insertions, concatenations, or replacements are about to be
       performed and the final length of the string is known, either precisely
       or approximately.

       Reserved  capacity  is  not  available  length;  writing  to  ss8_muta‐
       ble_cstr(str) beyond the length of *str results in undefined  behavior.
       See ss8_set_len(3) for ways to change the available length.

       ss8_shrink_to_fit()  reallocates  the  internal buffer of the ss8str at
       str so that it is the minimum size required to hold its contents.

       Shrinking to fit may improve memory usage if an ss8str is shortened  by
       a large factor and then retained for a long duration.

       Behavior of these 3 functions is undefined unless str points to a valid
       ss8str object.

RETURN VALUE
       ss8_capacity() returns the maximum length of the byte string  that  the
       ss8str pointed to by str can hold without allocating additional dynamic
       storage.

       ss8_reserve() and ss8_shrink_to_fit() return str.

NOTES
       The capacity of an ss8str is never zero but  has  a  platform-dependent
       fixed minimum.  Therefore, the capacity after performing

           ss8_shrink_to_fit(ss8_clear(str));

       is guaranteed to be greater than zero.  This also means that the capac‐
       ity   does   not   necessarily   match   the   length   after   calling
       ss8_shrink_to_fit().

       In  general,  ss8str functions that assign (copy) a string reserve just
       the capacity needed for the destination string.  Functions that insert,
       append,  or  replace  a substring heuristically grow the capacity in an
       attempt to minimize reallocation.  When a function shortens  a  string,
       or  does  not require more than its current capacity, it does not alter
       its capacity.  Only a call to ss8_shrink_to_fit() decreases the  capac‐
       ity of an ss8str.

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



SSSTR                             2023-12-30                   SS8_CAPACITY(3)