Strings

Description

API for working with strings.

Modules
	String array
	String array implementation.

Classes
class	Common::String

Macros
#define	tag2str(x)   Common::tag2string(x).c_str()
#define	tag2strP(x)   Common::tag2string(x, true).c_str()

Functions
String	Common::operator+ (const String &x, const String &y)
String	Common::operator+ (const char *x, const String &y)
String	Common::operator+ (const String &x, const char *y)
String	Common::operator+ (const String &x, char y)
String	Common::operator+ (char x, const String &y)
bool	Common::operator== (const char *x, const String &y)
bool	Common::operator!= (const char *x, const String &y)
char *	Common::ltrim (char *t)
char *	Common::rtrim (char *t)
char *	Common::trim (char *t)
String	Common::lastPathComponent (const String &path, const char sep)
String	Common::firstPathComponents (const String &path, const char sep)
String	Common::normalizePath (const String &path, const char sep)
bool	Common::matchString (const char *str, const char *pat, bool ignoreCase=false, const char *wildcardExclusions=NULL)
void	Common::replace (Common::String &source, const Common::String &what, const Common::String &with)
String	Common::tag2string (uint32 tag, bool nonPrintable=false)
void	Common::strcpy_s (char *dst, size_t size, const char *src)
template<typename T , size_t N>
FORCEINLINE void	Common::strcpy_s (T(&dst)[N], const char *src)
void	Common::strcat_s (char *dst, size_t size, const char *src)
template<typename T , size_t N>
FORCEINLINE void	Common::strcat_s (T(&dst)[N], const char *src)
int	Common::vsprintf_s (char *dst, size_t size, const char *format, va_list ap) GCC_PRINTF(3
template<typename T , size_t N>
int FORCEINLINE	Common::GCC_PRINTF (2, 0) int vsprintf_s(T(&dst)[N]
return	Common::vsprintf_s ((char *) dst, N, format, ap)
int	Common::sprintf_s (char *dst, size_t size, MSVC_PRINTF const char *format,...) GCC_PRINTF(3
template<typename T , size_t N>
int	Common::GCC_PRINTF (2, 3) int sprintf_s(T(&dst)[N]
	Common::va_start (ap, format)
	Common::va_end (ap)
size_t	Common::strlcpy (char *dst, const char *src, size_t size)
size_t	Common::strlcat (char *dst, const char *src, size_t size)
size_t	Common::strnlen (const char *src, size_t maxSize)
String	Common::toPrintable (const String &src, bool keepNewLines=true)

Variables
int FORCEINLINE const char *	Common::format
int FORCEINLINE const char va_list	Common::ap
int MSVC_PRINTF const char int	Common::ret

Macro Definition Documentation

tag2str

#define tag2str

(

x

)

Common::tag2string(x).c_str()

Convenience wrapper for tag2string which "returns" a C string. Note: It is NOT safe to do anything with the return value other than directly copying or printing it.

tag2strP

#define tag2strP

(

x

)

Common::tag2string(x, true).c_str()

Convenience wrapper for tag2string with non-printable characters which "returns" a C string. Note: It is NOT safe to do anything with the return value other than directly copying or printing it.

Function Documentation

lastPathComponent()

String Common::lastPathComponent	(	const String &	path,
		const char	sep
	)

Returns the last component of a given path.

Examples: /foo/bar.txt would return 'bar.txt' /foo/bar/ would return 'bar' /foo/./bar// would return 'bar'

Parameters

path	the path of which we want to know the last component
sep	character used to separate path components

Returns

The last component of the path.

firstPathComponents()

String Common::firstPathComponents	(	const String &	path,
		const char	sep
	)

Returns the first components of a given path (complementary to lastPathComponent)

Examples: /foo/bar.txt would return '/foo/' /foo/bar/ would return '/foo/' /foo/./bar// would return '/foo/./'

Parameters

path	the path of which we want to know the last component
sep	character used to separate path components

Returns

The all the components of the path except the last one.

normalizePath()

String Common::normalizePath	(	const String &	path,
		const char	sep
	)

Normalize a given path to a canonical form. In particular:

• trailing separators are removed: /foo/bar/ -> /foo/bar
• double separators (= empty components) are removed: /foo//bar -> /foo/bar
• dot components are removed: /foo/./bar -> /foo/bar

Parameters

path	the path to normalize
sep	the separator token (usually '/' on Unix-style systems, or '\' on Windows based stuff)

Returns

the normalized path

matchString()

bool Common::matchString	(	const char *	str,
		const char *	pat,
		bool	ignoreCase = false,
		const char *	wildcardExclusions = NULL
	)

Simple DOS-style pattern matching function (understands * and ? like used in DOS). Taken from exult/files/listfiles.cc

Token meaning: "*": any character, any amount of times. "?": any character, only once. "#": any decimal digit, only once.

Example strings/patterns: String: monkey.s01 Pattern: monkey.s?? => true String: monkey.s101 Pattern: monkey.s?? => false String: monkey.s99 Pattern: monkey.s?1 => false String: monkey.s101 Pattern: monkey.s* => true String: monkey.s99 Pattern: monkey.s*1 => false String: monkey.s01 Pattern: monkey.s## => true String: monkey.s01 Pattern: monkey.### => false

Parameters

str	Text to be matched against the given pattern.
pat	Glob pattern.
ignoreCase	Whether to ignore the case when doing pattern match
wildcardExclusions	Characters which are excluded from wildcards and must be matched explicitly.

Returns

true if str matches the pattern, false otherwise.

replace()

void Common::replace	(	Common::String &	source,
		const Common::String &	what,
		const Common::String &	with
	)

Function which replaces substring with the other. It happens in place. If there is no substring found, original string is not changed.

Parameters

source	String to search and replace substring in.
what	Substring to replace.
with	String to replace with.

tag2string()

String Common::tag2string	(	uint32	tag,
		bool	nonPrintable = false
	)

Take a 32 bit value and turn it into a four character string, where each of the four bytes is turned into one character. Most significant byte is printed first.

Parameters

tag	tag value to convert
nonPrintable	indicate if non-printable characters need to be printed as octals

strcpy_s() [1/2]

void Common::strcpy_s	(	char *	dst,
		size_t	size,
		const char *	src
	)

Copy up to size - 1 characters from src to dst and also zero terminate the result. Note that src must be a zero terminated string.

Note

This is modeled after strcpy_s from C11 but simplified by using warning instead of erroring out

Parameters

dst	The destination buffer.
size	The size of the destination buffer.
src	The source string.

strcpy_s() [2/2]

template<typename T , size_t N>

FORCEINLINE void Common::strcpy_s	(	T(&)	dst[N],
		const char *	src
	)

Copy up to N - 1 characters from src to dst and also zero terminate the result. Note that src must be a zero terminated string.

Note

This is modeled after strcpy_s from C11 but simplified by using warning instead of erroring out

Parameters

dst	The destination buffer as a reference to a constant size array.
src	The source string.

strcat_s() [1/2]

void Common::strcat_s	(	char *	dst,
		size_t	size,
		const char *	src
	)

Append the string src to the string dst. Note that both src and dst must be zero terminated. The result will be zero terminated. At most "size - strlen(dst) - 1" bytes will be appended.

Note

This is modeled after strcpy_s from C11 but simplified by using warning instead of erroring out

Parameters

dst	The string the source string should be appended to.
size	The (total) size of the destination buffer.
src	The source string.

strcat_s() [2/2]

template<typename T , size_t N>

FORCEINLINE void Common::strcat_s	(	T(&)	dst[N],
		const char *	src
	)

Append the string src to the string dst. Note that both src and dst must be zero terminated. The result will be zero terminated. At most "N - strlen(dst) - 1" bytes will be appended.

Note

This is modeled after strcat_s from C11 but simplified by using warning instead of erroring out

Parameters

dst	The string the source string should be appended to as a reference to a constant size array.
src	The source string.

vsprintf_s()

int Common::vsprintf_s	(	char *	dst,
		size_t	size,
		const char *	format,
		va_list	ap
	)

A sprintf shim which warns when the buffer overruns and null terminates in this case

Parameters

dst	Where the resulting string will be storeyyd.
size	The (total) size of the destination buffer.
format	The format string.

GCC_PRINTF() [1/2]

template<typename T , size_t N>

int FORCEINLINE Common::GCC_PRINTF	(	2	,
		0
	)		)[N] &

A sprintf shim which warns when the buffer overruns and null terminates in this case The size of the buffer is automatically determined.

Parameters

dst	Where the resulting string will be storeyyd.
format	The format string.

sprintf_s()

int Common::sprintf_s	(	char *	dst,
		size_t	size,
		MSVC_PRINTF const char *	format,
			...
	)

A sprintf shim which warns when the buffer overruns and null terminates in this case

Parameters

dst	Where the resulting string will be stored.
size	The (total) size of the destination buffer.
format	The format string.

GCC_PRINTF() [2/2]

template<typename T , size_t N>

int Common::GCC_PRINTF ( 2  , 3    ) )[N] &

inline

A sprintf shim which warns when the buffer overruns and null terminates in this case The size of the buffer is automatically determined.

Parameters

dst	Where the resulting string will be storeyyd.
format	The format string.

strlcpy()

size_t Common::strlcpy	(	char *	dst,
		const char *	src,
		size_t	size
	)

Copy up to size - 1 characters from src to dst and also zero terminate the result. Note that src must be a zero terminated string.

In case size is zero this function just returns the length of the source string.

Note

This is modeled after OpenBSD's strlcpy. See the manpage here: https://man.openbsd.org/strlcpy

Parameters

dst	The destination buffer.
src	The source string.
size	The size of the destination buffer.

Returns

The length of the (non-truncated) result, i.e. strlen(src).

strlcat()

size_t Common::strlcat	(	char *	dst,
		const char *	src,
		size_t	size
	)

Append the string src to the string dst. Note that both src and dst must be zero terminated. The result will be zero terminated. At most "size - strlen(dst) - 1" bytes will be appended.

In case the dst string does not contain a zero within the first "size" bytes the dst string will not be changed and size + strlen(src) is returned.

Note

This is modeled after OpenBSD's strlcat. See the manpage here: https://man.openbsd.org/strlcat

Parameters

dst	The string the source string should be appended to.
src	The source string.
size	The (total) size of the destination buffer.

Returns

The length of the (non-truncated) result. That is strlen(dst) + strlen(src). In case strlen(dst) > size size + strlen(src) is returned.

strnlen()

size_t Common::strnlen	(	const char *	src,
		size_t	maxSize
	)

Determine the length of a string up to a maximum of maxSize characters. This should be used instead of strlen when reading the length of a C string from potentially unsafe or corrupt sources, like game assets.

Parameters

src	The source string.
maxSize	The maximum size of the string.

Returns

The length of the string.

toPrintable()

String Common::toPrintable	(	const String &	src,
		bool	keepNewLines = true
	)

Converts string with all non-printable characters properly escaped with use of C++ escape sequences

Parameters

src	The source string.
keepNewLines	Whether keep newlines or convert them to ' ', default: true.

Returns

The converted string.

Variable Documentation

ap

va_list Common::ap

Initial value:

{
    STATIC_ASSERT(sizeof(T) == sizeof(char), T_is_not_compatible_with_char)

ret

return Common::ret

Initial value:

{
    STATIC_ASSERT(sizeof(T) == sizeof(char), T_is_not_compatible_with_char)