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.
| |
| 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... | |
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
◆ String() [1/21]
|
inline |
Default constructor produces an empty string.
◆ String() [2/21]
|
inline |
This is an implicit conversion from const char* to String.
◆ String() [3/21]
|
inlineexplicit |
We allow creating a String from a char but you have to do it explicitly.
◆ String() [4/21]
|
inline |
This is an implicit conversion from std::string to String.
◆ String() [5/21]
|
inline |
Construct a String as a copy of a substring beginning at position start with length len.
◆ String() [6/21]
|
inlineexplicit |
Format an int as a printable String.
◆ String() [7/21]
|
inlineexplicit |
Format a long as a printable String.
◆ String() [8/21]
|
inlineexplicit |
Format a long long as a printable String.
◆ String() [9/21]
|
inlineexplicit |
Format an unsigned int as a printable String.
◆ String() [10/21]
|
inlineexplicit |
Format an unsigned long as a printable String.
◆ String() [11/21]
|
inlineexplicit |
Format an unsigned long long as a printable String.
◆ String() [12/21]
|
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]
|
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]
|
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]
|
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]
|
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]
|
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]
|
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]
|
inline |
Same, but allows for format specification.
◆ String() [20/21]
|
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]
|
inline |
Same, but allows for format specification.
Member Function Documentation
◆ operator const char *()
|
inline |
This is an implicit conversion from String to null-terminated C-style string (array of chars).
◆ operator[]() [1/4]
|
inline |
Add operator[] that takes int index instead of size_type.
◆ operator[]() [2/4]
|
inline |
Add operator[] that takes int index instead of size_type.
◆ operator[]() [3/4]
|
inline |
Pass through to string::operator[].
◆ operator[]() [4/4]
|
inline |
Pass through to string::operator[].
◆ size()
|
inline |
Override std::string size() method to return an int instead of the inconvenient unsigned type size_type.
◆ length()
|
inline |
Override std::string length() method to return an int instead of the inconvenient unsigned type size_type.
◆ tryConvertTo()
|
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>()
◆ convertTo() [1/2]
|
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>()
◆ convertTo() [2/2]
|
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]
|
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]
|
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 |
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]
|
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]
|
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:
- See also
- String::convertTo()
◆ convertStringTo() [2/2]
|
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:
- See also
- String::convertTo()
The documentation for this class was generated from the following file:
