text.h File Reference

ASCII and UTF-8 text operations, the string builder and the string keys. More...

#include <algorithm>
#include <cstdarg>
#include <cstddef>
#include <cstring>
#include <filesystem>
#include <format>
#include <string>
#include <string.h>
#include <string_view>
#include <utility>
#include <variant>
#include <vector>
#include <rex/memory/endian.h>
#include <rex/platform.h>
#include <rex/types.h>
#include <strings.h>

Go to the source code of this file.

Classes
class	rex::string::StringBuffer
struct	rex::string::StringKey
struct	rex::string::StringKey::Hash
struct	rex::string::StringKeyIgnoreCase
struct	rex::string::StringKeyIgnoreCase::Hash
struct	std::hash< rex::string::StringKey >
struct	std::hash< rex::string::StringKeyIgnoreCase >

Namespaces
namespace	rex

Functions
i32	rex::string::CompareIgnoreCase (const char *string1, const char *string2)
i32	rex::string::CompareIgnoreCaseN (const char *string1, const char *string2, size_t count)
template<typename CharT>
std::basic_string_view< CharT >	rex::string::TrimLeft (std::basic_string_view< CharT > sv, std::basic_string_view< CharT > chars=kWhitespaceOf< CharT >)
template<typename CharT>
std::basic_string_view< CharT >	rex::string::TrimRight (std::basic_string_view< CharT > sv, std::basic_string_view< CharT > chars=kWhitespaceOf< CharT >)
template<typename CharT>
std::basic_string_view< CharT >	rex::string::Trim (std::basic_string_view< CharT > sv, std::basic_string_view< CharT > chars=kWhitespaceOf< CharT >)
std::string_view	rex::string::TrimLeft (std::string_view sv, std::string_view chars=kWhitespace)
std::string_view	rex::string::TrimRight (std::string_view sv, std::string_view chars=kWhitespace)
std::string_view	rex::string::Trim (std::string_view sv, std::string_view chars=kWhitespace)
std::string	rex::string::TrimString (std::string_view sv, std::string_view chars=kWhitespace)
char *	rex::string::Duplicate (const char *source)
size_t	rex::string::CopyTruncating (char *dest, const std::string_view source, size_t dest_buffer_count)
size_t	rex::string::CopyTruncating (char16_t *dest, const std::u16string_view source, size_t dest_buffer_count)
size_t	rex::string::CopyAndSwapTruncating (char16_t *dest, const std::u16string_view source, size_t dest_buffer_count)
size_t	rex::string::CopyUnterminated (char *dest, const std::string_view source, size_t dest_buffer_count)
std::string	rex::string::utf8_lower_ascii (const std::string_view view)
std::string	rex::string::utf8_upper_ascii (const std::string_view view)
size_t	rex::string::utf8_hash_fnv1a (const std::string_view view)
size_t	rex::string::utf8_hash_fnv1a_case (const std::string_view view)
std::vector< std::string_view >	rex::string::utf8_split (const std::string_view haystack, const std::string_view needles, bool remove_empty=false)
bool	rex::string::utf8_equal_z (const std::string_view left, const std::string_view right)
bool	rex::string::utf8_equal_case (const std::string_view left, const std::string_view right)
bool	rex::string::utf8_equal_case_z (const std::string_view left, const std::string_view right)
std::string_view::size_type	rex::string::utf8_find_any_of (const std::string_view haystack, const std::string_view needles)
std::string_view::size_type	rex::string::utf8_find_any_of_case (const std::string_view haystack, const std::string_view needles)
std::string_view::size_type	rex::string::utf8_find_first_of (const std::string_view haystack, const std::string_view needle)
std::string_view::size_type	rex::string::utf8_find_first_of_case (const std::string_view haystack, const std::string_view needle)
bool	rex::string::utf8_starts_with (const std::string_view haystack, const std::string_view needle)
bool	rex::string::utf8_starts_with_case (const std::string_view haystack, const std::string_view needle)
bool	rex::string::utf8_ends_with (const std::string_view haystack, const std::string_view needle)
bool	rex::string::utf8_ends_with_case (const std::string_view haystack, const std::string_view needle)
std::string	rex::string::ToUTF8 (const std::u16string_view source)
std::u16string	rex::string::ToUTF16 (const std::string_view source)
std::wstring	rex::string::ToWideString (const std::string_view source)
std::string	rex::string::ToUTF8 (const std::wstring_view source)
std::string	rex::string::ShiftJISToUTF8 (const std::string_view source)
std::string	rex::string::UTF8ToShiftJIS (const std::string_view source)
std::string	rex::string::PathToUTF8 (const std::filesystem::path &path)
std::u16string	rex::string::PathToUTF16 (const std::filesystem::path &path)
std::filesystem::path	rex::string::to_path (const std::string_view source)
std::filesystem::path	rex::string::to_path (const std::u16string_view source)
size_t	rex::string::utf8_count (const std::string_view view)

Variables
template<typename CharT>
constexpr std::basic_string_view< CharT >	rex::string::kWhitespaceOf {detail::kWhitespaceChars<CharT>, 4}
constexpr std::string_view	rex::string::kWhitespace = kWhitespaceOf<char>

Detailed Description

ASCII and UTF-8 text operations, the string builder and the string keys.

Copyright

Copyright (c) 2026 Tom Clay tomc@.nosp@m.tcte.nosp@m.chstu.nosp@m.ff.c.nosp@m.om All rights reserved.

License

BSD 3-Clause License See LICENSE file in the project root for full license text.

Remarks

Derived from Xenia's xenia/base/string.h, xenia/base/utf8.h, xenia/base/string_buffer.h and xenia/base/string_key.h (Ben Vanik, 2020).

Function Documentation

CompareIgnoreCase()

i32 rex::string::CompareIgnoreCase ( const char * string1, const char * string2 )

inline

Compares two NUL terminated strings, ignoring ASCII case.

Returns

Negative, 0 or positive as string1 orders before, equal to or after string2.

CompareIgnoreCaseN()

i32 rex::string::CompareIgnoreCaseN ( const char * string1, const char * string2, size_t count )

inline

Compares up to count characters of two strings, ignoring ASCII case.

Parameters

count

Maximum number of characters to compare.

Returns

Negative, 0 or positive as string1 orders before, equal to or after string2.

CopyAndSwapTruncating()

size_t rex::string::CopyAndSwapTruncating ( char16_t * dest, const std::u16string_view source, size_t dest_buffer_count )

inline

Copies a UTF-16 string into a fixed buffer, byte swapping each code unit.

Parameters

dest_buffer_count

Size of dest in code units, including the terminator.

Returns

Code units copied, not counting the terminator.

CopyTruncating() [1/2]

size_t rex::string::CopyTruncating ( char * dest, const std::string_view source, size_t dest_buffer_count )

inline

Copies a string into a fixed buffer, truncating to fit, and NUL terminates it.

Parameters

dest_buffer_count

Size of dest in characters, including the terminator.

Returns

Characters copied, not counting the terminator.

CopyTruncating() [2/2]

size_t rex::string::CopyTruncating ( char16_t * dest, const std::u16string_view source, size_t dest_buffer_count )

inline

Copies a UTF-16 string into a fixed buffer, truncating to fit, and NUL terminates it.

Parameters

dest_buffer_count

Size of dest in code units, including the terminator.

Returns

Code units copied, not counting the terminator.

CopyUnterminated()

size_t rex::string::CopyUnterminated ( char * dest, const std::string_view source, size_t dest_buffer_count )

inline

Copies a string into a fixed buffer, truncating to fit, without a terminator.

Parameters

dest_buffer_count

Size of dest in characters.

Returns

Characters copied.

Duplicate()

char * rex::string::Duplicate ( const char * source )

inline

Copies a NUL terminated string to the heap.

Returns

The copy. The caller frees it with free.

PathToUTF16()

std::u16string rex::string::PathToUTF16

(

const std::filesystem::path &

path

)

Converts a host path to UTF-16.

Returns

The path as UTF-16 text.

PathToUTF8()

std::string rex::string::PathToUTF8

(

const std::filesystem::path &

path

)

Converts a host path to UTF-8.

Returns

The path as UTF-8 text.

ShiftJISToUTF8()

std::string rex::string::ShiftJISToUTF8

(

const std::string_view

source

)

Converts Shift-JIS (code page 932) to UTF-8. Returns the input unchanged without the platform converter.

Parameters

source

Shift-JIS text.

Returns

The UTF-8 text.

to_path() [1/2]

std::filesystem::path rex::string::to_path

(

const std::string_view

source

)

Builds a host path from UTF-8 text.

Parameters

source

UTF-8 path text.

to_path() [2/2]

std::filesystem::path rex::string::to_path

(

const std::u16string_view

source

)

Builds a host path from UTF-16 text.

Parameters

source

UTF-16 path text.

ToUTF16()

std::u16string rex::string::ToUTF16

(

const std::string_view

source

)

Converts UTF-8 to UTF-16.

Parameters

source

UTF-8 text.

Returns

The UTF-16 text.

ToUTF8() [1/2]

std::string rex::string::ToUTF8

(

const std::u16string_view

source

)

Converts UTF-16 to UTF-8.

Parameters

source

UTF-16 text.

Returns

The UTF-8 text.

ToUTF8() [2/2]

std::string rex::string::ToUTF8

(

const std::wstring_view

source

)

Converts the host wide string, UTF-16 or UTF-32 by wchar_t size, to UTF-8. Invalid code units become U+FFFD.

Returns

The UTF-8 text.

ToWideString()

std::wstring rex::string::ToWideString

(

const std::string_view

source

)

Converts UTF-8 to the host wide string, UTF-16 or UTF-32 by wchar_t size. Invalid UTF-8 becomes U+FFFD.

Parameters

source

UTF-8 text.

Trim() [1/2]

template<typename CharT>

std::basic_string_view< CharT > rex::string::Trim ( std::basic_string_view< CharT > sv, std::basic_string_view< CharT > chars = kWhitespaceOf<CharT> )

inline

Removes leading and trailing characters.

Returns

View of sv without the leading and trailing characters.

Trim() [2/2]

std::string_view rex::string::Trim ( std::string_view sv, std::string_view chars = kWhitespace )

inline

Removes leading and trailing characters.

Returns

View of sv without the leading and trailing characters.

TrimLeft() [1/2]

template<typename CharT>

std::basic_string_view< CharT > rex::string::TrimLeft ( std::basic_string_view< CharT > sv, std::basic_string_view< CharT > chars = kWhitespaceOf<CharT> )

inline

Removes leading characters.

Returns

View of sv without the leading characters, empty when every character matches.

TrimLeft() [2/2]

std::string_view rex::string::TrimLeft ( std::string_view sv, std::string_view chars = kWhitespace )

inline

Removes leading characters.

Returns

View of sv without the leading characters, empty when every character matches.

TrimRight() [1/2]

template<typename CharT>

std::basic_string_view< CharT > rex::string::TrimRight ( std::basic_string_view< CharT > sv, std::basic_string_view< CharT > chars = kWhitespaceOf<CharT> )

inline

Removes trailing characters.

Returns

View of sv without the trailing characters, empty when every character matches.

TrimRight() [2/2]

std::string_view rex::string::TrimRight ( std::string_view sv, std::string_view chars = kWhitespace )

inline

Removes trailing characters.

Returns

View of sv without the trailing characters, empty when every character matches.

TrimString()

std::string rex::string::TrimString ( std::string_view sv, std::string_view chars = kWhitespace )

inline

Removes leading and trailing characters into a new string.

Returns

Copy of sv without the leading and trailing characters.

utf8_count()

size_t rex::string::utf8_count

(

const std::string_view

view

)

Counts code points.

Parameters

view	UTF-8 text.

Returns

Number of code points.

utf8_ends_with()

bool rex::string::utf8_ends_with	(	const std::string_view	haystack,
		const std::string_view	needle )

Reports whether a string ends with a suffix.

Returns

True when haystack ends with needle or needle is empty.

utf8_ends_with_case()

bool rex::string::utf8_ends_with_case	(	const std::string_view	haystack,
		const std::string_view	needle )

Reports whether a string ends with a suffix, ignoring ASCII case.

Returns

True when haystack ends with needle or needle is empty.

utf8_equal_case_z()

bool rex::string::utf8_equal_case_z	(	const std::string_view	left,
		const std::string_view	right )

Reports whether two strings match up to the first NUL in each, ignoring ASCII case.

Returns

True when the strings match up to their terminators.

utf8_equal_z()

bool rex::string::utf8_equal_z	(	const std::string_view	left,
		const std::string_view	right )

Reports whether two strings match up to the first NUL in each.

Returns

True when the strings match up to their terminators.

utf8_find_any_of()

std::string_view::size_type rex::string::utf8_find_any_of	(	const std::string_view	haystack,
		const std::string_view	needles )

Finds the first code point that matches any of a set.

Returns

Byte offset of the match, 0 when needles is empty, or npos when nothing matches.

utf8_find_any_of_case()

std::string_view::size_type rex::string::utf8_find_any_of_case	(	const std::string_view	haystack,
		const std::string_view	needles )

Finds the first code point that matches any of a set, ignoring ASCII case.

Returns

Byte offset of the match, 0 when needles is empty, or npos when nothing matches.

utf8_find_first_of()

std::string_view::size_type rex::string::utf8_find_first_of	(	const std::string_view	haystack,
		const std::string_view	needle )

Finds the first occurrence of a substring.

Returns

Byte offset of the match, 0 when needle is empty, or npos when nothing matches.

utf8_find_first_of_case()

std::string_view::size_type rex::string::utf8_find_first_of_case	(	const std::string_view	haystack,
		const std::string_view	needle )

Finds the first occurrence of a substring, ignoring ASCII case.

Returns

Byte offset of the match, 0 when needle is empty, or npos when nothing matches.

utf8_hash_fnv1a()

size_t rex::string::utf8_hash_fnv1a

(

const std::string_view

view

)

Hashes the code points of a string with FNV-1a.

Parameters

view	UTF-8 text.

utf8_hash_fnv1a_case()

size_t rex::string::utf8_hash_fnv1a_case

(

const std::string_view

view

)

Hashes the code points of a string with FNV-1a, with ASCII letters lowercased first.

Parameters

view	UTF-8 text.

utf8_lower_ascii()

std::string rex::string::utf8_lower_ascii

(

const std::string_view

view

)

Lowercases the ASCII letters of a string. Other code points pass through.

Parameters

view	UTF-8 text.

utf8_split()

std::vector< std::string_view > rex::string::utf8_split	(	const std::string_view	haystack,
		const std::string_view	needles,
		bool	remove_empty = false )

Splits a string on any of a set of delimiter code points.

Parameters

needles	Delimiter code points.
remove_empty	True to omit empty parts between adjacent delimiters.

Returns

Views of the parts, in order.

utf8_starts_with()

bool rex::string::utf8_starts_with	(	const std::string_view	haystack,
		const std::string_view	needle )

Reports whether a string starts with a prefix.

Returns

True when haystack starts with needle or needle is empty.

utf8_starts_with_case()

bool rex::string::utf8_starts_with_case	(	const std::string_view	haystack,
		const std::string_view	needle )

Reports whether a string starts with a prefix, ignoring ASCII case.

Returns

True when haystack starts with needle or needle is empty.

utf8_upper_ascii()

std::string rex::string::utf8_upper_ascii

(

const std::string_view

view

)

Uppercases the ASCII letters of a string.

Parameters

view	UTF-8 text.

UTF8ToShiftJIS()

std::string rex::string::UTF8ToShiftJIS

(

const std::string_view

source

)

Converts UTF-8 to Shift-JIS (code page 932). Unrepresentable characters become '?'. Returns the input unchanged without the platform converter.

Parameters

source

UTF-8 text.

Returns

The Shift-JIS text.

Variable Documentation

kWhitespace

std::string_view rex::string::kWhitespace = kWhitespaceOf<char>

inlineconstexpr

Characters the trim functions remove by default.

kWhitespaceOf

template<typename CharT>

std::basic_string_view<CharT> rex::string::kWhitespaceOf {detail::kWhitespaceChars<CharT>, 4}

inlineconstexpr

The characters the trim functions remove by default, as a view of the character type.