StringUtilities Namespace Reference

This namespace contains helper functions for converting types to and from strings along with other convenience string functions. More...

Functions

bool readSTLString (FILE *pInputFile, size_t readSize, std::string &target, bool append=STL_OVERWRITE)

std::string stripLeftWhitespace (const std::string &source)

std::string stripRightWhitespace (const std::string &source)

std::string stripWhitespace (const std::string &source)

bool isAllBlank (const std::string &source)

std::string toLower (const std::string &source)

std::string toUpper (const std::string &source)

std::vector< std::string > split (const std::string &source, char separator)

std::string join (const std::vector< std::string > &source, const std::string &separator)

std::string latLonToText (LocationType latLonCoords)

std::string expandVariables (const std::string &originalString, const std::vector< std::string > &ignoredExpansions=std::vector< std::string >())

template<typename T>

std::string toXmlString (const T &value, bool *pError=NULL)

template<typename T>

T fromXmlString (std::string value, bool *pError=NULL)

template<typename T>

std::string toDisplayString (const T &value, bool *pError=NULL)

template<typename T>

T fromDisplayString (std::string value, bool *pError=NULL)

template<typename T>

std::vector< T > getAllEnumValues ()

template<typename T>

std::vector< std::string > getAllEnumValuesAsDisplayString ()

template<typename T>

std::vector< std::string > getAllEnumValuesAsXmlString ()

const char * escapedToken (const std::string &textIn=std::string())

Variables

const bool STL_APPEND = true

const bool STL_OVERWRITE = false

Detailed Description

This namespace contains helper functions for converting types to and from strings along with other convenience string functions.

Function Documentation

const char* StringUtilities::escapedToken ( const std::string & textIn = std::string() )

Tokenizes string on spaces, with escape support.

This function will start tokenizing a string provided by textIn, or continue tokenizing if the default parameter is used. Whitespace to the left and right of the token is removed. Characters may be escaped with the '\' character. The following escape codes are understood:

'\' -- gives a single backslash.
' ' -- gives a single space character.

This function is not thread safe.

Parameters:

textIn

Input string, of which a local copy is made. Tokenizing starts from the beginning of the string, or where left off if the default parameter is used.

Returns:: Returns the first token, with escaped text replaced as appropriate. This method owns the memory returned.

std::string StringUtilities::expandVariables	(	const std::string &	originalString,
		const std::vector< std::string > &	ignoredExpansions = `std::vector< std::string >()`
	)

Expand the variables in this string and return the expanded result.

The syntax for referencing variables is $V(varname), $E(varname) or $C(varname). The $V(varname) syntax only recognizes the following variable names: APP_HOME, APP_VERSION, or USER_DOCS. These can be expanded to the location where this application was installed, the version of the application that is running, or the location of the user's documents folder. For example, $V(APP_HOME) could expand to "C:\Program Files\Application\4.0.0", $V(APP_VERSION) could expand to "4.0.0", and $V(USER_DOCS) could expand to "C:\Documents and Settings\user". The $E(varname) syntax looks for an environment variable defined with the same name and substitutes the value. If the environment variable cannot be found, the $E(varname) is left in the string. The $C(varname) syntax looks for a setting in ConfigurationSettings with the same name and if found substitute's in the value. If the setting cannot be found, the $C(varname) is left in the string. If you need to include a $ in the string, please use $$ to escape the $.

Parameters:

	originalString	The string that should be expanded.
	ignoredExpansions	The list of variable expansions that should be ignored. For example, providing a vector with 'E' and 'C' in it, would cause $E(varname) and $C(varname) to be left in the string as is (i.e. no expansion would occur).

Returns:: the expanded string.

template<typename T>

T StringUtilities::fromDisplayString	(	std::string	value,
		bool *	pError = `NULL`
	)

Parse the given string into the given type.

This method should only be used to parse string values that were returned from toDisplayString. For a list of types supported see Supported StringUtilities Types.

Parameters:

	value	The string to parse.
	pError	If this value is non-NULL, the bool will be set to true if there was an error while parsing the string, and false if the parse was successful.

Returns:: Returns the parsed value of the given type. If there was an error, a default constructed value of the given type will be returned. If the type is a pointer then NULL will be returned.

template<typename T>

T StringUtilities::fromXmlString	(	std::string	value,
		bool *	pError = `NULL`
	)

Parse the given string into the given type.

This method should only be used to parse string values that were returned from toXmlString. For a list of types supported see Supported StringUtilities Types.

Parameters:

	value	The string to parse.
	pError	If this value is non-NULL, the bool will be set to true if there was an error while parsing the string, and false if the parse was successful.

Returns:: Returns the parsed value of the given type. If there was an error, a default constructed value of the given type will be returned. If the type is a pointer then NULL will be returned.

template<typename T>

std::vector<T> StringUtilities::getAllEnumValues ( )

Provides a list of all enum values for the given enum provided to the template.

This method is only supported by the enum types listed in Supported StringUtilities Types.

Returns:: Returns a list all enum values for the given enum type.

See also:: getAllEnumValuesAsDisplayString(), getAllEnumValuesAsXmlString()

template<typename T>

std::vector<std::string> StringUtilities::getAllEnumValuesAsDisplayString ( )

Provides a list of display strings for all of the enum values for the given enum type.

This method is only supported by the enum types listed in Supported StringUtilities Types.

Returns:: Returns the result of calling toDisplayString() on every value in the vector that would be returned by getAllEnumValues(). The ordering of the vectors returned by this method and getAllEnumValues() is guaranteed to be the same.

See also:: getAllEnumValues(), getAllEnumValuesAsXmlString()

template<typename T>

std::vector<std::string> StringUtilities::getAllEnumValuesAsXmlString ( )

Provides a list of xml strings for all of the enum values for the given enum type.

This method is only supported by the enum types listed in Supported StringUtilities Types.

Returns:: Returns the result of calling toXmlString() on every value in the vector that would be returned by getAllEnumValues(). The ordering of the vectors returned by this method and getAllEnumValues() is guaranteed to be the same.

See also:: getAllEnumValues(), getAllEnumValuesAsDisplayString()

bool StringUtilities::isAllBlank ( const std::string & source )

Returns true if the string consists entirely of space characters.

Parameters:

source

The string to test

Returns:: True if the string contains only space characters or is empty, false otherwise.

std::string StringUtilities::join	(	const std::vector< std::string > &	source,
		const std::string &	separator
	)

Joins a vector of strings into a single string.

Parameters:

	source	The strings to join.
	separator	The string to insert between each source string.

Returns:: The joined string.

std::string StringUtilities::latLonToText ( LocationType latLonCoords )

Converts a LocationType whose values are in D.ddddd Lat/Lon format to a string.

Parameters:

latLonCoords

The source LocationType to be converted

Returns:: Returns a string displaying the Latitude/Longitude represented by the LocationType passed in.

bool StringUtilities::readSTLString	(	FILE *	pInputFile,
		size_t	readSize,
		std::string &	target,
		bool	append = `STL_OVERWRITE`
	)

Reads readSize number of characters from pInputFile and places them in string target.

Parameters:

	pInputFile	The file from which the string is read.
	readSize	The number of bytes to read
	target	Where to put the bytes that are read in.
	append	Whether to append to the existing string, or to overwrite it.

Returns:: Returns false if the file does not exist, or if there is a problem reading the requested bytes from the file. Otherwise, returns true.

std::vector<std::string> StringUtilities::split	(	const std::string &	source,
		char	separator
	)

Breaks up a string into a set of substrings.

This method breaks up a delimited string into its component substrings.

  string text("abc/123/def/456");
  vector<string> components = split(text, '/');
  // components has 4 strings: "abc", "123", "def", "456"

Parameters:

	source	The string to be split up.
	separator	This character will be used as a delimiter to break the source string up into substrings.

Returns:: Returns a vector containing the component strings.

std::string StringUtilities::stripLeftWhitespace ( const std::string & source )

Returns a copy of the string source, with all whitespace stripped from the left side.

Parameters:

source

The string from which the whitespace will be stripped.

Returns:: Returns a copy of the string with whitespace removed from the left side.

std::string StringUtilities::stripRightWhitespace ( const std::string & source )

Returns a copy of the string source, with all whitespace stripped from the right side.

Parameters:

source

The string from which the whitespace will be stripped.

Returns:: Returns a copy of the string with whitespace removed from the right side.

std::string StringUtilities::stripWhitespace ( const std::string & source )

Returns a copy of the string source, with all whitespace stripped from both sides.

Parameters:

source

The string from which the whitespace will be stripped.

Returns:: Returns a copy of the string with whitespace removed from both sides.

template<typename T>

std::string StringUtilities::toDisplayString	(	const T &	value,
		bool *	pError = `NULL`
	)

Convert the given value into a string.

The resulting string will be in a user-friendly representation. The resulting string is intended to be used when the value needs to be converted into a string in order to display to a end-user. The resulting string should not be expected to remain the same between different versions of the application.

Parameters:

	value	The value to convert into a string. For a list of types supported, see Supported StringUtilities Types.
	pError	If this value is non-NULL, the bool will be set to true if there was an error while converting the value into a string, and false if the conversion was successful.

Returns:: Returns the string representation of the given value. If there was an error, an empty string will be returned.

Examples:: Tutorial/Tutorial2.cpp, Tutorial/Tutorial3.cpp, and Tutorial/Tutorial4.cpp.

std::string StringUtilities::toLower ( const std::string & source )

Converts all uppercase letters to lowercase;.

Parameters:

source

The source string for the conversion process.

Returns:: Returns a copy of the string with all uppercase letters converted to lowercase.

std::string StringUtilities::toUpper ( const std::string & source )

Converts all lowercase letters to uppercase;.

Parameters:

source

The source string for the conversion process.

Returns:: Returns a copy of the string with all lowercase letters converted to uppercase.

template<typename T>

std::string StringUtilities::toXmlString	(	const T &	value,
		bool *	pError = `NULL`
	)

Convert the given value into a string.

The resulting string will be in a XML-friendly representation. In addition, the string representation of the value returned by this method should be subject to less change than the value returned from toDisplayString.

Parameters:

	value	The value to convert into a string. For a list of types supported, see Supported StringUtilities Types.
	pError	If this value is non-NULL, the bool will be set to true if there was an error while converting the value into a string, and false if the conversion was successful.

Returns:: Returns the string representation of the given value. If there was an error, an empty string will be returned.

Variable Documentation

const bool StringUtilities::STL_APPEND = true

Definition at line 26 of file StringUtilities.h.

const bool StringUtilities::STL_OVERWRITE = false

Definition at line 27 of file StringUtilities.h.


Functions
bool	readSTLString (FILE *pInputFile, size_t readSize, std::string &target, bool append=STL_OVERWRITE)
std::string	stripLeftWhitespace (const std::string &source)
std::string	stripRightWhitespace (const std::string &source)
std::string	stripWhitespace (const std::string &source)
bool	isAllBlank (const std::string &source)
std::string	toLower (const std::string &source)
std::string	toUpper (const std::string &source)
std::vector< std::string >	split (const std::string &source, char separator)
std::string	join (const std::vector< std::string > &source, const std::string &separator)
std::string	latLonToText (LocationType latLonCoords)
std::string	expandVariables (const std::string &originalString, const std::vector< std::string > &ignoredExpansions=std::vector< std::string >())
template<typename T>
std::string	toXmlString (const T &value, bool *pError=NULL)
template<typename T>
T	fromXmlString (std::string value, bool *pError=NULL)
template<typename T>
std::string	toDisplayString (const T &value, bool *pError=NULL)
template<typename T>
T	fromDisplayString (std::string value, bool *pError=NULL)
template<typename T>
std::vector< T >	getAllEnumValues ()
template<typename T>
std::vector< std::string >	getAllEnumValuesAsDisplayString ()
template<typename T>
std::vector< std::string >	getAllEnumValuesAsXmlString ()
const char *	escapedToken (const std::string &textIn=std::string())
Variables
const bool	STL_APPEND = true
const bool	STL_OVERWRITE = false