213 lines
6.9 KiB
C
213 lines
6.9 KiB
C
#ifndef STRING_VIEW_H
|
|
#define STRING_VIEW_H
|
|
|
|
#include <stdbool.h>
|
|
#include <stddef.h>
|
|
|
|
/**
|
|
* @brief A non-owning view of a string
|
|
*
|
|
* @details Represents a contiguous sequence of characters defined by a pointer
|
|
* and a byte length. It does not own the memory buffer, so the underlying
|
|
* source string must remain valid while the StringView is in use.
|
|
*/
|
|
|
|
typedef struct StringView {
|
|
char *text;
|
|
size_t length;
|
|
} StringView;
|
|
|
|
/**
|
|
* @brief Constant macro representing an empty or null StringView
|
|
*
|
|
* @details Useful for initializing or returning an invalid/empty view safely.
|
|
*/
|
|
#define SV_NULL (StringView){.text = NULL, .length = 0}
|
|
|
|
/**
|
|
* @brief Bit masks and flags for UTF-8 wide character parsing
|
|
*
|
|
* @details These masks are used to examine the bit patterns of UTF-8 bytes
|
|
* in order to distinguish between standard ASCII characters and multibyte
|
|
* sequences (2, 3, or 4 bytes), as well as continuation bytes.
|
|
*/
|
|
enum StringViewWideFlags {
|
|
SV_START_WIDE_CHAR = 0x80, //< Bit mask to check if a byte belongs to a
|
|
//< multibyte sequence (10000000)
|
|
SV_BYTES_2_WIDE_CHAR = 0xC0, //< Pattern/mask for the start of a 2-byte
|
|
//< UTF-8 character (11000000)
|
|
SV_BYTES_3_WIDE_CHAR = 0xE0, //< Pattern/mask for the start of a 3-byte
|
|
//< UTF-8 character (11100000)
|
|
SV_BYTES_4_WIDE_CHAR = 0xF0, //< Pattern/mask for the start of a 4-byte
|
|
//< UTF-8 character (11110000)
|
|
SV_CONTINUE_WIDE_CHAR =
|
|
0x80 //< Pattern/mask for a UTF-8 continuation byte (10xxxxxx)
|
|
};
|
|
|
|
/*
|
|
* @brief Create a string view from a const char* and set their length
|
|
*
|
|
* @details This string view provides a view of a string. It does not allocate
|
|
* memory, therefore, it lives only while the source is alive. The
|
|
* length is a bytes number of the string. It does not represents the number of
|
|
* characters.
|
|
*
|
|
* @param str pointer from the original string. It can be NULL.
|
|
*
|
|
* @return a StringView with the view of original string with corresponding
|
|
* length.
|
|
*/
|
|
|
|
StringView sv_from_cstr(const char *);
|
|
|
|
/**
|
|
* @brief Count the number of logical characters in the string view
|
|
*
|
|
* @details Traverses the string view bytes while properly handling UTF-8 wide
|
|
* characters. It counts each logical character exactly once, regardless of
|
|
* whether it occupies 1, 2, 3, or 4 physical bytes. Returns 0 if the pointer
|
|
* or internal text is NULL.
|
|
*
|
|
* @param sv pointer to the StringView to evaluate.
|
|
*
|
|
* @return the total number of logical characters in the string view.
|
|
*/
|
|
size_t sv_chars_count(StringView *);
|
|
|
|
/**
|
|
* @brief Reduce the string view to its first 'l' bytes
|
|
*
|
|
* @details Modifies the string view in place, shortening its length to the
|
|
* specified number of bytes from the beginning.
|
|
*
|
|
* @param sv pointer to the StringView to modify.
|
|
* @param l number of bytes to keep from the left.
|
|
*/
|
|
void sv_left(StringView *sv, size_t l);
|
|
|
|
/**
|
|
* @brief Reduce the string view to its last 'l' bytes
|
|
*
|
|
* @details Modifies the string view in place, adjusting its start pointer and
|
|
* length to keep only the specified number of bytes from the end.
|
|
*
|
|
* @param sv pointer to the StringView to modify.
|
|
* @param l number of bytes to keep from the right.
|
|
*/
|
|
void sv_right(StringView *sv, size_t l);
|
|
|
|
/**
|
|
* @brief Trim leading whitespace from the string view
|
|
*
|
|
* @details Modifies the string view in place by advancing the internal text
|
|
* pointer and decreasing the length to skip any whitespace characters at the
|
|
* beginning.
|
|
*
|
|
* @param sv pointer to the StringView to trim.
|
|
*/
|
|
void sv_ltrim(StringView *sv);
|
|
|
|
/**
|
|
* @brief Trim trailing whitespace from the string view
|
|
*
|
|
* @details Modifies the string view in place by decreasing its length to remove
|
|
* any whitespace characters at the end.
|
|
*
|
|
* @param sv pointer to the StringView to trim.
|
|
*/
|
|
void sv_rtrim(StringView *sv);
|
|
|
|
/**
|
|
* @brief Trim leading and trailing whitespace from the string view
|
|
*
|
|
* @details Combines left and right trimming to remove all surrounding
|
|
* whitespace characters from the string view in place.
|
|
*
|
|
* @param sv pointer to the StringView to trim.
|
|
*/
|
|
void sv_trim(StringView *sv);
|
|
|
|
/**
|
|
* @brief Find the first occurrence of a character in the string view
|
|
*
|
|
* @details Searches sequentially through the bytes of the string view for the
|
|
* specified character.
|
|
*
|
|
* @param sv the StringView to search within (passed by value).
|
|
* @param c the character to look for.
|
|
*
|
|
* @return the index of the character if found, or -1 if the character is not
|
|
* present.
|
|
*/
|
|
int sv_index_of(StringView sv, char c);
|
|
|
|
/**
|
|
* @brief Split the string view at the first occurrence of a delimiter
|
|
*
|
|
* @details Modifies the original string view by advancing past the delimiter,
|
|
* and returns a new StringView representing the portion before the delimiter.
|
|
*
|
|
* @param sv pointer to the StringView to chop.
|
|
* @param delim the delimiter character used for splitting.
|
|
*
|
|
* @return a StringView containing the prefix up to the delimiter.
|
|
*/
|
|
StringView sv_chop_by_delim(StringView *sv, char delim);
|
|
|
|
/**
|
|
* @brief Chop the string view based on a custom character classification
|
|
* function
|
|
*
|
|
* @details Advances through the string view while the provided classification
|
|
* function returns true for characters, then modifies the original string view
|
|
* and returns the chopped prefix.
|
|
*
|
|
* @param sv pointer to the StringView to chop.
|
|
* @param checktype function pointer to classify characters (e.g., isspace,
|
|
* isdigit).
|
|
*
|
|
* @return a StringView representing the chopped portion matching the condition.
|
|
*/
|
|
StringView sv_chop_by_type(StringView *sv, int (*checktype)(int));
|
|
|
|
/**
|
|
* @brief Check if two string views are equal
|
|
*
|
|
* @details Compares the lengths and byte contents of two string views to
|
|
* determine if they are identical.
|
|
*
|
|
* @param sv1 pointer to the first StringView.
|
|
* @param sv2 pointer to the second StringView.
|
|
*
|
|
* @return true if both string views match in length and content, false
|
|
* otherwise.
|
|
*/
|
|
bool sv_equals(StringView *sv1, StringView *sv2);
|
|
|
|
/**
|
|
* @brief Check if a string view starts with a specific prefix
|
|
*
|
|
* @details Determines whether the given string view begins with the character
|
|
* sequence contained in the prefix string view.
|
|
*
|
|
* @param sv pointer to the main StringView.
|
|
* @param prefix pointer to the StringView representing the prefix to check.
|
|
*
|
|
* @return true if sv starts with prefix, false otherwise.
|
|
*/
|
|
bool sv_starts_with(StringView *sv, StringView *prefix);
|
|
|
|
/**
|
|
* @brief Check if a string view ends with a specific suffix
|
|
*
|
|
* @details Determines whether the given string view finishes with the character
|
|
* sequence contained in the suffix string view.
|
|
*
|
|
* @param sv pointer to the main StringView.
|
|
* @param suffix pointer to the StringView representing the suffix to check.
|
|
*
|
|
* @return true if sv ends with suffix, false otherwise.
|
|
*/
|
|
bool sv_ends_with(StringView *sv, StringView *suffix);
|
|
#endif
|