ds_string_t Struct Reference

A growable string. Will be UTF-8–encoded in the future. More...

#include <string.h>

Private Attributes
ds_cstr_mut_t	buf
	Points to an internal buffer String uses to store its data. More...
ds_usize_t	len
	The number of bytes currently stored in the buffer. More...
ds_usize_t	cap
	The size of the buffer in bytes. More...

Detailed Description

A growable string. Will be UTF-8–encoded in the future.

The String type is the most common string type that has ownership over the contents of the string. It has a close relationship with its standard counterpart, the primitive C-string.

Examples

You can create a String from a literal string with ds_string_from:

ds_string_t hello;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&hello, "Hello, world!", 13));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&hello));

You can append a char to a String with the ds_string_push method, and append a C-string with the ds_string_push_str method:

ds_string_t hello;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&hello, "Hello,", 6));
 
DS_RESULT_PROPAGATE_ERR (ds_string_push (&hello, ' '));
DS_RESULT_PROPAGATE_ERR (ds_string_push_str (&hello, "world!", 6));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&hello));

Representation

A String is made up of three components: a pointer to some bytes, a length, and a capacity. The pointer points to an internal buffer String uses to store its data. The length is the number of bytes currently stored in the buffer, and the capacity is the size of the buffer in bytes. As such, the length will always be less than or equal to the capacity.

This buffer is always stored on the heap.

You can look at these with the ds_string_as_ptr, ds_string_len, and ds_string_capacity methods:

ds_string_t story;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&story, "Once upon a time...",
                                         19));
 
ds_cstr_t const ptr = ds_string_as_ptr (story);
ds_usize_t const len = ds_string_len (story);
ds_usize_t const capacity = ds_string_capacity (story);
 
// story has nineteen bytes
assert (19 == len);
assert (len <= capacity);
 
// We can re-build a String out of ptr, len, and capacity. This is all
// unsafe because we are responsible for making sure the components are
// valid:
ds_string_t const s = ds_string_from_raw_parts (ptr, len, capacity);
 
assert (ds_string_eq (s, story));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&story));

If a String has enough capacity, adding elements to it will not re-allocate. For example, consider this program:

ds_string_t s = ds_string_new ();
 
printf ("%" DS_PRI_USIZE "\n", ds_string_capacity (s));
 
for (ds_usize_t i = DS_USIZE_MIN; i < 5; i++)
  {
    DS_RESULT_PROPAGATE_ERR (ds_string_push_str (&s, "hello", 5));
    printf ("%" DS_PRI_USIZE "\n", ds_string_capacity (s));
  }
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

This may output the following:

0
8
16
16
32
32

At first, we have no memory allocated at all, but as we append to the string, it increases its capacity appropriately. If we instead use the ds_string_with_capacity method to allocate the correct capacity initially:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_with_capacity (&s, 25));
 
printf ("%" DS_PRI_USIZE "\n", ds_string_capacity (s));
 
for (ds_usize_t i = DS_USIZE_MIN; i < 5; i++)
  {
    DS_RESULT_PROPAGATE_ERR (ds_string_push_str (&s, "hello", 5));
    printf ("%" DS_PRI_USIZE "\n", ds_string_capacity (s));
  }
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

We may end up with a different output:

25
25
25
25
25
25

Here, there's no need to allocate more memory inside the loop.

Definition at line 162 of file string.h.

Field Documentation

buf

ds_cstr_mut_t ds_string_t::buf

private

Points to an internal buffer String uses to store its data.

This buffer is always stored on the heap.

Definition at line 169 of file string.h.

cap

ds_usize_t ds_string_t::cap

private

The size of the buffer in bytes.

The length will always be less than or equal to the capacity.

Definition at line 181 of file string.h.

len

ds_usize_t ds_string_t::len

private

The number of bytes currently stored in the buffer.

The length will always be less than or equal to the capacity.

Definition at line 175 of file string.h.

---

The documentation for this struct was generated from the following file:

• include/ds/string.h