#ifndef STRING_VIEW_H #define STRING_VIEW_H #include #include /** * @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