SimTK::String is a plug-compatible std::string replacement (plus some additional functionality) intended to be suitable for passing through the SimTK API without introducing binary compatibility problems the way std::string does, especially on Windows. More...

Inheritance diagram for SimTK::String:

Public Member Functions
	String ()
	Default constructor produces an empty string. More...

	String (const char *s)
	This is an implicit conversion from const char* to String. More...

	String (char c)
	We allow creating a String from a char but you have to do it explicitly. More...

	String (const std::string &s)
	This is an implicit conversion from std::string to String. More...

	String (const String &s, int start, int len)
	Construct a String as a copy of a substring begining at position start with length len. More...

	operator const char * () const
	This is an implicit conversion from String to null-terminated C-style string (array of chars). More...

char &	operator[] (int i)
	Add operator[] that takes int index instead of size_type. More...

char	operator[] (int i) const
	Add operator[] that takes int index instead of size_type. More...

char &	operator[] (std::string::size_type i)
	Pass through to string::operator[]. More...

char	operator[] (std::string::size_type i) const
	Pass through to string::operator[]. More...

int	size () const
	Override std::string size() method to return an int instead of the inconvenient unsigned type size_type. More...

int	length () const
	Override std::string length() method to return an int instead of the inconvenient unsigned type size_type. More...

Formatted output constructors
These contructors format the supplied argument into a human-readable String, using a default or caller-supplied printf-like format. By default, maximum precision is used for floating point values, and user-friendly strings are used for bool (true or false) and non-finite floating point values (NaN, Inf, -Inf).
	String (int i, const char *fmt="%d")
	Format an int as a printable String. More...

	String (long i, const char *fmt="%ld")
	Format a long as a printable String. More...

	String (long long i, const char *fmt="%lld")
	Format a long long as a printable String. More...

	String (unsigned int s, const char *fmt="%u")
	Format an unsigned int as a printable String. More...

	String (unsigned long s, const char *fmt="%lu")
	Format an unsigned long as a printable String. More...

	String (unsigned long long s, const char *fmt="%llu")
	Format an unsigned long long as a printable String. More...

	String (float r, const char *fmt="%.7g")
	Format a float as a printable String. More...

	String (double r, const char *fmt="%.15g")
	Format a double as a printable String. More...

	String (long double r, const char *fmt="%.20Lg")
	Format a long double as a printable String. More...

	String (std::complex< float > r, const char *fmt="%.7g")
	Format a complex<float> as a printable String (real,imag) with parentheses and a comma as shown. More...

	String (std::complex< double > r, const char *fmt="%.15g")
	Format a complex<double> as a printable String (real,imag) with parentheses and a comma as shown. More...

	String (std::complex< long double > r, const char *fmt="%.20Lg")
	Format a complex<long double> as a printable String (real,imag) with parentheses and a comma as shown. More...

	String (bool b)
	Format a bool as a printable String "true" or "false"; if you want "1" or "0" cast the bool to an int first. More...

template<class T >
	String (const T &t)
	For any type T for which there is no matching constructor, this templatized constructor will format an object of type T into a String provided that there is either an available specialization or (as a last resort) a stream insertion operator<<() available for type T. More...

template<class T >
	String (const negator< T > &nt)
	Constructing a String from a negated value converts to the underlying native type and then uses one of the native-type constructors. More...

template<class T >
	String (const negator< T > &nt, const char *fmt)
	Same, but allows for format specification. More...

template<class T >
	String (const conjugate< T > &ct)
	Constructing a String from a conjugate value converts to the underlying complex type and then uses one of the native-type constructors. More...

template<class T >
	String (const conjugate< T > &ct, const char *fmt)
	Same, but allows for format specification. More...

Formatted input from String
These templatized methods attempt to interpret the entire contents of this String as a single object of type T (although T may itself be a container like an Array or Vector). It is an error if the String has the wrong format for an object of this type, or if the entire String is not consumed. The acceptable formatting is defined by type T based on what it thinks is acceptable stream formatting. Leading and trailing white space are ignored except when type T is itself a String or std::string in which case the white space is included in the result. It is not acceptable for type T to be a pointer type. In particular if you want to convert a String to a null- terminated C-style char*, use the standard c_str() method rather than any of these. See also Related namespace-level static methods convertStringTo<T>().
template<class T >
bool	tryConvertTo (T &out) const
	Attempt to convert this String to an object of type T, returning a status value to indicate success or failure. More...

template<class T >
void	convertTo (T &out) const
	Convert this String to an object of type T using the tryConvertTo<T>() method but throwing an error on failure rather than returning status. More...

template<class T >
T	convertTo () const
	A more convenient form of convertTo<T>() that returns the result as its function argument, although this may involve an extra copy operation. More...

bool	tryConvertToBool (bool &out) const
	Special-purpose method for interpreting this String as a bool. More...

bool	tryConvertToFloat (float &out) const
	Special-purpose method for interpreting this String as a float. More...

bool	tryConvertToDouble (double &out) const
	Special-purpose method for interpreting this String as a double. More...

bool	tryConvertToLongDouble (long double &out) const
	Special-purpose method for interpreting this String as a long double. More...

In-place modifications
These are member functions which add to the existing std::string functionality. These methods return a reference to "this" String, so may be chained like assignment statements. If you would like to use these on an std::string, use the String::updAs() method to recast the std::string to a String. Note that there is also an equivalent set of static methods which return a new String rather than changing the original.
String &	toUpper ()
	Upshift the given String in place, so that lowercase letters are replaced with their uppercase equivalents as defined by std::toupper(). More...

String &	toLower ()
	Downshift the given String in place, so that uppercase letters are replaced with their lowercase equivalents as defined by std::tolower(). More...

String &	trimWhiteSpace ()
	Trim this String in place, removing all the initial leading and trailing white space, as defined by std::isspace() which typically includes space, tab (\t), newline (\n), return (\r), and form feed (\f). More...

String &	replaceAllChar (char oldChar, char newChar)
	Substitute in place newChar for oldChar wherever oldChar appears in this String. More...

Related Functions
(Note that these are not member functions.)
template<class T >
static void	convertStringTo (const String &in, T &out)
	This method converts its String argument to type T and returns it into the variable supplied as its second argument; this is particularly convenient when you have a string literal or std::string since the conversion to String happens automatically. More...

template<class T >
static T	convertStringTo (const String &in)
	This method converts its String argument to type T and returns it as its function value; this is particularly convenient when you have a string literal or std::string since the conversion to String happens automatically. More...

Utility methods
These static methods operate on SimTK::String or std::string objects and return SimTK::String objects.
String &	replaceAllChar (const std::string &in, char oldChar, char newChar)
	Copy the input std::string to a new SimTK::String while substituting newChar for oldChar wherever oldChar appears in the input. More...

static String	toUpper (const std::string &in)
	Upshift the given std::string returning a new SimTK::String in which all the letters have been made upper case with toupper(). More...

static String	toLower (const std::string &in)
	Downshift the given std::string returning a new SimTK::String in which all the letters have be made lower case with tolower(). More...

static String	trimWhiteSpace (const std::string &in)
	Copy the input std::string to a new SimTK::String leaving off all the initial leading and trailing white space, as defined by isspace() which typically includes space, tab (\t), newline (\n), return (\r), and form feed (\f). More...

Detailed Description

SimTK::String is a plug-compatible std::string replacement (plus some additional functionality) intended to be suitable for passing through the SimTK API without introducing binary compatibility problems the way std::string does, especially on Windows.

You can work in your own code with std::strings which will be quietly converted to and from SimTK::Strings when invoking SimTK API methods. Or, you can use SimTK::Strings and still pass them to standard library or other methods that are expecting std::strings, usually transparently. The SimTK::Array_<T> class is used similarly to avoid binary compatibility problems that arise with std::vector<T>.

See also: SimTK::Array_

Constructor & Destructor Documentation

SimTK::String::String ( )

inline

Default constructor produces an empty string.

SimTK::String::String ( const char * s )

inline

This is an implicit conversion from const char* to String.

SimTK::String::String ( char c )

inlineexplicit

We allow creating a String from a char but you have to do it explicitly.

SimTK::String::String ( const std::string & s )

inline

This is an implicit conversion from std::string to String.

SimTK::String::String	(	const String &	s,
		int	start,
		int	len
	)

inline

Construct a String as a copy of a substring begining at position start with length len.

SimTK::String::String	(	int	i,
		const char *	fmt = `"%d"`
	)

inlineexplicit

Format an int as a printable String.

SimTK::String::String	(	long	i,
		const char *	fmt = `"%ld"`
	)

inlineexplicit

Format a long as a printable String.

SimTK::String::String	(	long long	i,
		const char *	fmt = `"%lld"`
	)

inlineexplicit

Format a long long as a printable String.

SimTK::String::String	(	unsigned int	s,
		const char *	fmt = `"%u"`
	)

inlineexplicit

Format an unsigned int as a printable String.

SimTK::String::String	(	unsigned long	s,
		const char *	fmt = `"%lu"`
	)

inlineexplicit

Format an unsigned long as a printable String.

SimTK::String::String	(	unsigned long long	s,
		const char *	fmt = `"%llu"`
	)

inlineexplicit

Format an unsigned long long as a printable String.

SimTK::String::String	(	float	r,
		const char *	fmt = `"%.7g"`
	)

explicit

Format a float as a printable String.

Nonfinite values are formatted as NaN, Inf, or -Inf as appropriate (Matlab compatible).

SimTK::String::String	(	double	r,
		const char *	fmt = `"%.15g"`
	)

explicit

Format a double as a printable String.

Nonfinite values are formatted as NaN, Inf, or -Inf as appropriate (Matlab compatible).

SimTK::String::String	(	long double	r,
		const char *	fmt = `"%.20Lg"`
	)

explicit

Format a long double as a printable String.

Nonfinite values are formatted as NaN, Inf, or -Inf as appropriate (Matlab compatible).

SimTK::String::String	(	std::complex< float >	r,
		const char *	fmt = `"%.7g"`
	)

inlineexplicit

Format a complex<float> as a printable String (real,imag) with parentheses and a comma as shown.

The format string should be for a single float and will be used twice; the default format is the same as for float.

SimTK::String::String	(	std::complex< double >	r,
		const char *	fmt = `"%.15g"`
	)

inlineexplicit

Format a complex<double> as a printable String (real,imag) with parentheses and a comma as shown.

The format string should be for a single double and will be used twice; the default format is the same as for double.

SimTK::String::String	(	std::complex< long double >	r,
		const char *	fmt = `"%.20Lg"`
	)

inlineexplicit

Format a complex<long double> as a printable String (real,imag) with parentheses and a comma as shown.

The format string should be for a single long double and will be used twice; the default format is the same as for long double.

SimTK::String::String ( bool b )

inlineexplicit

Format a bool as a printable String "true" or "false"; if you want "1" or "0" cast the bool to an int first.

template<class T >

SimTK::String::String ( const T & t )

inlineexplicit

For any type T for which there is no matching constructor, this templatized constructor will format an object of type T into a String provided that there is either an available specialization or (as a last resort) a stream insertion operator<<() available for type T.

Generic templatized String constructor uses T::operator<<() to generate the String when no specialization is available.

template<class T >

SimTK::String::String ( const negator< T > & nt )

inlineexplicit

Constructing a String from a negated value converts to the underlying native type and then uses one of the native-type constructors.

template<class T >

SimTK::String::String	(	const negator< T > &	nt,
		const char *	fmt
	)

inline

Same, but allows for format specification.

template<class T >

SimTK::String::String ( const conjugate< T > & ct )

inlineexplicit

Constructing a String from a conjugate value converts to the underlying complex type and then uses one of the native-type constructors.

template<class T >

SimTK::String::String	(	const conjugate< T > &	ct,
		const char *	fmt
	)

inline

Same, but allows for format specification.

Member Function Documentation

SimTK::String::operator const char * ( ) const

inline

This is an implicit conversion from String to null-terminated C-style string (array of chars).

char& SimTK::String::operator[] ( int i )

inline

Add operator[] that takes int index instead of size_type.

char SimTK::String::operator[] ( int i ) const

inline

Add operator[] that takes int index instead of size_type.

char& SimTK::String::operator[] ( std::string::size_type i )

inline

Pass through to string::operator[].

char SimTK::String::operator[] ( std::string::size_type i ) const

inline

Pass through to string::operator[].

int SimTK::String::size ( ) const

inline

Override std::string size() method to return an int instead of the inconvenient unsigned type size_type.

int SimTK::String::length ( ) const

inline

Override std::string length() method to return an int instead of the inconvenient unsigned type size_type.

template<class T >

bool SimTK::String::tryConvertTo ( T & out ) const

inline

Attempt to convert this String to an object of type T, returning a status value to indicate success or failure.

We require that the whole string is consumed except possibly for some trailing white space.

Template Parameters

T	A non-pointer type that supports extraction operator>>() from an istream. You will get a compilation failure if you try to use this method for a type T for which no extraction operator is available and a runtime error if T is a pointer type.

Parameters

[out] out The converted value if we were able to parse the string successfully (i.e., function return is true), otherwise the output value is undefined.

Returns: true if we got what we're looking for, false if anything went wrong including failure to consume the entire string.

See also: convertTo<T>()

template<class T >

void SimTK::String::convertTo ( T & out ) const

inline

Convert this String to an object of type T using the tryConvertTo<T>() method but throwing an error on failure rather than returning status.

Using this routine can save you a lot of error-checking code if you were going to have to throw an error anyway.

Parameters

[out] out The converted value.

See also: tryConvertTo<T>(out), SimTK::convertStringTo<T>()

template<class T >

T SimTK::String::convertTo ( ) const

inline

A more convenient form of convertTo<T>() that returns the result as its function argument, although this may involve an extra copy operation.

For very large objects you may want to use the other form where the output is written to an already-constructed object you provide.

Returns: The converted value as an object of type T.

See also: convertTo<T>(out), tryConvertTo<T>(out), SimTK::convertStringTo<T>()

bool SimTK::String::tryConvertToBool ( bool & out ) const

Special-purpose method for interpreting this String as a bool.

Recognizes "true" and "false" (in any case) as well as whatever operator>>() accepts. Returns false if the contents of this String, ignoring leading and trailing whitespace, can't be interpreted as a bool.

bool SimTK::String::tryConvertToFloat ( float & out ) const

Special-purpose method for interpreting this String as a float.

Recognizes NaN, [-]Inf, [-]Infinity (in any case) as well as whatever operator>>() accepts. Returns false if the contents of this String, ignoring leading and trailing whitespace, can't be interpreted as a float.

bool SimTK::String::tryConvertToDouble ( double & out ) const

Special-purpose method for interpreting this String as a double.

Recognizes NaN, [-]Inf, [-]Infinity (in any case) as well as whatever operator>>() accepts. Returns false if the contents of this String, ignoring leading and trailing whitespace, can't be interpreted as a double.

bool SimTK::String::tryConvertToLongDouble ( long double & out ) const

Special-purpose method for interpreting this String as a long double.

Recognizes NaN, [-]Inf, [-]Infinity (in any case) as well as whatever operator>>() accepts. Returns false if the contents of this String, ignoring leading and trailing whitespace, can't be interpreted as a long double.

String& SimTK::String::toUpper ( )

Upshift the given String in place, so that lowercase letters are replaced with their uppercase equivalents as defined by std::toupper().

String& SimTK::String::toLower ( )

Downshift the given String in place, so that uppercase letters are replaced with their lowercase equivalents as defined by std::tolower().

String& SimTK::String::trimWhiteSpace ( )

Trim this String in place, removing all the initial leading and trailing white space, as defined by std::isspace() which typically includes space, tab (\t), newline (\n), return (\r), and form feed (\f).

String& SimTK::String::replaceAllChar	(	char	oldChar,
		char	newChar
	)

Substitute in place newChar for oldChar wherever oldChar appears in this String.

static String SimTK::String::toUpper ( const std::string & in )

inlinestatic

Upshift the given std::string returning a new SimTK::String in which all the letters have been made upper case with toupper().

static String SimTK::String::toLower ( const std::string & in )

inlinestatic

Downshift the given std::string returning a new SimTK::String in which all the letters have be made lower case with tolower().

static String SimTK::String::trimWhiteSpace ( const std::string & in )

static

Copy the input std::string to a new SimTK::String leaving off all the initial leading and trailing white space, as defined by isspace() which typically includes space, tab (\t), newline (\n), return (\r), and form feed (\f).

String& SimTK::String::replaceAllChar	(	const std::string &	in,
		char	oldChar,
		char	newChar
	)

inline

Copy the input std::string to a new SimTK::String while substituting newChar for oldChar wherever oldChar appears in the input.

Friends And Related Function Documentation

template<class T >

static void convertStringTo	(	const String &	in,
		T &	out
	)

This method converts its String argument to type T and returns it into the variable supplied as its second argument; this is particularly convenient when you have a string literal or std::string since the conversion to String happens automatically.

For example the two lines shown are equivalent:

Array_<float> array;
convertStringTo("1.2 -4.1e-3 5", array);
String("1.2 -4.1e-3 5").convertTo(array);

See also: String::convertTo()

template<class T >

static T convertStringTo ( const String & in )

This method converts its String argument to type T and returns it as its function value; this is particularly convenient when you have a string literal or std::string since the conversion to String happens automatically.

For example the two lines shown are equivalent:

Array_<float> array = convertStringTo< Array_<float> >("1.2 -4.1e-3 5");

Array_<float> array = String("1.2 -4.1e-3 5").convertTo< Array_<float> >();

See also: String::convertTo()

The documentation for this class was generated from the following file:

String.h

Public Member Functions

Related Functions

Utility methods

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation