OpenTTD Source  12.0-beta2
string_func.h File Reference
#include <stdarg.h>
#include <iosfwd>
#include "core/bitmath_func.hpp"
#include "string_type.h"

Go to the source code of this file.

Functions

char * strecat (char *dst, const char *src, const char *last) NOACCESS(3)
 Appends characters from one string to another. More...
 
char * strecpy (char *dst, const char *src, const char *last) NOACCESS(3)
 Copies characters from one buffer to another. More...
 
char * stredup (const char *src, const char *last=nullptr) NOACCESS(2)
 Create a duplicate of the given string. More...
 
int CDECL seprintf (char *str, const char *last, const char *format,...) WARN_FORMAT(3
 
int CDECL NOACCESS (2)
 
int CDECL vseprintf (char *str, const char *last, const char *format, va_list ap) WARN_FORMAT(3
 
char *CDECL str_fmt (const char *str,...) WARN_FORMAT(1
 
char *CDECL void StrMakeValidInPlace (char *str, const char *last, StringValidationSettings settings=SVS_REPLACE_WITH_QUESTION_MARK) NOACCESS(2)
 Scans the string for invalid characters and replaces then with a question mark '?' (if not ignored). More...
 
std::string StrMakeValid (const std::string &str, StringValidationSettings settings=SVS_REPLACE_WITH_QUESTION_MARK)
 Scans the string for invalid characters and replaces then with a question mark '?' (if not ignored). More...
 
void StrMakeValidInPlace (char *str, StringValidationSettings settings=SVS_REPLACE_WITH_QUESTION_MARK)
 Scans the string for invalid characters and replaces then with a question mark '?' (if not ignored). More...
 
void str_fix_scc_encoded (char *str, const char *last) NOACCESS(2)
 Scan the string for old values of SCC_ENCODED and fix it to it's new, static value. More...
 
void str_strip_colours (char *str)
 Scans the string for colour codes and strips them.
 
bool strtolower (char *str)
 Convert a given ASCII string to lowercase. More...
 
bool strtolower (std::string &str, std::string::size_type offs=0)
 
bool StrValid (const char *str, const char *last) NOACCESS(2)
 Checks whether the given string is valid, i.e. More...
 
void StrTrimInPlace (std::string &str)
 Trim the spaces from given string in place, i.e. More...
 
bool StrStartsWith (const std::string_view str, const std::string_view prefix)
 Check whether the given string starts with the given prefix. More...
 
bool StrEndsWith (const std::string_view str, const std::string_view suffix)
 Check whether the given string ends with the given suffix. More...
 
static bool StrEmpty (const char *s)
 Check if a string buffer is empty. More...
 
static size_t ttd_strnlen (const char *str, size_t maxlen)
 Get the length of a string, within a limited buffer. More...
 
char * md5sumToString (char *buf, const char *last, const uint8 md5sum[16])
 Convert the md5sum to a hexadecimal string representation. More...
 
bool IsValidChar (WChar key, CharSetFilter afilter)
 Only allow certain keys. More...
 
size_t Utf8Decode (WChar *c, const char *s)
 Decode and consume the next UTF-8 encoded character. More...
 
size_t Utf8Encode (char *buf, WChar c)
 
size_t Utf8Encode (std::ostreambuf_iterator< char > &buf, WChar c)
 
size_t Utf8TrimString (char *s, size_t maxlen)
 Properly terminate an UTF8 string to some maximum length. More...
 
static WChar Utf8Consume (const char **s)
 
template<class Titr >
static WChar Utf8Consume (Titr &s)
 
static int8 Utf8CharLen (WChar c)
 Return the length of a UTF-8 encoded character. More...
 
static int8 Utf8EncodedCharLen (char c)
 Return the length of an UTF-8 encoded value based on a single char. More...
 
static bool IsUtf8Part (char c)
 
static char * Utf8PrevChar (char *s)
 Retrieve the previous UNICODE character in an UTF-8 encoded string. More...
 
static const char * Utf8PrevChar (const char *s)
 
size_t Utf8StringLength (const char *s)
 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. More...
 
size_t Utf8StringLength (const std::string &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. More...
 
static bool Utf16IsLeadSurrogate (uint c)
 Is the given character a lead surrogate code point? More...
 
static bool Utf16IsTrailSurrogate (uint c)
 Is the given character a lead surrogate code point? More...
 
static WChar Utf16DecodeSurrogate (uint lead, uint trail)
 Convert an UTF-16 surrogate pair to the corresponding Unicode character. More...
 
static WChar Utf16DecodeChar (const uint16 *c)
 Decode an UTF-16 character. More...
 
static bool IsTextDirectionChar (WChar c)
 Is the given character a text direction character. More...
 
static bool IsPrintable (WChar c)
 
static bool IsWhitespace (WChar c)
 Check whether UNICODE character is whitespace or not, i.e. More...
 
int strnatcmp (const char *s1, const char *s2, bool ignore_garbage_at_front=false)
 Compares two strings using case insensitive natural sort. More...
 

Detailed Description

Functions related to low-level strings.

Note
Be aware of "dangerous" string functions; string functions that have behaviour that could easily cause buffer overruns and such:
  • strncpy: does not '\0' terminate when input string is longer than the size of the output string. Use strecpy instead.
  • [v]snprintf: returns the length of the string as it would be written when the output is large enough, so it can be more than the size of the buffer and than can underflow size_t (uint-ish) which makes all subsequent snprintf alikes write outside of the buffer. Use [v]seprintf instead; it will return the number of bytes actually added so no [v]seprintf will cause outside of bounds writes.
  • [v]sprintf: does not bounds checking: use [v]seprintf instead.

Definition in file string_func.h.

Function Documentation

◆ IsTextDirectionChar()

static bool IsTextDirectionChar ( WChar  c)
inlinestatic

Is the given character a text direction character.

Parameters
cThe character to test.
Returns
true iff the character is used to influence the text direction.

Definition at line 225 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.

◆ IsValidChar()

bool IsValidChar ( WChar  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
keycharacter to be checked
afilterthe filter to use
Returns
true or false depending if the character is printable/valid or not

Definition at line 476 of file string.cpp.

References CS_ALPHANUMERAL.

Referenced by IConsoleCmdExec().

◆ IsWhitespace()

static bool IsWhitespace ( WChar  c)
inlinestatic

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

whether this is a potential line-break character.

Parameters
cUNICODE 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 257 of file string_func.h.

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

◆ md5sumToString()

char* md5sumToString ( char *  buf,
const char *  last,
const uint8  md5sum[16] 
)

Convert the md5sum to a hexadecimal string representation.

Parameters
bufbuffer to put the md5sum into
lastlast character of buffer (usually lastof(buf))
md5sumthe md5sum itself
Returns
a pointer to the next character after the md5sum

Definition at line 553 of file string.cpp.

References seprintf().

Referenced by HandleSavegameLoadCrash(), IsGoodGRFConfigList(), OutputContentState(), PrintGrfInfo(), and ClientNetworkGameSocketHandler::Receive_SERVER_CHECK_NEWGRFS().

◆ str_fix_scc_encoded()

void str_fix_scc_encoded ( char *  str,
const char *  last 
)

Scan the string for old values of SCC_ENCODED and fix it to it's new, static value.

Parameters
strthe string to scan
lastthe last valid character of str

Definition at line 169 of file string.cpp.

References Utf8Decode(), and Utf8EncodedCharLen().

◆ strecat()

char* strecat ( char *  dst,
const char *  src,
const char *  last 
)

Appends characters from one string to another.

Appends the source string to the destination string with respect of the terminating null-character and and the last pointer to the last element in the destination buffer. If the last pointer is set to nullptr no boundary check is performed.

Note
usage: strecat(dst, src, lastof(dst));
lastof() applies only to fixed size arrays
Parameters
dstThe buffer containing the target string
srcThe buffer containing the string to append
lastThe pointer to the last element of the destination buffer
Returns
The pointer to the terminating null-character in the destination buffer

Definition at line 84 of file string.cpp.

References strecpy().

Referenced by KeycodeToString(), Squirrel::PrintFunc(), SaveKeycodes(), and ScriptConfig::SettingsToString().

◆ strecpy()

char* strecpy ( char *  dst,
const char *  src,
const char *  last 
)

Copies characters from one buffer to another.

Copies the source string to the destination buffer with respect of the terminating null-character and the last pointer to the last element in the destination buffer. If the last pointer is set to nullptr no boundary check is performed.

Note
usage: strecpy(dst, src, lastof(dst));
lastof() applies only to fixed size arrays
Parameters
dstThe destination buffer
srcThe buffer containing the string to copy
lastThe pointer to the last element of the destination buffer
Returns
The pointer to the terminating null-character in the destination buffer

Definition at line 112 of file string.cpp.

References Debug, and error().

Referenced by ScenarioScanner::AddFile(), Textbuf::Assign(), DriverFactoryBase::DriverFactoryBase(), GameScannerInfo::FindInfo(), AIScannerInfo::FindInfo(), BoolSettingDesc::FormatValue(), StringSettingDesc::FormatValue(), GamelogRevision(), GenerateTownNameString(), GetClipboardContents(), GRFBuildParamList(), FileStringReader::HandlePragma(), IConsoleAliasExec(), MakeCatalanTownName(), MakeCzechTownName(), MakeFinnishTownName(), MakeFrenchTownName(), MakeHungarianTownName(), MakeItalianTownName(), MakeNorwegianTownName(), MakeRomanianTownName(), MakeSillyTownName(), MakeSlovakTownName(), MakeSpanishTownName(), MakeSwissTownName(), MakeTurkishTownName(), mkpath(), NetworkFindBroadcastIPsInternal(), AIDebugWindow::OnEditboxChanged(), MusicDriver_ExtMidi::PlaySong(), StringListReader::ReadLine(), SetFallbackFont(), FileToSaveLoad::SetTitle(), strecat(), and DriverFactoryBase::~DriverFactoryBase().

◆ stredup()

char* stredup ( const char *  s,
const char *  last 
)

Create a duplicate of the given string.

Parameters
sThe string to duplicate.
lastThe last character that is safe to duplicate. If nullptr, the whole string is duplicated.
Note
The maximum length of the resulting string might therefore be last - s + 1.
Returns
The duplicate of the string.

Definition at line 137 of file string.cpp.

References ttd_strnlen().

Referenced by ScriptConfig::Change(), NetworkChatWindow::ChatTabCompletion(), CmdSetGoalProgress(), CmdSetGoalText(), CmdSetStoryPageTitle(), AIInfo::Constructor(), ErrorMessageData::ErrorMessageData(), FileWriter::FileWriter(), GamelogSetting(), GetFontByFaceName(), GRFConfig::GRFConfig(), GRFFile::GRFFile(), IConsolePrint(), IsGoodGRFConfigList(), ScriptScanner::RegisterScript(), ScriptConfig::ScriptConfig(), ErrorMessageData::SetDParamStr(), AIConfig::SetSetting(), ScriptConfig::SetSetting(), SlError(), MusicDriver_ExtMidi::Start(), ScriptConfig::StringToSettings(), UpdateElement(), and UpdateOSKOriginalText().

◆ StrEmpty()

◆ StrEndsWith()

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

Check whether the given string ends with the given suffix.

Parameters
strThe string to look at.
suffixThe suffix to look for.
Returns
True iff the end of the string is the same as the suffix.

Definition at line 380 of file string.cpp.

Referenced by GetSettingFromName().

◆ StrMakeValid()

std::string StrMakeValid ( const std::string &  str,
StringValidationSettings  settings 
)

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

Parameters
strThe string to validate.
settingsThe settings for the string validation.

Definition at line 281 of file string.cpp.

References settings, and StrMakeValidInPlace().

Referenced by IniGroup::IniGroup(), IniItem::IniItem(), IniLoadFile::LoadFromDisk(), StringSettingDesc::MakeValueValid(), and Packet::Recv_string().

◆ StrMakeValidInPlace() [1/2]

char* CDECL void StrMakeValidInPlace ( char *  str,
const char *  last,
StringValidationSettings  settings 
)

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

Parameters
strThe string to validate.
lastThe last valid character of str.
settingsThe settings for the string validation.

Definition at line 255 of file string.cpp.

References settings, and StrMakeValidInPlace().

Referenced by StrMakeValid(), and StrMakeValidInPlace().

◆ StrMakeValidInPlace() [2/2]

void StrMakeValidInPlace ( char *  str,
StringValidationSettings  settings 
)

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

Only use this function when you are sure the string ends with a '\0'; otherwise use StrMakeValidInPlace(str, last, settings) variant.

Parameters
strThe string (of which you are sure ends with '\0') to validate.

Definition at line 269 of file string.cpp.

References settings, and StrMakeValidInPlace().

◆ strnatcmp()

int strnatcmp ( const char *  s1,
const char *  s2,
bool  ignore_garbage_at_front 
)

Compares two strings using case insensitive natural sort.

Parameters
s1First string to compare.
s2Second string to compare.
ignore_garbage_at_frontSkip 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 718 of file string.cpp.

References _current_collator, and SkipGarbage().

Referenced by GRFSorter(), IndustryDirectoryWindow::IndustryNameSorter(), NetworkContentListWindow::NameSorter(), NewGRFWindow::NameSorter(), NetworkGameWindow::NGameNameSorter(), SignList::SignNameSorter(), CompanyStationsWindow::StationNameSorter(), TownDirectoryWindow::TownNameSorter(), and NetworkContentListWindow::TypeSorter().

◆ StrStartsWith()

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

Check whether the given string starts with the given prefix.

Parameters
strThe string to look at.
prefixThe prefix to look for.
Returns
True iff the begin of the string is the same as the prefix.

Definition at line 367 of file string.cpp.

Referenced by ClientNetworkCoordinatorSocketHandler::ConnectToServer(), GetCompanySettingFromName(), and ServerAddress::Parse().

◆ strtolower()

bool strtolower ( char *  str)

Convert a given ASCII string to lowercase.

NOTE: only support ASCII characters, no UTF8 fancy. As currently the function is only used to lowercase data-filenames if they are not found, this is sufficient. If more, or general functionality is needed, look to r7271 where it was removed because it was broken when using certain locales: eg in Turkish the uppercase 'I' was converted to '?', so just revert to the old functionality

Parameters
strstring to convert
Returns
String has changed.

Definition at line 447 of file string.cpp.

Referenced by GameScannerInfo::FindInfo(), AIScannerInfo::FindInfo(), GameScannerLibrary::FindLibrary(), AIScannerLibrary::FindLibrary(), ScriptScanner::RegisterScript(), and SimplifyFileName().

◆ 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
strThe string to perform the in place trimming on.

Definition at line 355 of file string.cpp.

References StrLeftTrimInPlace(), and StrRightTrimInPlace().

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

◆ StrValid()

bool StrValid ( const char *  str,
const char *  last 
)

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

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

Parameters
strThe string to validate.
lastThe last character of the string, i.e. the string must be terminated here or earlier.

Definition at line 300 of file string.cpp.

References Utf8Decode(), and Utf8EncodedCharLen().

◆ ttd_strnlen()

static size_t ttd_strnlen ( const char *  str,
size_t  maxlen 
)
inlinestatic

Get the length of a string, within a limited buffer.

Parameters
strThe pointer to the first element of the buffer
maxlenThe maximum size of the buffer
Returns
The length of the string

Definition at line 76 of file string_func.h.

Referenced by stredup().

◆ Utf16DecodeChar()

static WChar Utf16DecodeChar ( const uint16 *  c)
inlinestatic

Decode an UTF-16 character.

Parameters
cPointer to one or two UTF-16 code points.
Returns
Decoded Unicode character.

Definition at line 210 of file string_func.h.

References Utf16DecodeSurrogate(), and Utf16IsLeadSurrogate().

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

◆ Utf16DecodeSurrogate()

static WChar Utf16DecodeSurrogate ( uint  lead,
uint  trail 
)
inlinestatic

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

Parameters
leadLead surrogate code point.
trailTrail surrogate code point.
Returns
Decoded Unicode character.

Definition at line 200 of file string_func.h.

Referenced by HandleCharMsg(), and Utf16DecodeChar().

◆ Utf16IsLeadSurrogate()

static bool Utf16IsLeadSurrogate ( uint  c)
inlinestatic

Is the given character a lead surrogate code point?

Parameters
cThe character to test.
Returns
True if the character is a lead surrogate code point.

Definition at line 179 of file string_func.h.

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

◆ Utf16IsTrailSurrogate()

static bool Utf16IsTrailSurrogate ( uint  c)
inlinestatic

Is the given character a lead surrogate code point?

Parameters
cThe character to test.
Returns
True if the character is a lead surrogate code point.

Definition at line 189 of file string_func.h.

Referenced by HandleCharMsg().

◆ Utf8CharLen()

static int8 Utf8CharLen ( WChar  c)
inlinestatic

Return the length of a UTF-8 encoded character.

Parameters
cUnicode character.
Returns
Length of UTF-8 encoding for character.

Definition at line 113 of file string_func.h.

◆ Utf8Decode()

size_t Utf8Decode ( WChar c,
const char *  s 
)

Decode and consume the next UTF-8 encoded character.

Parameters
cBuffer to place decoded character.
sCharacter stream to retrieve character from.
Returns
Number of characters in the sequence.

Definition at line 574 of file string.cpp.

References GB(), and HasBit().

Referenced by Layouter::GetCharPosition(), Layouter::Layouter(), str_fix_scc_encoded(), str_strip_colours(), StrValid(), and TranslateTTDPatchCodes().

◆ Utf8EncodedCharLen()

static int8 Utf8EncodedCharLen ( char  c)
inlinestatic

Return the length of an UTF-8 encoded value based on a single char.

This char should be the first byte of the UTF-8 encoding. If not, or encoding is invalid, return value is 0

Parameters
cchar to query length of
Returns
requested size

Definition at line 132 of file string_func.h.

References GB().

Referenced by str_fix_scc_encoded(), StrValid(), TranslateTTDPatchCodes(), and Utf8TrimString().

◆ Utf8PrevChar()

static char* Utf8PrevChar ( char *  s)
inlinestatic

Retrieve the previous UNICODE character in an UTF-8 encoded string.

Parameters
schar pointer pointing to (the first char of) the next character
Returns
a pointer in 's' to the previous UNICODE character's first byte
Note
The function should not be used to determine the length of the previous encoded char because it might be an invalid/corrupt start-sequence

Definition at line 157 of file string_func.h.

◆ Utf8StringLength() [1/2]

size_t Utf8StringLength ( const char *  s)

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
sThe string to get the length for.
Returns
The length of the string in characters.

Definition at line 417 of file string.cpp.

Referenced by CmdAlterGroup(), CmdPlaceSign(), CmdRenameCompany(), CmdRenameDepot(), CmdRenameEngine(), CmdRenamePresident(), CmdRenameStation(), CmdRenameTown(), CmdRenameVehicle(), CmdRenameWaypoint(), Utf8StringLength(), and VerifyTownName().

◆ Utf8StringLength() [2/2]

size_t Utf8StringLength ( const std::string &  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
sThe string to get the length for.
Returns
The length of the string in characters.

Definition at line 431 of file string.cpp.

References Utf8StringLength().

◆ Utf8TrimString()

size_t Utf8TrimString ( char *  s,
size_t  maxlen 
)

Properly terminate an UTF8 string to some maximum length.

Parameters
sstring to check if it needs additional trimming
maxlenthe maximum length the buffer can have.
Returns
the new length in bytes of the string (eg. strlen(new_string))
Note
maxlen is the string length INCLUDING the terminating '\0'

Definition at line 660 of file string.cpp.

References Utf8EncodedCharLen().