The SV_Str_view Interface. More...

#include <stdbool.h>
#include <stddef.h>

Include dependency graph for str_view.h:

Detailed Description

The SV_Str_view Interface.

A SV_Str_view is a read only view of null terminated C strings. It's purpose is to provide robust read only string construction, tokenizing, and matching. This introduces tremendous flexibility to string handling in C programming from low-level kernel code to application layer programming.

Read only string handling offers many safety benefits as well. All functions in the interface are either constant or pure functions. This means that given the same inputs, they will provide the same outputs. And because no functions can modify the underlying string, compilers can often help use these guarantees to produce faster code. This also means that all string view functions are inherently safe to be used from multiple threads over the same string data.

This interface also aims to provide robust read only tokenization without any of the concerns that come with functions like strtok versus strtok_r. Tokenization can occur simultaneously from multiple threads and a natural iteration abstraction is provided.

Finally, all major string matching functions are provided and run in linear time, using constant space. There are also variants of the substring matching algorithms that run in reverse providing the optimal time complexity for reverse string matching. Constant space complexity is an important component of maintaining the pure attributes of the searching function. Regardless of the underlying string matching algorithm, no side effects occur and no auxiliary global or static global storage is needed.

Data Structures
struct	SV_Str_view
	A read-only view of string data in C. More...

Macros
#define	SV_ATTRIB_PURE
	Describes a function as having no side effects when given the same arguments with same underlying data. Can be used when pointers are provided.

#define	SV_ATTRIB_CONST
	Describes a function as having no side effects and not depending on any pointer input that could change between calls.

#define	SV_ATTRIB_NULLTERM(...)
	Describes a parameter as null terminated.

#define	SV_STR_LITERAL(str_literal) str_literal
	MSVC does not allow strong enforcement of string literals to the SV_from constructor. This is a dummy wrapper for compatibility.

#define	SV_API
	A macro to help with library linking on windows.

Construction
A macro and functions for constructing a `SV_Str_view`.
#define	SV_from(str_literal) ((SV_Str_view){SV_STR_LITERAL(str_literal), sizeof(str_literal) - 1})
	A macro to reduce the chance for errors in repeating oneself when constructing an inline or const SV_Str_view. The input must be a string literal.

SV_API SV_Str_view	SV_from_terminated (char const *str) SV_ATTRIB_NULLTERM(1) SV_ATTRIB_PURE
	Constructs and returns a string view from a null terminated string.

SV_API SV_Str_view	SV_from_view (size_t n, char const *str) SV_ATTRIB_NULLTERM(2) SV_ATTRIB_PURE
	Constructs and returns a string view from a sequence of valid n bytes or string length, whichever comes first.

SV_API SV_Str_view	SV_from_delimiter (char const str, char const delim) SV_ATTRIB_NULLTERM(1) SV_ATTRIB_NULLTERM(2) SV_ATTRIB_PURE
	Constructs and returns a string view from a null terminated string broken on the first occurrence of delimiter if found or null terminator if delim cannot be found.

SV_API SV_Str_view	SV_substr (SV_Str_view sv, size_t pos, size_t count) SV_ATTRIB_PURE
	Creates the substring from position pos for count length. The count is the minimum value between count and `(length - pos)`.

SV_API size_t	SV_str_bytes (char const *str) SV_ATTRIB_NULLTERM(1) SV_ATTRIB_PURE
	Returns the bytes of the string pointer to, null terminator included.

SV_API SV_Str_view	SV_copy (size_t str_bytes, char const *src_str) SV_ATTRIB_NULLTERM(2) SV_ATTRIB_PURE
	Copies the max of string bytes or input string length into a view, whichever ends first.

SV_API size_t	SV_fill (size_t dest_bytes, char *dest_buf, SV_Str_view src)
	Fills the destination buffer with the minimum between destination size and source view size, null terminating the string.

SV_API SV_Str_view	SV_extend (SV_Str_view sv) SV_ATTRIB_PURE
	Returns a SV_Str_view of the entirety of the underlying string, starting at the current view pointer position.

Types
The types of the `SV_Str_view` interface.
enum	SV_Order { SV_ORDER_LESSER = -1 , SV_ORDER_EQUAL , SV_ORDER_GREATER , SV_ORDER_ERROR }
	Standard three way comparison type in C. More...

Comparison
Comparing a `SV_Str_view` with another instance or a C string.
SV_API SV_Order	SV_compare (SV_Str_view lhs, SV_Str_view rhs) SV_ATTRIB_PURE
	Returns the standard C threeway comparison between cmp(lhs, rhs) between two string views.

SV_API SV_Order	SV_terminated_compare (SV_Str_view lhs, char const *rhs) SV_ATTRIB_NULLTERM(2) SV_ATTRIB_PURE
	Returns the standard C threeway comparison between cmp(lhs, rhs) between a SV_Str_view and a C string.

SV_API SV_Order	SV_view_compare (SV_Str_view lhs, char const *rhs, size_t n) SV_ATTRIB_NULLTERM(2) SV_ATTRIB_PURE
	Returns the standard C threeway comparison between cmp(lhs, rhs) between a SV_Str_view and a C string, bounded by n bytes of the right hand side. If `n` is shorter than the right hand side string the `n`th byte is compared.

Tokenization and Iteration
Tokenize a `SV_Str_view` and use convenient iteration abstractions.
SV_API SV_Str_view	SV_token_begin (SV_Str_view src, SV_Str_view delim) SV_ATTRIB_PURE
	Finds the first tokenized position in the string view given any length delim SV_Str_view.

SV_API bool	SV_token_end (SV_Str_view src, SV_Str_view token) SV_ATTRIB_PURE
	Provides the status of the current tokenization for use in conditions such as loops.

SV_API SV_Str_view	SV_token_next (SV_Str_view src, SV_Str_view token, SV_Str_view delim) SV_ATTRIB_PURE
	Advances to the next token in the remaining view separated by the delim.

SV_API SV_Str_view	SV_token_reverse_begin (SV_Str_view src, SV_Str_view delim) SV_ATTRIB_PURE

SV_API bool	SV_token_reverse_end (SV_Str_view src, SV_Str_view token) SV_ATTRIB_PURE
	Provides the status of the current tokenization for use in conditions such as loops.

SV_API SV_Str_view	SV_token_reverse_next (SV_Str_view src, SV_Str_view token, SV_Str_view delim) SV_ATTRIB_PURE
	Advances the token in src to the next token between two delimiters provided by delim.

SV_API char const *	SV_begin (SV_Str_view sv) SV_ATTRIB_PURE
	Returns a read only pointer to the beginning of the string view, the first valid character in the view.

SV_API char const *	SV_reverse_begin (SV_Str_view sv) SV_ATTRIB_PURE
	Returns the reverse iterator beginning, the last character of the current view.

SV_API char const *	SV_next (char const *c) SV_ATTRIB_NULLTERM(1) SV_ATTRIB_PURE
	Advances the null terminated string pointer from its previous position. If NULL is provided SV_null() is returned.

SV_API char const *	SV_reverse_next (char const *c) SV_ATTRIB_PURE
	Advances the iterator to the next character in the SV_Str_view being iterated through in reverse.

SV_API char const *	SV_end (SV_Str_view sv) SV_ATTRIB_PURE
	Returns a read only pointer to the end of the string view.

SV_API char const *	SV_reverse_end (SV_Str_view sv) SV_ATTRIB_PURE
	The ending position of a reverse iteration.

String Matching
Search a `SV_Str_view` for various types of substrings and character matches.
SV_API size_t	SV_find (SV_Str_view haystack, size_t pos, SV_Str_view needle) SV_ATTRIB_PURE
	Searches for needle in haystack starting from pos.

SV_API size_t	SV_reverse_find (SV_Str_view haystack, size_t pos, SV_Str_view needle) SV_ATTRIB_PURE
	Searches for the last occurrence of needle in haystack starting from pos from right to left.

SV_API bool	SV_contains (SV_Str_view haystack, SV_Str_view needle) SV_ATTRIB_PURE
	Tests membership of needle in haystack.

SV_API SV_Str_view	SV_match (SV_Str_view haystack, SV_Str_view needle) SV_ATTRIB_PURE
	Search for a substring within a source string view.

SV_API SV_Str_view	SV_reverse_match (SV_Str_view haystack, SV_Str_view needle) SV_ATTRIB_PURE
	Search for a substring within a source string in reverse.

SV_API bool	SV_starts_with (SV_Str_view sv, SV_Str_view prefix) SV_ATTRIB_PURE
	Confirms the presence of a prefix within a string view.

SV_API SV_Str_view	SV_remove_prefix (SV_Str_view sv, size_t n) SV_ATTRIB_PURE

SV_API bool	SV_ends_with (SV_Str_view sv, SV_Str_view suffix) SV_ATTRIB_PURE
	Confirms the presence of a suffix within a string view.

SV_API SV_Str_view	SV_remove_suffix (SV_Str_view sv, size_t n) SV_ATTRIB_PURE

SV_API size_t	SV_find_first_of (SV_Str_view haystack, SV_Str_view set) SV_ATTRIB_PURE

SV_API size_t	SV_find_first_not_of (SV_Str_view haystack, SV_Str_view set) SV_ATTRIB_PURE

SV_API size_t	SV_find_last_of (SV_Str_view haystack, SV_Str_view set) SV_ATTRIB_PURE

SV_API size_t	SV_find_last_not_of (SV_Str_view haystack, SV_Str_view set) SV_ATTRIB_PURE

State
Obtain current state of an `SV_Str_view` and C strings.
SV_API size_t	SV_min_len (char const *str, size_t n) SV_ATTRIB_NULLTERM(1) SV_ATTRIB_PURE
	Returns the minimum between the string size vs n bytes.

SV_API char const *	SV_null (void) SV_ATTRIB_PURE
	A sentinel empty string. Safely dereference to view a null terminator. This may be returned from various functions when bad input is given such as NULL pointers as the underlying SV_Str_view string pointer.

SV_API size_t	SV_npos (SV_Str_view sv) SV_ATTRIB_CONST
	The end of a SV_Str_view guaranteed to be greater than or equal to size.

SV_API bool	SV_is_empty (SV_Str_view sv) SV_ATTRIB_CONST
	Returns true if the provided SV_Str_view is empty, false otherwise.

SV_API size_t	SV_len (SV_Str_view sv) SV_ATTRIB_CONST
	Returns the length of the SV_Str_view in O(1) time.

SV_API size_t	SV_bytes (SV_Str_view sv) SV_ATTRIB_CONST

SV_API char const *	SV_pointer (SV_Str_view sv, size_t i) SV_ATTRIB_PURE
	Returns the character pointer at the minimum between the indicated position and the end of the string view.

SV_API char	SV_at (SV_Str_view sv, size_t i) SV_ATTRIB_PURE
	Obtain a character at a position in the string view.

SV_API char	SV_front (SV_Str_view sv) SV_ATTRIB_PURE
	Obtain the character at the first position of SV_Str_view.

SV_API char	SV_back (SV_Str_view sv) SV_ATTRIB_PURE
	Obtain the character at the last position of SV_Str_view.

Macro Definition Documentation

◆ SV_from

#define SV_from ( str_literal ) ((SV_Str_view){SV_STR_LITERAL(str_literal), sizeof(str_literal) - 1})

A macro to reduce the chance for errors in repeating oneself when constructing an inline or const SV_Str_view. The input must be a string literal.

Parameters

[in] str_literal a C string literal

Returns: a string view constructed in O(1) at compile time. For example:

static SV_Str_view const prefix = SV_from("test_");

SV_from

#define SV_from(str_literal)

A macro to reduce the chance for errors in repeating oneself when constructing an inline or const SV_...

Definition: str_view.h:171

SV_Str_view

A read-only view of string data in C.

Definition: str_view.h:124

One can even use this in code when string literals are used rather than saved constants to avoid errors in SV_Str_view constructions.

for (SV_Str_view cur = SV_token_begin(src, SV_from(" "));
    !SV_token_end(src, cur);
    cur = SV_token_next(src, cur, SV_from(" "))
{}

However saving the SV_Str_view in a constant may be more convenient.

Enumeration Type Documentation

◆ SV_Order

enum SV_Order

Standard three way comparison type in C.

Orders the result of a comparison between left and right hand side elements, describing the order of the left hand side element compared to the right.

Function Documentation

◆ SV_at()

SV_API char SV_at	(	SV_Str_view	sv,
		size_t	i
	)

Obtain a character at a position in the string view.

Parameters

[in]	sv	the input string view.
[in]	i	the index within `[0, string view length - 1)`

Returns: the character in the string at position i with bounds checking. If i is greater than or equal to the size of SV_Str_view the null terminator character is returned.

◆ SV_back()

SV_API char SV_back ( SV_Str_view sv )

Obtain the character at the last position of SV_Str_view.

Parameters

[in] sv the input string view.

Returns: the last character in the string view. An empty SV_Str_view or NULL pointer is valid and will return '\0'.

◆ SV_begin()

SV_API char const * SV_begin ( SV_Str_view sv )

Returns a read only pointer to the beginning of the string view, the first valid character in the view.

Parameters

[in] sv the input string view.

Returns: if the view stores NULL, the placeholder SV_null() is returned.

◆ SV_bytes()

SV_API size_t SV_bytes ( SV_Str_view sv )

Returns the bytes of SV_Str_view including null terminator.

Parameters

[in] sv the string view to check.

Returns: the size in bytes of the view including the null terminator position character.

Note: String views may not actually be null terminated but the position at SV_Str_view[SV_Str_view.len] is interpreted as the null terminator and thus counts towards the byte count.

◆ SV_compare()

SV_API SV_Order SV_compare	(	SV_Str_view	lhs,
		SV_Str_view	rhs
	)

Returns the standard C threeway comparison between cmp(lhs, rhs) between two string views.

Parameters

[in]	lhs	the string view left hand side.
[in]	rhs	the string view right hand side.

Returns: the order of the left hand side string view compared to the right hand side.

Comparison is bounded by the shorter SV_Str_view length. ERR is returned if bad input is provided such as a SV_Str_view with a NULL pointer field.

◆ SV_contains()

SV_API bool SV_contains	(	SV_Str_view	haystack,
		SV_Str_view	needle
	)

Tests membership of needle in haystack.

Parameters

[in]	haystack	the source string view to search.
[in]	needle	the substring to match within haystack.

Returns: true if the needle is found in the haystack, false otherwise.

◆ SV_copy()

SV_API SV_Str_view SV_copy	(	size_t	str_bytes,
		char const *	src_str
	)

Copies the max of string bytes or input string length into a view, whichever ends first.

Parameters

[in]	str_bytes	the number of bytes to scan, at most.
[in]	src_str	the null terminated string to scan.

Returns: a string view constructed from the minimum between the length of the input string and the provided byte count.

Warning: If no \0 character is encountered, the character found at byte str_bytes of the input string is conceptually at the position of the null terminator of the view.

◆ SV_end()

SV_API char const * SV_end ( SV_Str_view sv )

Returns a read only pointer to the end of the string view.

Parameters

[in] sv the view being iterated over.

Returns: the character pointer to the end of this iteration. This may or may not be a null terminated character depending on the view. If the view stores NULL, the placeholder SV_null() is returned.

◆ SV_ends_with()

SV_API bool SV_ends_with	(	SV_Str_view	sv,
		SV_Str_view	suffix
	)

Confirms the presence of a suffix within a string view.

Parameters

[in]	sv	the string view to search.
[in]	suffix	the substring suffix to match with the input view.

Returns: true if a suffix shorter than or equal in length to the SV_Str_view is present, false otherwise.

◆ SV_extend()

SV_API SV_Str_view SV_extend ( SV_Str_view sv )

Returns a SV_Str_view of the entirety of the underlying string, starting at the current view pointer position.

Parameters

[in] sv the string view to extend.

Returns: a string view extended to include the rest of the characters before the null terminator of the underlying string.

This guarantees that the SV_Str_view returned ends at the null terminator of the underlying string as all strings used with SV_Str_views are assumed to be null terminated. It is undefined behavior to provide non null terminated strings to any SV_Str_view code.

◆ SV_fill()

SV_API size_t SV_fill	(	size_t	dest_bytes,
		char *	dest_buf,
		SV_Str_view	src
	)

Fills the destination buffer with the minimum between destination size and source view size, null terminating the string.

Parameters

[in]	dest_bytes	the bytes available in the destination.
[in]	dest_buf	the character buffer destination.
[in]	src	the string view to copy into the buffer.

Returns: the number of bytes successfully written, including the null terminator.

Warning: This may cut off src data if destination bytes < source length. Returns how many bytes were written to the buffer.

◆ SV_find()

SV_API size_t SV_find	(	SV_Str_view	haystack,
		size_t	pos,
		SV_Str_view	needle
	)

Searches for needle in haystack starting from pos.

Parameters

[in]	haystack	the string view to search.
[in]	pos	the position from which to start the search.
[in]	needle	the substring to match within haystack.

Returns: the index of the first character of the match. If the needle is larger than the haystack, or position is greater than haystack length, then haystack length (npos) is returned.

◆ SV_find_first_not_of()

SV_API size_t SV_find_first_not_of	(	SV_Str_view	haystack,
		SV_Str_view	set
	)

Finds the first position at which no characters in set can be found.

Parameters

[in]	haystack	the input view to search.
[in]	set	the set of characters banned in the search for of haystack. Each character in the input set is considered a valid match if encountered in haystack.

Returns: the position of the first occurrence of any character NOT in the input set provided. If only characters in the set are encountered haystack size is returned. An empty set (NULL) is valid, returning npos. An empty haystack returns 0.

◆ SV_find_first_of()

SV_API size_t SV_find_first_of	(	SV_Str_view	haystack,
		SV_Str_view	set
	)

Finds the first position of an occurrence of any character in set.

Parameters

[in]	haystack	the input view to search.
[in]	set	the set of characters to search for in the haystack. Each character in the input set is considered a valid match if encountered in haystack.

Returns: the position of the first occurrence of any character in the input set provided. If no occurrence is found haystack size is returned. An empty set (NULL) is valid, returning npos. An empty haystack returns 0.

◆ SV_find_last_not_of()

SV_API size_t SV_find_last_not_of	(	SV_Str_view	haystack,
		SV_Str_view	set
	)

Finds the last position at which no characters in set can be found.

Parameters

[in]	haystack	the input view to search.
[in]	set	the set of characters banned in the search for of haystack. Each character in the input set is considered a valid match if encountered in haystack.

Returns: the position of the last occurrence of any character NOT in the input set provided. If only characters in the set are encountered haystack size is returned. An empty set (NULL) is valid, returning npos. An empty haystack returns 0.

◆ SV_find_last_of()

SV_API size_t SV_find_last_of	(	SV_Str_view	haystack,
		SV_Str_view	set
	)

Finds the last position of an occurrence of any character in set.

Parameters

[in]	haystack	the input view to search.
[in]	set	the set of characters to search for in the haystack. Each character in the input set is considered a valid match if encountered in haystack.

Returns: the position of the last occurrence of any character in the input set provided. If no occurrence is found haystack size is returned. An empty set (NULL) is valid, returning npos. An empty haystack returns 0.

◆ SV_from_delimiter()

SV_API SV_Str_view SV_from_delimiter	(	char const *	str,
		char const *	delim
	)

Constructs and returns a string view from a null terminated string broken on the first occurrence of delimiter if found or null terminator if delim cannot be found.

Parameters

[in]	str	the null terminated input string.
[in]	delim	the null terminated delimiter on which to break.

Returns: the constructed string view broken on the first occurrence of the delimiter or the entire string if no delimiter is found.

This constructor will also skip the delimiter if that delimiter starts the string. This is similar to the tokenizing function in the iteration section.

◆ SV_from_terminated()

SV_API SV_Str_view SV_from_terminated ( char const * str )

Constructs and returns a string view from a null terminated string.

Parameters

[in] str a pointer to the null terminated string.

Returns: a constructed string view in linear time at runtime.

Warning: The provided string must be null terminated. It is expected that all strings provided to string views are null terminated.

◆ SV_from_view()

SV_API SV_Str_view SV_from_view	(	size_t	n,
		char const *	str
	)

Constructs and returns a string view from a sequence of valid n bytes or string length, whichever comes first.

Parameters

[in]	n	the number of bytes to scan, at most.
[in]	str	the null terminated string to scan.

Returns: a string view constructed from the minimum between the length of the input string and the provided byte count.

Warning: If no \0 character is encountered, the character found at byte n of the input string is conceptually at the position of the null terminator of the view.

◆ SV_front()

SV_API char SV_front ( SV_Str_view sv )

Obtain the character at the first position of SV_Str_view.

Parameters

[in] sv the input string view.

Returns: the first character in the string view. An empty SV_Str_view or NULL pointer is valid and will return '\0'.

◆ SV_is_empty()

SV_API bool SV_is_empty ( SV_Str_view sv )

Returns true if the provided SV_Str_view is empty, false otherwise.

Parameters

[in] sv the string view to check.

Returns: true if empty otherwise false.

This is a useful function to check for SV_Str_view searches that yield an empty view at the end of a SV_Str_view when an element cannot be found.

◆ SV_len()

SV_API size_t SV_len ( SV_Str_view sv )

Returns the length of the SV_Str_view in O(1) time.

Parameters

[in] sv the string view to check.

Returns: the length of the string view, not including the null terminator byte.

The position at SV_Str_view size is interpreted as the null terminator and not counted toward length of a SV_Str_view.

◆ SV_match()

SV_API SV_Str_view SV_match	(	SV_Str_view	haystack,
		SV_Str_view	needle
	)

Search for a substring within a source string view.

Parameters

[in]	haystack	the source string view to search.
[in]	needle	the substring to match within haystack.

Returns: a view of the needle found in haystack at the first found position. If the needle cannot be found the empty view at the haystack length position is returned. This may or may not be null terminated at that position. If needle is greater than haystack length an empty view at the end of haystack is returned. If haystack is NULL, SV_null is returned.

◆ SV_min_len()

SV_API size_t SV_min_len	(	char const *	str,
		size_t	n
	)

Returns the minimum between the string size vs n bytes.

Parameters

[in]	str	the null terminated input string.
[in]	n	the limiting byte count to compare.

Returns: the minimum between the length of the string and n.

◆ SV_next()

SV_API char const * SV_next ( char const * c )

Advances the null terminated string pointer from its previous position. If NULL is provided SV_null() is returned.

Parameters

[in] c the pointer to a null terminated string iterator.

Returns: the next character in the string or the end iterator if no characters remain.

◆ SV_npos()

SV_API size_t SV_npos ( SV_Str_view sv )

The end of a SV_Str_view guaranteed to be greater than or equal to size.

Parameters

[in] sv the string view.

Returns: the end position of the string as an index.

This value may be used for the idiomatic check for most string searching function return values when something is not found. If a size is returned from a searching function it is possible to check it against this value.

◆ SV_null()

SV_API char const * SV_null ( void )

A sentinel empty string. Safely dereference to view a null terminator. This may be returned from various functions when bad input is given such as NULL pointers as the underlying SV_Str_view string pointer.

Returns: a read only character pointer that points to a null terminator and can be safely dereferenced.

◆ SV_pointer()

SV_API char const * SV_pointer	(	SV_Str_view	sv,
		size_t	i
	)

Returns the character pointer at the minimum between the indicated position and the end of the string view.

Parameters

[in]	sv	the string view input.
[in]	i	the index within range of `[0, string view length - 1)`.

Returns: a pointer to the character at the designated index. If NULL is stored by the SV_Str_view then SV_null() is returned.

◆ SV_remove_prefix()

SV_API SV_Str_view SV_remove_prefix	(	SV_Str_view	sv,
		size_t	n
	)

Removes the minimum between SV_Str_view length and n from the start of the SV_Str_view.

Parameters

[in]	sv	the input string view.
[in]	n	the bytes to remove from the start of the input view.

Returns: the new view with the requested bytes removed from the start.

It is safe to provide n larger than SV_Str_view size as that will result in a size 0 view to the end of the current view which may or may not be the null terminator.

◆ SV_remove_suffix()

SV_API SV_Str_view SV_remove_suffix	(	SV_Str_view	sv,
		size_t	n
	)

Removes the minimum between SV_Str_view length and n from the end of the SV_Str_view.

Parameters

[in]	sv	the input string view.
[in]	n	the bytes to remove from the end of the input view.

Returns: the new view with the requested bytes removed from the end.

It is safe to provide n larger than SV_Str_view size as that will result in a size 0 view to the end of the current view which may or may not be the null terminator.

◆ SV_reverse_begin()

SV_API char const * SV_reverse_begin ( SV_Str_view sv )

Returns the reverse iterator beginning, the last character of the current view.

Parameters

[in] sv the input string view.

Returns: if the view is null SV_null() is returned. If the view is sized zero with a valid pointer that pointer in the view is returned.

◆ SV_reverse_end()

SV_API char const * SV_reverse_end ( SV_Str_view sv )

The ending position of a reverse iteration.

Parameters

[in] sv the view being iterated over in reverse.

Returns: the character position at the reverse end of this iteration.

Warning: It is undefined behavior to access or use rend. It is undefined behavior to pass in any SV_Str_view not being iterated through as started with reverse_begin.

◆ SV_reverse_find()

SV_API size_t SV_reverse_find	(	SV_Str_view	haystack,
		size_t	pos,
		SV_Str_view	needle
	)

Searches for the last occurrence of needle in haystack starting from pos from right to left.

Parameters

[in]	haystack	the string view to search.
[in]	pos	the position from which to start the search.
[in]	needle	the substring to match within haystack.

Returns: if found the starting position of the string is returned, the same as find. If not found haystack size is returned. The only difference from find is the search direction. If needle is larger than haystack, haystack length is returned.

If the position is larger than the haystack, the entire haystack is searched.

◆ SV_reverse_match()

SV_API SV_Str_view SV_reverse_match	(	SV_Str_view	haystack,
		SV_Str_view	needle
	)

Search for a substring within a source string in reverse.

Parameters

[in]	haystack	the source string view to reverse search.
[in]	needle	the substring to match within haystack.

Returns: a view of the needle found in haystack at the last found position. If the needle cannot be found the empty view at the haystack length position is returned. This may or may not be null terminated at that position. If needle is greater than haystack length an empty view at haystack size is returned. If haystack is NULL, SV_null is returned (modeled after strstr).

◆ SV_reverse_next()

SV_API char const * SV_reverse_next ( char const * c )

Advances the iterator to the next character in the SV_Str_view being iterated through in reverse.

Parameters

[in] c the pointer to the null terminated string iterator.

Warning: It is undefined behavior to change the SV_Str_view one is iterating through during iteration. If the char pointer is null, SV_null() is returned.

◆ SV_starts_with()

SV_API bool SV_starts_with	(	SV_Str_view	sv,
		SV_Str_view	prefix
	)

Confirms the presence of a prefix within a string view.

Parameters

[in]	sv	the string view to search.
[in]	prefix	the substring prefix to match with the input view.

Returns: true if a prefix shorter than or equal in length to the SV_Str_view is present, false otherwise.

◆ SV_str_bytes()

SV_API size_t SV_str_bytes ( char const * str )

Returns the bytes of the string pointer to, null terminator included.

Parameters

[in] str the null terminated input string.

Returns: the size in bytes of str, including the null terminator.

◆ SV_substr()

SV_API SV_Str_view SV_substr	(	SV_Str_view	sv,
		size_t	pos,
		size_t	count
	)

Creates the substring from position pos for count length. The count is the minimum value between count and (length - pos).

Parameters

[in]	sv	the string view.
[in]	pos	the position from which to start the substring.
[in]	count	the new string length of the substring.

Returns: a newly constructed string view substring. If an invalid position is given greater than SV_Str_view length an empty view is returned positioned at the end of SV_Str_view.

Warning: The end position may or may not hold the null terminator.

◆ SV_terminated_compare()

SV_API SV_Order SV_terminated_compare	(	SV_Str_view	lhs,
		char const *	rhs
	)

Returns the standard C threeway comparison between cmp(lhs, rhs) between a SV_Str_view and a C string.

Parameters

[in]	lhs	the string view that serves as the left hand side of the order.
[in]	rhs	the null terminated string to compare against.

Returns: the order of the left hand side compared to the right hand side: SV_ORDER_LESSER, SV_ORDER_EQUAL, or SV_ORDER_GREATER.

Comparison is bounded by the shorter SV_Str_view length. An error value is returned if bad input is provided such as a SV_Str_view with a NULL pointer field.

◆ SV_token_begin()

SV_API SV_Str_view SV_token_begin	(	SV_Str_view	src,
		SV_Str_view	delim
	)

Finds the first tokenized position in the string view given any length delim SV_Str_view.

Parameters

[in]	src	the source string view to tokenize.
[in]	delim	the delimiter that separates tokens.

Returns: the first token encountered in the source view or the entire view if no token was found. Skips leading delimiters in construction. If the SV_Str_view to be searched stores NULL than the SV_null() is returned. If delim stores NULL, that is interpreted as a search for the null terminating character or empty string and the size zero substring at the final position in the SV_Str_view is returned wich may or may not be the null termiator. If no delim is found the entire SV_Str_view is returned.

◆ SV_token_end()

SV_API bool SV_token_end	(	SV_Str_view	src,
		SV_Str_view	token
	)

Provides the status of the current tokenization for use in conditions such as loops.

Parameters

[in]	src	the source view being tokenized.
[in]	token	the current token obtained from tokenization.

Returns: true if no further tokens are found and position is at the end position, meaning a call to SV_token_begin() or SV_token_next() has yielded a size 0 SV_Str_view that points at the end of the src SV_Str_view, which may or may not be null terminated.

◆ SV_token_next()

SV_API SV_Str_view SV_token_next	(	SV_Str_view	src,
		SV_Str_view	token,
		SV_Str_view	delim
	)

Advances to the next token in the remaining view separated by the delim.

Parameters

[in]	src	the source string view being tokenized.
[in]	token	the current token obtained from tokenizing.
[in]	delim	the delimeter that separates tokens.

Returns: the string view of the next available token. Repeating delimiter patterns will be skipped until the next token or end of string is found. If SV_Str_view stores NULL the SV_null() placeholder is returned. If delim stores NULL the end position of the SV_Str_view is returned which may or may not be the null terminator. The token is bounded by the length of the view between two delimiters or the length from a delimiter to the end of src, whichever comes first.

◆ SV_token_reverse_begin()

SV_API SV_Str_view SV_token_reverse_begin	(	SV_Str_view	src,
		SV_Str_view	delim
	)

Obtains the last token in a string in preparation for reverse tokenized iteration.

Parameters

[in]	src	the source view to tokenize in reverse.
[in]	delim	the delimiter that separates tokens.

Returns: the last token in the source view or the entire view if no token was found. Any delimiters that end the string are skipped, as in the forward version. If src is NULL SV_null is returned. If delim is null the entire src view is returned.

Note: Though the SV_Str_view is tokenized in reverse, the token view returned will start at the first character and be the length of the token found.

◆ SV_token_reverse_end()

SV_API bool SV_token_reverse_end	(	SV_Str_view	src,
		SV_Str_view	token
	)

Provides the status of the current tokenization for use in conditions such as loops.

Parameters

[in]	src	the source view being tokenized.
[in]	token	the current token obtained from tokenization.

Returns: true if no further tokens are found and position is at the start position, meaning a call to SV_token_reverse_begin() or SV_token_reverse_next() has yielded a size 0 SV_Str_view that points at the start of the src SV_Str_view.

◆ SV_token_reverse_next()

SV_API SV_Str_view SV_token_reverse_next	(	SV_Str_view	src,
		SV_Str_view	token,
		SV_Str_view	delim
	)

Advances the token in src to the next token between two delimiters provided by delim.

Parameters

[in]	src	the source string view being reverse tokenized.
[in]	token	the current token obtained from tokenization.
[in]	delim	the delimiter that separates tokens.

Returns: the string view of the next available token. Repeating delimiters are skipped until the next token is found. If no further tokens can be found an empty SV_Str_view is returned with its pointer set to the start of the src string being iterated through.

Note: A multi-character delimiter may yield different tokens in reverse than in the forward direction when partial matches occur and some portion of the delimiter is in a token. This is because the string is now being parsed from right to left. However, the token returned starts at the first character and is read from left to right between two delimiters as in the forward version.

◆ SV_view_compare()

SV_API SV_Order SV_view_compare	(	SV_Str_view	lhs,
		char const *	rhs,
		size_t	n
	)

Returns the standard C threeway comparison between cmp(lhs, rhs) between a SV_Str_view and a C string, bounded by n bytes of the right hand side. If n is shorter than the right hand side string the nth byte is compared.

Parameters

[in]	lhs	the string view that serves as the left hand side of the order.
[in]	rhs	the null terminated string to compare against.
[in]	n	limit bytes of the comparison if less than right hand side length.

Returns: the order of the left hand side compared to the right hand side: SV_ORDER_LESSER, SV_ORDER_EQUAL, or SV_ORDER_GREATER.

Comparison is bounded by the shortest length between left hand side, right hand side string length, and the byte limit n. An error value is returned if bad input is provided such as a SV_Str_view with a NULL pointer field.

Detailed Description

Data Structures

Macros

Construction

Types

Comparison

Tokenization and Iteration

String Matching

State

Macro Definition Documentation

◆ SV_from

Enumeration Type Documentation

◆ SV_Order

Function Documentation

◆ SV_at()

◆ SV_back()

◆ SV_begin()

◆ SV_bytes()

◆ SV_compare()

◆ SV_contains()

◆ SV_copy()

◆ SV_end()

◆ SV_ends_with()

◆ SV_extend()

◆ SV_fill()

◆ SV_find()

◆ SV_find_first_not_of()

◆ SV_find_first_of()

◆ SV_find_last_not_of()

◆ SV_find_last_of()

◆ SV_from_delimiter()

◆ SV_from_terminated()

◆ SV_from_view()

◆ SV_front()

◆ SV_is_empty()

◆ SV_len()

◆ SV_match()

◆ SV_min_len()

◆ SV_next()

◆ SV_npos()

◆ SV_null()

◆ SV_pointer()

◆ SV_remove_prefix()

◆ SV_remove_suffix()

◆ SV_reverse_begin()

◆ SV_reverse_end()

◆ SV_reverse_find()

◆ SV_reverse_match()

◆ SV_reverse_next()

◆ SV_starts_with()

◆ SV_str_bytes()

◆ SV_substr()

◆ SV_terminated_compare()

◆ SV_token_begin()

◆ SV_token_end()

◆ SV_token_next()

◆ SV_token_reverse_begin()

◆ SV_token_reverse_end()

◆ SV_token_reverse_next()

◆ SV_view_compare()