Strutil Namespace Reference

String-related utilities. More...

Namespaces
	fmt
	old
	pvt
	sync

Classes
class	StringHash
struct	StringEqual
	C++ functor for comparing two strings for equality of their characters. More...
struct	StringIEqual
struct	StringLess
	C++ functor for comparing the ordering of two strings. More...
struct	StringILess

Enumerations
enum	QuoteBehavior { DeleteQuotes, KeepQuotes }
enum	EditDistMetric { EditDistMetric::Levenshtein }

Functions
void OIIO_UTIL_API	sync_output (FILE *file, string_view str, bool flush=true)
void OIIO_UTIL_API	sync_output (std::ostream &file, string_view str, bool flush=true)
template<typename... Args>
void	printf (const char *fmt, const Args &...args)
template<typename... Args>
void	fprintf (FILE *file, const char *fmt, const Args &...args)
template<typename... Args>
void	fprintf (std::ostream &file, const char *fmt, const Args &...args)
template<typename... Args>
void	debug (const char *fmt, Args &&...args)
std::string OIIO_UTIL_API	vsprintf (const char *fmt, va_list ap)
std::string OIIO_UTIL_API	vformat (const char *fmt, va_list ap)
std::string OIIO_UTIL_API	memformat (long long bytes, int digits=1)
std::string OIIO_UTIL_API	timeintervalformat (double secs, int digits=1)
bool OIIO_UTIL_API	get_rest_arguments (const std::string &str, std::string &base, std::map< std::string, std::string > &result)
std::string OIIO_UTIL_API	escape_chars (string_view unescaped)
std::string OIIO_UTIL_API	unescape_chars (string_view escaped)
std::string OIIO_UTIL_API	wordwrap (string_view src, int columns=80, int prefix=0, string_view sep=" ", string_view presep="")
constexpr size_t	strhash (size_t len, const char *s)
constexpr uint64_t	strhash64 (size_t len, const char *s)
	A guaranteed 64-bit string hash on all platforms. More...
constexpr size_t	strhash (string_view s)
constexpr uint64_t	strhash64 (string_view s)
	Hash a string_view, guaranteed 64 bits (even on 32 bit platforms). More...
bool OIIO_UTIL_API	iequals (string_view a, string_view b)
bool OIIO_UTIL_API	iless (string_view a, string_view b)
bool OIIO_UTIL_API	starts_with (string_view a, string_view b)
	Does 'a' start with the string 'b', with a case-sensitive comparison? More...
bool OIIO_UTIL_API	istarts_with (string_view a, string_view b)
bool OIIO_UTIL_API	ends_with (string_view a, string_view b)
	Does 'a' end with the string 'b', with a case-sensitive comparison? More...
bool OIIO_UTIL_API	iends_with (string_view a, string_view b)
size_t OIIO_UTIL_API	find (string_view a, string_view b)
size_t OIIO_UTIL_API	ifind (string_view a, string_view b)
size_t OIIO_UTIL_API	rfind (string_view a, string_view b)
size_t OIIO_UTIL_API	irfind (string_view a, string_view b)
bool OIIO_UTIL_API	contains (string_view a, string_view b)
	Does 'a' contain the string 'b' within it? More...
bool OIIO_UTIL_API	icontains (string_view a, string_view b)
bool	rcontains (string_view a, string_view b)
bool	ircontains (string_view a, string_view b)
bool OIIO_UTIL_API	contains_any_char (string_view a, string_view set)
	Does 'a' contain any of the characters within set? More...
void OIIO_UTIL_API	to_lower (std::string &a)
void OIIO_UTIL_API	to_upper (std::string &a)
std::string	lower (string_view a)
	Return an all-upper case version of a (locale-independent). More...
std::string	upper (string_view a)
	Return an all-upper case version of a (locale-independent). More...
string_view OIIO_UTIL_API	strip (string_view str, string_view chars=string_view())
string_view OIIO_UTIL_API	lstrip (string_view str, string_view chars=string_view())
string_view OIIO_UTIL_API	rstrip (string_view str, string_view chars=string_view())
void OIIO_UTIL_API	split (string_view str, std::vector< string_view > &result, string_view sep=string_view(), int maxsplit=-1)
void OIIO_UTIL_API	split (string_view str, std::vector< std::string > &result, string_view sep=string_view(), int maxsplit=-1)
OIIO_UTIL_API std::vector < std::string >	splits (string_view str, string_view sep="", int maxsplit=-1)
OIIO_UTIL_API std::vector < string_view >	splitsv (string_view str, string_view sep="", int maxsplit=-1)
template<class Sequence >
std::string	join (const Sequence &seq, string_view sep="")
template<class Sequence >
std::string	join (const Sequence &seq, string_view sep, size_t len)
std::string OIIO_UTIL_API	concat (string_view s, string_view t)
std::string OIIO_UTIL_API	repeat (string_view str, int n)
	Repeat a string formed by concatenating str n times. More...
std::string OIIO_UTIL_API	replace (string_view str, string_view pattern, string_view replacement, bool global=false)
float OIIO_UTIL_API	strtof (const char *nptr, char **endptr=nullptr) noexcept
double OIIO_UTIL_API	strtod (const char *nptr, char **endptr=nullptr) noexcept
OIIO_UTIL_API int	stoi (string_view s, size_t *pos=0, int base=10)
OIIO_UTIL_API unsigned int	stoui (string_view s, size_t *pos=0, int base=10)
OIIO_UTIL_API float	stof (string_view s, size_t *pos=0)
OIIO_UTIL_API float	stof (const std::string &s, size_t *pos=0)
OIIO_UTIL_API float	stof (const char *s, size_t *pos=0)
OIIO_UTIL_API double	stod (string_view s, size_t *pos=0)
OIIO_UTIL_API double	stod (const std::string &s, size_t *pos=0)
OIIO_UTIL_API double	stod (const char *s, size_t *pos=0)
OIIO_UTIL_API bool	string_is_int (string_view s)
OIIO_UTIL_API bool	string_is_float (string_view s)
template<typename T >
T	from_string (string_view s)
template<>
int	from_string< int > (string_view s)
template<>
unsigned int	from_string< unsigned int > (string_view s)
template<>
float	from_string< float > (string_view s)
template<>
double	from_string< double > (string_view s)
template<>
int64_t	from_string< int64_t > (string_view s)
template<>
uint64_t	from_string< uint64_t > (string_view s)
template<typename T >
std::string	to_string (const T &value)
std::string	to_string (const std::string &value)
std::string	to_string (string_view value)
std::string	to_string (const char *value)
template<typename T >
bool	string_is (string_view)
template<>
bool	string_is< int > (string_view s)
template<>
bool	string_is< float > (string_view s)
template<class T , class Allocator >
int	extract_from_list_string (std::vector< T, Allocator > &vals, string_view list, string_view sep=",")
template<class T >
std::vector< T >	extract_from_list_string (string_view list, size_t nvals=0, T val=T(), string_view sep=",")
OIIO_UTIL_API bool	scan_datetime (string_view str, int &year, int &month, int &day, int &hour, int &min, int &sec)
std::wstring OIIO_UTIL_API	utf8_to_utf16wstring (string_view utf8str) noexcept
std::wstring OIIO_UTIL_API	utf8_to_utf16 (string_view utf8str) noexcept
std::string OIIO_UTIL_API	utf16_to_utf8 (const std::wstring &utf16str) noexcept
std::string OIIO_UTIL_API	utf16_to_utf8 (const std::u16string &utf16str) noexcept
	Conversion from UTF-16 std::u16string to a UTF-8 std::string. More...
OIIO_UTIL_API char *	safe_strcpy (char *dst, string_view src, size_t size) noexcept
OIIO_UTIL_API char *	safe_strcat (char *dst, string_view src, size_t size) noexcept
OIIO_UTIL_API size_t	safe_strlen (const char *str, size_t size) noexcept
string_view	safe_string_view (const char *str, size_t size) noexcept
std::string	safe_string (const char *str, size_t size)
bool	isspace (char c)
void OIIO_UTIL_API	skip_whitespace (string_view &str) noexcept
void OIIO_UTIL_API	remove_trailing_whitespace (string_view &str) noexcept
void	trim_whitespace (string_view &str) noexcept
string_view	trimmed_whitespace (string_view str) noexcept
bool OIIO_UTIL_API	parse_char (string_view &str, char c, bool skip_whitespace=true, bool eat=true) noexcept
bool OIIO_UTIL_API	parse_until_char (string_view &str, char c, bool eat=true) noexcept
bool OIIO_UTIL_API	parse_prefix (string_view &str, string_view prefix, bool eat=true) noexcept
bool OIIO_UTIL_API	parse_int (string_view &str, int &val, bool eat=true) noexcept
bool OIIO_UTIL_API	parse_float (string_view &str, float &val, bool eat=true) noexcept
bool	parse_value (string_view &str, float &val, bool eat=true) noexcept
	Synonym for parse_int. More...
bool	parse_value (string_view &str, int &val, bool eat=true) noexcept
	Synonym for parse_float. More...
bool OIIO_UTIL_API	parse_values (string_view &str, string_view prefix, span< int > values, string_view sep="", string_view postfix="", bool eat=true) noexcept
bool OIIO_UTIL_API	parse_values (string_view &str, string_view prefix, span< float > values, string_view sep="", string_view postfix="", bool eat=true) noexcept
	parse_values for float. More...
bool	scan_values (string_view str, string_view prefix, span< int > values, string_view sep="", string_view postfix="") noexcept
bool	scan_values (string_view str, string_view prefix, span< float > values, string_view sep="", string_view postfix="") noexcept
bool OIIO_UTIL_API	parse_string (string_view &str, string_view &val, bool eat=true, QuoteBehavior keep_quotes=DeleteQuotes) noexcept
string_view OIIO_UTIL_API	parse_word (string_view &str, bool eat=true) noexcept
string_view OIIO_UTIL_API	parse_identifier (string_view &str, bool eat=true) noexcept
string_view OIIO_UTIL_API	parse_identifier (string_view &str, string_view allowed, bool eat=true) noexcept
bool OIIO_UTIL_API	parse_identifier_if (string_view &str, string_view id, bool eat=true) noexcept
string_view OIIO_UTIL_API	parse_until (string_view &str, string_view set=" \t\r\n", bool eat=true) noexcept
string_view OIIO_UTIL_API	parse_while (string_view &str, string_view set, bool eat=true) noexcept
string_view OIIO_UTIL_API	parse_line (string_view &str, bool eat=true) noexcept
string_view OIIO_UTIL_API	parse_nested (string_view &str, bool eat=true) noexcept
bool	string_is_identifier (string_view str)
	Does the string follow the lexical rule of a C identifier? More...
OIIO_UTIL_API std::string	excise_string_after_head (std::string &str, string_view head)
void OIIO_UTIL_API	utf8_to_unicode (string_view str, std::vector< uint32_t > &uvec)
std::string OIIO_UTIL_API	base64_encode (string_view str)
OIIO_UTIL_API size_t	edit_distance (string_view a, string_view b, EditDistMetric metric=EditDistMetric::Levenshtein)
OIIO_UTIL_API bool	eval_as_bool (string_view value)
float	stof (ustring s)
template<>
std::string	to_string (const ustring &value)
template<>
std::string	to_string (const ustringhash &value)

Detailed Description

String-related utilities.

Enumeration Type Documentation

enum Strutil::EditDistMetric

strong

Enumerator
Levenshtein

Definition at line 1154 of file strutil.h.

enum Strutil::QuoteBehavior

Enumerator
DeleteQuotes
KeepQuotes

Definition at line 1046 of file strutil.h.

Function Documentation

std::string OIIO_UTIL_API Strutil::base64_encode

(

string_view

str

)

Encode the string in base64. https://en.wikipedia.org/wiki/Base64

std::string OIIO_UTIL_API Strutil::concat	(	string_view	s,
		string_view	t
	)

Concatenate two strings, returning a std::string, implemented carefully to not perform any redundant copies or allocations.

bool OIIO_UTIL_API Strutil::contains	(	string_view	a,
		string_view	b
	)

Does 'a' contain the string 'b' within it?

bool OIIO_UTIL_API Strutil::contains_any_char	(	string_view	a,
		string_view	set
	)

Does 'a' contain any of the characters within set?

template<typename... Args>

void Strutil::debug	(	const char *	fmt,
		Args &&...	args
	)

debug(format, ...) prints debugging message when attribute "debug" is nonzero, which it is by default for DEBUG compiles or when the environment variable OPENIMAGEIO_DEBUG is set. This is preferred to raw output to stderr for debugging statements.

Definition at line 293 of file strutil.h.

OIIO_UTIL_API size_t Strutil::edit_distance	(	string_view	a,
		string_view	b,
		EditDistMetric	metric = EditDistMetric::Levenshtein
	)

Compute an edit distance metric between strings a and b, roughly speaking, the number of changes that would be made to transform one string into the other. Identical strings have a distance of 0. The method selects among possible algorithms, which may have different distance metrics or allow different types of edits. (Currently, the only method supported is Levenshtein; this parameter is for future expansion.)

bool OIIO_UTIL_API Strutil::ends_with	(	string_view	a,
		string_view	b
	)

Does 'a' end with the string 'b', with a case-sensitive comparison?

std::string OIIO_UTIL_API Strutil::escape_chars

(

string_view

unescaped

)

Take a string that may have embedded newlines, tabs, etc., and turn those characters into escape sequences like \n, \t, \v, \b, \r, \f, \a, \\, \".

OIIO_UTIL_API bool Strutil::eval_as_bool

(

string_view

value

)

Evaluate a string as a boolean value using the following heuristic:

• If the string is a valid numeric value (represents an integer or floating point value), return true if it's non-zero, false if it's zero.
• If the string is one of "false", "no", or "off", or if it contains only whitespace, return false.
• All other non-empty strings return true. The comparisons are case-insensitive and ignore leading and trailing whitespace.

OIIO_UTIL_API std::string Strutil::excise_string_after_head	(	std::string &	str,
		string_view	head
	)

Look within str for the pattern: head nonwhitespace_chars whitespace Remove that full pattern from str and return the nonwhitespace part that followed the head (or return the empty string and leave str unmodified, if the head was never found).

template<class T , class Allocator >

int Strutil::extract_from_list_string	(	std::vector< T, Allocator > &	vals,
		string_view	list,
		string_view	sep = ","
	)

Given a string containing values separated by a comma (or optionally another separator), extract the individual values, placing them into vals[] which is presumed to already contain defaults. If only a single value was in the list, replace all elements of vals[] with the value. Otherwise, replace them in the same order. A missing value will simply not be replaced. Return the number of values found in the list (including blank or malformed ones). If the vals vector was empty initially, grow it as necessary.

For example, if T=float, suppose initially, vals[] = {0, 1, 2}, then "3.14" results in vals[] = {3.14, 3.14, 3.14} "3.14,,-2.0" results in vals[] = {3.14, 1, -2.0}

This can work for type T = int, float, or any type for that has an explicit constructor from a std::string.

Definition at line 752 of file strutil.h.

template<class T >

std::vector<T> Strutil::extract_from_list_string	(	string_view	list,
		size_t	nvals = 0,
		T	val = T(),
		string_view	sep = ","
	)

Given a string containing values separated by a comma (or optionally another separator), extract the individual values, returning them as a std::vector<T>. The vector will be initialized with nvals elements with default value val. If only a single value was in the list, replace all elements of vals[] with the value. Otherwise, replace them in the same order. A missing value will simply not be replaced and will retain the initialized default value. If the string contains more then nvals values, they will append to grow the vector.

For example, if T=float, extract_from_list_string ("", 3, 42.0f) –> {42.0, 42.0, 42.0} extract_from_list_string ("3.14", 3, 42.0f) –> {3.14, 3.14, 3.14} extract_from_list_string ("3.14,,-2.0", 3, 42.0f) –> {3.14, 42.0, -2.0} extract_from_list_string ("1,2,3,4", 3, 42.0f) –> {1.0, 2.0, 3.0, 4.0}

This can work for type T = int, float, or any type for that has an explicit constructor from a std::string.

Definition at line 800 of file strutil.h.

size_t OIIO_UTIL_API Strutil::find	(	string_view	a,
		string_view	b
	)

Return the position of the first occurrence of b within a, or std::npos if not found.

template<typename... Args>

void Strutil::fprintf ( FILE *  file, const char *  fmt, const Args &...  args  )

inline

Definition at line 180 of file strutil.h.

template<typename... Args>

void Strutil::fprintf ( std::ostream &  file, const char *  fmt, const Args &...  args  )

inline

Definition at line 186 of file strutil.h.

template<typename T >

T Strutil::from_string ( string_view  s )

inline

Definition at line 663 of file strutil.h.

template<>

double Strutil::from_string< double > ( string_view  s )

inline

Definition at line 683 of file strutil.h.

template<>

float Strutil::from_string< float > ( string_view  s )

inline

Definition at line 678 of file strutil.h.

template<>

int Strutil::from_string< int > ( string_view  s )

inline

Definition at line 669 of file strutil.h.

template<>

int64_t Strutil::from_string< int64_t > ( string_view  s )

inline

Definition at line 687 of file strutil.h.

template<>

uint64_t Strutil::from_string< uint64_t > ( string_view  s )

inline

Definition at line 693 of file strutil.h.

template<>

unsigned int Strutil::from_string< unsigned int > ( string_view  s )

inline

Definition at line 673 of file strutil.h.

bool OIIO_UTIL_API Strutil::get_rest_arguments	(	const std::string &	str,
		std::string &	base,
		std::map< std::string, std::string > &	result
	)

Get a map with RESTful arguments extracted from the given string 'str'. Add it into the 'result' argument (Warning: the 'result' argument may be changed even if 'get_rest_arguments ()' return an error!). Return true on success, false on error. Acceptable forms:

• text?arg1=val1&arg2=val2...
• ?arg1=val1&arg2=val2... Everything before question mark will be saved into the 'base' argument.

bool OIIO_UTIL_API Strutil::icontains	(	string_view	a,
		string_view	b
	)

Does 'a' contain the string 'b' within it, using a case-insensitive comparison? Caveat: the case-sensivive contains() is about 20x faster than this case-insensitive function.

bool OIIO_UTIL_API Strutil::iends_with	(	string_view	a,
		string_view	b
	)

Does 'a' end with the string 'b', with a case-insensitive comparison? For speed, this always uses a static locale that doesn't require a mutex. Caveat: the case-sensivive ends_with() is about 20x faster than this case-insensitive function.

bool OIIO_UTIL_API Strutil::iequals	(	string_view	a,
		string_view	b
	)

Case-insensitive comparison of strings. For speed, this always uses a static locale that doesn't require a mutex. Caveat: the case-sensivive == of string_view's is about 20x faster than this case-insensitive function.

size_t OIIO_UTIL_API Strutil::ifind	(	string_view	a,
		string_view	b
	)

Return the position of the first occurrence of b within a, with a case-insensitive comparison, or std::npos if not found. Caveat: the case-sensivive find() is about 20x faster than this case-insensitive function.

bool OIIO_UTIL_API Strutil::iless	(	string_view	a,
		string_view	b
	)

Case-insensitive ordered comparison of strings. For speed, this always uses a static locale that doesn't require a mutex.

bool Strutil::ircontains ( string_view  a, string_view  b  )

inline

Does 'a' contain the string 'b' within it? But start looking at the end! This can be a bit faster than contains() if you think that the substring b will tend to be close to the end of a. Caveat: the case-sensivive rcontains() is about 20x faster than this case-insensitive function.

Definition at line 477 of file strutil.h.

size_t OIIO_UTIL_API Strutil::irfind	(	string_view	a,
		string_view	b
	)

Return the position of the last occurrence of b within a, with a case-insensitive comparison, or npos if not found. Caveat: the case-sensivive rfind() is about 20x faster than this case-insensitive function.

bool Strutil::isspace ( char  c )

inline

Is the character a whitespace character (space, linefeed, tab, carrage return)? Note: this is safer than C isspace(), which has undefined behavior for negative char values. Also note that it differs from C isspace by not detecting form feed or vertical tab, because who cares.

Definition at line 938 of file strutil.h.

bool OIIO_UTIL_API Strutil::istarts_with	(	string_view	a,
		string_view	b
	)

Does 'a' start with the string 'b', with a case-insensitive comparison? For speed, this always uses a static locale that doesn't require a mutex. Caveat: the case-sensivive starts_with() is about 20x faster than this case-insensitive function.

template<class Sequence >

std::string Strutil::join	(	const Sequence &	seq,
		string_view	sep = ""
	)

Join all the strings in 'seq' into one big string, separated by the 'sep' string. The Sequence can be any iterable collection of items that are able to convert to string via stream output. Examples include: std::vector<string_view>, std::vector<std::string>, std::set<ustring>, std::vector<int>, etc.

Definition at line 552 of file strutil.h.

template<class Sequence >

std::string Strutil::join	(	const Sequence &	seq,
		string_view	sep,
		size_t	len
	)

Join all the strings in 'seq' into one big string, separated by the 'sep' string. The Sequence can be any iterable collection of items that are able to convert to string via stream output. Examples include: std::vector<string_view>, std::vector<std::string>, std::set<ustring>, std::vector<int>, etc. Values will be rendered into the string in a locale-independent manner (i.e., '.' for decimal in floats). If the optional len is nonzero, exactly that number of elements will be output (truncating or default-value-padding the sequence).

Definition at line 575 of file strutil.h.

std::string Strutil::lower ( string_view  a )

inline

Return an all-upper case version of a (locale-independent).

Definition at line 493 of file strutil.h.

string_view OIIO_UTIL_API Strutil::lstrip	(	string_view	str,
		string_view	chars = string_view()
	)

Return a reference to the section of str that has all consecutive characters in chars removed from the beginning (left side). If chars is empty, it will be interpreted as " \t\n\r\f\v" (whitespace).

std::string OIIO_UTIL_API Strutil::memformat	(	long long	bytes,
		int	digits = 1
	)

Return a string expressing a number of bytes, in human readable form.

• memformat(153) -> "153 B"
• memformat(15300) -> "14.9 KB"
• memformat(15300000) -> "14.6 MB"
• memformat(15300000000LL) -> "14.2 GB"

bool OIIO_UTIL_API Strutil::parse_char ( string_view &  str, char  c, bool  skip_whitespace = true, bool  eat = true  )

noexcept

If str's first character is c (or first non-whitespace char is c, if skip_whitespace is true), return true and additionally modify str to skip over that first character if eat is also true. Otherwise, if str does not begin with character c, return false and don't modify str.

bool OIIO_UTIL_API Strutil::parse_float ( string_view &  str, float &  val, bool  eat = true  )

noexcept

If str's first non-whitespace characters form a valid float, return true, place the float's value in val, and additionally modify str to skip over the parsed float if eat is also true. Otherwise, if no float is found at the beginning of str, return false and don't modify val or str.

string_view OIIO_UTIL_API Strutil::parse_identifier ( string_view &  str, bool  eat = true  )

noexcept

If str's first non-whitespace characters form a valid C-like identifier, return the identifier, and additionally modify str to skip over the parsed identifier if eat is also true. Otherwise, if no identifier is found at the beginning of str, return an empty string_view and don't modify str.

string_view OIIO_UTIL_API Strutil::parse_identifier ( string_view &  str, string_view  allowed, bool  eat = true  )

noexcept

If str's first non-whitespace characters form a valid C-like identifier, return the identifier, and additionally modify str to skip over the parsed identifier if eat is also true. Otherwise, if no identifier is found at the beginning of str, return an empty string_view and don't modify str. The 'allowed' parameter may specify a additional characters accepted that would not ordinarily be allowed in C identifiers, for example, parse_identifier (blah, "$:") would allow "identifiers" containing dollar signs and colons as well as the usual alphanumeric and underscore characters.

bool OIIO_UTIL_API Strutil::parse_identifier_if ( string_view &  str, string_view  id, bool  eat = true  )

noexcept

If the C-like identifier at the head of str exactly matches id, return true, and also advance str if eat is true. If it is not a match for id, return false and do not alter str.

bool OIIO_UTIL_API Strutil::parse_int ( string_view &  str, int &  val, bool  eat = true  )

noexcept

If str's first non-whitespace characters form a valid integer, return true, place the integer's value in val, and additionally modify str to skip over the parsed integer if eat is also true. Otherwise, if no integer is found at the beginning of str, return false and don't modify val or str.

string_view OIIO_UTIL_API Strutil::parse_line ( string_view &  str, bool  eat = true  )

noexcept

Return the prefix of str up to and including the first newline ('
') character, or all of str if no newline is found within it. If eat is true, then str will be modified to trim off this returned prefix (including the newline character).

string_view OIIO_UTIL_API Strutil::parse_nested ( string_view &  str, bool  eat = true  )

noexcept

Assuming the string str starts with either '(', '[', or '{', return the head, up to and including the corresponding closing character (')', ']', or '}', respectively), recognizing nesting structures. For example, parse_nested("(a(b)c)d") should return "(a(b)c)", NOT "(a(b)". Return an empty string if str doesn't start with one of those characters, or doesn't contain a correctly matching nested pair. If eat==true, str will be modified to trim off the part of the string that is returned as the match.

bool OIIO_UTIL_API Strutil::parse_prefix ( string_view &  str, string_view  prefix, bool  eat = true  )

noexcept

If str's first non-whitespace characters are the prefix, return true and additionally modify str to skip over that prefix if eat is also true. Otherwise, if str doesn't start with optional whitespace and the prefix, return false and don't modify str.

bool OIIO_UTIL_API Strutil::parse_string ( string_view &  str, string_view &  val, bool  eat = true, QuoteBehavior  keep_quotes = DeleteQuotes  )

noexcept

If str's first non-whitespace characters form a valid string (either a single word separated by whitespace or anything inside a double-quoted ("") or single-quoted ('') string, return true, place the string's value (not including surrounding double quotes) in val, and additionally modify str to skip over the parsed string if eat is also true. Otherwise, if no string is found at the beginning of str, return false and don't modify val or str. If keep_quotes is true, the surrounding double quotes (if present) will be kept in val.

string_view OIIO_UTIL_API Strutil::parse_until ( string_view &  str, string_view  set = " \t\r\n", bool  eat = true  )

noexcept

Return the longest prefix of str that does not contain any characters found in set (which defaults to the set of common whitespace characters). If eat is true, then str will be modified to trim off this returned prefix (but not the separator character).

bool OIIO_UTIL_API Strutil::parse_until_char ( string_view &  str, char  c, bool  eat = true  )

noexcept

Modify str to trim all characters up to (but not including) the first occurrence of c, and return true if c was found or false if the whole string was trimmed without ever finding c. But if eat is false, then don't modify str, just return true if any c is found, false if no c is found.

bool Strutil::parse_value ( string_view &  str, float &  val, bool  eat = true  )

inlinenoexcept

Synonym for parse_int.

Definition at line 1000 of file strutil.h.

bool Strutil::parse_value ( string_view &  str, int &  val, bool  eat = true  )

inlinenoexcept

Synonym for parse_float.

Definition at line 1006 of file strutil.h.

bool OIIO_UTIL_API Strutil::parse_values ( string_view &  str, string_view  prefix, span< int >  values, string_view  sep = "", string_view  postfix = "", bool  eat = true  )

noexcept

Parse from str: a prefix, a series of int values separated by the sep string, and a postfix, placing the values in the elements of mutable span values, where the span length indicates the number of values to read. Any of the prefix, separator, or postfix may be empty strings. If eat is true and the parse was successful, str will be updated in place to trim everything that was parsed, but if any part of the parse failed, str will not be altered from its original state.

bool OIIO_UTIL_API Strutil::parse_values ( string_view &  str, string_view  prefix, span< float >  values, string_view  sep = "", string_view  postfix = "", bool  eat = true  )

noexcept

parse_values for float.

string_view OIIO_UTIL_API Strutil::parse_while ( string_view &  str, string_view  set, bool  eat = true  )

noexcept

Return the longest prefix of str that contain only characters found in set. If eat is true, then str will be modified to trim off this returned prefix.

string_view OIIO_UTIL_API Strutil::parse_word ( string_view &  str, bool  eat = true  )

noexcept

Return the first "word" (set of contiguous alphabetical characters) in str, and additionally modify str to skip over the parsed word if eat is also true. Otherwise, if no word is found at the beginning of str, return an empty string_view and don't modify str.

template<typename... Args>

void Strutil::printf ( const char *  fmt, const Args &...  args  )

inline

Strutil::printf (fmt, ...) Strutil::fprintf (FILE*, fmt, ...) Strutil::fprintf (ostream& fmt, ...)

Output formatted strings to stdout, a FILE*, or a stream, respectively. All use printf-like formatting rules, are type-safe, are thread-safe (the outputs are "atomic", at least versus other calls to Strutil::*printf), and automatically flush their outputs. They are all locale-independent (forcing classic "C" locale).

Definition at line 174 of file strutil.h.

bool Strutil::rcontains ( string_view  a, string_view  b  )

inline

Does 'a' contain the string 'b' within it? But start looking at the end! This can be a bit faster than contains() if you think that the substring b will tend to be close to the end of a.

Definition at line 469 of file strutil.h.

void OIIO_UTIL_API Strutil::remove_trailing_whitespace ( string_view &  str )

noexcept

Modify str to trim any trailing whitespace (space, tab, linefeed, cr) from the back.

std::string OIIO_UTIL_API Strutil::repeat	(	string_view	str,
		int	n
	)

Repeat a string formed by concatenating str n times.

std::string OIIO_UTIL_API Strutil::replace	(	string_view	str,
		string_view	pattern,
		string_view	replacement,
		bool	global = false
	)

Replace a pattern inside a string and return the result. If global is true, replace all instances of the pattern, otherwise just the first.

size_t OIIO_UTIL_API Strutil::rfind	(	string_view	a,
		string_view	b
	)

Return the position of the last occurrence of b within a, or npos if not found.

string_view OIIO_UTIL_API Strutil::rstrip	(	string_view	str,
		string_view	chars = string_view()
	)

Return a reference to the section of str that has all consecutive characters in chars removed from the ending (right side). If chars is empty, it will be interpreted as " \t\n\r\f\v" (whitespace).

OIIO_UTIL_API char* Strutil::safe_strcat ( char *  dst, string_view  src, size_t  size  )

noexcept

Append src to the end of the C-string buffer dst, plus a terminating null, assuming that dst can hold at most size characters (including terminating 0 character). Returns dst. Note that this behavior is similar to strcat, but guarantees that the resulting string fits into size bytes and is null-terminated.

OIIO_UTIL_API char* Strutil::safe_strcpy ( char *  dst, string_view  src, size_t  size  )

noexcept

Copy at most size characters (including terminating 0 character) from src into dst[], filling any remaining characters with 0 values. Returns dst. Note that this behavior is identical to strncpy, except that it guarantees that there will be a terminating 0 character.

std::string Strutil::safe_string ( const char *  str, size_t  size  )

inline

Return a std::string that is a substring of the given C string, ending at the first null character or after size characters, whichever comes first.

Definition at line 927 of file strutil.h.

string_view Strutil::safe_string_view ( const char *  str, size_t  size  )

inlinenoexcept

Return a string_view that is a substring of the given C string, ending at the first null character or after size characters, whichever comes first.

Definition at line 920 of file strutil.h.

OIIO_UTIL_API size_t Strutil::safe_strlen ( const char *  str, size_t  size  )

noexcept

Return the length of null-terminated string str, up to maximum size. If str is nullptr, return 0. This is equivalent to C11 strnlen_s.

OIIO_UTIL_API bool Strutil::scan_datetime	(	string_view	str,
		int &	year,
		int &	month,
		int &	day,
		int &	hour,
		int &	min,
		int &	sec
	)

Scan a string for date and time information. Return true upon success, false if the string did not appear to contain a valid date/time. If, after parsing a valid date/time (including out of range values), str contains more characters after that, it is not considered a failure.

Valid date/time formats include:

• YYYY-MM-DD HH:MM:SS
• YYYY:MM:DD HH:MM:SS
• YYYY/MM/DD HH:MM:SS

bool Strutil::scan_values ( string_view  str, string_view  prefix, span< int >  values, string_view  sep = "", string_view  postfix = ""  )

inlinenoexcept

Similar to parse_values, but with no option to "eat" from or modify the source string.

Definition at line 1031 of file strutil.h.

bool Strutil::scan_values ( string_view  str, string_view  prefix, span< float >  values, string_view  sep = "", string_view  postfix = ""  )

inlinenoexcept

Definition at line 1039 of file strutil.h.

void OIIO_UTIL_API Strutil::skip_whitespace ( string_view &  str )

noexcept

Modify str to trim any leading whitespace (space, tab, linefeed, cr) from the front.

void OIIO_UTIL_API Strutil::split	(	string_view	str,
		std::vector< string_view > &	result,
		string_view	sep = string_view(),
		int	maxsplit = -1
	)

Fills the "result" list with the words in the string, using sep as the delimiter string. If maxsplit is > -1, the string will be split into at most maxsplit pieces (a negative value will impose no maximum). If sep is "", any whitespace string is a separator. If the source str is empty, there will be zero pieces.

void OIIO_UTIL_API Strutil::split	(	string_view	str,
		std::vector< std::string > &	result,
		string_view	sep = string_view(),
		int	maxsplit = -1
	)

OIIO_UTIL_API std::vector<std::string> Strutil::splits	(	string_view	str,
		string_view	sep = "",
		int	maxsplit = -1
	)

Split the contents of str using sep as the delimiter string. If sep is "", any whitespace string is a separator. If maxsplit > -1, at most maxsplit split fragments will be produced (for example, maxsplit=2 will split at only the first separator, yielding at most two fragments). The result is returned as a vector of std::string (for splits()) or a vector of string_view (for splitsv()). If the source str is empty, there will be zero pieces.

Examples:

RAY/RAY_DemoMountain.C, and RAY/RAY_DemoMountain.h.

OIIO_UTIL_API std::vector<string_view> Strutil::splitsv	(	string_view	str,
		string_view	sep = "",
		int	maxsplit = -1
	)

bool OIIO_UTIL_API Strutil::starts_with	(	string_view	a,
		string_view	b
	)

Does 'a' start with the string 'b', with a case-sensitive comparison?

OIIO_UTIL_API double Strutil::stod	(	string_view	s,
		size_t *	pos = 0
	)

OIIO_UTIL_API double Strutil::stod	(	const std::string &	s,
		size_t *	pos = 0
	)

OIIO_UTIL_API double Strutil::stod	(	const char *	s,
		size_t *	pos = 0
	)

OIIO_UTIL_API float Strutil::stof	(	string_view	s,
		size_t *	pos = 0
	)

stof() returns the float conversion of text from several string types. No exceptions or errors – parsing errors just return 0.0. These always use '.' for the decimal mark (versus atof and std::strtof, which are locale-dependent).

OIIO_UTIL_API float Strutil::stof	(	const std::string &	s,
		size_t *	pos = 0
	)

OIIO_UTIL_API float Strutil::stof	(	const char *	s,
		size_t *	pos = 0
	)

float Strutil::stof ( ustring  s )

inline

Definition at line 1111 of file ustring.h.

OIIO_UTIL_API int Strutil::stoi	(	string_view	s,
		size_t *	pos = 0,
		int	base = 10
	)

OIIO_UTIL_API unsigned int Strutil::stoui	(	string_view	s,
		size_t *	pos = 0,
		int	base = 10
	)

constexpr size_t Strutil::strhash ( size_t  len, const char *  s  )

inline

Our favorite "string" hash of a length of bytes. Currently, it is just a wrapper for an inlined, constexpr, Cuda-safe farmhash. It returns a size_t, so will be a 64 bit hash on 64-bit platforms, but a 32 bit hash on 32-bit platforms.

Definition at line 373 of file strutil.h.

constexpr size_t Strutil::strhash ( string_view  s )

inline

Hash a string_view. This is OIIO's default favorite string hasher. Currently, it uses farmhash, is constexpr (for C++14), and works in Cuda. This is rigged, though, so that empty strings hash always hash to 0 (that isn't what a raw farmhash would give you, but it's a useful property, especially for trivial initialization). It returns a size_t, so will be a 64 bit hash on 64-bit platforms, but a 32 bit hash on 32-bit platforms.

Definition at line 394 of file strutil.h.

constexpr uint64_t Strutil::strhash64 ( size_t  len, const char *  s  )

inline

A guaranteed 64-bit string hash on all platforms.

Definition at line 381 of file strutil.h.

constexpr uint64_t Strutil::strhash64 ( string_view  s )

inline

Hash a string_view, guaranteed 64 bits (even on 32 bit platforms).

Definition at line 403 of file strutil.h.

template<typename T >

bool Strutil::string_is ( string_view  )

inline

Definition at line 720 of file strutil.h.

template<>

bool Strutil::string_is< float > ( string_view  s )

inline

Definition at line 729 of file strutil.h.

template<>

bool Strutil::string_is< int > ( string_view  s )

inline

Definition at line 724 of file strutil.h.

OIIO_UTIL_API bool Strutil::string_is_float

(

string_view

s

)

Return true if the string is exactly (other than leading or trailing whitespace) a valid float. This operations in a locale-independent manner, i.e., it assumes '.' as the decimal mark.

bool Strutil::string_is_identifier ( string_view  str )

inline

Does the string follow the lexical rule of a C identifier?

Definition at line 1121 of file strutil.h.

OIIO_UTIL_API bool Strutil::string_is_int

(

string_view

s

)

Return true if the string is exactly (other than leading and trailing whitespace) a valid int.

string_view OIIO_UTIL_API Strutil::strip	(	string_view	str,
		string_view	chars = string_view()
	)

Return a reference to the section of str that has all consecutive characters in chars removed from the beginning and ending. If chars is empty, it will be interpreted as " \t\n\r\f\v" (whitespace).

double OIIO_UTIL_API Strutil::strtod ( const char *  nptr, char **  endptr = nullptr  )

noexcept

float OIIO_UTIL_API Strutil::strtof ( const char *  nptr, char **  endptr = nullptr  )

noexcept

strtod/strtof equivalents that are "locale-independent", always using '.' as the decimal separator. This should be preferred for I/O and other situations where you want the same standard formatting regardless of locale.

void OIIO_UTIL_API Strutil::sync_output	(	FILE *	file,
		string_view	str,
		bool	flush = true
	)

Output the string to the file/stream in a synchronized fashion, with an internal mutex used to prevent threads from clobbering each other – output strings coming from concurrent threads may be interleaved, but each string is "atomic" and will never splice each other character-by-character. If flush is true, the underlying stream will be flushed after the string is output.

void OIIO_UTIL_API Strutil::sync_output	(	std::ostream &	file,
		string_view	str,
		bool	flush = true
	)

std::string OIIO_UTIL_API Strutil::timeintervalformat	(	double	secs,
		int	digits = 1
	)

Return a string expressing an elapsed time, in human readable form. e.g. "0:35.2"

void OIIO_UTIL_API Strutil::to_lower ( std::string &  a )

inline

Convert to upper case in place, faster than std::toupper because we use a static locale that doesn't require a mutex lock.

Definition at line 96 of file Name.h.

template<typename T >

std::string Strutil::to_string ( const T &  value )

inline

Template function to convert any type to a string. The default implementation is just to use sprintf or fmt::to_string. The template can be overloaded if there is a better method for particular types.

Definition at line 706 of file strutil.h.

std::string Strutil::to_string ( const std::string &  value )

inline

Definition at line 711 of file strutil.h.

std::string Strutil::to_string ( string_view  value )

inline

Definition at line 712 of file strutil.h.

std::string Strutil::to_string ( const char *  value )

inline

Definition at line 713 of file strutil.h.

template<>

std::string Strutil::to_string ( const ustring &  value )

inline

Definition at line 1118 of file ustring.h.

template<>

std::string Strutil::to_string ( const ustringhash &  value )

inline

Definition at line 1125 of file ustring.h.

void OIIO_UTIL_API Strutil::to_upper

(

std::string &

a

)

Convert to upper case in place, faster than std::toupper because we use a static locale that doesn't require a mutex lock.

void Strutil::trim_whitespace ( string_view &  str )

inlinenoexcept

Modify str to trim any whitespace (space, tab, linefeed, cr) from both the front and back.

Definition at line 952 of file strutil.h.

string_view Strutil::trimmed_whitespace ( string_view  str )

inlinenoexcept

Return the portion of str that is trimmed of any whitespace (space, tab, linefeed, cr) from both the front and back.

Definition at line 959 of file strutil.h.

std::string OIIO_UTIL_API Strutil::unescape_chars

(

string_view

escaped

)

Take a string that has embedded escape sequences (\\, \", \n, etc.) and collapse them into the 'real' characters.

std::string Strutil::upper ( string_view  a )

inline

Return an all-upper case version of a (locale-independent).

Definition at line 500 of file strutil.h.

std::string OIIO_UTIL_API Strutil::utf16_to_utf8 ( const std::wstring &  utf16str )

noexcept

Conversion from wstring UTF-16 to a UTF-8 std::string. This is the standard way to convert from Windows wide character strings used for filenames into the UTF-8 strings OIIO expects for filenames when passed to functions like ImageInput::open().

std::string OIIO_UTIL_API Strutil::utf16_to_utf8 ( const std::u16string &  utf16str )

noexcept

Conversion from UTF-16 std::u16string to a UTF-8 std::string.

void OIIO_UTIL_API Strutil::utf8_to_unicode	(	string_view	str,
		std::vector< uint32_t > &	uvec
	)

Converts utf-8 string to vector of unicode codepoints. This function will not stop on invalid sequences. It will let through some invalid utf-8 sequences like: 0xfdd0-0xfdef, 0x??fffe/0x??ffff. It does not support 5-6 bytes long utf-8 sequences. Will skip trailing character if there are not enough bytes for decoding a codepoint.

N.B. Following should probably return u32string instead of taking vector, but C++11 support is not yet stabilized across compilers. We will eventually add that and deprecate this one, after everybody is caught up to C++11.

std::wstring OIIO_UTIL_API Strutil::utf8_to_utf16 ( string_view  utf8str )

noexcept

Old name for utf8_to_utf16wstring. Will be deprecated for OIIO 2.5+ and removed for OIIO 3.0. Use utf8_to_utf16wstring which is more clear that this particular conversion from utf8 to utf16 returns a std::wstring and not a std::u16string.

std::wstring OIIO_UTIL_API Strutil::utf8_to_utf16wstring ( string_view  utf8str )

noexcept

Conversion of normal char-based strings (presumed to be UTF-8 encoding) to a UTF-16 encoded wide char string, wstring.

std::string OIIO_UTIL_API Strutil::vformat	(	const char *	fmt,
		va_list	ap
	)

Return a std::string formatted like Strutil::format, but passed already as a va_list. This is not guaranteed type-safe and is not extensible like format(). Use with caution!

std::string OIIO_UTIL_API Strutil::vsprintf	(	const char *	fmt,
		va_list	ap
	)

Return a std::string formatted from printf-like arguments – passed already as a va_list. This is not guaranteed type-safe and is not extensible like format(). Use with caution!

std::string OIIO_UTIL_API Strutil::wordwrap	(	string_view	src,
		int	columns = 80,
		int	prefix = 0,
		string_view	sep = " ",
		string_view	presep = ""
	)

Word-wrap string src to no more than columns width, starting with an assumed position of prefix on the first line and intending by prefix blanks before all lines other than the first.

Words may be split AT any characters in sep or immediately AFTER any characters in presep. After the break, any extra sep characters will be deleted.

By illustration, wordwrap("0 1 2 3 4 5 6 7 8", 10, 4) should return: "0 1 2\n 3 4 5\n 6 7 8"