Functions related to low-level strings. More...

#include <iosfwd>
#include "core/bitmath_func.hpp"
#include "string_type.h"

Data Structures
struct	CaseInsensitiveComparator
	Case insensitive comparator for strings, for example for use in std::map. More...

Functions
void	strecpy (std::span< char > dst, std::string_view src)
	Copies characters from one buffer to another.

std::string	FormatArrayAsHex (std::span< const uint8_t > data)
	Format a byte array into a continuous hex string.

void	StrMakeValidInPlace (char *str, StringValidationSettings settings=StringValidationSetting::ReplaceWithQuestionMark)
	Scans the string for invalid characters and replaces them with a question mark '?' (if not ignored).

void	StrMakeValidInPlace (std::string &str, StringValidationSettings settings=StringValidationSetting::ReplaceWithQuestionMark)
	Scans the string for invalid characters and replaces them with a question mark '?' (if not ignored).

std::string	StrMakeValid (std::string_view str, StringValidationSettings settings=StringValidationSetting::ReplaceWithQuestionMark)
	Copies the valid (UTF-8) characters from `str` to the returned string.

std::string	StrMakeValid (const char *str, StringValidationSettings settings=StringValidationSetting::ReplaceWithQuestionMark)

std::string	StrMakeValid (std::string &&str, StringValidationSettings settings=StringValidationSetting::ReplaceWithQuestionMark)

bool	strtolower (std::string &str, std::string::size_type offs=0)

bool	StrValid (std::span< const char > str)
	Checks whether the given string is valid, i.e.

void	StrTrimInPlace (std::string &str)
	Trim the spaces from given string in place, i.e.

std::string_view	StrTrimView (std::string_view str)

bool	StrStartsWithIgnoreCase (std::string_view str, const std::string_view prefix)
	Check whether the given string starts with the given prefix, ignoring case.

bool	StrEndsWithIgnoreCase (std::string_view str, const std::string_view suffix)
	Check whether the given string ends with the given suffix, ignoring case.

int	StrCompareIgnoreCase (const std::string_view str1, const std::string_view str2)
	Compares two string( view)s, while ignoring the case of the characters.

bool	StrEqualsIgnoreCase (const std::string_view str1, const std::string_view str2)
	Compares two string( view)s for equality, while ignoring the case of the characters.

bool	StrContainsIgnoreCase (const std::string_view str, const std::string_view value)
	Checks if a string is contained in another string, while ignoring the case of the characters.

int	StrNaturalCompare (std::string_view s1, std::string_view s2, bool ignore_garbage_at_front=false)
	Compares two strings using case insensitive natural sort.

bool	StrNaturalContains (const std::string_view str, const std::string_view value)
	Checks if a string is contained in another string with a locale-aware comparison that is case sensitive.

bool	StrNaturalContainsIgnoreCase (const std::string_view str, const std::string_view value)
	Checks if a string is contained in another string with a locale-aware comparison that is case insensitive.

bool	ConvertHexToBytes (std::string_view hex, std::span< uint8_t > bytes)
	Convert a hex-string to a byte-array, while validating it was actually hex.

bool	StrEmpty (const char *s)
	Check if a string buffer is empty.

bool	IsValidChar (char32_t key, CharSetFilter afilter)
	Only allow certain keys.

size_t	Utf8StringLength (std::string_view str)
	Get the length of an UTF-8 encoded string in number of characters and thus not the number of bytes that the encoded string contains.

bool	Utf16IsLeadSurrogate (uint c)
	Is the given character a lead surrogate code point?

bool	Utf16IsTrailSurrogate (uint c)
	Is the given character a lead surrogate code point?

char32_t	Utf16DecodeSurrogate (uint lead, uint trail)
	Convert an UTF-16 surrogate pair to the corresponding Unicode character.

char32_t	Utf16DecodeChar (const uint16_t *c)
	Decode an UTF-16 character.

bool	IsTextDirectionChar (char32_t c)
	Is the given character a text direction character.

bool	IsPrintable (char32_t c)

bool	IsWhitespace (char32_t c)
	Check whether UNICODE character is whitespace or not, i.e.

Detailed Description

Functions related to low-level strings.

Definition in file string_func.h.

Function Documentation

◆ ConvertHexToBytes()

bool ConvertHexToBytes	(	std::string_view	hex,
		std::span< uint8_t >	bytes
	)

Convert a hex-string to a byte-array, while validating it was actually hex.

Parameters

hex	The hex-string to convert.
bytes	The byte-array to write the result to.

Note: The length of the hex-string has to be exactly twice that of the length of the byte-array, otherwise conversion will fail.

Returns: True iff the hex-string was valid and the conversion succeeded.

Definition at line 562 of file string.cpp.

References ConvertHexNibbleToByte().

Referenced by X25519AuthorizedKeyClientHandler::GetValidSecretKeyAndUpdatePublicKey(), GRFLoadConfig(), PickerLoadConfig(), and ValidateSignature().

◆ FormatArrayAsHex()

std::string FormatArrayAsHex ( std::span< const uint8_t > data )

Format a byte array into a continuous hex string.

Parameters

data	Array to format

Returns: Converted string.

Definition at line 75 of file string.cpp.

Referenced by AddGrfInfo(), CalculateHashV1(), GenerateUid(), X25519AuthenticationHandler::GetPeerPublicKey(), X25519AuthorizedKeyClientHandler::GetValidSecretKeyAndUpdatePublicKey(), HandleSavegameLoadCrash(), IsGoodGRFConfigList(), CommandHelperBase::LogCommandExecution(), NetworkContentListWindow::OpenExternalSearch(), OutputContentState(), ClientNetworkGameSocketHandler::Receive_SERVER_CHECK_NEWGRFS(), and SurveyGrfs().

◆ IsPrintable()

bool IsPrintable ( char32_t c )

inline

Definition at line 145 of file string_func.h.

◆ IsTextDirectionChar()

bool IsTextDirectionChar ( char32_t c )

inline

Is the given character a text direction character.

Parameters

c	The character to test.

Returns: true iff the character is used to influence the text direction.

Definition at line 128 of file string_func.h.

References CHAR_TD_LRE, CHAR_TD_LRM, CHAR_TD_LRO, CHAR_TD_PDF, CHAR_TD_RLE, CHAR_TD_RLM, and CHAR_TD_RLO.

Referenced by MissingGlyphSearcher::FindMissingGlyphs(), GetLayouter(), and FallbackParagraphLayout::NextLine().

◆ IsValidChar()

bool IsValidChar	(	char32_t	key,
		CharSetFilter	afilter
	)

Only allow certain keys.

You can define the filter to be used. This makes sure no invalid keys can get into an editbox, like BELL.

Parameters

key	character to be checked
afilter	the filter to use

Returns: true or false depending if the character is printable/valid or not

Definition at line 363 of file string.cpp.

References CS_ALPHA, CS_ALPHANUMERAL, CS_HEXADECIMAL, CS_NUMERAL, CS_NUMERAL_SIGNED, and CS_NUMERAL_SPACE.

Referenced by Textbuf::InsertString(), OskWindow::OnClick(), VideoDriver_SDL_Base::PollEvent(), TranslateTTDPatchCodes(), and OskWindow::UpdateOskState().

◆ IsWhitespace()

bool IsWhitespace ( char32_t c )

inline

Check whether UNICODE character is whitespace or not, i.e.

whether this is a potential line-break character.

Parameters

c	UNICODE character to check

Returns: a boolean value whether 'c' is a whitespace character or not

See also: http://www.fileformat.info/info/unicode/category/Zs/list.htm

Definition at line 160 of file string_func.h.

Referenced by IConsoleHistoryAdd(), IcuStringIterator::Next(), FallbackParagraphLayout::NextLine(), IcuStringIterator::Prev(), and StringFilter::SetFilterTerm().

◆ StrCompareIgnoreCase()

int StrCompareIgnoreCase	(	const std::string_view	str1,
		const std::string_view	str2
	)

Compares two string( view)s, while ignoring the case of the characters.

Parameters

str1	The first string.
str2	The second string.

Returns: Less than zero if str1 < str2, zero if str1 == str2, greater than zero if str1 > str2. All ignoring the case of the characters.

Definition at line 300 of file string.cpp.

Referenced by MatchesExtension(), StrEqualsIgnoreCase(), and StrNaturalCompare().

◆ StrContainsIgnoreCase()

bool StrContainsIgnoreCase	(	const std::string_view	str,
		const std::string_view	value
	)

Checks if a string is contained in another string, while ignoring the case of the characters.

Parameters

str	The string to search in.
value	The string to search for.

Returns: True if a match was found.

Definition at line 326 of file string.cpp.

Referenced by StringFilter::AddLine(), and LoadWin32Font().

◆ strecpy()

void strecpy	(	std::span< char >	dst,
		std::string_view	src
	)

Copies characters from one buffer to another.

Copies the source string to the destination buffer with respect of the terminating null-character and the size of the destination buffer.

Note: usage: strecpy(dst, src);

Parameters

dst	The destination buffer
src	The buffer containing the string to copy

Definition at line 54 of file string.cpp.

References Debug.

Referenced by FileStringReader::HandlePragma(), and StringReader::ParseFile().

◆ StrEmpty()

bool StrEmpty ( const char * s )

inline

Check if a string buffer is empty.

Parameters

s	The pointer to the first element of the buffer

Returns: true if the buffer starts with the terminating null-character or if the given pointer points to nullptr else return false

Definition at line 68 of file string_func.h.

Referenced by GetEnv(), Window::HandleEditBoxKey(), IConsoleHistoryAdd(), SavePresetWindow::OnClick(), openttd_main(), FileStringReader::ParseFile(), RenameSign(), and MusicDriver_ExtMidi::Start().

◆ StrEndsWithIgnoreCase()

bool StrEndsWithIgnoreCase	(	std::string_view	str,
		const std::string_view	suffix
	)

Check whether the given string ends with the given suffix, ignoring case.

Parameters

str	The string to look at.
suffix	The suffix to look for.

Returns: True iff the end of the string is the same as the suffix, ignoring case.

Definition at line 287 of file string.cpp.

References StrEqualsIgnoreCase().

Referenced by TextfileWindow::AfterLoadText(), and TextfileWindow::NavigateToFile().

◆ StrEqualsIgnoreCase()

bool StrEqualsIgnoreCase	(	const std::string_view	str1,
		const std::string_view	str2
	)

Compares two string( view)s for equality, while ignoring the case of the characters.

Parameters

str1	The first string.
str2	The second string.

Returns: True iff both strings are equal, barring the case of the characters.

Definition at line 313 of file string.cpp.

References StrCompareIgnoreCase().

Referenced by ChangeWorkingDirectoryToExecutable(), ConListDirs(), AIScannerInfo::FindInfo(), GameScannerInfo::FindInfo(), FindKey(), FiosGetSavegameListCallback(), FiosGetScenarioListCallback(), FiosGetTownDataListCallback(), FiosMakeFilename(), FiosNumberedSaveName::FiosNumberedSaveName(), BlitterFactory::GetBlitterFactory(), GetFontByFaceName(), IsSameScript(), ParseCode(), ScriptScanner::RegisterScript(), DriverFactoryBase::SelectDriverImpl(), StrEndsWithIgnoreCase(), StringToContentType(), and StrStartsWithIgnoreCase().

◆ StrMakeValid() [1/3]

std::string StrMakeValid	(	const char *	str,
		StringValidationSettings	settings = `StringValidationSetting::ReplaceWithQuestionMark`
	)

inline

Definition at line 28 of file string_func.h.

◆ StrMakeValid() [2/3]

std::string StrMakeValid	(	std::string &&	str,
		StringValidationSettings	settings = `StringValidationSetting::ReplaceWithQuestionMark`
	)

inline

Definition at line 32 of file string_func.h.

◆ StrMakeValid() [3/3]

std::string StrMakeValid	(	std::string_view	str,
		StringValidationSettings	settings
	)

Copies the valid (UTF-8) characters from str to the returned string.

Depending on the settings invalid characters can be replaced with a question mark, as well as determining what characters are deemed invalid.

Parameters

str	The string to validate.
settings	The settings for the string validation.

Definition at line 186 of file string.cpp.

References settings, and StrMakeValid().

◆ StrMakeValidInPlace() [1/2]

void StrMakeValidInPlace	(	char *	str,
		StringValidationSettings	settings
	)

Scans the string for invalid characters and replaces them with a question mark '?' (if not ignored).

Parameters

str	The string to validate.
settings	The settings for the string validation.

Note: The string must be properly NUL terminated.

Definition at line 155 of file string.cpp.

References InPlaceBuilder::AnyBytesUnused(), InPlaceReplacement::builder, InPlaceReplacement::consumer, BaseStringBuilder::PutChar(), settings, and StrMakeValid().

Referenced by StringSettingDesc::MakeValueValid(), SanitizeSingleStringHelper(), and SlStdString().

◆ StrMakeValidInPlace() [2/2]

void StrMakeValidInPlace	(	std::string &	str,
		StringValidationSettings	settings
	)

Scans the string for invalid characters and replaces them with a question mark '?' (if not ignored).

Parameters

str	The string to validate.
settings	The settings for the string validation.

Note: The string must be properly NUL terminated.

Definition at line 170 of file string.cpp.

References InPlaceReplacement::builder, InPlaceReplacement::consumer, InPlaceBuilder::GetBytesWritten(), settings, and StrMakeValid().

◆ StrNaturalCompare()

int StrNaturalCompare	(	std::string_view	s1,
		std::string_view	s2,
		bool	ignore_garbage_at_front
	)

Compares two strings using case insensitive natural sort.

Parameters

s1	First string to compare.
s2	Second string to compare.
ignore_garbage_at_front	Skip punctuation characters in the front

Returns: Less than zero if s1 < s2, zero if s1 == s2, greater than zero if s1 > s2.

Definition at line 417 of file string.cpp.

References _current_collator, MacOSStringCompare(), SkipGarbage(), and StrCompareIgnoreCase().

Referenced by BuildGuiGroupList(), CargoSpecNameSorter(), EngineNameSorter(), GRFSorter(), IndustryDirectoryWindow::IndustryNameSorter(), IndustryTypeNameSorter(), NetworkContentListWindow::NameSorter(), NewGRFWindow::NameSorter(), DropDownString< TBase, TFs, TEnd >::NatSortFunc(), NetworkGameWindow::NGameNameSorter(), FiosItem::operator<(), SignList::SignNameSorter(), CompanyStationsWindow::StationNameSorter(), TownDirectoryWindow::TownNameSorter(), NetworkContentListWindow::TypeSorter(), and VehicleNameSorter().

◆ StrNaturalContains()

bool StrNaturalContains	(	const std::string_view	str,
		const std::string_view	value
	)

Checks if a string is contained in another string with a locale-aware comparison that is case sensitive.

Parameters

str	The string to search in.
value	The string to search for.

Returns: True if a match was found.

Definition at line 488 of file string.cpp.

References ICUStringContains(), MacOSStringContains(), and Win32StringContains().

Referenced by StringFilter::AddLine().

◆ StrNaturalContainsIgnoreCase()

bool StrNaturalContainsIgnoreCase	(	const std::string_view	str,
		const std::string_view	value
	)

Checks if a string is contained in another string with a locale-aware comparison that is case insensitive.

Parameters

str	The string to search in.
value	The string to search for.

Returns: True if a match was found.

Definition at line 515 of file string.cpp.

References ICUStringContains(), MacOSStringContains(), and Win32StringContains().

Referenced by StringFilter::AddLine().

◆ StrStartsWithIgnoreCase()

bool StrStartsWithIgnoreCase	(	std::string_view	str,
		const std::string_view	prefix
	)

Check whether the given string starts with the given prefix, ignoring case.

Parameters

str	The string to look at.
prefix	The prefix to look for.

Returns: True iff the begin of the string is the same as the prefix, ignoring case.

Definition at line 247 of file string.cpp.

References StrEqualsIgnoreCase().

◆ strtolower()

bool strtolower	(	std::string &	str,
		std::string::size_type	offs = `0`
	)

Definition at line 345 of file string.cpp.

◆ StrTrimInPlace()

void StrTrimInPlace ( std::string & str )

Trim the spaces from given string in place, i.e.

the string buffer that is passed will be modified whenever spaces exist in the given string. When there are spaces at the begin, the whole string is moved forward and when there are spaces at the back the '\0' termination is moved.

Parameters

str	The string to perform the in place trimming on.

Definition at line 226 of file string.cpp.

Referenced by TarScanner::AddFile(), CheckClientAndServerName(), NetworkValidateClientName(), and NetworkValidateServerName().

◆ StrTrimView()

std::string_view StrTrimView ( std::string_view str )

Definition at line 231 of file string.cpp.

◆ StrValid()

bool StrValid ( std::span< const char > str )

Checks whether the given string is valid, i.e.

contains only valid (printable) characters and is properly terminated.

Note: std::span is used instead of std::string_view as we are validating fixed-length string buffers, and std::string_view's constructor will assume a C-string that ends with a NUL terminator, which is one of the things we are checking.

Parameters

str	Span of chars to validate.

Definition at line 203 of file string.cpp.

References StringConsumer::AnyBytesLeft(), and StringConsumer::TryReadUtf8().

Referenced by LanguagePackHeader::IsValid().

◆ Utf16DecodeChar()

char32_t Utf16DecodeChar ( const uint16_t * c )

inline

Decode an UTF-16 character.

Parameters

c	Pointer to one or two UTF-16 code points.

Returns: Decoded Unicode character.

Definition at line 113 of file string_func.h.

References Utf16DecodeSurrogate(), and Utf16IsLeadSurrogate().

Referenced by IcuStringIterator::Next(), and IcuStringIterator::Prev().

◆ Utf16DecodeSurrogate()

char32_t Utf16DecodeSurrogate	(	uint	lead,
		uint	trail
	)

inline

Convert an UTF-16 surrogate pair to the corresponding Unicode character.

Parameters

lead	Lead surrogate code point.
trail	Trail surrogate code point.

Returns: Decoded Unicode character.

Definition at line 103 of file string_func.h.

Referenced by HandleCharMsg(), and Utf16DecodeChar().

◆ Utf16IsLeadSurrogate()

bool Utf16IsLeadSurrogate ( uint c )

inline

Is the given character a lead surrogate code point?

Parameters

c	The character to test.

Returns: True if the character is a lead surrogate code point.

Definition at line 82 of file string_func.h.

Referenced by HandleCharMsg(), HandleIMEComposition(), and Utf16DecodeChar().

◆ Utf16IsTrailSurrogate()

bool Utf16IsTrailSurrogate ( uint c )

inline

Is the given character a lead surrogate code point?

Parameters

c	The character to test.

Returns: True if the character is a lead surrogate code point.

Definition at line 92 of file string_func.h.

Referenced by HandleCharMsg().

◆ Utf8StringLength()

size_t Utf8StringLength ( std::string_view str )

Get the length of an UTF-8 encoded string in number of characters and thus not the number of bytes that the encoded string contains.

Parameters

s	The string to get the length for.

Returns: The length of the string in characters.

Definition at line 339 of file string.cpp.

Referenced by CmdAlterGroup(), CmdFoundTown(), CmdPlaceSign(), CmdRenameCompany(), CmdRenameDepot(), CmdRenameEngine(), CmdRenamePresident(), CmdRenameSign(), CmdRenameStation(), CmdRenameTown(), CmdRenameVehicle(), CmdRenameWaypoint(), Textbuf::DeleteChar(), Textbuf::DeleteText(), GenerateCompanyName(), GeneratePresidentName(), Textbuf::UpdateSize(), and VerifyTownName().

Data Structures

Functions

Detailed Description

Function Documentation

◆ ConvertHexToBytes()

◆ FormatArrayAsHex()

◆ IsPrintable()

◆ IsTextDirectionChar()

◆ IsValidChar()

◆ IsWhitespace()

◆ StrCompareIgnoreCase()

◆ StrContainsIgnoreCase()

◆ strecpy()

◆ StrEmpty()

◆ StrEndsWithIgnoreCase()

◆ StrEqualsIgnoreCase()

◆ StrMakeValid() [1/3]

◆ StrMakeValid() [2/3]

◆ StrMakeValid() [3/3]

◆ StrMakeValidInPlace() [1/2]

◆ StrMakeValidInPlace() [2/2]

◆ StrNaturalCompare()

◆ StrNaturalContains()

◆ StrNaturalContainsIgnoreCase()

◆ StrStartsWithIgnoreCase()

◆ strtolower()

◆ StrTrimInPlace()

◆ StrTrimView()

◆ StrValid()

◆ Utf16DecodeChar()

◆ Utf16DecodeSurrogate()

◆ Utf16IsLeadSurrogate()

◆ Utf16IsTrailSurrogate()

◆ Utf8StringLength()