dlr::utilities Namespace Reference

This namespace contains general utility functions and classes for string manipluation, program option parsing, working with time and filenames, and a few other odds and ends. More...

Classes
class	Date
	As you'd expect, the Date class represents a date, like 2003-03-15. More...
class	FrequencyGoverner
	The FrequencyGoverner class allows you to conveniently throttle a loop so that it runs at a specific speed. More...
class	LockFile
	The LockFile class tries to create a file which is uniquely owned by the calling process. More...
class	OptionDescription
	The OptionDescription class. More...
class	OptionParser
	The OptionParser class parses program options. More...
Functions
bool	operator< (const Date &date0, const Date &date1)
	This function compares two dates.
bool	operator> (const Date &date0, const Date &date1)
	This function compares two dates.
bool	operator<= (const Date &date0, const Date &date1)
	This function compares two dates.
bool	operator>= (const Date &date0, const Date &date1)
	This function compares two dates.
bool	operator== (const Date &date0, const Date &date1)
	This function compares two dates.
bool	operator!= (const Date &date0, const Date &date1)
	This function compares two dates.
std::ostream &	operator<< (std::ostream &stream, const Date &date)
	This operator formats a date in ISO standard format ("yyyy-mm-dd") for stream output.
std::istream &	operator>> (std::istream &stream, Date &date)
	This operator reads a date in ISO standard format ("yyyy-mm-dd") from an input stream.
	DLR_DECLARE_EXCEPTION_TYPE (ConversionException, ValueException)
	This is an Exception class for errors involving failed conversions from one type to another.
template<class Type>
void	writePGM (const std::string &fileName, const Type *imageData, const size_t rows, const size_t columns, bool normalize, bool rawFormat, int bitsPerPixel)
template<class Type>
void	writePPM (const std::string &fileName, const Type *imageData, const size_t rows, const size_t columns, bool normalize=false, bool rawFormat=true, int bitsPerPixel=8)
std::ostream &	operator<< (std::ostream &stream, const OptionDescription &optionDescription)
bool	isDirectory (const std::string &path)
	This function returns a bool indicating whether or not the specified path is a directory.
bool	isExistingPath (const std::string &path)
bool	isRegularFile (const std::string &path)
std::string	joinPath (const std::string &part0, const std::string &part1)
	Joins two path elements with the appropriate path delimiter.
std::vector< std::string >	listDirectory (const std::string &directoryName, bool fullPath=false)
	Returns the names of the entries in the specified directory, in no particular order.
std::vector< std::string >	recursiveListDirectory (const std::string &directoryName, bool fullPath=false, bool includeDirectoryNames=false)
	Returns the names of files in the directory tree below the specified directory.
std::pair< std::string, std::string >	splitExtension (const std::string &fileName)
	Returns a std::pair<std::string, std::string> containing the fileName without its extension, and the extension.
std::pair< std::string, std::string >	splitPath (const std::string &path)
	This function accepts a path returns a pair of strings in which the first element is the directory name and the second is the filename.
template<class ArrayType>
std::string	toPythonList (const ArrayType &array0)
	This function formats a 1D array in a way that python can parse into a built-in list.
template<class ArrayType>
std::string	toPythonNumericArray (const ArrayType &array0)
template<class ArrayType>
std::string	toPythonNumeric1DArray (const ArrayType &array0)
	This function formats a 1D Array object in a way that python can parse into a Numeric array.
template<class ArrayType>
std::string	toPythonNumeric2DArray (const ArrayType &array0)
	This function formats an 2D Array object in a way that python can parse into a Numeric array.
std::string	cleanString (const std::string &inputString, const std::string &specialCharacters="\"~#$&*()\\|[]{};'`<>/?", char quoteCharacter='\\', bool alreadyQuoted=false)
	This function takes an input string and returns a string in which all special shell characters have been escaped.
std::string	joinString (const std::vector< std::string > &inputStringVector, const std::string &separator="")
	This function returns a single string comprising copies of all of the strings in inputStringVector, interposed by the copies of separator.
std::string	lowerCaseString (const std::string &inputString)
	This function returns a copy of the input argument in which every uppercase character has been replaced with its lowercase equivalent.
std::string	replaceString (const std::string &inputString, const std::string &target, const std::string &replacement)
	This function copies a string, replacing non-overlapping occurrences of a target string with the specified replacement.
std::vector< std::string >	splitString (const std::string &inputString, const std::string &delimiter, bool includeNullStrings=false, size_t maxSplit=0)
	This function divides inputString around instances of delimiter.
std::string	stripString (const std::string &inputString, const std::string &whiteSpace=" \t\n")
	This function removes whitespace from the beginning and end of a string.
std::string	upperCaseString (const std::string &inputString)
	This function returns a copy of the input argument in which every lowercase character has been replaced with its uppercase equivalent.
std::string	wrapString (const std::string &inputString, const std::string &fillPrefix="", size_t width=78, const std::string &whitespace=" \t\n", const std::string &eolString="\n")
	This function returns a copy of the input argument in which end-of-line markers have been inserted to wrap the string at a specified line length.
template<class Type>
Type	convertString (const std::string &inputString)
	This function converts the string inputString to Type.
template<class Type>
Type	convertString (const std::string &inputString, type_tag< Type >)
	This function converts the string inputString to Type.
std::string	wrapString (const std::string &inputString, size_t width, const std::string &whitespace=" \t\n", const std::string &eolString="\n")

---

Detailed Description

This namespace contains general utility functions and classes for string manipluation, program option parsing, working with time and filenames, and a few other odds and ends.

---

Function Documentation

std::string dlr::utilities::cleanString	(	const std::string &	inputString,
		const std::string &	specialCharacters = "\"~#$&*()\\|[]{};'`<>/?",
		char	quoteCharacter = '\\',
		bool	alreadyQuoted = false
	)

This function takes an input string and returns a string in which all special shell characters have been escaped.

The list of special characters is specified as a string, and defaults to the following characters, including the double quote character: "~#$&*()\|[]{};'`<>/?". The third argument specifies the quote character, and defaults to the backslash character ("\"). The third argument affects how quote characters in the input are handled. By default, quote characters are escaped just like any other special character. If the third argument is set to true, then it is assumed that parts of the string have already been quoted, and quote characters are not quoted. For example:

cleanString("~foo\;bar\b;az", "\;~", '\', false); will return the string "\~foo\\\;bar\\b\;az",

and

cleanString("~foo\;bar\b;az", "\;~", '\', true); will return the string "\~foo\;bar\b\;az".

Parameters:

inputString

Returns:

Definition at line 24 of file stringManipulation.cpp.

template<class Type>

Type dlr::utilities::convertString	(	const std::string &	inputString,
		type_tag< Type >
	)			[inline]

This function converts the string inputString to Type.

For example:

int intValue = convertString("23", dlr::type_tag<int>());

or, using the predefined tag "Int",

int intValue = convertString("23", dlr::Int);

Conversion is done using the stream input operator of the target class. If the conversion fails, a dlr::utilities::ConversionException is thrown.

Parameters:

inputString

This argument is the string to be converted.

Returns:

The return value an instance of the target type which has had its value set by stream input from the specified string.

Definition at line 415 of file stringManipulation.h.

template<class Type>

Type dlr::utilities::convertString

(

const std::string &

inputString

)

[inline]

This function converts the string inputString to Type.

For example:

int intValue = convertString<int>("23");

Conversion is done using the stream input operator of the target class. If the conversion fails, a dlr::utilities::ConversionException is thrown.

Parameters:

inputString

This argument is the string to be converted.

Returns:

The return value an instance of the target type which has had its value set by stream input from the specified string.

Definition at line 397 of file stringManipulation.h.

References DLR_THROW.

dlr::utilities::DLR_DECLARE_EXCEPTION_TYPE	(	ConversionException	,
		ValueException
	)

This is an Exception class for errors involving failed conversions from one type to another.

bool dlr::utilities::isDirectory

(

const std::string &

path

)

This function returns a bool indicating whether or not the specified path is a directory.

If the path is a symbolic link, the return value is currently unspecified, but will eventually be true iff the link points to a directory.

Parameters:

path

This argument is the filename to evaluate.

Returns:

The return value is true if path refers to a directory, false otherwise.

Definition at line 34 of file path.cpp.

References dlr::portability::isDirectory().

Referenced by recursiveListDirectory().

std::string dlr::utilities::joinPath	(	const std::string &	part0,
		const std::string &	part1
	)

Joins two path elements with the appropriate path delimiter.

For example: joinPath("foo", "bar"); might give "foo/bar" while joinPath("foo/baz/", "bar"); might give "/foo/baz/bar"

Definition at line 73 of file path.cpp.

References dlr::portability::joinPath().

Referenced by recursiveListDirectory().

std::string dlr::utilities::joinString	(	const std::vector< std::string > &	inputStringVector,
		const std::string &	separator = ""
	)

This function returns a single string comprising copies of all of the strings in inputStringVector, interposed by the copies of separator.

For example:

joinString(["Hi", "there", "honey", "bear"], "/");

will return "Hi/there/honey/bear".

Parameters:

	inputStringVector	This argument specifies the strings to be concatenated.
	separator	This argument specifies text to be repeated between consecutive elements of inputStringVector.

Returns:

The return value is the concatenation of the elements of inputStringVector, with the contents of separator interposed between elements.

Definition at line 81 of file stringManipulation.cpp.

std::vector< std::string > dlr::utilities::listDirectory	(	const std::string &	directoryName,
		bool	fullPath = false
	)

Returns the names of the entries in the specified directory, in no particular order.

For example, listDirectory("/etc"); might give ["fstab", "init.d", "modules.conf", ...] while listDirectory("/etc", true); might give ["/etc/fstab", "/etc/init.d", "/etc/modules.conf", ...]

Definition at line 82 of file path.cpp.

References dlr::portability::listDirectory().

Referenced by recursiveListDirectory().

std::string dlr::utilities::lowerCaseString

(

const std::string &

inputString

)

This function returns a copy of the input argument in which every uppercase character has been replaced with its lowercase equivalent.

For example:

lowerCaseString("hI TheRe!")

will return "hi there!"

Parameters:

inputString

This argument specifies the string which will be converted to lower case.

Returns:

The return value is the converted string.

Definition at line 105 of file stringManipulation.cpp.

bool dlr::utilities::operator!=	(	const Date &	date0,
		const Date &	date1
	)

This function compares two dates.

Parameters:

	date0	This argument is the first date to compare.
	date1	This argument is the second date to compare.

Returns:

The return value is true if first date is different than the second, otherwise false.

Definition at line 157 of file date.cpp.

bool dlr::utilities::operator<	(	const Date &	date0,
		const Date &	date1
	)

This function compares two dates.

Parameters:

	date0	This argument is the first date to compare.
	date1	This argument is the second date to compare.

Returns:

The return value is true if first date is earlier than the second, otherwise false.

Definition at line 112 of file date.cpp.

References dlr::utilities::Date::day(), dlr::utilities::Date::month(), and dlr::utilities::Date::year().

std::ostream & dlr::utilities::operator<<	(	std::ostream &	stream,
		const Date &	date
	)

This operator formats a date in ISO standard format ("yyyy-mm-dd") for stream output.

Parameters:

	stream	This argument is the stream to which the format is to be written.
	date	This argument is the date to be formatted.

Returns:

The return value is the stream, after the output operation.

Definition at line 163 of file date.cpp.

References dlr::utilities::Date::day(), dlr::utilities::Date::month(), and dlr::utilities::Date::year().

bool dlr::utilities::operator<=	(	const Date &	date0,
		const Date &	date1
	)

This function compares two dates.

Parameters:

	date0	This argument is the first date to compare.
	date1	This argument is the second date to compare.

Returns:

The return value is true if first date is earlier than or equal to the second, otherwise false.

Definition at line 137 of file date.cpp.

bool dlr::utilities::operator==	(	const Date &	date0,
		const Date &	date1
	)

This function compares two dates.

Parameters:

	date0	This argument is the first date to compare.
	date1	This argument is the second date to compare.

Returns:

The return value is true if first date is the same as the second, otherwise false.

Definition at line 149 of file date.cpp.

References dlr::utilities::Date::day(), dlr::utilities::Date::month(), and dlr::utilities::Date::year().

bool dlr::utilities::operator>	(	const Date &	date0,
		const Date &	date1
	)

This function compares two dates.

Parameters:

	date0	This argument is the first date to compare.
	date1	This argument is the second date to compare.

Returns:

The return value is true if first date is later than the second, otherwise false.

Definition at line 131 of file date.cpp.

bool dlr::utilities::operator>=	(	const Date &	date0,
		const Date &	date1
	)

This function compares two dates.

Parameters:

	date0	This argument is the first date to compare.
	date1	This argument is the second date to compare.

Returns:

The return value is true if first date is later than or equal to the second, otherwise false.

Definition at line 143 of file date.cpp.

std::istream & dlr::utilities::operator>>	(	std::istream &	stream,
		Date &	date
	)

This operator reads a date in ISO standard format ("yyyy-mm-dd") from an input stream.

Parameters:

	stream	This argument is the stream from which the date is to be read.
	date	This argument is the date to be modified.

Returns:

The return value is the stream, after the input operation.

Definition at line 172 of file date.cpp.

std::vector< std::string > dlr::utilities::recursiveListDirectory	(	const std::string &	directoryName,
		bool	fullPath = false,
		bool	includeDirectoryNames = false
	)

Returns the names of files in the directory tree below the specified directory.

For example,

recursiveListDirectory("/etc");

might give

["fstab", "init.d/cron", "init.d/ssh", "modules.conf", ...]

while

recursiveListDirectory("/etc", true);

might give

["fstab", "init.d", "init.d/cron", "init.d/ssh", "modules.conf", ...]

and

recursiveListDirectory("/etc", true, true);

might give

["/etc/fstab", "/etc/init.d", "/etc/init.d/cron", "/etc/init.d/ssh", "/etc/modules.conf", ...]

Parameters:

directoryName

This argument specifies the directory to be listed.

Returns:

The return value is a vector of file names.

Definition at line 92 of file path.cpp.

References isDirectory(), joinPath(), and listDirectory().

std::string dlr::utilities::replaceString	(	const std::string &	inputString,
		const std::string &	target,
		const std::string &	replacement
	)

This function copies a string, replacing non-overlapping occurrences of a target string with the specified replacement.

For example:

replaceString("hohoohooohooooho", "oo", "ii")

gives

"hohiihiiohiiiiho"

Parameters:

	inputString	This argument species the string which is to be copied.
	target	This argument specifies the substring which is to be replaced.
	replacement	This argument specifies the string which is to be substituted for each instance of the target.

Returns:

The return value is a string in which all non-overlapping instances of target have been replaced with replacement.

Definition at line 121 of file stringManipulation.cpp.

Referenced by dlr::utilities::Date::setISODate().

std::pair< std::string, std::string > dlr::utilities::splitExtension

(

const std::string &

fileName

)

Returns a std::pair<std::string, std::string> containing the fileName without its extension, and the extension.

For example: splitExt("/foo/bar.baz") might return {"/foo/bar", ".baz"}

Definition at line 151 of file path.cpp.

References dlr::portability::extensionDelimiter(), and dlr::portability::pathDelimiter().

std::pair< std::string, std::string > dlr::utilities::splitPath

(

const std::string &

path

)

This function accepts a path returns a pair of strings in which the first element is the directory name and the second is the filename.

For example:

splitPath("/foo/bar.baz")

might return

{"/foo/", "bar.baz"}

Also,

splitPath("bar.baz")

might return

{"", "bar.baz"}

splitPath("/foo/")

might return

{"/foo/", ""}

Returns:

The return value is a pair containing first the directory name, and second the file name.

Definition at line 173 of file path.cpp.

References dlr::portability::splitPath().

std::vector< std::string > dlr::utilities::splitString	(	const std::string &	inputString,
		const std::string &	delimiter,
		bool	includeNullStrings = false,
		size_t	maxSplit = 0
	)

This function divides inputString around instances of delimiter.

For example:

splitString("04//22/2001", "/")

gives

["04", "22", "2001"]

and

splitString("04 - 22 - 2001", " - ")

gives

["04", "22", "2001"]

Setting includeNullStrings to true makes the return value include even strings of zero length.

splitString("04//22/2001", "/", true)

gives

["04", "", "22", "2001"]

and

splitString("hellohehoundhe", "he", true)

gives

["", "llo", "hound", ""]

Parameters:

	inputString	This argument specifies the string which is to be split.
	delimiter	This argument the substring around which inputString should be divided.
	includeNullStrings	This argument specifies whether zero-length substrings should be included in the output.
	maxSplit	If this argument is non-zero, it limits the number of splits performed. If maxSplit is non-zero, then the returned vector of strings will have at most (maxSplit + 1) elements, with the first maxSplit elements being formed by splitting chunks off the beginning of the string, and the final element being the remainder of the string after the first maxSplit splits are performed. If this argument is zero, then the number of splits will not be limited.

Returns:

The return value is a vector of substrings as described above.

Definition at line 148 of file stringManipulation.cpp.

Referenced by dlr::utilities::OptionDescription::getMatchLength().

std::string dlr::utilities::stripString	(	const std::string &	inputString,
		const std::string &	whiteSpace = " \t\n"
	)

This function removes whitespace from the beginning and end of a string.

If the second argument is specified, it indicates which characters should be considered to be whitespace.

Parameters:

	inputString	This is the string to be stripped.
	whiteSpace	The characters of this string define what qualifies as whitespace.

Returns:

A copy of inputString from which leading and trailing whitespace has been removed.

Definition at line 185 of file stringManipulation.cpp.

template<class ArrayType>

std::string dlr::utilities::toPythonList

(

const ArrayType &

array0

)

[inline]

This function formats a 1D array in a way that python can parse into a built-in list.

The output will look something like this:

[1, 2, 3, 4]

The provided array object should provide the following member functions.

• size() const: This member function should return the total number of elements in the array.

• operator[](size_t) const: This member function should return by value one element of the array.

Parameters:

array0

This argument is the array to be formatted.

Returns:

The return value is a string containing the python-friendly text.

Definition at line 141 of file pythonIO.h.

References dlr::numeric::count().

Referenced by toPythonNumeric1DArray(), and toPythonNumeric2DArray().

template<class ArrayType>

std::string dlr::utilities::toPythonNumeric1DArray

(

const ArrayType &

array0

)

[inline]

This function formats a 1D Array object in a way that python can parse into a Numeric array.

The output will look something like this:

array([1, 2, 3, 4])

The provided array object should provide an interface compatible with the function toPythonList(), which is declared above.

Parameters:

array0

This argument is the array to be formatted.

Returns:

The return value is a string containing the python-friendly text.

Definition at line 189 of file pythonIO.h.

References toPythonList().

template<class ArrayType>

std::string dlr::utilities::toPythonNumeric2DArray

(

const ArrayType &

array0

)

[inline]

This function formats an 2D Array object in a way that python can parse into a Numeric array.

The output will look something like this:

array([[1, 2], [3, 4]])

The provided array object should provide the following member functions.

• rows() const: This member function should return the total number of rows in the array.

• row(size_t) const: This member function should return an array-like object which addresses a specific row of the array. This object must be compatible with the function toPythonList(), which is declared above.

Parameters:

array0

This argument is the array to be formatted.

Returns:

The return value is a string containing the python-friendly text.

Definition at line 209 of file pythonIO.h.

References toPythonList().

Referenced by toPythonNumericArray().

template<class ArrayType>

std::string dlr::utilities::toPythonNumericArray

(

const ArrayType &

array0

)

[inline]

Deprecated:

{Replaced by toPythonNumeric2DArray().}

This function is an alias for toPythonNumeric2DArray(). It is deprecated, and kept around to support legacy code.

Parameters:

array0

This argument is the array to be formatted.

Returns:

The return value is a string containing the python-friendly text.

Definition at line 64 of file pythonIO.h.

References toPythonNumeric2DArray().

std::string dlr::utilities::upperCaseString

(

const std::string &

inputString

)

This function returns a copy of the input argument in which every lowercase character has been replaced with its uppercase equivalent.

For example:

upperCaseString("hI TheRe!")

will return "HI THERE!"

Parameters:

inputString

This argument specifies the string which will be converted to upper case.

Returns:

The return value is the converted string.

Definition at line 202 of file stringManipulation.cpp.

std::string dlr::utilities::wrapString	(	const std::string &	inputString,
		size_t	width,
		const std::string &	whitespace = " \t\n",
		const std::string &	eolString = "\n"
	)			[inline]

Deprecated:

{Please use the 5-argument version of wrapString().}

This is a deprecated interface to the wrapString function. It does not allow specifying a fill prefix, and is retained to support legacy code.

Parameters:

	inputString	This argument is the string to be wrapped.
	width	This argument specifies the target line length for the returned string. Individual lines will only exceed this length if there are words in the input string which have more than width characters.
	whitespace	This argument specifies which characters should count as whitespace when breaking inputString. The string may be broken around an character present in whitespace.
	eolString	This argument specifies the end-of-line marker. This is used for two things: its presence is used to identify existing newlines in the input string, and it is inserted into the output string to introduce a newline.

Returns:

The return value is a wrapped string.

Definition at line 355 of file stringManipulation.h.

References wrapString().

std::string dlr::utilities::wrapString	(	const std::string &	inputString,
		const std::string &	fillPrefix = "",
		size_t	width = 78,
		const std::string &	whitespace = " \t\n",
		const std::string &	eolString = "\n"
	)

This function returns a copy of the input argument in which end-of-line markers have been inserted to wrap the string at a specified line length.

Wrapping will only occur at places where there is whitespace. This means that long sections with no whitespace will not be broken, and may exceed the requested line length. For example:

wrapString("This is a string to be wrapped.\nYesyesyes indeed it is", "", 8, " ", "\n")

will return

"This is\na string\nto be\nwrapped.\nYesyesyes\nindeed\nit is"

and

wrapString("This is a string to be wrapped.\nYesyesyes indeed", "> ", 10, " ", "\n")

will return

"This is a\n> string\n> to be\n> wrapped.\n> Yesyesyes\n> indeed"

Parameters:

	inputString	This argument is the string to be wrapped.
	fillPrefix	This prefix will be inserted immediately after each newline in the output string.
	width	This argument specifies the target line length for the returned string. Individual lines will only exceed this length if there are words in the input string which have more than width characters.
	whitespace	This argument specifies which characters should count as whitespace when breaking inputString. The string may be broken around an character present in whitespace.
	eolString	This argument specifies the end-of-line marker. This is used for two things: its presence is used to identify existing newlines in the input string, and it is inserted into the output string to introduce a newline.

Returns:

The return value is a wrapped string.

Definition at line 219 of file stringManipulation.cpp.

Referenced by dlr::utilities::OptionDescription::getOptionDoc(), dlr::utilities::OptionParser::getUsage(), and wrapString().

---