Simbody  3.6
SimTK::String Class Reference

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 beginning 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 constructors 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="%.9g")
 Format a float as a printable String. More...
 
 String (double r, const char *fmt="%.17g")
 Format a double as a printable String. More...
 
 String (std::complex< float > r, const char *fmt="%.9g")
 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="%.17g")
 Format a complex<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 >
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...
 
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.

StringtoUpper ()
 Upshift the given String in place, so that lowercase letters are replaced with their uppercase equivalents as defined by std::toupper(). More...
 
StringtoLower ()
 Downshift the given String in place, so that uppercase letters are replaced with their lowercase equivalents as defined by std::tolower(). More...
 
StringtrimWhiteSpace ()
 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...
 
StringreplaceAllChar (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.

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

◆ String() [1/21]

SimTK::String::String ( )
inline

Default constructor produces an empty string.

◆ String() [2/21]

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

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

◆ String() [3/21]

SimTK::String::String ( char  c)
inlineexplicit

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

◆ String() [4/21]

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

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

◆ String() [5/21]

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

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

◆ String() [6/21]

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

Format an int as a printable String.

◆ String() [7/21]

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

Format a long as a printable String.

◆ String() [8/21]

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

Format a long long as a printable String.

◆ String() [9/21]

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

Format an unsigned int as a printable String.

◆ String() [10/21]

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

Format an unsigned long as a printable String.

◆ String() [11/21]

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

Format an unsigned long long as a printable String.

◆ String() [12/21]

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

Format a float as a printable String.

Nonfinite values are formatted as NaN, Inf, or -Inf as appropriate (Matlab compatible). The default format specification includes enough digits so that the identical value will be recovered if the string is converted back to float.

◆ String() [13/21]

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

Format a double as a printable String.

Nonfinite values are formatted as NaN, Inf, or -Inf as appropriate (Matlab compatible). The default format specification includes enough digits so that the identical value will be recovered if the string is converted back to double.

◆ String() [14/21]

SimTK::String::String ( std::complex< float >  r,
const char *  fmt = "%.9g" 
)
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.

◆ String() [15/21]

SimTK::String::String ( std::complex< double >  r,
const char *  fmt = "%.17g" 
)
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.

◆ String() [16/21]

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.

◆ String() [17/21]

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 stream insertion operator<<(T) to generate the String when no specialization of this constructor is available.

A runtime error is thrown if this method is invoked and neither a specialization nor stream insertion operator is available.

◆ String() [18/21]

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.

◆ String() [19/21]

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

Same, but allows for format specification.

◆ String() [20/21]

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.

◆ String() [21/21]

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

Same, but allows for format specification.

Member Function Documentation

◆ operator const char *()

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

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

◆ operator[]() [1/4]

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

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

◆ operator[]() [2/4]

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

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

◆ operator[]() [3/4]

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

Pass through to string::operator[].

◆ operator[]() [4/4]

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

Pass through to string::operator[].

◆ size()

int SimTK::String::size ( ) const
inline

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

◆ length()

int SimTK::String::length ( ) const
inline

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

◆ tryConvertTo()

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
TA 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]outThe 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>()

◆ convertTo() [1/2]

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]outThe converted value.
See also
tryConvertTo<T>(out), SimTK::convertStringTo<T>()

◆ convertTo() [2/2]

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

◆ tryConvertToBool()

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.

◆ tryConvertToFloat()

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.

◆ tryConvertToDouble()

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.

◆ toUpper() [1/2]

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

◆ toLower() [1/2]

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

◆ trimWhiteSpace() [1/2]

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

◆ replaceAllChar() [1/2]

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

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

◆ toUpper() [2/2]

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

◆ toLower() [2/2]

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

◆ trimWhiteSpace() [2/2]

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

◆ replaceAllChar() [2/2]

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

◆ convertStringTo() [1/2]

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

◆ convertStringTo() [2/2]

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: