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...

#include <String.h>

Public Member Functions
	String ()
	Default constructor produces an empty string.
	String (const char *s)
	This is an implicit conversion from const char* to String.
	String (char c)
	We allow creating a String from a char but you have to do it explicitly.
	String (const std::string &s)
	This is an implicit conversion from std::string to String.
	String (const String &s, int start, int len)
	Construct a String as a copy of a substring begining at position start with length len.
	operator const char * () const
	This is an implicit conversion from String to null-terminated C-style string (array of chars).
char &	operator[] (int i)
	Add operator[] that takes int index instead of size_type.
char	operator[] (int i) const
	Add operator[] that takes int index instead of size_type.
char &	operator[] (std::string::size_type i)
	Pass through to string::operator[].
char	operator[] (std::string::size_type i) const
	Pass through to string::operator[].
int	size () const
	Override std::string size() method to return an int instead of the inconvenient unsigned type size_type.
int	length () const
	Override std::string length() method to return an int instead of the inconvenient unsigned type size_type.
Formatted output constructors
These contructors format the supplied argument into a human-readable String.
	String (int i)
	Format an int as a printable String.
	String (long i)
	Format a long as a printable String.
	String (long long i)
	Format a long long as a printable String.
	String (unsigned int s)
	Format an unsigned int as a printable String.
	String (unsigned long s)
	Format an unsigned long as a printable String.
	String (unsigned long long s)
	Format an unsigned long long as a printable String.
	String (float r)
	Format a float as a printable String.
	String (double r)
	Format a double as a printable String.
	String (long double r)
	Format a long double as a printable String.
	String (std::complex< float > r)
	Format a complex<float> as a printable String (real,imag).
	String (std::complex< double > r)
	Format a complex<double> as a printable String (real,imag).
	String (std::complex< long double > r)
	Format a complex<long double> as a printable String (real,imag).
	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.
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 a stream insertion operator<<() available for type T.
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.
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.
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.
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().
String &	toLower ()
	Downshift the given String in place, so that uppercase letters are replaced with their lowercase equivalents as defined by std::tolower().
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 &	replaceAllChar (char oldChar, char newChar)
	Substitute in place newChar for oldChar wherever oldChar appears in this String.
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 variables 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.
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.
Utility methods
These static methods operate on SimTK::String or std::string objects and return SimTK::String objects (which are also std::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.
static const String &	getAs (const std::string &s)
	Cast an std::string to a SimTK::String without copying; subsequent changes to the std::string will affect the SimTK::String too since it is just a reference to the original std::string.
static String &	updAs (std::string &s)
	Cast a non-const std::string to a non-const SimTK::String without copying; changes made to the SimTK::String will affect the original std::string and vice versa.
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().
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().
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).

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>.

Todo:: Currently this is just derived from std::string and inherits all the binary compatibility issues. Use it now anyway and you'll pick up the compatibility benefits later, when we get the time ...

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 ) [inline, explicit]

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 ) [inline, explicit]

Format an int as a printable String.

SimTK::String::String ( long i ) [inline, explicit]

Format a long as a printable String.

SimTK::String::String ( long long i ) [inline, explicit]

Format a long long as a printable String.

SimTK::String::String ( unsigned int s ) [inline, explicit]

Format an unsigned int as a printable String.

SimTK::String::String ( unsigned long s ) [inline, explicit]

Format an unsigned long as a printable String.

SimTK::String::String ( unsigned long long s ) [inline, explicit]

Format an unsigned long long as a printable String.

SimTK::String::String ( float r ) [inline, explicit]

Format a float as a printable String.

SimTK::String::String ( double r ) [inline, explicit]

Format a double as a printable String.

SimTK::String::String ( long double r ) [inline, explicit]

Format a long double as a printable String.

SimTK::String::String ( std::complex< float > r ) [inline, explicit]

Format a complex<float> as a printable String (real,imag).

SimTK::String::String ( std::complex< double > r ) [inline, explicit]

Format a complex<double> as a printable String (real,imag).

SimTK::String::String ( std::complex< long double > r ) [inline, explicit]

Format a complex<long double> as a printable String (real,imag).

SimTK::String::String ( bool b ) [inline, explicit]

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 ) [inline, explicit]

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 a stream insertion operator<<() available for type T.

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>()

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 const String& SimTK::String::getAs ( const std::string & s ) [inline, static]

Cast an std::string to a SimTK::String without copying; subsequent changes to the std::string will affect the SimTK::String too since it is just a reference to the original std::string.

static String& SimTK::String::updAs ( std::string & s ) [inline, static]

Cast a non-const std::string to a non-const SimTK::String without copying; changes made to the SimTK::String will affect the original std::string and vice versa.

static String SimTK::String::toUpper ( const std::string & in ) [inline, static]

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 ) [inline, static]

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
	)		`[related]`

This method converts its String argument to type T and returns it into the variables 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 ) [related]

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

SimTK::String Class Reference

Public Member Functions

Related Functions

Utility methods

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation