Handling of strings (std::string/std::string_view). More...

#include "stdafx.h"
#include "debug.h"
#include "core/math_func.hpp"
#include "error_func.h"
#include "string_func.h"
#include "string_base.h"
#include "core/utf8.hpp"
#include "core/string_inplace.hpp"
#include "table/control_codes.h"
#include <unicode/brkiter.h>
#include <unicode/stsearch.h>
#include <unicode/ustring.h>
#include <unicode/utext.h>
#include "language.h"
#include "gfx_func.h"
#include "safeguards.h"

Data Structures
struct	CaseInsensitiveCharTraits
	Case insensitive implementation of the standard character type traits. More...

class	IcuStringIterator
	String iterator using ICU as a backend. More...

Typedefs
typedef std::basic_string_view< char, CaseInsensitiveCharTraits >	CaseInsensitiveStringView
	Case insensitive string view.

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.

static bool	IsSccEncodedCode (char32_t c)
	Test if a character is (only) part of an encoded string.

template<class Builder >
static void	StrMakeValid (Builder &builder, StringConsumer &consumer, StringValidationSettings settings)
	Copies the valid (UTF-8) characters from `consumer` to the `builder`.

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

void	StrMakeValidInPlace (std::string &str, StringValidationSettings settings)
	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)
	Copies the valid (UTF-8) characters from `str` to the returned string.

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, std::string_view characters_to_trim)

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

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

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

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

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

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	strtolower (std::string &str, std::string::size_type offs)

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

static bool	IsGarbageCharacter (char32_t c)
	Test if a unicode character is considered garbage to be skipped.

static std::string_view	SkipGarbage (std::string_view str)
	Skip some of the 'garbage' in the string that we don't want to use to sort on.

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

static int	ICUStringContains (std::string_view str, std::string_view value, bool case_insensitive)
	Search if a string is contained in another string using the current locale.

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

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

static int	ConvertHexNibbleToByte (char c)
	Convert a single hex-nibble to a byte.

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.

std::optional< std::string_view >	GetEnv (const char *variable)
	Get the environment variable using std::getenv and when it is an empty string (or nullptr), return `std::nullopt` instead.

Detailed Description

Handling of strings (std::string/std::string_view).

Definition in file string.cpp.

Typedef Documentation

◆ CaseInsensitiveStringView

typedef std::basic_string_view<char, CaseInsensitiveCharTraits> CaseInsensitiveStringView

Case insensitive string view.

Definition at line 290 of file string.cpp.

Function Documentation

◆ ConvertHexNibbleToByte()

static int ConvertHexNibbleToByte ( char c )

static

Convert a single hex-nibble to a byte.

Parameters

c	The hex-nibble to convert.

Returns: The byte the hex-nibble represents, or -1 if it is not a valid hex-nibble.

Definition at line 552 of file string.cpp.

Referenced by ConvertHexToBytes().

◆ 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 571 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 78 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().

◆ GetEnv()

std::optional< std::string_view > GetEnv ( const char * variable )

Get the environment variable using std::getenv and when it is an empty string (or nullptr), return std::nullopt instead.

Parameters

variable The environment variable to read from.

Returns: The environment value, or std::nullopt.

Definition at line 855 of file string.cpp.

Referenced by DetermineBasePaths(), DeterminePaths(), GetCurrentLocale(), GetHomeDir(), NetworkContentMirrorUriString(), NetworkContentServerConnectionString(), NetworkCoordinatorConnectionString(), NetworkStunConnectionString(), and NetworkSurveyUriString().

◆ ICUStringContains()

static int ICUStringContains	(	std::string_view	str,
		std::string_view	value,
		bool	case_insensitive
	)

static

Search if a string is contained in another string using the current locale.

Parameters

str	String to search in.
value	String to search for.
case_insensitive	Search case-insensitive.

Returns: 1 if value was found, 0 if it was not found, or -1 if not supported by the OS.

Definition at line 467 of file string.cpp.

References _current_collator.

Referenced by StrNaturalContains(), and StrNaturalContainsIgnoreCase().

◆ IsGarbageCharacter()

static bool IsGarbageCharacter ( char32_t c )

static

Test if a unicode character is considered garbage to be skipped.

Parameters

c	Character to test.

Returns: true iff the character should be skipped.

Definition at line 392 of file string.cpp.

Referenced by SkipGarbage().

◆ IsSccEncodedCode()

static bool IsSccEncodedCode ( char32_t c )

static

Test if a character is (only) part of an encoded string.

Parameters

c	Character to test.

Returns: True iff the character is an encoded string control code.

Definition at line 95 of file string.cpp.

References SCC_ENCODED, SCC_ENCODED_INTERNAL, SCC_ENCODED_NUMERIC, and SCC_ENCODED_STRING.

Referenced by StrMakeValid().

◆ 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 374 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().

◆ SkipGarbage()

static std::string_view SkipGarbage ( std::string_view str )

static

Skip some of the 'garbage' in the string that we don't want to use to sort on.

This way the alphabetical sorting will work better as we would be actually using those characters instead of some other characters such as spaces and tildes at the begin of the name.

Parameters

str	The string to skip the initial garbage of.

Returns: The string with the garbage skipped.

Definition at line 411 of file string.cpp.

References IsGarbageCharacter().

Referenced by StrNaturalCompare().

◆ StrCompareIgnoreCase()

int StrCompareIgnoreCase	(	std::string_view	str1,
		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 311 of file string.cpp.

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

◆ StrContainsIgnoreCase()

bool StrContainsIgnoreCase	(	std::string_view	str,
		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 337 of file string.cpp.

Referenced by StringFilter::AddLine(), and Win32FontCacheFactory::LoadFont().

◆ 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 57 of file string.cpp.

References Debug.

Referenced by FileStringReader::HandlePragma().

◆ StrEndsWithIgnoreCase()

bool StrEndsWithIgnoreCase	(	std::string_view	str,
		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 298 of file string.cpp.

References StrEqualsIgnoreCase().

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

◆ StrEqualsIgnoreCase()

bool StrEqualsIgnoreCase	(	std::string_view	str1,
		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 324 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/2]

template<class Builder >

static void StrMakeValid	(	Builder &	builder,
		StringConsumer &	consumer,
		StringValidationSettings	settings
	)

static

Copies the valid (UTF-8) characters from consumer to the builder.

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

Parameters

builder	The destination to write to.
consumer	The string to validate.
settings	The settings for the string validation.

Definition at line 120 of file string.cpp.

References AllowControlCode, AllowNewline, StringConsumer::AnyBytesLeft(), IsSccEncodedCode(), StringConsumer::PeekCharIf(), ReplaceTabCrNlWithSpace, ReplaceWithQuestionMark, settings, StringConsumer::Skip(), and StringConsumer::TryReadUtf8().

Referenced by FiosFileScanner::AddFile(), ScriptInfo::AddLabels(), ScriptInfo::AddSetting(), Textbuf::Assign(), CopyFromOldName(), NewGRFInspectWindow::DrawMainPanelWidget(), DrawNewsString(), ErrorUnknownCallbackResult(), ExtractString(), GetFileTitle(), GetMusicCatEntryName(), GlobalVarChangeInfo(), IConsolePrint(), IniGroup::IniGroup(), IniItem::IniItem(), IniLoadFile::LoadFromDisk(), LoadFromHighScore(), LoadNewGRFSound(), ScriptInstance::LoadObjects(), TextfileWindow::LoadText(), NewGRFWindow::NameSorter(), ReadDWordAsString(), Packet::Recv_string(), ShowNewGrfVehicleError(), StrMakeValid(), StrMakeValidInPlace(), and StrMakeValidInPlace().

◆ StrMakeValid() [2/2]

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 189 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 158 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 173 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 428 of file string.cpp.

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

Referenced by 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	(	std::string_view	str,
		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 497 of file string.cpp.

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

Referenced by StringFilter::AddLine().

◆ StrNaturalContainsIgnoreCase()

bool StrNaturalContainsIgnoreCase	(	std::string_view	str,
		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 524 of file string.cpp.

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

Referenced by StringFilter::AddLine().

◆ StrStartsWithIgnoreCase()

bool StrStartsWithIgnoreCase	(	std::string_view	str,
		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 258 of file string.cpp.

References StrEqualsIgnoreCase().

◆ strtolower()

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

Definition at line 356 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 229 of file string.cpp.

References StringConsumer::WHITESPACE_NO_NEWLINE.

Referenced by CheckClientAndServerName(), NetworkValidateClientName(), and NetworkValidateServerName().

◆ StrTrimView()

std::string_view StrTrimView	(	std::string_view	str,
		std::string_view	characters_to_trim
	)

Definition at line 242 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 206 of file string.cpp.

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

Referenced by LanguagePackHeader::IsValid().

◆ 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 350 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

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ CaseInsensitiveStringView

Function Documentation

◆ ConvertHexNibbleToByte()

◆ ConvertHexToBytes()

◆ FormatArrayAsHex()

◆ GetEnv()

◆ ICUStringContains()

◆ IsGarbageCharacter()

◆ IsSccEncodedCode()

◆ IsValidChar()

◆ SkipGarbage()

◆ StrCompareIgnoreCase()

◆ StrContainsIgnoreCase()

◆ strecpy()

◆ StrEndsWithIgnoreCase()

◆ StrEqualsIgnoreCase()

◆ StrMakeValid() [1/2]

◆ StrMakeValid() [2/2]

◆ StrMakeValidInPlace() [1/2]

◆ StrMakeValidInPlace() [2/2]

◆ StrNaturalCompare()

◆ StrNaturalContains()

◆ StrNaturalContainsIgnoreCase()

◆ StrStartsWithIgnoreCase()

◆ strtolower()

◆ StrTrimInPlace()

◆ StrTrimView()

◆ StrValid()

◆ Utf8StringLength()