string.c File Reference

Implementation of the String type, related constants and functions. More...

#include <stdbool.h>
#include <stddef.h>
#include <string.h>
#include "ds/char.h"
#include "ds/cstr.h"
#include "ds/helpers.h"
#include "ds/result.h"
#include "ds/usize.h"

Include dependency graph for string.c:

Go to the source code of this file.

Functions
ds_string_t	ds_string_new (void)
	Creates a new empty String. More...
ds_result_t	ds_string_with_capacity (ds_string_t *const self, ds_usize_t const capacity)
	Creates a new empty String with at least the specified capacity. More...
ds_result_t	ds_string_into_raw_parts (ds_string_t *const self, ds_cstr_mut_t *const buf_ptr, ds_usize_t *const len_ptr, ds_usize_t *const cap_ptr)
	Decomposes self into its raw components. More...
ds_string_t	ds_string_from_raw_parts (ds_cstr_mut_t const buf, ds_usize_t const length, ds_usize_t const capacity)
	Creates a new String from a length, capacity, and buf pointer. More...
ds_result_t	ds_string_push_str (ds_string_t *const self, ds_cstr_t const string, ds_usize_t const string_len)
	Appends string onto the end of self. More...
ds_usize_t	ds_string_capacity (ds_string_t const self)
	Returns self's capacity, in bytes. More...
ds_result_t	ds_string_reserve (ds_string_t *const self, ds_usize_t const additional)
	Reserves capacity for at least additional bytes more than self's current length. The allocator may reserve more space to speculatively avoid frequent allocations. After calling ds_string_reserve, capacity will be greater than or equal to ds_string_len (self) + additional. Does nothing if capacity is already sufficient. More...
ds_result_t	ds_string_reserve_exact (ds_string_t *const self, ds_usize_t const additional)
	Reserves the minimum capacity for at least additional bytes more than self's current length. Unlike ds_string_reserve, this will not deliberately over-allocate to speculatively avoid frequent allocations. After calling ds_string_reserve_exact, capacity will be greater than or equal to ds_string_len (self) + additional. Does nothing if the capacity is already sufficient. More...
ds_result_t	ds_string_shrink_to_fit (ds_string_t *const self)
	Shrinks the capacity of self to match its length. More...
ds_result_t	ds_string_shrink_to (ds_string_t *const self, ds_usize_t const min_capacity)
	Shrinks the capacity of self with a lower bound. More...
ds_result_t	ds_string_push (ds_string_t *const self, ds_char_t const chr)
	Appends chr to the end of self. More...
ds_result_t	ds_string_truncate (ds_string_t *self, ds_usize_t new_len)
	Shortens self to new_len. More...
ds_result_t	ds_string_pop (ds_string_t *const self, ds_char_t *const chr_ptr)
	Removes the last character from the string buffer and retrieves it. More...
ds_result_t	ds_string_remove (ds_string_t *const self, ds_usize_t const idx, ds_char_t *const chr_ptr)
	Removes a char from self at a byte position and retrieves it. More...
ds_result_t	ds_string_retain (ds_string_t *const self, ds_predicate_char_t const match)
	Retains only the characters specified by the predicate. More...
ds_result_t	ds_string_insert (ds_string_t *const self, ds_usize_t const idx, ds_char_t const chr)
	Inserts chr into self at a byte position. More...
ds_result_t	ds_string_insert_str (ds_string_t *const self, ds_usize_t const idx, ds_cstr_t const string, ds_usize_t const string_len)
	Inserts a string slice into self at a byte position. More...
ds_usize_t	ds_string_len (ds_string_t const self)
	Returns the length of self, in bytes, not graphemes. In other words, it might not be what a human considers the length of the string. More...
bool	ds_string_is_empty (ds_string_t const self)
	Returns true if self has a length of zero, and false otherwise. More...
ds_result_t	ds_string_split_off (ds_string_t *const self, ds_usize_t const idx, ds_string_t *const target)
	Splits self into two at the given byte index. More...
ds_result_t	ds_string_clear (ds_string_t *const self)
	Truncates self, removing all contents. More...
ds_result_t	ds_string_clone (ds_string_t const self, ds_string_t *const target)
	Retrieves a copy of self. More...
ds_result_t	ds_string_clone_from (ds_string_t *const self, ds_string_t const source)
	Performs copy-assignment from source. More...
ds_string_t	ds_string_default (void)
	Creates an empty String. More...
ds_result_t	ds_string_from (ds_string_t *const self, ds_cstr_t const string, ds_usize_t const string_len)
	Converts a C-string into a String. More...
bool	ds_string_eq (ds_string_t const self, ds_string_t const other)
	This method tests for self and other values to be equal. More...
bool	ds_string_ne (ds_string_t const self, ds_string_t const other)
	This method tests for self and other values to not be equal. More...
ds_cstr_t	ds_string_as_ptr (ds_string_t const self)
	Converts self to a raw pointer. More...
ds_cstr_mut_t	ds_string_as_mut_ptr (ds_string_t const self)
	Converts self to a mutable raw pointer. More...
ds_result_t	ds_string_drop (ds_string_t *const self)
	Disposes of a value. More...

Detailed Description

Implementation of the String type, related constants and functions.

Author

Avinash Maddikonda (svass.nosp@m.saka.nosp@m.vi@gm.nosp@m.ail..nosp@m.com)

Since

0.10.0

Date

2023-08-31

Definition in file string.c.

Function Documentation

ds_string_as_mut_ptr()

ds_cstr_mut_t ds_string_as_mut_ptr

(

ds_string_t

self

)

Converts self to a mutable raw pointer.

As string slices are a slice of bytes, the raw pointer points to a char. This pointer will be pointing to the first byte of the string slice.

It is your responsibility to make sure that the string slice only gets modified in a way that it remains valid UTF-8.

Parameters

self	The String to convert to a mutable raw pointer.

Returns

The mutable raw pointer pointing to the first byte of self.

Definition at line 386 of file string.c.

Here is the caller graph for this function:

ds_string_as_ptr()

ds_cstr_t ds_string_as_ptr

(

ds_string_t

self

)

Converts self to a raw pointer.

As string slices are a slice of bytes, the raw pointer points to a char. This pointer will be pointing to the first byte of the string slice.

The caller must ensure that the returned pointer is never written to. If you need to mutate the contents of the string slice, use ds_string_as_mut_ptr.

Parameters

self	The String to convert to a raw pointer.

Returns

The raw pointer pointing to the first byte of self.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "Hello", 5));
ds_cstr_t ptr = ds_string_as_ptr (s);
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 380 of file string.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ds_string_capacity()

ds_usize_t ds_string_capacity

(

ds_string_t

self

)

Returns self's capacity, in bytes.

Parameters

self	The String to return the capacity, in bytes, of.

Returns

self's capacity, in bytes.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_with_capacity (&s, 10));
 
assert (ds_string_capacity (s) >= 10);
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 135 of file string.c.

Here is the caller graph for this function:

ds_string_clear()

ds_result_t ds_string_clear

(

ds_string_t *

self

)

Truncates self, removing all contents.

While this means self will have a length of zero, it does not touch its capacity.

Parameters

[out]

self

Pointer to the String to truncate and remove all contents.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "foo", 3));
 
DS_RESULT_PROPAGATE_ERR (ds_string_clear (&s));
 
assert (ds_string_is_empty (s));
assert (0 == ds_string_len (s));
assert (3 <= ds_string_capacity (s));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 317 of file string.c.

Here is the call graph for this function:

ds_string_clone()

ds_result_t ds_string_clone	(	ds_string_t	self,
		ds_string_t *	target
	)

Retrieves a copy of self.

Parameters

	self	The value to clone.
[out]	target	Pointer to the value to clone into.

Returns

Ok on success.

Err(PtrIsNull) if target is NULL.

Err(MemAllocFailed) if a memory allocation fails.

Definition at line 323 of file string.c.

Here is the call graph for this function:

ds_string_clone_from()

ds_result_t ds_string_clone_from	(	ds_string_t *	self,
		ds_string_t	source
	)

Performs copy-assignment from source.

Parameters

[out]	self	Pointer to the value to clone into.
	source	The value to clone.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Err(MemAllocFailed) if a memory allocation fails.

Definition at line 329 of file string.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ds_string_default()

ds_string_t ds_string_default

(

void

)

Creates an empty String.

Returns

An empty String.

Definition at line 336 of file string.c.

Here is the call graph for this function:

ds_string_drop()

ds_result_t ds_string_drop

(

ds_string_t *

self

)

Disposes of a value.

Parameters

[out]

self

The value to dispose.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "abc", 3));
 
// explicitly drop the vector
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 392 of file string.c.

Here is the call graph for this function:

ds_string_eq()

bool ds_string_eq	(	ds_string_t	self,
		ds_string_t	other
	)

This method tests for self and other values to be equal.

Parameters

self	The first value to test.
other	The second value to test.

Returns

true if self and other values are equal, and false otherwise.

Definition at line 352 of file string.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ds_string_from()

ds_result_t ds_string_from	(	ds_string_t *	self,
		ds_cstr_t	string,
		ds_usize_t	string_len
	)

Converts a C-string into a String.

The result is allocated on the heap.

Parameters

[out]	self	Pointer to the String to convert string into.
	string	The C-string to convert into self.
	string_len	The length of string.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Err(MemAllocFailed) if a memory allocation fails.

Definition at line 342 of file string.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ds_string_from_raw_parts()

ds_string_t ds_string_from_raw_parts	(	ds_cstr_mut_t	buf,
		ds_usize_t	length,
		ds_usize_t	capacity
	)

Creates a new String from a length, capacity, and buf pointer.

Warning

This is highly unsafe, due to the number of invariants that aren't checked:

• The memory at buf needs to have been previously allocated by the same allocator String uses, with a required alignment of exactly 1.
• length needs to be less than or equal to capacity.
• capacity needs to be the correct value.
• The first length bytes at buf need to be valid UTF-8.

Violating these may cause problems like corrupting the allocator's internal data structures. For example, it is normally not safe to build a String from a pointer to a C char array containing UTF-8 unless you are certain that array was originally allocated by the same allocator String uses.

The ownership of buf is effectively transferred to the String which may then deallocate, reallocate or change the contents of memory pointed to by the pointer at will. Ensure that nothing else uses the pointer after calling this function.

Parameters

buf	The pointer to the buffer.
length	The length of the string (in bytes).
capacity	The allocated capacity of the data (in bytes).

Returns

A new String from a length, capacity, and buf pointer.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "hello", 5));
 
ds_cstr_t const ptr = ds_string_as_ptr (s);
ds_usize_t const len = ds_string_len (s);
ds_usize_t const capacity = ds_string_capacity (s);
 
ds_string_t const hello = ds_string_from_raw_parts (ptr, len, capacity);
 
assert (ds_string_eq (hello, s));

Definition at line 118 of file string.c.

Here is the caller graph for this function:

ds_string_insert()

ds_result_t ds_string_insert	(	ds_string_t *	self,
		ds_usize_t	idx,
		ds_char_t	chr
	)

Inserts chr into self at a byte position.

This is an O(n) operation as it requires copying every element in the buffer.

Parameters

[out]	self	Pointer to the String to insert chr into at the byte position.
	idx	The byte position to insert chr into self at.
	chr	The character to insert into self at the byte position.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Err(OutOfRange) if idx is larger than self's length.

Err(MemAllocFailed) if a memory allocation fails.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_with_capacity (&s, 3));
 
DS_RESULT_PROPAGATE_ERR (ds_string_insert (&s, 0, 'f'));
DS_RESULT_PROPAGATE_ERR (ds_string_insert (&s, 1, 'o'));
DS_RESULT_PROPAGATE_ERR (ds_string_insert (&s, 2, 'o'));
 
ds_string_t foo;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&foo, "foo", 3));
assert (ds_string_eq (foo, s));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&foo));
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 251 of file string.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ds_string_insert_str()

ds_result_t ds_string_insert_str	(	ds_string_t *	self,
		ds_usize_t	idx,
		ds_cstr_t	string,
		ds_usize_t	string_len
	)

Inserts a string slice into self at a byte position.

This is an O(n) operation as it requires copying every element in the buffer.

Parameters

[out]	self	Pointer to the String to insert the string slice into at the byte position.
	idx	The byte position to insert the string slice into self at.
	string	The string slice to insert into self at the byte position.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Err(OutOfRange) if idx is larger than self's length.

Err(MemAllocFailed) if a memory allocation fails.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "bar", 3));
 
DS_RESULT_PROPAGATE_ERR (ds_string_insert_str (&s, 0, "foo", 3));
 
ds_string_t foobar;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&foobar, "foobar", 6));
assert (ds_string_eq (foobar, s));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&foobar));
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 258 of file string.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ds_string_into_raw_parts()

ds_result_t ds_string_into_raw_parts	(	ds_string_t *	self,
		ds_cstr_mut_t *	buf_ptr,
		ds_usize_t *	len_ptr,
		ds_usize_t *	cap_ptr
	)

Decomposes self into its raw components.

Retrieves the raw pointer to the underlying data, the length of the string (in bytes), and the allocated capacity of the data (in bytes), and stores them in memory locations pointed at by buf_ptr, len_ptr, and cap_ptr respectively. These are the same arguments in the same order as the arguments to ds_string_from_raw_parts.

After calling this function, the caller is responsible for the memory previously managed by self. The only way to do this is to convert the raw pointer, length, and capacity back into a String with the ds_string_from_raw_parts function, and calling ds_string_drop to perform the cleanup.

Parameters

[out]	self	Pointer to the String to decompose into its raw components.
[out]	buf_ptr	Pointer to the raw pointer to the underlying data.
[out]	len_ptr	Pointer to the length of the string (in bytes).
[out]	cap_ptr	Pointer to the allocated capacity of the data (in bytes).

Returns

Ok on success.

Err(PtrIsNull) if self, buf_ptr, len_ptr, or cap_ptr is NULL.

Examples

Basic usage:

ds_string_t s;
ds_string_t hello;
 
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "hello", 5));
DS_RESULT_PROPAGATE_ERR (ds_string_from (&hello, "hello", 5));
 
ds_cstr_mut_t ptr;
ds_usize_t len;
ds_usize_t cap;
DS_RESULT_PROPAGATE_ERR (ds_string_into_raw_parts (&s, &ptr, &len,
                                                   &cap));
 
ds_string_t const rebuilt = ds_string_from_raw_parts (ptr, len, cap);
assert (ds_string_eq (rebuilt, hello));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&rebuilt));
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&hello));
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 100 of file string.c.

Here is the call graph for this function:

ds_string_is_empty()

bool ds_string_is_empty

(

ds_string_t

self

)

Returns true if self has a length of zero, and false otherwise.

Parameters

self	The String to check if has length of zero.

Returns

true if self has a length of zero, and false otherwise.

Examples

Basic usage:

ds_string_t v = ds_string_new ();
assert (ds_string_is_empty (v));
 
DS_RESULT_PROPAGATE_ERR (ds_string_push (&v, 'a'));
assert (!ds_string_is_empty (v));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&v));

Definition at line 287 of file string.c.

Here is the call graph for this function:

ds_string_len()

ds_usize_t ds_string_len

(

ds_string_t

self

)

Returns the length of self, in bytes, not graphemes. In other words, it might not be what a human considers the length of the string.

Parameters

self	The String to return the length of, in bytes.

Returns

The length of self, in bytes.

Examples

Basic usage:

ds_string_t a;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&a, "foo", 3));
assert (ds_string_len (a) == 3);
 
ds_string_t fancy_f;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&fancy_f, "ƒoo", 4));
assert (ds_string_len (fancy_f), 4);
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&fancy_f));
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 281 of file string.c.

Here is the caller graph for this function:

ds_string_ne()

bool ds_string_ne	(	ds_string_t	self,
		ds_string_t	other
	)

This method tests for self and other values to not be equal.

Parameters

self	The first value to test.
other	The second value to test.

Returns

true if self and other values are not equal, and false otherwise.

Definition at line 374 of file string.c.

Here is the call graph for this function:

ds_string_new()

ds_string_t ds_string_new

(

void

)

Creates a new empty String.

Given that the String is empty, this will not allocate any initial buffer. While that means that this initial operation is very inexpensive, it may cause excessive allocation later when you add data. If you have an idea of how much data the String will hold, consider the ds_string_with_capacity method to prevent excessive re-allocation.

Returns

A new empty String.

Examples

Basic usage:

ds_string_t const s = ds_string_new ();
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 85 of file string.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ds_string_pop()

ds_result_t ds_string_pop	(	ds_string_t *	self,
		ds_char_t *	chr_ptr
	)

Removes the last character from the string buffer and retrieves it.

Parameters

[out]	self	Pointer to the String to remove the last character from its string buffer and retrieve it from.
[out]	chr_ptr	Pointer to the last character removed and retrieved from self's string buffer.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Err(OutOfRange) if self is empty.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "foo", 3));
 
ds_char_t chr;
 
DS_RESULT_PROPAGATE_ERR (ds_string_pop (&s, &chr));
assert (chr == 'o');
DS_RESULT_PROPAGATE_ERR (ds_string_pop (&s, &chr));
assert (chr == 'o');
DS_RESULT_PROPAGATE_ERR (ds_string_pop (&s, &chr));
assert (chr == 'f');
 
assert (ds_string_pop (&s, &chr) == DS_RESULT_ERR_OUT_OF_RANGE);
assert (chr == 'f');
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 194 of file string.c.

Here is the call graph for this function:

ds_string_push()

ds_result_t ds_string_push	(	ds_string_t *	self,
		ds_char_t	chr
	)

Appends chr to the end of self.

Parameters

[out]	self	Pointer to the String to append chr to the end of.
	chr	The char to append to the end of self.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Err(MemAllocFailed) if a memory allocation fails.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "abc", 3));
 
DS_RESULT_PROPAGATE_ERR (ds_string_push (&s, '1'));
DS_RESULT_PROPAGATE_ERR (ds_string_push (&s, '2'));
DS_RESULT_PROPAGATE_ERR (ds_string_push (&s, '3'));
 
ds_string_t abc123;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&abc123, "abc123", 6));
assert (ds_string_eq (abc123, s));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&abc123));
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 176 of file string.c.

Here is the call graph for this function:

ds_string_push_str()

ds_result_t ds_string_push_str	(	ds_string_t *	self,
		ds_cstr_t	string,
		ds_usize_t	string_len
	)

Appends string onto the end of self.

Parameters

[out]	self	Pointer to the String to append string onto the end of.
	string	A C-string slice to append to self.
	string_len	The length of string (in bytes).

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Err(MemAllocFailed) if a memory allocation fails.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "foo", 3));
 
DS_RESULT_PROPAGATE_ERR (ds_string_push_str (&s, "bar", 3));
 
ds_string_t foobar;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "foobar", 6));
assert (ds_string_eq (foobar, s));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&foobar));
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 125 of file string.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ds_string_remove()

ds_result_t ds_string_remove	(	ds_string_t *	self,
		ds_usize_t	idx,
		ds_char_t *	chr_ptr
	)

Removes a char from self at a byte position and retrieves it.

This is an O(n) operation, as it requires copying every element in the buffer.

Parameters

[out]	self	Pointer to the String to remove a char and retrieve it at a byte position.
	idx	The byte position to remove a char at.
[out]	chr_ptr	Pointer to the char removed and retrieved at a byte position.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Err(OutOfRange) if idx is larger than or equal to self's length.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "foo", 3));
 
ds_char_t chr;
 
DS_RESULT_PROPAGATE_ERR (ds_string_remove (&s, 0, &chr));
assert (chr == 'f');
DS_RESULT_PROPAGATE_ERR (ds_string_remove (&s, 1, &chr));
assert (chr == 'o');
DS_RESULT_PROPAGATE_ERR (ds_string_remove (&s, 0, &chr));
assert (chr == 'o');
 
assert (ds_string_remove (&s, 0, &chr) == DS_RESULT_ERR_OUT_OF_RANGE);
assert (chr == 'f');
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 201 of file string.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ds_string_reserve()

ds_result_t ds_string_reserve	(	ds_string_t *	self,
		ds_usize_t	additional
	)

Reserves capacity for at least additional bytes more than self's current length. The allocator may reserve more space to speculatively avoid frequent allocations. After calling ds_string_reserve, capacity will be greater than or equal to ds_string_len (self) + additional. Does nothing if capacity is already sufficient.

Parameters

[out]	self	Pointer to the String to reserve capacity for at least additional bytes more than its current length.
	additional	The minimum number of bytes more than self's current length to allocate.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Err(OutOfRange) if the new capacity overflows usize.

Err(MemAllocFailed) if a memory allocation fails.

Examples

Basic usage:

ds_string_t s = ds_string_new ();
 
DS_RESULT_PROPAGATE_ERR (ds_string_reserve (&s, 10));
 
assert (ds_string_capacity (s) >= 10);
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

This might not actually increase the capacity:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_with_capacity (&s, 10));
DS_RESULT_PROPAGATE_ERR (ds_string_push (&s, 'a'));
DS_RESULT_PROPAGATE_ERR (ds_string_push (&s, 'b'));
 
// s now has a length of 2 and a capacity of at least 10
let capacity = ds_string_capacity (s);
assert (2 == ds_string_len (s));
assert (capacity >= 10);
 
// Since we already have at least an extra 8 capacity, calling this...
DS_RESULT_PROPAGATE_ERR (ds_string_reserve (&s, 8));
 
// ... doesn't actually increase.
assert (capacity == ds_string_capacity (s));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 141 of file string.c.

Here is the caller graph for this function:

ds_string_reserve_exact()

ds_result_t ds_string_reserve_exact	(	ds_string_t *	self,
		ds_usize_t	additional
	)

Reserves the minimum capacity for at least additional bytes more than self's current length. Unlike ds_string_reserve, this will not deliberately over-allocate to speculatively avoid frequent allocations. After calling ds_string_reserve_exact, capacity will be greater than or equal to ds_string_len (self) + additional. Does nothing if the capacity is already sufficient.

Parameters

[out]	self	Pointer to the String to reserve the minimum capacity for at least additional bytes more than its current length.
	additional	The minimum number of bytes more than self's current length to allocate without deliberately over-allocating.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Err(OutOfRange) if the new capacity overflows usize.

Err(MemAllocFailed) if a memory allocation fails.

Examples

Basic usage:

ds_string_t s = ds_string_new ();
 
DS_RESULT_PROPAGATE_ERR (ds_string_reserve_exact (&s, 10));
 
assert (ds_string_capacity (s) >= 10);
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

This might not actually increase the capacity:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_with_capacity (&s, 10));
DS_RESULT_PROPAGATE_ERR (ds_string_push (&s, 'a'));
DS_RESULT_PROPAGATE_ERR (ds_string_push (&s, 'b'));
 
// s now has a length of 2 and a capacity of at least 10
let capacity = ds_string_capacity (s);
assert (2 == ds_string_len (s));
assert (capacity >= 10);
 
// Since we already have at least an extra 8 capacity, calling this...
DS_RESULT_PROPAGATE_ERR (ds_string_reserve_exact (&s, 8));
 
// ... doesn't actually increase.
assert (capacity == ds_string_capacity (s));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 147 of file string.c.

ds_string_retain()

ds_result_t ds_string_retain	(	ds_string_t *	self,
		ds_predicate_char_t	match
	)

Retains only the characters specified by the predicate.

In other words, remove all characters c such that match(c) returns false. This method operates in place, visiting each character exactly once in the original order, and preserves the order of the retained characters.

Parameters

[out]	self	Pointer to the String whose characters are to be retained based on the predicate.
	match	The predicate that specifies which characters to retain.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "f_o_ob_ar", 9));
 
bool is_not_underscore (char const c)
{
  return c != '_';
}
 
DS_RESULT_PROPAGATE_ERR (ds_string_retain (&s, is_not_underscore));
 
ds_string_t foobar;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&foobar, "foobar", 6));
 
assert (ds_string_eq (s, foobar));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&foobar));
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Because the elements are visited exactly once in the original order, external state may be used to decide which elements to keep.

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "abcde", 5));
bool keep[] = { false, true, true, false, true };
bool only_keep (char const c)
{
  static ds_usize_t i = DS_USIZE_MIN;
  return keep[i++];
}
DS_RESULT_PROPAGATE_ERR (ds_string_retain (&s, only_keep));
ds_string_t bce;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&bce, "bce", 3));
assert (ds_string_eq (s, bce));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&bce));
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 227 of file string.c.

Here is the call graph for this function:

ds_string_shrink_to()

ds_result_t ds_string_shrink_to	(	ds_string_t *	self,
		ds_usize_t	min_capacity
	)

Shrinks the capacity of self with a lower bound.

The capacity will remain at least as large as both the length and the supplied value.

If the current capacity is less than the lower limit, this is a no-op.

Parameters

[out]	self	Pointer to the String to shrink the capacity with a lower bound.
	min_capacity	The lower bound of the capacity.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "foo", 3));
 
DS_RESULT_PROPAGATE_ERR (ds_string_reserve (&s, 100));
assert (ds_string_capacity (s) >= 100);
 
DS_RESULT_PROPAGATE_ERR (ds_string_shrink_to (&s, 10));
assert (ds_string_capacity (s) >= 10);
DS_RESULT_PROPAGATE_ERR (ds_string_shrink_to (&s, 0));
assert (ds_string_capacity (s) >= 3);
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 160 of file string.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ds_string_shrink_to_fit()

ds_result_t ds_string_shrink_to_fit

(

ds_string_t *

self

)

Shrinks the capacity of self to match its length.

Parameters

[out]

self

Pointer to the String to shrink the capacity to match its length.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "foo", 3));
 
DS_RESULT_PROPAGATE_ERR (ds_string_reserve (&s, 100));
assert (ds_string_capacity (s) >= 100);
 
DS_RESULT_PROPAGATE_ERR (ds_string_shrink_to_fit (&s));
assert (3 == ds_string_capacity (s));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 153 of file string.c.

Here is the call graph for this function:

ds_string_split_off()

ds_result_t ds_string_split_off	(	ds_string_t *	self,
		ds_usize_t	idx,
		ds_string_t *	target
	)

Splits self into two at the given byte index.

Retrieves a newly allocated String. self contains bytes [0, idx), and the retrieved target contains bytes [idx, len).

Note that the capacity of self does not change.

Parameters

[out]	self	Pointer to the String to split into two at the given byte index.
	idx	The byte index to split self into two at.
[out]	target	Pointer to the newly allocated String containing bytes [idx, len).

Returns

Ok on success.

Err(PtrIsNull) if self or target is NULL.

Err(OutOfRange) if idx is beyond the last code point of the string.

Err(MemAllocFailed) if a memory allocation fails.

Examples

ds_string_t hello;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&hello, "Hello, World!", 13));
ds_string_t world;
DS_RESULT_PROPAGATE_ERR (ds_string_split_off (&hello, 7, &world));
ds_string_t hello_actual;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&hello_actual, "Hello, ", 7));
ds_string_t world_actual;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&world_actual, "World!", 6));
assert (ds_string_eq (hello, hello_actual));
assert (ds_string_eq (world, world_actual));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&world_actual));
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&hello_actual));
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&world));
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&hello));

Definition at line 293 of file string.c.

Here is the call graph for this function:

ds_string_truncate()

ds_result_t ds_string_truncate	(	ds_string_t *	self,
		ds_usize_t	new_len
	)

Shortens self to new_len.

If new_len is greater than self's current length, this has no effect.

Note that this method has no effect on the allocated capacity of self.

Parameters

[out]	self	Pointer to the String to shorten to new_len.
	new_len	The length to shorten self to.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&s, "hello", 5));
 
DS_RESULT_PROPAGATE_ERR (ds_string_truncate (&s, 2));
 
ds_string_t he;
DS_RESULT_PROPAGATE_ERR (ds_string_from (&he, "he", 2));
assert (ds_string_eq (he, s));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&he));
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 183 of file string.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ds_string_with_capacity()

ds_result_t ds_string_with_capacity	(	ds_string_t *	self,
		ds_usize_t	capacity
	)

Creates a new empty String with at least the specified capacity.

Strings have an internal buffer to hold their data. The capacity is the length of that buffer, and can be queried with the ds_string_capacity method. This method creates an empty String, but one with an initial buffer that can hold at least capacity bytes. This is useful when you may be appending a bunch of data to the String, reducing the number of reallocations it needs to do.

If the given capacity is 0, no allocation will occur, and this method is identical to the ds_string_new method.

Parameters

[out]	self	Pointer to a new empty String with at least the specified capacity.
	capacity	The minimum number of bytes to allocate.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Err(MemAllocFailed) if a memory allocation fails.

Examples

Basic usage:

ds_string_t s;
DS_RESULT_PROPAGATE_ERR (ds_string_with_capacity (&s, 10));
 
// The String contains no chars, even though it has capacity for more
assert (ds_string_len (s) == 0);
 
// These are all done without reallocating...
ds_usize_t const cap = ds_string_capacity (s);
for (ds_usize_t i = DS_USIZE_MIN; i < 10; i++)
  {
    DS_RESULT_PROPAGATE_ERR (ds_string_push (&s, 'a'));
  }
 
assert (ds_string_capacity (s) == cap);
 
// ...but this may make the string reallocate
DS_RESULT_PROPAGATE_ERR (ds_string_push (&s, 'a'));
 
DS_RESULT_PROPAGATE_ERR (ds_string_drop (&s));

Definition at line 91 of file string.c.

Here is the call graph for this function: