Description:

This is the reference documentation of sub-namespace characters of the ALib C++ Library, which holds types of library module ALib Characters.

Extensive documentation for this module is provided with ALib Module Characters - Programmer's Manual.

Nested Namespaces:
namespace	compatibility

Type Index:
struct	AlignedCharArray

struct	ArrayTraits

struct	ZTArrayTraits

Concepts
concept	IsArray

concept	IsZTArray

concept	IsImplicitArraySource

concept	IsExplicitArraySource

concept	IsMutableArraySource

concept	IsImplicitArrayCast

concept	IsExplicitArrayCast

concept	IsImplicitZTArraySource

concept	IsExplicitZTArraySource

concept	IsMutableZTArraySource

concept	IsImplicitZTArrayCast

concept	IsExplicitZTArrayCast

concept	IsCharacter

Type Definition Index:
using	character = PLATFORM_SPECIFIC

using	complementChar = PLATFORM_SPECIFIC

template<typename TChar>
using	ComplementType

using	nchar = char

using	strangeChar = PLATFORM_SPECIFIC

template<typename T>
using	Type

template<size_t TSizeOf>
using	TypeBySize

using	wchar = PLATFORM_SPECIFIC

using	xchar = PLATFORM_SPECIFIC

template<typename T>
using	ZTType

Enumeration Index:
enum class	Policy { NONE , Implicit , ExplicitOnly , MutableOnly }

Function Index:
template<typename T>
constexpr integer	ArrayLength ()

template<typename TChar>
int	Compare (const TChar lhs, const TChar rhs, integer cmpLength)

template<typename TChar>
int	CompareIgnoreCase (const TChar lhs, const TChar rhs, integer cmpLength)

template<typename TChar>
void	Copy (const TChar src, integer length, TChar dest)

template<typename TChar>
bool	Equal (const TChar lhs, const TChar rhs, integer cmpLength)

template<typename TChar, lang::Case sensitivity, typename TRhs>
bool	Equal (TChar lhs, TRhs rhs)

template<typename TChar>
void	Fill (TChar *dest, integer length, TChar value)

template<typename TChar>
integer	IndexOfAnyExcluded (const TChar haystack, integer haystackLength, const TChar needles, integer needlesLength)

template<typename TChar>
integer	IndexOfAnyExcludedZT (const TChar haystack, const TChar needles)

template<typename TChar>
integer	IndexOfAnyIncluded (const TChar haystack, integer haystackLength, const TChar needles, integer needlesLength)

template<typename TChar>
integer	IndexOfAnyIncludedZT (const TChar haystack, const TChar needles)

template<typename TChar>
integer	IndexOfFirstDifference (const TChar haystack, integer haystackLength, const TChar needle, integer needleLength, lang::Case sensitivity)

template<typename TChar>
integer	LastIndexOfAnyExclude (const TChar haystack, integer startIdx, const TChar needles, integer needlesLength)

template<typename TChar>
integer	LastIndexOfAnyInclude (const TChar haystack, integer startIdx, const TChar needles, integer needlesLength)

template<typename TChar>
integer	Length (const TChar *cstring)

template<typename TChar>
void	Move (const TChar src, integer length, TChar dest)

template<typename TChar>
void	Reverse (TChar *src, integer length)

template<typename TChar>
const TChar *	Search (const TChar *haystack, integer haystackLength, TChar needle)

template<typename TChar>
void	ToLower (TChar *src, integer length)

template<typename TChar>
TChar	ToLower (TChar c)

template<typename TChar>
void	ToUpper (TChar *src, integer length)

template<typename TChar>
TChar	ToUpper (TChar c)

Type Definition Details:

◆ character

using alib::characters::character = PLATFORM_SPECIFIC

This type represents a standard ALib character. The width (size) of a character is dependent on the platform and compilation flags.

This is why this type is called a "logical" type. The two other logical character types are complementChar and strangeChar.

See also: For details, see chapter 2. Character Types of the Programmer's Manual of module ALib Characters.

Definition at line 91 of file chartypes.inl.

◆ complementChar

using alib::characters::complementChar = PLATFORM_SPECIFIC

This type represents a non-standard ALib character. If alib::character is defined to implement a narrow character type, then this type implements a wide character and vice versa. Note, that the width of a wide character is not defined as well. It might be 2 or 4 bytes wide.

This type is called a "logical" type. The two other logical character types are character and strangeChar.

See also: For details, see chapter 2. Character Types of the Programmer's Manual of module ALib Characters.

Definition at line 105 of file chartypes.inl.

◆ ComplementType

template<typename TChar>

using alib::characters::ComplementType

Initial value:

std::conditional_t<std::same_as<TChar, nchar>, wchar,

std::conditional_t<std::same_as<TChar, wchar>, nchar, void > >

alib::characters::wchar

PLATFORM_SPECIFIC wchar

Definition chartypes.inl:38

alib::characters::nchar

char nchar

Definition chartypes.inl:20

This templated alias type-definition provides the "complement" to the given character type. By that, it is defined to wchar if type nchar is given and vice versa.

Note that for type xchar, no complement is defined. For this type (and all other types), this alias evaluates to void.

Template Parameters

TChar The character type to get the complement for.

Definition at line 501 of file chartraits.inl.

◆ nchar

using alib::characters::nchar = char

This type represents a narrow character in ALib. This is an alias for built-in C++ type char.

See also: For details, see chapter 2. Character Types of the Programmer's Manual of module ALib Characters.

Definition at line 20 of file chartypes.inl.

◆ strangeChar

using alib::characters::strangeChar = PLATFORM_SPECIFIC

Besides types alib::character and alib::complementChar, this is the third logical character type defined by ALib.
independent of compiler defaults and optional the compiler-symbols provided, this type always is equivalent to type xchar

See also: For details, see chapter 2. Character Types of the Programmer's Manual of module ALib Characters.

Definition at line 115 of file chartypes.inl.

◆ Type

template<typename T>

using alib::characters::Type

Initial value:

 std::conditional_t<ArrayTraits<T,nchar>::Access != Policy::NONE, nchar,
             std::conditional_t<ArrayTraits<T,wchar>::Access != Policy::NONE, wchar,
             std::conditional_t<ArrayTraits<T,xchar>::Access != Policy::NONE, xchar,
                                                                              void   > > >

Determines the character type of the array that the given template type T represents. In case no a specialization of the type trait ArrayTraits<T, TChar> exists, this evaluates to void. Otherwise, this alias evaluates to one of nchar, wchar or xchar.

See also

For details see chapter 4.6 Type Aliases Type and ZTType of the Programmer's Manual of module ALib Characters.
Concept IsArray.
A sibling alias exists with ZTType.

Template Parameters

T	The custom type to get the character type for.

Definition at line 211 of file chartraits.inl.

◆ TypeBySize

template<size_t TSizeOf>

using alib::characters::TypeBySize

Initial value:

 std::conditional_t<TSizeOf == sizeof(nchar), nchar,
                   std::conditional_t<TSizeOf == sizeof(wchar), wchar,
                   std::conditional_t<TSizeOf == sizeof(xchar), xchar, void   > > >

This templated type alias can be used to determine the corresponding ALib character type from the size of the type. Typically (on common 64-bit platforms), this alias evaluates to: nchar if TSizeOf is given as 0. Values 2 and 4 evaluate to wchar or xchar depending on the compiler and platform.

As an example, the QT Class Library uses a 2-byte character width, independent of compiler and platform. Therefore, to convert a QT character value to an ALib character value, the destination type is:

     using qtChar= alib::characters::TypeBySize<2>;

Template Parameters

TSizeOf The size of the required character type in bytes.

Definition at line 520 of file chartraits.inl.

◆ wchar

using alib::characters::wchar = PLATFORM_SPECIFIC

This type represents a wide character in ALib. Usually this is an alias for built-in C++ type wchar_t. As the width of the latter is compiler-specific (the width may vary with different compilers even on the same platform), the compiler-symbol ALIB_CHARACTERS_SIZEOF_WCHAR may be used to manipulate its width.

See also: For details, see chapter 2. Character Types of the Programmer's Manual of module ALib Characters.

Definition at line 38 of file chartypes.inl.

◆ xchar

using alib::characters::xchar = PLATFORM_SPECIFIC

This type represents a second wide character type which has a width complementary to that of type wchar: If wchar is 2 bytes wide, then this type aliases char32_t and if its width is 4 bytes, this type aliases char16_t.

While together with types alib::nchar and alib::wchar it forms the group of "explicit character types", it is always identical to logical type alib::strangeChar.

See also: For details, see chapter 2. Character Types of the Programmer's Manual of module ALib Characters.

Definition at line 51 of file chartypes.inl.

◆ ZTType

template<typename T>

using alib::characters::ZTType

Initial value:

 std::conditional_t<ZTArrayTraits<T,nchar>::Access != Policy::NONE, nchar,
               std::conditional_t<ZTArrayTraits<T,wchar>::Access != Policy::NONE, wchar,
               std::conditional_t<ZTArrayTraits<T,xchar>::Access != Policy::NONE, xchar,
                                                                                  void  > > >

Determines the character type of the zero-terminated array that the given template type T represents. In case no a specialization of the type trait ZTArrayTraits<T, TChar> exists, this evaluates to void. Otherwise, this alias evaluates to one of nchar, wchar or xchar.

See also

For details see chapter 4.6 Type Aliases Type and ZTType of the Programmer's Manual of module ALib Characters.
Concept IsArray.
A sibling alias exists with ZTType.

Template Parameters

T	The custom type to get the character type for.

Definition at line 248 of file chartraits.inl.

Enumeration Details:

◆ Policy

enum class alib::characters::Policy

strong

Enumeration of possible values for fields Access and Construction of traits-types ArrayTraits and ZTArrayTraits. The elements of this enumeration indicate if and how the data of a "char-array-like type" (which may be non-zero- or zero-terminated) may be accessed and, reversely, how such types may be constructed from character arrays.

This is best explained when looking at class TString of higher-level module ALib Strings. That classes' constructors use this policy to decide if an instance it may be constructed implicitly or explicitly from a third-party type. In the other direction, the type provides cast methods, which let instances of TString implicitly or explicitly convert into third-party types.

Enumerator
NONE	Data may not be received, respectively the custom type may not be constructed from a (character-array-) type. This value usually indicates that a custom type does not represent a character array at all. Hence, this is the default value exposed by the non-specialized version of type-traits structs ArrayTraits and ZTArrayTraits.
Implicit	Allows implicit (and explicit) access of the character array data, respectively allows implicit and explicit construction of string-like custom types, from mutable or constant objects.
ExplicitOnly	Allows explicit access of the character array data respectively allows explicit construction of string-like custom types, from mutable or constant objects.
MutableOnly	Allows explicit access of the character array data from mutable objects only. With field Construction of traits-types ArrayTraits and ZTArrayTraits, this enumeration element is not used.

Definition at line 22 of file chartraits.inl.

Function Details:

◆ ArrayLength()

template<typename T>

integer alib::characters::ArrayLength ( )

constexpr

Returns the length of C++ arrays like std::extent, but subtracts 1 if the array's element-type satisfies concept IsCharacter. (Thus, this "removes" the zero-termination character.)

Template Parameters

T	The type to get the length for. Deduced by the compiler.

Returns: In case of character-arrays, the string length. For other arrays the true length and 0 for non-array types.

Definition at line 547 of file chartraits.inl.

◆ Compare()

template<typename TChar>

int alib::characters::Compare	(	const TChar *	lhs,
		const TChar *	rhs,
		integer	cmpLength )

Compares up to cmpLength characters of two character arrays. Comparison stops if termination character '\0' is found in one of the arrays.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

lhs	The first array to compare.
rhs	The second array to compare.
cmpLength	The number of characters to compare.

Returns: Negative value if lhs appears before rhs in lexicographical order. 0 if lhs and rhs are equal. Positive value if lhs appears after rhs in lexicographical order.

Definition at line 348 of file functions.inl.

◆ CompareIgnoreCase()

template<typename TChar>

int alib::characters::CompareIgnoreCase	(	const TChar *	lhs,
		const TChar *	rhs,
		integer	cmpLength )

Compares two character arrays of equal length ignoring letter case.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

lhs	The first array to compare.
rhs	The second array to compare.
cmpLength	The number of characters to compare.

Returns: Negative value if lhs appears before rhs in lexicographical order. 0 if lhs and rhs are equal. Positive value if lhs appears after rhs in lexicographical order.

◆ Copy()

template<typename TChar>

void alib::characters::Copy	(	const TChar *	src,
		integer	length,
		TChar *	dest )

Copies the contents of a character array into another, non-overlapping (!) array.

Note: This method is implemented as an inlined, direct direct call to std::char_traits::copy.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

src	Pointer to the source array.
length	The length to copy.
dest	Pointer to the destination array.

Definition at line 108 of file functions.inl.

◆ Equal() [1/2]

template<typename TChar>

bool alib::characters::Equal	(	const TChar *	lhs,
		const TChar *	rhs,
		integer	cmpLength )

Searches for a difference in two character arrays of equal length.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

lhs	The first array to compare.
rhs	The second array to compare.
cmpLength	The number of characters to compare.

Returns: true if the string arrays have identical contents, false otherwise.

Definition at line 329 of file functions.inl.

◆ Equal() [2/2]

template<typename TChar, lang::Case sensitivity, typename TRhs>

bool alib::characters::Equal	(	TChar	lhs,
		TRhs	rhs )

Compares two characters of arbitrary types.

Template Parameters

TChar	One of the six (overlapping) character types.
sensitivity	Letter case sensitivity of the comparison.
TRhs	The type of the right hand side letter to compare.

Parameters

lhs	The left-hand side character to compare of class template type TChar.
rhs	The right-hand side character to compare of method template type TCharRhs .

Returns: true if the given characters are equal, false otherwise.

Definition at line 62 of file functions.inl.

Here is the call graph for this function:

◆ Fill()

template<typename TChar>

void alib::characters::Fill	(	TChar *	dest,
		integer	length,
		TChar	value )

Sets all elements of the given character array to value value.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

dest	Pointer to the destination array.
length	The length to fill.
value	The value to fill the array with.

◆ IndexOfAnyExcluded()

template<typename TChar>

integer alib::characters::IndexOfAnyExcluded	(	const TChar *	haystack,
		integer	haystackLength,
		const TChar *	needles,
		integer	needlesLength )

Returns the index of the first character in haystack which is not included in a given set of needles.

This method searches up to a given maximum index. For a search to the end of the zero-terminated string, use the faster method provided with class CString.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

haystack	Pointer to the start of the string.
haystackLength	The length of the string or the maximum position to search. If -1 is provided, the length is determined using standard library function strlen (which needs haystack to be zero-terminated).
needles	Pointer to a set of characters to be searched for.
needlesLength	The length of the string of needles. If -1 is provided, the length is determined using standard library function strlen (which needs needles to be zero-terminated).

Returns: The index of the first character that is not included in needles. If all characters of haystack are included in needles, -1 is returned.

◆ IndexOfAnyExcludedZT()

template<typename TChar>

integer alib::characters::IndexOfAnyExcludedZT	(	const TChar *	haystack,
		const TChar *	needles )

Same as IndexOfAnyExcluded(const TChar*,integer,const TChar*,integer) but works on zero-terminated strings.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

haystack	Pointer to a zero-terminated character array to search in.
needles	Pointer to a zero-terminated set of characters to search for.

Returns: The index of the first character that is not included in needles. If all characters of haystack are included in needles, -1 is returned.

◆ IndexOfAnyIncluded()

template<typename TChar>

integer alib::characters::IndexOfAnyIncluded	(	const TChar *	haystack,
		integer	haystackLength,
		const TChar *	needles,
		integer	needlesLength )

Returns the index of the first character in haystack which is included in a given set of needles.

This method searches up to a given maximum index. For a search to the end of the zero-terminated string, use faster method provided with class CString.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

haystack	Pointer to the start of the string.
haystackLength	The length of the string or the maximum position to search. If -1 is provided, the length is determined using standard library function strlen (which needs haystack to be zero-terminated).
needles	Pointer to a set of characters to be searched for.
needlesLength	The length of the string of needles. If -1 is provided, the length is determined using standard library function strlen (which needs needles to be zero-terminated).

Returns: The index of the first character found that is included in needles. If no character of haystack is included in needles, -1 is returned.

◆ IndexOfAnyIncludedZT()

template<typename TChar>

integer alib::characters::IndexOfAnyIncludedZT	(	const TChar *	haystack,
		const TChar *	needles )

Same as IndexOfAnyIncluded(const TChar*,integer,const TChar*,integer) but works on zero-terminated strings.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

haystack	Pointer to a zero-terminated character array to search in.
needles	Pointer to a zero-terminated set of characters to search for.

Returns: The index of the first character found that is included in needles. If no character of haystack is included in needles, -1 is returned.

◆ IndexOfFirstDifference()

template<typename TChar>

integer alib::characters::IndexOfFirstDifference	(	const TChar *	haystack,
		integer	haystackLength,
		const TChar *	needle,
		integer	needleLength,
		lang::Case	sensitivity )

Returns the index of the first character which is not equal within two strings. If haystack starts with needle, then the length of needle is returned.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

haystack	Pointer to the start of the string.
haystackLength	The length of the string or the maximum position to search. If -1 is provided, the length is determined using standard library function strlen (which needs haystack to be zero-terminated).
needle	Pointer to the start of the string to compare with.
needleLength	The length of needle. If -1 is provided, the length is determined using standard library function strlen (which needs needles to be zero-terminated).
sensitivity	Denotes whether the comparison should be made case-sensitive or not.

Returns: The index of the first character found which is not equal in given strings.

◆ LastIndexOfAnyExclude()

template<typename TChar>

integer alib::characters::LastIndexOfAnyExclude	(	const TChar *	haystack,
		integer	startIdx,
		const TChar *	needles,
		integer	needlesLength )

Returns the index of the last character in haystack which is not included in a given set of needles.

This method searches backwards from the end of the string.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

haystack	Pointer to the start of the string.
startIdx	The position to start the search from. This must be smaller than the length of the string and greater or equal to zero.
needles	Pointer to a set of characters to be searched for.
needlesLength	The length of the string of needles. If -1 is provided, the length is determined using standard library function strlen (which needs needles to be zero-terminated).

Returns: The index of the first character found which is included in the given set of characters. If nothing is found, -1 is returned.

◆ LastIndexOfAnyInclude()

template<typename TChar>

integer alib::characters::LastIndexOfAnyInclude	(	const TChar *	haystack,
		integer	startIdx,
		const TChar *	needles,
		integer	needlesLength )

Returns the index of the last character in haystack which is included in a given set of needles.

This method searches backwards from the end of the string.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

haystack	Pointer to the start of the string.
startIdx	The position to start the search from. This must be smaller than the length of the string and greater or equal to zero.
needles	Pointer to a set of characters to be searched for.
needlesLength	The length of the string of needles. If -1 is provided, the length is determined using standard library function strlen (which needs needles to be zero-terminated).

Returns: The index of the first character found which is included in the given set of characters. If nothing is found, -1 is returned.

◆ Length()

template<typename TChar>

integer alib::characters::Length ( const TChar * cstring )

Returns the length of a zero-terminated "c-style" character array.

Note: This method is implemented as an inlined, direct direct call to std::char_traits::length.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

cstring Pointer to a zero-terminated character array.

Returns: The length of the string.

Definition at line 91 of file functions.inl.

◆ Move()

template<typename TChar>

void alib::characters::Move	(	const TChar *	src,
		integer	length,
		TChar *	dest )

Copies the contents of a character array into another, possibly overlapping array.

Note: This method is implemented as an inlined, direct direct call to std::char_traits::move.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

src	Pointer to the source array.
length	The length to copy.
dest	Pointer to the destination array, optionally within source.

Definition at line 125 of file functions.inl.

◆ Reverse()

template<typename TChar>

void alib::characters::Reverse	(	TChar *	src,
		integer	length )

Reverses the order of the characters.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

src	Pointer to the character array.
length	The length of the array.

◆ Search()

template<typename TChar>

const TChar * alib::characters::Search	(	const TChar *	haystack,
		integer	haystackLength,
		TChar	needle )

Searches the character. Returns a pointer to the location of needle in haystack, respectively nullptr if not found.

Note: This method is implemented as a direct call to std::memchr, respectively other character versions of it.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

haystack	Pointer to the start of the string.
haystackLength	The length of the string or the maximum position to search.
needle	Character to search.

Returns: The pointer to the first occurrence of needle respectively nullptr if not found.

Definition at line 167 of file functions.inl.

◆ ToLower() [1/2]

template<typename TChar>

void alib::characters::ToLower	(	TChar *	src,
		integer	length )

Converts a character sequence to lower case.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

src	Pointer to the character array.
length	The length of the array.

◆ ToLower() [2/2]

template<typename TChar>

TChar alib::characters::ToLower ( TChar c )

Converts a character to lower case.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

c	The character to convert

Returns: The lower case version of the given character.

◆ ToUpper() [1/2]

template<typename TChar>

void alib::characters::ToUpper	(	TChar *	src,
		integer	length )

Converts a character sequence to upper case.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

src	Pointer to the character array.
length	The length of the array.

◆ ToUpper() [2/2]

template<typename TChar>

TChar alib::characters::ToUpper ( TChar c )

Converts a character to upper case.

Template Parameters

TChar One of the six (overlapping) character types.

Parameters

c	The character to convert

Returns: The upper case version of the given character.

Description:

Nested Namespaces:

Type Index:

Concepts

Type Definition Index:

Enumeration Index:

Function Index:

Type Definition Details:

◆ character

◆ complementChar

◆ ComplementType

◆ nchar

◆ strangeChar

◆ Type

◆ TypeBySize

◆ wchar

◆ xchar

◆ ZTType

Enumeration Details:

◆ Policy

Function Details:

◆ ArrayLength()

◆ Compare()

◆ CompareIgnoreCase()

◆ Copy()

◆ Equal() [1/2]

◆ Equal() [2/2]

◆ Fill()

◆ IndexOfAnyExcluded()

◆ IndexOfAnyExcludedZT()

◆ IndexOfAnyIncluded()

◆ IndexOfAnyIncludedZT()

◆ IndexOfFirstDifference()

◆ LastIndexOfAnyExclude()

◆ LastIndexOfAnyInclude()

◆ Length()

◆ Move()

◆ Reverse()

◆ Search()

◆ ToLower() [1/2]

◆ ToLower() [2/2]

◆ ToUpper() [1/2]

◆ ToUpper() [2/2]