String Functions¶

API: String Functions

API

Functions
bool	opp_isempty (const char *s)
	Returns true if the string is nullptr or has zero length.
const char *	opp_nulltoempty (const char *s)
	Returns the pointer passed as argument unchanged, except that if it was nullptr, it returns a pointer to a null string ("").
const char *	opp_emptytodefault (const char s, const char defaultString)
	Returns the pointer passed as argument unchanged, except that if it was empty, it returns the second argument.
SIM_API bool	opp_isblank (const char *txt)
	Returns true if the string only contains whitespace.
int	opp_strlen (const char *s)
	Same as the standard strlen() function, except that does not crash on nullptr but returns 0.
char *	opp_strdup (const char *s)
	Duplicates the string, using new char[]. For nullptr and empty strings it returns nullptr.
char *	opp_strcpy (char s1, const char s2)
	Same as the standard strcpy() function, except that nullptr in the second argument is treated as a pointer to an empty string ("").
int	opp_strcmp (const char s1, const char s2)
	Same as the standard strcmp() function, except that nullptr is treated exactly as an empty string ("").
SIM_API std::string	opp_trim (const std::string &text)
	Removes any leading and trailing whitespace.
SIM_API char *	opp_strprettytrunc (char dest, const char src, unsigned maxlen)
	Copies src string into dest, and if its length would exceed maxlen, it is truncated with an ellipsis. For example, opp_strprettytrunc(buf,"long-long",6) yields "lon...".
SIM_API std::string	opp_stringf (const char *fmt,...)
	Create a string using printf-like formatting. Allocates storage dynamically.
SIM_API std::string	opp_vstringf (const char *fmt, va_list &args)
	Create a string using printf-like formatting. Allocates storage dynamically.
SIM_API std::string	opp_replacesubstring (const std::string &text, const std::string &substring, const std::string &replacement, bool replaceAll)
	Performs find/replace within a string.
SIM_API std::vector< std::string >	opp_splitandtrim (const std::string &text)
	Split a string into parts by whitespace sequences. Returned items will have no leading or trailing whitespace. Returns an empty array if the input string is empty or only contains whitespace.
SIM_API std::vector< std::string >	opp_split (const std::string &text, const std::string &separator)
	Split a string into parts separated by the given separator. If the input string is empty, it returns an empty array. Otherwise, it returns exactly #separators+1 items. The separator cannot be empty.
SIM_API std::vector< std::string >	opp_splitandtrim (const std::string &text, const std::string &separator)
	Split a string into parts separated by the given separator, trimming each item of whitespace. Returns an empty array if the input string doesn't contain anything but whitespace. The separator cannot be empty.
SIM_API bool	opp_stringbeginswith (const char s, const char prefix)
	Returns true if the first string begins with the second string.
SIM_API bool	opp_stringendswith (const char s, const char ending)
	Returns true if the first string ends in the second string.
SIM_API std::string	opp_substringbefore (const std::string &str, const std::string &substr)
	Returns the substring up to the first occurrence of the given substring, or "".
SIM_API std::string	opp_substringafter (const std::string &str, const std::string &substr)
	Returns the substring after the first occurrence of the given substring, or "".
SIM_API std::string	opp_substringbeforelast (const std::string &str, const std::string &substr)
	Returns the substring up to the last occurrence of the given substring, or "".
SIM_API std::string	opp_substringafterlast (const std::string &str, const std::string &substr)
	Returns the substring after the last occurrence of the given substring, or "".
SIM_API std::string	opp_removestart (const std::string &str, const std::string &prefix)
	Remove the prefix if the s string starts with it, otherwise return the string unchanged.
SIM_API std::string	opp_removeend (const std::string &str, const std::string &end)
	Remove the given end string if the s string ends with it, otherwise return the string unchanged.
SIM_API std::string	opp_strlower (const char *s)
	Converts the string to lower case, and returns the result.
SIM_API std::string	opp_strupper (const char *s)
	Converts the string to upper case, and returns the result.
SIM_API const char *	opp_strnistr (const char haystack, const char needle, int n, bool caseSensitive)
	Locates the first occurrence of the nul-terminated string needle in the string haystack, where not more than n characters are searched. Characters that appear after a '\0' character are not searched.
SIM_API int	opp_strdictcmp (const char s1, const char s2)
	Dictionary-compare two strings, the main difference from strcasecmp() being that integers embedded in the strings are compared in numerical order.
SIM_API std::string	opp_join (const char separator, const char s1, const char *s2)
	If either s1 or s2 is empty, returns the other one, otherwise returns s1 + separator + s2.
SIM_API std::string	opp_join (const char *separator, const std::string &s1, const std::string &s2)
	If either s1 or s2 is empty, returns the other one, otherwise returns s1 + separator + s2.
SIM_API std::string	opp_join (const char *strings, const char separator, bool skipEmpty=false, char quoteChar=0)
	Concatenate the strings passed in the nullptr-terminated const char * array, using the given separator and putting each item between quoteChars unless it is '\0'. Empty elements are optionally skipped.
SIM_API std::string	opp_join (const char *strings, int n, const char separator, bool skipEmpty=false, char quoteChar=0)
	Concatenate the strings passed in the const char * array of size n, using the given separator and putting each item between quoteChars unless it is '\0'. Empty elements are optionally skipped.
SIM_API std::string	opp_join (const std::vector< std::string > &strings, const char *separator, bool skipEmpty=false, char quoteChar=0)
	Concatenate the strings passed in the vector, using the given separator, and putting each item between quoteChars unless it is '\0'. Empty elements are optionally skipped.
SIM_API char *	opp_itoa (char *buf, int d)
	Prints the d integer into the given buffer, then returns the buffer pointer.
SIM_API char *	opp_ltoa (char *buf, long d)
	Prints the d integer into the given buffer, then returns the buffer pointer.
SIM_API char *	opp_i64toa (char *buf, int64_t d)
	Prints the d integer into the given buffer, then returns the buffer pointer.
SIM_API char *	opp_dtoa (char *buf, double d, int numSignificantDigits=6)
	Prints the d double into the given buffer, then returns the buffer pointer. Uses std::to_chars for locale-independent formatting. If numSignificantDigits is >= 17, the shortest round-trip representation is used; otherwise the value is formatted with the given number of significant digits (like printf's "%.*g"). Non-finite values are printed as "inf", "-inf" or "nan".
SIM_API char *	opp_dtoa (char buf, const char format, double d)
	Prints the d double into the given buffer, then returns the buffer pointer. If d is finite, the given printf format is used (e.g. "%g"), otherwise it prints "inf", "-inf" or "nan". (Note that printf's handling of NaN and infinity is platform-dependent, e.g. MSVC produces "1.#QNAN" and "1.#INF".)
SIM_API long	opp_strtol (const char s, char *endptr)
	Like the standard strtol(), but throws opp_runtime_error if an overflow occurs during conversion. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).
SIM_API long	opp_atol (const char *s)
	Like the standard atol(), but throws opp_runtime_error if an overflow occurs during conversion, or if there is (non-whitespace) trailing garbage after the number. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).
SIM_API unsigned long	opp_strtoul (const char s, char *endptr)
	Like the standard strtoul(), but throws opp_runtime_error if an overflow occurs during conversion. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).
SIM_API unsigned long	opp_atoul (const char *s)
	Like the standard atol(), but for unsigned long, and throws opp_runtime_error if an overflow occurs during conversion, or if there is (non-whitespace) trailing garbage after the number. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).
SIM_API long long	opp_strtoll (const char s, char *endptr)
	Like the standard strtoll(), but throws opp_runtime_error if an overflow occurs during conversion. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).
SIM_API long long	opp_atoll (const char *s)
	Like the standard atoll(), but throws opp_runtime_error if an overflow occurs during conversion, or if there is (non-whitespace) trailing garbage after the number. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).
SIM_API unsigned long long	opp_strtoull (const char s, char *endptr)
	Like the standard strtoull(), but throws opp_runtime_error if an overflow occurs during conversion. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).
SIM_API unsigned long long	opp_atoull (const char *s)
	Like the standard atoull(), but throws opp_runtime_error if an overflow occurs during conversion, or if there is (non-whitespace) trailing garbage after the number. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).
SIM_API double	opp_strtod (const char s, char *endptr)
	Like the standard strtod(), but throws opp_runtime_error if an overflow occurs during conversion.
SIM_API double	opp_atof (const char *s)
	Like the standard atof(), but throws opp_runtime_error if an overflow occurs during conversion, or if there is (non-whitespace) trailing garbage after the number.

Description

Miscellaneous string-related utility functions.

Function Documentation

◆ opp_isempty()

bool opp_isempty ( const char * s )

inline

Returns true if the string is nullptr or has zero length.

Referenced by opp_emptytodefault().

◆ opp_nulltoempty()

const char * opp_nulltoempty ( const char * s )

inline

Returns the pointer passed as argument unchanged, except that if it was nullptr, it returns a pointer to a null string ("").

◆ opp_emptytodefault()

const char * opp_emptytodefault	(	const char *	s,
		const char *	defaultString )

inline

Returns the pointer passed as argument unchanged, except that if it was empty, it returns the second argument.

References opp_isempty().

◆ opp_isblank()

SIM_API bool opp_isblank ( const char * txt )

Returns true if the string only contains whitespace.

◆ opp_strlen()

int opp_strlen ( const char * s )

inline

Same as the standard strlen() function, except that does not crash on nullptr but returns 0.

◆ opp_strdup()

char * opp_strdup ( const char * s )

inline

Duplicates the string, using new char[]. For nullptr and empty strings it returns nullptr.

◆ opp_strcpy()

char * opp_strcpy	(	char *	s1,
		const char *	s2 )

inline

Same as the standard strcpy() function, except that nullptr in the second argument is treated as a pointer to an empty string ("").

◆ opp_strcmp()

int opp_strcmp	(	const char *	s1,
		const char *	s2 )

inline

Same as the standard strcmp() function, except that nullptr is treated exactly as an empty string ("").

◆ opp_trim()

SIM_API std::string opp_trim ( const std::string & text )

Removes any leading and trailing whitespace.

◆ opp_strprettytrunc()

SIM_API char * opp_strprettytrunc	(	char *	dest,
		const char *	src,
		unsigned	maxlen )

Copies src string into dest, and if its length would exceed maxlen, it is truncated with an ellipsis. For example, opp_strprettytrunc(buf,"long-long",6) yields "lon...".

◆ opp_stringf()

SIM_API std::string opp_stringf	(	const char *	fmt,
			... )

Create a string using printf-like formatting. Allocates storage dynamically.

References opp_stringf().

Referenced by opp_stringf().

◆ opp_vstringf()

SIM_API std::string opp_vstringf	(	const char *	fmt,
		va_list &	args )

Create a string using printf-like formatting. Allocates storage dynamically.

References opp_vstringf().

Referenced by opp_vstringf().

◆ opp_replacesubstring()

SIM_API std::string opp_replacesubstring	(	const std::string &	text,
		const std::string &	substring,
		const std::string &	replacement,
		bool	replaceAll )

Performs find/replace within a string.

References opp_replacesubstring().

Referenced by opp_replacesubstring().

◆ opp_splitandtrim() [1/2]

SIM_API std::vector< std::string > opp_splitandtrim ( const std::string & text )

Split a string into parts by whitespace sequences. Returned items will have no leading or trailing whitespace. Returns an empty array if the input string is empty or only contains whitespace.

References opp_splitandtrim().

Referenced by opp_splitandtrim(), and opp_splitandtrim().

◆ opp_split()

SIM_API std::vector< std::string > opp_split	(	const std::string &	text,
		const std::string &	separator )

Split a string into parts separated by the given separator. If the input string is empty, it returns an empty array. Otherwise, it returns exactly #separators+1 items. The separator cannot be empty.

References opp_split().

Referenced by opp_split().

◆ opp_splitandtrim() [2/2]

SIM_API std::vector< std::string > opp_splitandtrim	(	const std::string &	text,
		const std::string &	separator )

Split a string into parts separated by the given separator, trimming each item of whitespace. Returns an empty array if the input string doesn't contain anything but whitespace. The separator cannot be empty.

References opp_splitandtrim().

◆ opp_stringbeginswith()

SIM_API bool opp_stringbeginswith	(	const char *	s,
		const char *	prefix )

Returns true if the first string begins with the second string.

References opp_stringbeginswith().

Referenced by opp_stringbeginswith().

◆ opp_stringendswith()

SIM_API bool opp_stringendswith	(	const char *	s,
		const char *	ending )

Returns true if the first string ends in the second string.

References opp_stringendswith().

Referenced by opp_stringendswith().

◆ opp_substringbefore()

SIM_API std::string opp_substringbefore	(	const std::string &	str,
		const std::string &	substr )

Returns the substring up to the first occurrence of the given substring, or "".

References opp_substringbefore().

Referenced by opp_substringbefore().

◆ opp_substringafter()

SIM_API std::string opp_substringafter	(	const std::string &	str,
		const std::string &	substr )

Returns the substring after the first occurrence of the given substring, or "".

References opp_substringafter().

Referenced by opp_substringafter().

◆ opp_substringbeforelast()

SIM_API std::string opp_substringbeforelast	(	const std::string &	str,
		const std::string &	substr )

Returns the substring up to the last occurrence of the given substring, or "".

References opp_substringbeforelast().

Referenced by opp_substringbeforelast().

◆ opp_substringafterlast()

SIM_API std::string opp_substringafterlast	(	const std::string &	str,
		const std::string &	substr )

Returns the substring after the last occurrence of the given substring, or "".

References opp_substringafterlast().

Referenced by opp_substringafterlast().

◆ opp_removestart()

SIM_API std::string opp_removestart	(	const std::string &	str,
		const std::string &	prefix )

Remove the prefix if the s string starts with it, otherwise return the string unchanged.

References opp_removestart().

Referenced by opp_removestart().

◆ opp_removeend()

SIM_API std::string opp_removeend	(	const std::string &	str,
		const std::string &	end )

Remove the given end string if the s string ends with it, otherwise return the string unchanged.

References opp_removeend().

Referenced by opp_removeend().

◆ opp_strlower()

SIM_API std::string opp_strlower ( const char * s )

Converts the string to lower case, and returns the result.

References opp_strlower().

Referenced by opp_strlower().

◆ opp_strupper()

SIM_API std::string opp_strupper ( const char * s )

Converts the string to upper case, and returns the result.

References opp_strupper().

Referenced by opp_strupper().

◆ opp_strnistr()

SIM_API const char * opp_strnistr	(	const char *	haystack,
		const char *	needle,
		int	n,
		bool	caseSensitive )

Locates the first occurrence of the nul-terminated string needle in the string haystack, where not more than n characters are searched. Characters that appear after a '\0' character are not searched.

References opp_strnistr().

Referenced by opp_strnistr().

◆ opp_strdictcmp()

SIM_API int opp_strdictcmp	(	const char *	s1,
		const char *	s2 )

Dictionary-compare two strings, the main difference from strcasecmp() being that integers embedded in the strings are compared in numerical order.

References opp_strdictcmp().

Referenced by opp_strdictcmp().

◆ opp_join() [1/5]

SIM_API std::string opp_join	(	const char *	separator,
		const char *	s1,
		const char *	s2 )

If either s1 or s2 is empty, returns the other one, otherwise returns s1 + separator + s2.

References opp_join().

Referenced by opp_join(), opp_join(), opp_join(), opp_join(), and opp_join().

◆ opp_join() [2/5]

SIM_API std::string opp_join	(	const char *	separator,
		const std::string &	s1,
		const std::string &	s2 )

If either s1 or s2 is empty, returns the other one, otherwise returns s1 + separator + s2.

References opp_join().

◆ opp_join() [3/5]

SIM_API std::string opp_join	(	const char **	strings,
		const char *	separator,
		bool	skipEmpty = false,
		char	quoteChar = 0 )

Concatenate the strings passed in the nullptr-terminated const char * array, using the given separator and putting each item between quoteChars unless it is '\0'. Empty elements are optionally skipped.

References opp_join().

◆ opp_join() [4/5]

SIM_API std::string opp_join	(	const char **	strings,
		int	n,
		const char *	separator,
		bool	skipEmpty = false,
		char	quoteChar = 0 )

Concatenate the strings passed in the const char * array of size n, using the given separator and putting each item between quoteChars unless it is '\0'. Empty elements are optionally skipped.

References opp_join().

◆ opp_join() [5/5]

SIM_API std::string opp_join	(	const std::vector< std::string > &	strings,
		const char *	separator,
		bool	skipEmpty = false,
		char	quoteChar = 0 )

Concatenate the strings passed in the vector, using the given separator, and putting each item between quoteChars unless it is '\0'. Empty elements are optionally skipped.

References opp_join().

◆ opp_itoa()

SIM_API char * opp_itoa	(	char *	buf,
		int	d )

Prints the d integer into the given buffer, then returns the buffer pointer.

References opp_itoa().

Referenced by opp_itoa().

◆ opp_ltoa()

SIM_API char * opp_ltoa	(	char *	buf,
		long	d )

Prints the d integer into the given buffer, then returns the buffer pointer.

References opp_ltoa().

Referenced by opp_ltoa().

◆ opp_i64toa()

SIM_API char * opp_i64toa	(	char *	buf,
		int64_t	d )

Prints the d integer into the given buffer, then returns the buffer pointer.

References opp_i64toa().

Referenced by opp_i64toa().

◆ opp_dtoa() [1/2]

SIM_API char * opp_dtoa	(	char *	buf,
		double	d,
		int	numSignificantDigits = 6 )

Prints the d double into the given buffer, then returns the buffer pointer. Uses std::to_chars for locale-independent formatting. If numSignificantDigits is >= 17, the shortest round-trip representation is used; otherwise the value is formatted with the given number of significant digits (like printf's "%.*g"). Non-finite values are printed as "inf", "-inf" or "nan".

References opp_dtoa().

Referenced by opp_dtoa(), and opp_dtoa().

◆ opp_dtoa() [2/2]

SIM_API char * opp_dtoa	(	char *	buf,
		const char *	format,
		double	d )

Prints the d double into the given buffer, then returns the buffer pointer. If d is finite, the given printf format is used (e.g. "%g"), otherwise it prints "inf", "-inf" or "nan". (Note that printf's handling of NaN and infinity is platform-dependent, e.g. MSVC produces "1.#QNAN" and "1.#INF".)

Deprecated: Use the format-free overload instead.

References opp_dtoa().

◆ opp_strtol()

SIM_API long opp_strtol	(	const char *	s,
		char **	endptr )

Like the standard strtol(), but throws opp_runtime_error if an overflow occurs during conversion. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).

References opp_strtol().

Referenced by opp_strtol().

◆ opp_atol()

SIM_API long opp_atol ( const char * s )

Like the standard atol(), but throws opp_runtime_error if an overflow occurs during conversion, or if there is (non-whitespace) trailing garbage after the number. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).

References opp_atol().

Referenced by opp_atol().

◆ opp_strtoul()

SIM_API unsigned long opp_strtoul	(	const char *	s,
		char **	endptr )

Like the standard strtoul(), but throws opp_runtime_error if an overflow occurs during conversion. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).

References opp_strtoul().

Referenced by opp_strtoul().

◆ opp_atoul()

SIM_API unsigned long opp_atoul ( const char * s )

Like the standard atol(), but for unsigned long, and throws opp_runtime_error if an overflow occurs during conversion, or if there is (non-whitespace) trailing garbage after the number. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).

References opp_atoul().

Referenced by opp_atoul().

◆ opp_strtoll()

SIM_API long long opp_strtoll	(	const char *	s,
		char **	endptr )

Like the standard strtoll(), but throws opp_runtime_error if an overflow occurs during conversion. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).

References opp_strtoll().

Referenced by opp_strtoll().

◆ opp_atoll()

SIM_API long long opp_atoll ( const char * s )

Like the standard atoll(), but throws opp_runtime_error if an overflow occurs during conversion, or if there is (non-whitespace) trailing garbage after the number. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).

References opp_atoll().

Referenced by opp_atoll().

◆ opp_strtoull()

SIM_API unsigned long long opp_strtoull	(	const char *	s,
		char **	endptr )

Like the standard strtoull(), but throws opp_runtime_error if an overflow occurs during conversion. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).

References opp_strtoull().

Referenced by opp_strtoull().

◆ opp_atoull()

SIM_API unsigned long long opp_atoull ( const char * s )

Like the standard atoull(), but throws opp_runtime_error if an overflow occurs during conversion, or if there is (non-whitespace) trailing garbage after the number. Accepts decimal and C-style hexadecimal notation, but not octal (leading zeroes are simply discarded and the number is interpreted as decimal).

References opp_atoull().

Referenced by opp_atoull().

◆ opp_strtod()

SIM_API double opp_strtod	(	const char *	s,
		char **	endptr )

Like the standard strtod(), but throws opp_runtime_error if an overflow occurs during conversion.

References opp_strtod().

Referenced by opp_strtod().

◆ opp_atof()

SIM_API double opp_atof ( const char * s )

Like the standard atof(), but throws opp_runtime_error if an overflow occurs during conversion, or if there is (non-whitespace) trailing garbage after the number.

References opp_atof().

Referenced by opp_atof().