Description

Functions for operating on strings.

This name space provides functions for operating on strings. See also, Boost String Algo [http://http://www.boost.org/doc/libs/1_61_0/doc/html/string_algo.html].

Classes
struct	StringWithLineNumber
	String with source location information. More...

Typedefs
typedef std::vector< StringWithLineNumber >	FileWithLineNumbers
	A vector of strings with line numbers and file names. More...

Enumerations
enum	OSType { OS_TYPE_UNKNOWN, OS_TYPE_LINUX, OS_TYPE_OSX, OS_TYPE_WINDOWS, OS_TPYE_WINDOWSXP }

Functions
ROSE_UTIL_API OSType	getOSType ()
	Obtain operating system type information. More...

ROSE_UTIL_API void	writeFile (const std::string &outputString, const std::string &fileNameString, const std::string &directoryName)
	Create a file. More...

ROSE_UTIL_API std::string	readFile (const std::string &fileName)
	Reads entire text file. More...

ROSE_UTIL_API FileWithLineNumbers	readFileWithPos (const std::string &fileName)
	Reads an entire text file. More...

ROSE_UTIL_API void	homeDir (std::string &dir)
	Name of the home directory. More...

ROSE_UTIL_API std::string	stripPathFromFileName (const std::string &fileNameWithPath)
	Returns the last component of a path in a filesystem. More...

ROSE_UTIL_API std::string	getPathFromFileName (const std::string &fileNameWithPath)
	Returns all but the last component of a path in a filesystem. More...

ROSE_UTIL_API std::string	stripFileSuffixFromFileName (const std::string &fileNameWithSuffix)
	Get the file name without the ".suffix". More...

ROSE_UTIL_API std::string	getAbsolutePathFromRelativePath (const std::string &relativePath, bool printErrorIfAny=false)
	Get the absolute path from the relative path. More...

ROSE_UTIL_API std::string	fileNameSuffix (const std::string &fileName)
	Get the file name suffix (extension) without the leading dot. More...

ROSE_UTIL_API std::string	htmlEscape (const std::string &)
	Escapes HTML special characters. More...

ROSE_UTIL_API std::string	cUnescape (const std::string &)
	Unescapes C++ string literals. More...

ROSE_UTIL_API std::string	bourneEscape (const std::string &)
	Escapes characters that are special to the Bourne shell. More...

ROSE_UTIL_API std::string	escapeNewLineCharaters (const std::string &)
	Escapes line feeds and double quotes. More...

ROSE_UTIL_API std::string	escapeNewlineAndDoubleQuoteCharacters (const std::string &)

ROSE_UTIL_API std::list< std::string >	tokenize (const std::string &, char delim)
	Split a string into a list based on a separator character. More...

ROSE_UTIL_API std::string	joinEnglish (const std::vector< std::string > &phrases, const std::string &separator=",", const std::string &finalIntro="and")
	Join strings as if they were English prose. More...

ROSE_UTIL_API std::string	listToString (const std::list< int > &, bool separateStrings=false)
	Generate a string from a list of integers. More...

ROSE_UTIL_API std::list< std::string >	stringToList (const std::string &)
	Split a string into substrings at line feeds. More...

ROSE_UTIL_API void	splitStringIntoStrings (const std::string &inputString, char separator, std::vector< std::string > &stringList)
	Splits string into substring based on a separator character. More...

ROSE_UTIL_API std::string	numberToString (const void *)
	Convert a pointer to a string. More...

ROSE_UTIL_API std::string	numberToString (double)
	Convert a floating-point number to a string. More...

ROSE_UTIL_API std::string	intToHex (uint64_t)
	Convert an integer to a hexadecimal string. More...

ROSE_UTIL_API std::string	addrToString (uint64_t value, size_t nbits=0)
	Convert a virtual address to a string. More...

ROSE_UTIL_API std::string	addrToString (const Sawyer::Container::Interval< uint64_t > &interval, size_t nbits=0)
	Convert an interval of virtual addresses to a string. More...

ROSE_UTIL_API std::string	addrToString (const Sawyer::Container::IntervalSet< Sawyer::Container::Interval< uint64_t > > &iset, size_t nbits=0)
	Convert an interval set of virtual addresses to a string. More...

template<typename Unsigned >
std::string	toBinary (Unsigned value, size_t nBits=0, size_t groupSize=4, const std::string groupSeparator="_")
	Convert a number to a binary string. More...

ROSE_UTIL_API unsigned	hexadecimalToInt (char)
	Convert an ASCII hexadecimal character to an integer. More...

ROSE_UTIL_API std::string	convertToLowerCase (const std::string &inputString)
	Convert to lower case. More...

ROSE_UTIL_API std::string	fixLineTermination (const std::string &input)
	Normalizes line termination. More...

ROSE_UTIL_API std::string	prefixLines (const std::string &lines, const std::string &prefix, bool prefixAtFront=true, bool prefixAtBack=false)
	Insert a prefix string before every line. More...

ROSE_UTIL_API std::string	makeOneLine (const std::string &s, std::string replacement=" ")
	Converts a multi-line string to a single line. More...

ROSE_UTIL_API std::string	trim (const std::string &str, const std::string &strip=" \t\r\n", bool at_beginning=true, bool at_end=true)
	Trims white space from the beginning and end of a string. More...

ROSE_UTIL_API std::string	untab (const std::string &str, size_t tabstops=8, size_t firstcol=0)
	Expand horizontal tab characters. More...

ROSE_UTIL_API std::string	removeRedundantSubstrings (const std::string &)
	Remove redundant and blank lines. More...

ROSE_UTIL_API std::vector< uint8_t >	decode_base64 (const std::string &encoded)
	Convert base-64 to binary. More...

ROSE_UTIL_API unsigned long	generate_checksum (std::string s)
	Compute a checkshum. More...

bool	isContainedIn (const std::string &longString, const std::string &shortString)
	Determines whether one string contains another. More...

ROSE_UTIL_API bool	isLineTerminated (const std::string &s)
	Returns true if the string ends with line termination. More...

ROSE_UTIL_API std::string	indentMultilineString (const std::string &inputString, int statementColumnNumber)
	Formatting support for generated code strings. More...

ROSE_UTIL_API void	add_to_reason_string (std::string &result, bool isset, bool do_pad, const std::string &abbr, const std::string &full)
	Append an abbreviation or full name to a string. More...

ROSE_UTIL_API std::string	appendAsmComment (const std::string &s, const std::string &comment)
	Append an assembly comment to a string. More...

template<typename T >
std::string	plural (T n, const std::string &plural_phrase, const std::string &singular_phrase="")
	Helpful way to print singular or plural words. More...

std::string	demangledName (std::string)
	Compute demangled version of mangled name. More...


ROSE_UTIL_API std::string	cEscape (const std::string &, char context= '"')
	Escapes characters that are special to C/C++. More...

ROSE_UTIL_API std::string	cEscape (char, char context= '\'')
	Escapes characters that are special to C/C++. More...


ROSE_UTIL_API std::vector< std::string >	split (const std::string &separator, const std::string &str, size_t maxparts=UNLIMITED, bool trim_white_space=false)
	Splits strings into parts. More...

ROSE_UTIL_API std::vector< std::string >	split (char separator, const std::string &str, size_t maxparts=UNLIMITED, bool trim_white_space=false)
	Splits strings into parts. More...


template<class Iterator >
std::string	join_range (const std::string &separator, Iterator begin, Iterator end)
	Join individual items to form a single string. More...

template<class Container >
std::string	join (const std::string &separator, const Container &container)
	Join individual items to form a single string. More...

template<class Container >
std::string	join (char separator, const Container &container)
	Join individual items to form a single string. More...

ROSE_UTIL_API std::string	join (const std::string &separator, char *strings[], size_t nstrings)
	Join individual items to form a single string. More...

ROSE_UTIL_API std::string	join (const std::string &separator, const char *strings[], size_t nstrings)
	Join individual items to form a single string. More...

ROSE_UTIL_API std::string	join (char separator, char *strings[], size_t nstrings)
	Join individual items to form a single string. More...

ROSE_UTIL_API std::string	join (char separator, const char *strings[], size_t nstrings)
	Join individual items to form a single string. More...


ROSE_UTIL_API std::string	listToString (const std::list< std::string > &, bool separateStrings=false)
	Generate a string from a container of strings. More...

ROSE_UTIL_API std::string	listToString (const std::vector< std::string > &, bool separateStrings=false)
	Generate a string from a container of strings. More...


ROSE_UTIL_API std::string	numberToString (long long)
	Convert an integer to a string. More...

ROSE_UTIL_API std::string	numberToString (unsigned long long)
	Convert an integer to a string. More...

ROSE_UTIL_API std::string	numberToString (long)
	Convert an integer to a string. More...

ROSE_UTIL_API std::string	numberToString (unsigned long)
	Convert an integer to a string. More...

ROSE_UTIL_API std::string	numberToString (int)
	Convert an integer to a string. More...

ROSE_UTIL_API std::string	numberToString (unsigned int)
	Convert an integer to a string. More...


ROSE_UTIL_API std::string	toHex2 (uint64_t value, size_t nbits, bool show_unsigned_decimal=true, bool show_signed_decimal=true, uint64_t decimal_threshold=256)
	Convert a number to a hexadecimal and decimal string. More...

ROSE_UTIL_API std::string	signedToHex2 (uint64_t value, size_t nbits)
	Convert a number to a hexadecimal and decimal string. More...

ROSE_UTIL_API std::string	unsignedToHex2 (uint64_t value, size_t nbits)
	Convert a number to a hexadecimal and decimal string. More...

template<typename T >
std::string	toHex (T value)
	Convert a number to a hexadecimal and decimal string. More...

template<typename T >
std::string	signedToHex (T value)
	Convert a number to a hexadecimal and decimal string. More...

template<typename T >
std::string	unsignedToHex (T value)
	Convert a number to a hexadecimal and decimal string. More...


template<class Container , class Stringifier >
std::vector< std::string >	toStrings (const Container &numbers, const Stringifier &stringifier=numberToString)
	Converts a bunch of numbers to strings. More...

template<class Iterator , class Stringifier >
std::vector< std::string >	toStrings_range (Iterator begin, Iterator end, const Stringifier &stringifier=numberToString)
	Converts a bunch of numbers to strings. More...


ROSE_UTIL_API std::string	encode_base64 (const std::vector< uint8_t > &data, bool do_pad=true)
	Convert binary data to base-64. More...

ROSE_UTIL_API std::string	encode_base64 (const uint8_t *data, size_t nbytes, bool do_padd=true)
	Convert binary data to base-64. More...

Typedef Documentation

typedef std::vector<StringWithLineNumber> Rose::StringUtility::FileWithLineNumbers

A vector of strings with line numbers and file names.

Definition at line 52 of file FileUtility.h.

Function Documentation

ROSE_UTIL_API OSType Rose::StringUtility::getOSType ( )

Obtain operating system type information.

ROSE_UTIL_API void Rose::StringUtility::writeFile	(	const std::string &	outputString,
		const std::string &	fileNameString,
		const std::string &	directoryName
	)

Create a file.

Creates a new file, truncating any existing file with the same name, and writes the string outputString into the file. The name of the file is constructed by concatenating directoryName and fileNameString without any intervening component separator (e.g., no "/").

If the file cannot be created then this function silently fails (or aborts if ROSE is compiled in debug mode).

ROSE_UTIL_API std::string Rose::StringUtility::readFile ( const std::string & fileName )

Reads entire text file.

Opens the specified file, reads its contents into a string, closes the file, and returns that string.

If the file cannot be opened then an std::string error message is thrown. The message reads "File not found" regardless of the actual error condition.

ROSE_UTIL_API FileWithLineNumbers Rose::StringUtility::readFileWithPos ( const std::string & fileName )

Reads an entire text file.

Opens the specified file, reads its contents line by line into a vector of strings with location information, closes the file, and returns the vector. The file names in the returned value are absolute names. The strings in the return value have their final line-feeds removed.

If the file cannot be opened then an std::string error message is thrown. The message reads "File not found" regardless of the actual error condition.

ROSE_UTIL_API void Rose::StringUtility::homeDir ( std::string & dir )

Name of the home directory.

Returns the value of the "HOME" environment variable by copying it into the dir argument. Will segfault if this environment variable is not set.

ROSE_UTIL_API std::string Rose::StringUtility::stripPathFromFileName ( const std::string & fileNameWithPath )

Returns the last component of a path in a filesystem.

Removes the "path" part of a "filename" (if there is one) and returns just the file name.

Terms are loosely defined and not likely to work for non-POSIX systems; consider using boost::filesystem instead.

ROSE_UTIL_API std::string Rose::StringUtility::getPathFromFileName ( const std::string & fileNameWithPath )

Returns all but the last component of a path in a filesystem.

This function removes the filename from the combined path and filename if it includes a path and returns only the path. Make it safe to input a filename without a path name (return the filename).

Terms are loosely defined and this function possibly doesn't work for non-POSIX file systems; consider using boost::filesystem instead.

ROSE_UTIL_API std::string Rose::StringUtility::stripFileSuffixFromFileName ( const std::string & fileNameWithSuffix )

Get the file name without the ".suffix".

Terms are loosely defined and it's not clear what happens for inputs like ".", ".foo", "..", ".foo.bar", "/.", etc. Consider using boost::filesystem instead.

ROSE_UTIL_API std::string Rose::StringUtility::getAbsolutePathFromRelativePath	(	const std::string &	relativePath,
		bool	printErrorIfAny = `false`
	)

Get the absolute path from the relative path.

Terms are loosely defined and this function is not likely to work on non-POSIX systems. Consider using boost::filesystem instead.

ROSE_UTIL_API std::string Rose::StringUtility::fileNameSuffix ( const std::string & fileName )

Get the file name suffix (extension) without the leading dot.

Filename could be either base name or name with full path. If no dot is found in the input fileName, the function just returns the original fileName.

Terms are loosely defined and this function is not likely to work correctly in some situations, such as when the "." is not in the last component of the file name. Consider using boost::filesystem instead.

ROSE_UTIL_API std::string Rose::StringUtility::htmlEscape ( const std::string & )

Escapes HTML special characters.

Replaces "<", ">", and "&" with HTML character names and returns the result.

ROSE_UTIL_API std::string Rose::StringUtility::cEscape	(	const std::string &	,
		char	context = `'"'`
	)

Escapes characters that are special to C/C++.

Replaces special characters in the input so that it is suitable for the contents of a C string literal (if context is a double quote character) or the contents of a C character constant (if context is a single quote). That is, things like double quotes, line-feeds, tabs, non-printables, etc. are replace by their C backslash escaped versions. Returns the resulting string.

Note that if the first argument is a string then the context defaults to string literals, and if the first argument is a single character then the context defaults to character literals. Although this is usually what one wants, it's possible to change the context in both situations.

Referenced by Rose::BinaryAnalysis::VxcoreParser::Exception::toString().

ROSE_UTIL_API std::string Rose::StringUtility::cEscape	(	char	,
		char	context = `'\''`
	)

Escapes characters that are special to C/C++.

Replaces special characters in the input so that it is suitable for the contents of a C string literal (if context is a double quote character) or the contents of a C character constant (if context is a single quote). That is, things like double quotes, line-feeds, tabs, non-printables, etc. are replace by their C backslash escaped versions. Returns the resulting string.

Note that if the first argument is a string then the context defaults to string literals, and if the first argument is a single character then the context defaults to character literals. Although this is usually what one wants, it's possible to change the context in both situations.

ROSE_UTIL_API std::string Rose::StringUtility::cUnescape ( const std::string & )

Unescapes C++ string literals.

When given a C++ string literals content, the part between the enclosing quotes, this function will look for escape sequences, parse them, and replace them in the return value with the actual characters they represent. For instance, passing in std::string{"hello\\nworld\\00hidden"} that contains 20 characters including two backslashes, the function replaces the first backslash+"n" pair with a line feed, and the second backslash+"0"+"0" with a NUL to result in std::string{"hello\nworld\0hidden"} (18 characters including the LF and NUL). Unicode escapes are not supported and will be left escaped in the return value.

ROSE_UTIL_API std::string Rose::StringUtility::bourneEscape ( const std::string & )

Escapes characters that are special to the Bourne shell.

Assumes that the context is outside of any quoting and possibly adds quotes.

ROSE_UTIL_API std::string Rose::StringUtility::escapeNewLineCharaters ( const std::string & )

Escapes line feeds and double quotes.

Scans the input string character by character and replaces line-feed characters with a backslash followed by the letter "l" and replaces double quotes by a backslash followed by a double qoute.

ROSE_UTIL_API std::vector<std::string> Rose::StringUtility::split	(	const std::string &	separator,
		const std::string &	str,
		size_t	maxparts = `UNLIMITED`,
		bool	trim_white_space = `false`
	)

Splits strings into parts.

Find all non-overlapping occurrences the specified separator string by greedily scanning from left to right in the input string, str. The input string is then logically chopped into parts at each separator position and the parts are assembled into the return value. Only up to maxparts-1 occurrences of the separator string are found, and any remaining occurrences are not treated specially. For instance, if maxparts is two then at most one separator is found and at most two substrings are returned. Separators at positions that would result in empty substrings being returned are not treated specially–empty substrings can be returned. This occurs when a separator is found at the beginning or end of a string or two separators are adjacent. The C++ library already has other functions for removing empty strings from a list. If trim_white_space is true then white space is removed from the beginning and end of each returned substring and resulting empty substrings are not removed from the return value. The first few arguments are in the same order as for Perl's "split" operator.

ROSE_UTIL_API std::vector<std::string> Rose::StringUtility::split	(	char	separator,
		const std::string &	str,
		size_t	maxparts = `UNLIMITED`,
		bool	trim_white_space = `false`
	)

Splits strings into parts.

Find all non-overlapping occurrences the specified separator string by greedily scanning from left to right in the input string, str. The input string is then logically chopped into parts at each separator position and the parts are assembled into the return value. Only up to maxparts-1 occurrences of the separator string are found, and any remaining occurrences are not treated specially. For instance, if maxparts is two then at most one separator is found and at most two substrings are returned. Separators at positions that would result in empty substrings being returned are not treated specially–empty substrings can be returned. This occurs when a separator is found at the beginning or end of a string or two separators are adjacent. The C++ library already has other functions for removing empty strings from a list. If trim_white_space is true then white space is removed from the beginning and end of each returned substring and resulting empty substrings are not removed from the return value. The first few arguments are in the same order as for Perl's "split" operator.

ROSE_UTIL_API std::list<std::string> Rose::StringUtility::tokenize	(	const std::string &	,
		char	delim
	)

Split a string into a list based on a separator character.

Scans the input string for delimiter characters and splits the input into substrings at each delimiter positions. The delimiter is not included in the substring. Consecutive delimiter characters will result in an empty substring.

template<class Iterator >

std::string Rose::StringUtility::join_range	(	const std::string &	separator,
		Iterator	begin,
		Iterator	end
	)

Join individual items to form a single string.

Given a container containing printable objects (such as std::list<std::string>, join the objects together separated from one another by the specified separator. The separator does not appear before the first object or after the final object. If the container is empty then an empty string is returned.

Definition at line 132 of file StringUtility.h.

Referenced by join().

template<class Container >

std::string Rose::StringUtility::join	(	const std::string &	separator,
		const Container &	container
	)

Join individual items to form a single string.

Given a container containing printable objects (such as std::list<std::string>, join the objects together separated from one another by the specified separator. The separator does not appear before the first object or after the final object. If the container is empty then an empty string is returned.

Definition at line 140 of file StringUtility.h.

References join_range().

Referenced by SqlDatabase::in_numbers().

template<class Container >

std::string Rose::StringUtility::join	(	char	separator,
		const Container &	container
	)

Join individual items to form a single string.

Given a container containing printable objects (such as std::list<std::string>, join the objects together separated from one another by the specified separator. The separator does not appear before the first object or after the final object. If the container is empty then an empty string is returned.

Definition at line 145 of file StringUtility.h.

References join_range().

ROSE_UTIL_API std::string Rose::StringUtility::join	(	const std::string &	separator,
		char *	strings[],
		size_t	nstrings
	)

Join individual items to form a single string.

Given a container containing printable objects (such as std::list<std::string>, join the objects together separated from one another by the specified separator. The separator does not appear before the first object or after the final object. If the container is empty then an empty string is returned.

ROSE_UTIL_API std::string Rose::StringUtility::join	(	const std::string &	separator,
		const char *	strings[],
		size_t	nstrings
	)

Join individual items to form a single string.

Given a container containing printable objects (such as std::list<std::string>, join the objects together separated from one another by the specified separator. The separator does not appear before the first object or after the final object. If the container is empty then an empty string is returned.

ROSE_UTIL_API std::string Rose::StringUtility::join	(	char	separator,
		char *	strings[],
		size_t	nstrings
	)

Join individual items to form a single string.

Given a container containing printable objects (such as std::list<std::string>, join the objects together separated from one another by the specified separator. The separator does not appear before the first object or after the final object. If the container is empty then an empty string is returned.

ROSE_UTIL_API std::string Rose::StringUtility::join	(	char	separator,
		const char *	strings[],
		size_t	nstrings
	)

Join individual items to form a single string.

Given a container containing printable objects (such as std::list<std::string>, join the objects together separated from one another by the specified separator. The separator does not appear before the first object or after the final object. If the container is empty then an empty string is returned.

ROSE_UTIL_API std::string Rose::StringUtility::joinEnglish	(	const std::vector< std::string > &	phrases,
		const std::string &	separator = `","`,
		const std::string &	finalIntro = `"and"`
	)

Join strings as if they were English prose.

This is useful when generating documentation strings.

If the input is empty, the output is the empty string. I.e., () => ""

If the input is one phrase, the output is that phrase. E.g., ("foo") => "foo"

If the input is two phrases, the output will be those two phrases separated by "and" (the finalIntro). E.g., ("foo", "bar") => "foo and bar"

If the input is three or more phrases, they will be separated from one another by commas (the separator) and the last item will also be introduced with "and" (the finalIntro). E.g., ("foo", "bar", "baz") => "foo, bar, and baz"

No transformations are performed on the input phrases. Space characters are inserted after each separator and finalIntro. A space is also inserted before the finalIntro when the input is two phrases.

ROSE_UTIL_API std::string Rose::StringUtility::listToString	(	const std::list< int > &	,
		bool	separateStrings = `false`
	)

Generate a string from a list of integers.

The return value is the concatenation of substrings. Each substring is formed by converting the corresponding integer from the list into a string via numberToString and then adding a single space character and an optional line feed. The line feeds are added only if separateStrings is true.

ROSE_UTIL_API std::string Rose::StringUtility::listToString	(	const std::list< std::string > &	,
		bool	separateStrings = `false`
	)

Generate a string from a container of strings.

The return value is the concatenation of substrings. Each substring is formed by adding a single space to the corresponding list element and an optional line feed. The line feeds are added only if separateStrings is true.

ROSE_UTIL_API std::string Rose::StringUtility::listToString	(	const std::vector< std::string > &	,
		bool	separateStrings = `false`
	)

Generate a string from a container of strings.

The return value is the concatenation of substrings. Each substring is formed by adding a single space to the corresponding list element and an optional line feed. The line feeds are added only if separateStrings is true.

ROSE_UTIL_API std::list<std::string> Rose::StringUtility::stringToList ( const std::string & )

Split a string into substrings at line feeds.

Splits the input string into substrings at the linefeed characters to construct a list, then removes empty strings from the list.

The original implementation (pre-2016) had a bug (ROSE-304) that caused the last substring to not be returned if it was not followed by a linefeed. That implementation was also slow for large inputs (ROSE-305). Both of these are now fixed since stringToList is now implemented in terms of split.

ROSE_UTIL_API void Rose::StringUtility::splitStringIntoStrings	(	const std::string &	inputString,
		char	separator,
		std::vector< std::string > &	stringList
	)

Splits string into substring based on a separator character.

Empty strings are removed from the result, which is returned in the stringList argument. The return argument is cleared before the splitting begins.

ROSE_UTIL_API std::string Rose::StringUtility::numberToString ( long long )

Convert an integer to a string.

These functions are wrappers around boost::lexical_cast<std::string>.

Referenced by Rose::BinaryAnalysis::Partitioner2::GraphViz::BaseEmitter< G >::emit(), Rose::BinaryAnalysis::Partitioner2::GraphViz::BaseEmitter< G >::emitEdge(), Rose::BinaryAnalysis::Partitioner2::GraphViz::BaseEmitter< G >::emitVertex(), Rose::BinaryAnalysis::get_ast_node(), plural(), Rose::BinaryAnalysis::put_ast_node(), and Rose::BinaryAnalysis::DataFlow::Engine< CFG, State, TransferFunction, MergeFunction, PathFeasibility >::runOneIteration().

ROSE_UTIL_API std::string Rose::StringUtility::numberToString ( unsigned long long )

Convert an integer to a string.

These functions are wrappers around boost::lexical_cast<std::string>.

ROSE_UTIL_API std::string Rose::StringUtility::numberToString ( long )

Convert an integer to a string.

These functions are wrappers around boost::lexical_cast<std::string>.

ROSE_UTIL_API std::string Rose::StringUtility::numberToString ( unsigned long )

Convert an integer to a string.

These functions are wrappers around boost::lexical_cast<std::string>.

ROSE_UTIL_API std::string Rose::StringUtility::numberToString ( int )

Convert an integer to a string.

These functions are wrappers around boost::lexical_cast<std::string>.

ROSE_UTIL_API std::string Rose::StringUtility::numberToString ( unsigned int )

Convert an integer to a string.

These functions are wrappers around boost::lexical_cast<std::string>.

ROSE_UTIL_API std::string Rose::StringUtility::numberToString ( const void * )

Convert a pointer to a string.

ROSE_UTIL_API std::string Rose::StringUtility::numberToString ( double )

Convert a floating-point number to a string.

The returned string uses printf with "%2.2f" format.

ROSE_UTIL_API std::string Rose::StringUtility::intToHex ( uint64_t )

Convert an integer to a hexadecimal string.

ROSE_UTIL_API std::string Rose::StringUtility::toHex2	(	uint64_t	value,
		size_t	nbits,
		bool	show_unsigned_decimal = `true`,
		bool	show_signed_decimal = `true`,
		uint64_t	decimal_threshold = `256`
	)

Convert a number to a hexadecimal and decimal string.

The returned string starts with the hexadecimal representation of the number and an optional decimal representation in angle brackets. The decimal portion will contain a signed and/or unsigned value depending on whether the value is interpretted as signed and whether the sign bit is set. The signedToHex versions print the decimal value for only the signed interpretation; the unsignedToHex versions print only the decimal unsigned interpretation, and the toHex versions print both (but not redunantly).

Referenced by toHex().

ROSE_UTIL_API std::string Rose::StringUtility::signedToHex2	(	uint64_t	value,
		size_t	nbits
	)

Convert a number to a hexadecimal and decimal string.

The returned string starts with the hexadecimal representation of the number and an optional decimal representation in angle brackets. The decimal portion will contain a signed and/or unsigned value depending on whether the value is interpretted as signed and whether the sign bit is set. The signedToHex versions print the decimal value for only the signed interpretation; the unsignedToHex versions print only the decimal unsigned interpretation, and the toHex versions print both (but not redunantly).

Referenced by signedToHex().

ROSE_UTIL_API std::string Rose::StringUtility::unsignedToHex2	(	uint64_t	value,
		size_t	nbits
	)

Convert a number to a hexadecimal and decimal string.

The returned string starts with the hexadecimal representation of the number and an optional decimal representation in angle brackets. The decimal portion will contain a signed and/or unsigned value depending on whether the value is interpretted as signed and whether the sign bit is set. The signedToHex versions print the decimal value for only the signed interpretation; the unsignedToHex versions print only the decimal unsigned interpretation, and the toHex versions print both (but not redunantly).

Referenced by unsignedToHex().

template<typename T >

std::string Rose::StringUtility::toHex ( T value )

Convert a number to a hexadecimal and decimal string.

The returned string starts with the hexadecimal representation of the number and an optional decimal representation in angle brackets. The decimal portion will contain a signed and/or unsigned value depending on whether the value is interpretted as signed and whether the sign bit is set. The signedToHex versions print the decimal value for only the signed interpretation; the unsignedToHex versions print only the decimal unsigned interpretation, and the toHex versions print both (but not redunantly).

Definition at line 276 of file StringUtility.h.

References toHex2().

template<typename T >

std::string Rose::StringUtility::signedToHex ( T value )

Convert a number to a hexadecimal and decimal string.

The returned string starts with the hexadecimal representation of the number and an optional decimal representation in angle brackets. The decimal portion will contain a signed and/or unsigned value depending on whether the value is interpretted as signed and whether the sign bit is set. The signedToHex versions print the decimal value for only the signed interpretation; the unsignedToHex versions print only the decimal unsigned interpretation, and the toHex versions print both (but not redunantly).

Definition at line 277 of file StringUtility.h.

References signedToHex2().

template<typename T >

std::string Rose::StringUtility::unsignedToHex ( T value )

Convert a number to a hexadecimal and decimal string.

The returned string starts with the hexadecimal representation of the number and an optional decimal representation in angle brackets. The decimal portion will contain a signed and/or unsigned value depending on whether the value is interpretted as signed and whether the sign bit is set. The signedToHex versions print the decimal value for only the signed interpretation; the unsignedToHex versions print only the decimal unsigned interpretation, and the toHex versions print both (but not redunantly).

Definition at line 278 of file StringUtility.h.

References unsignedToHex2().

ROSE_UTIL_API std::string Rose::StringUtility::addrToString	(	uint64_t	value,
		size_t	nbits = `0`
	)

Convert a virtual address to a string.

Converts a virtual address to a hexadecimal string with a leading "0x". The string is zero-padded so that it explicitly represents at least nbits bits (four bits per hexadecimal digits). If nbits is zero then the function uses 32 bits for values that fit in 32 bits, otherwise 64 bits.

Referenced by Rose::BitPattern< uint16_t >::check_insertion(), SqlDatabase::AddrRenderer::operator()(), Rose::BinaryAnalysis::CallingConvention::ParameterLocation::print(), Rose::BitPattern< uint16_t >::print(), and Rose::BinaryAnalysis::ControlFlow::write_graphviz().

ROSE_UTIL_API std::string Rose::StringUtility::addrToString	(	const Sawyer::Container::Interval< uint64_t > &	interval,
		size_t	nbits = `0`
	)

Convert an interval of virtual addresses to a string.

Converts an interval to a string by converting each address to a string, separating them with a comma, and enclosing the whole string in square brackets.

ROSE_UTIL_API std::string Rose::StringUtility::addrToString	(	const Sawyer::Container::IntervalSet< Sawyer::Container::Interval< uint64_t > > &	iset,
		size_t	nbits = `0`
	)

Convert an interval set of virtual addresses to a string.

Converts the interval-set to a string by converting each interval to a string, separating the intervals with commas, and enclosing the whole string in curly braces.

template<typename Unsigned >

std::string Rose::StringUtility::toBinary	(	Unsigned	value,
		size_t	nBits = `0`,
		size_t	groupSize = `4`,
		const std::string	groupSeparator = `"_"`
	)

Convert a number to a binary string.

Definition at line 304 of file StringUtility.h.

References Rose::BitOps::bit(), and Rose::BitOps::nBits().

ROSE_UTIL_API unsigned Rose::StringUtility::hexadecimalToInt ( char )

Convert an ASCII hexadecimal character to an integer.

Converts the characters 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, a, b, c, d, e, f, A, B, C, D, E, and F into their hexadecimal integer equivalents. Returns zero if the input character is not in this set.

template<class Container , class Stringifier >

std::vector<std::string> Rose::StringUtility::toStrings	(	const Container &	numbers,
		const Stringifier &	stringifier = `numberToString`
	)

Converts a bunch of numbers to strings.

This is convenient when one has a container of numbers and wants to call join to turn it into a single string. For instance, here's how to convert a set of integers to a comma-separated list:

using namespace Rose::StringUtility;
std::set<int> numbers = ...;
std::string s = join(", ", toStrings(numbers));

Here's how to convert a vector of addresses to space-separated hexadecimal values:

using namespace Rose::StringUtility;
std::vector<rose_addr_t> addresses = ...;
std::string s = join(" ", toStrings(addresses, addrToString));

Here's how one could surround each address with angle brackets:

using namespace Rose::StringUtility;
struct AngleSurround {
    std::string operator()(rose_addr_t addr) {
       return "<" + addrToString(addr) + ">";
    }
};
std::string s = join(" ", toStrings(addresses, AngleSurround()));

Definition at line 356 of file StringUtility.h.

References toStrings_range().

Referenced by SqlDatabase::in_numbers().

template<class Iterator , class Stringifier >

std::vector<std::string> Rose::StringUtility::toStrings_range	(	Iterator	begin,
		Iterator	end,
		const Stringifier &	stringifier = `numberToString`
	)

Converts a bunch of numbers to strings.

This is convenient when one has a container of numbers and wants to call join to turn it into a single string. For instance, here's how to convert a set of integers to a comma-separated list:

using namespace Rose::StringUtility;
std::set<int> numbers = ...;
std::string s = join(", ", toStrings(numbers));

Here's how to convert a vector of addresses to space-separated hexadecimal values:

using namespace Rose::StringUtility;
std::vector<rose_addr_t> addresses = ...;
std::string s = join(" ", toStrings(addresses, addrToString));

Here's how one could surround each address with angle brackets:

using namespace Rose::StringUtility;
struct AngleSurround {
    std::string operator()(rose_addr_t addr) {
       return "<" + addrToString(addr) + ">";
    }
};
std::string s = join(" ", toStrings(addresses, AngleSurround()));

Definition at line 360 of file StringUtility.h.

Referenced by toStrings().

ROSE_UTIL_API std::string Rose::StringUtility::convertToLowerCase ( const std::string & inputString )

Convert to lower case.

Returns a new string by converting each of the input characters to lower case with tolower.

ROSE_UTIL_API std::string Rose::StringUtility::fixLineTermination ( const std::string & input )

Normalizes line termination.

Changes ASCII-based line termination conventions used by various operating systems into the LF (line-feed) termination used by Multics, Unix and Unix-like systems (GNU/Linux, Mac OS X, FreeBSD, AIX, Xenix, etc.), BeOS, Amiga, RISC OS and others. Any occurrance of CR+LF, LF+CR, or CR by itself (in that order of left-to-right matching) is replaced by a single LF character.

ROSE_UTIL_API std::string Rose::StringUtility::prefixLines	(	const std::string &	lines,
		const std::string &	prefix,
		bool	prefixAtFront = `true`,
		bool	prefixAtBack = `false`
	)

Insert a prefix string before every line.

This function breaks the lines string into individual lines, inserts the prefix string at the beginning of each line, then concatenates the lines together into a return value. If prefixAtFront is true (the default) then the prefix is added to the first line of lines, otherwise the first line is unchanged. An empty lines string is considered to be a single line. If prefixAtBack is false (the default) then the prefix is not appended to the lines string if lines ends with a linefeed.

Referenced by Rose::BinaryAnalysis::DataFlow::Engine< CFG, State, TransferFunction, MergeFunction, PathFeasibility >::runOneIteration().

ROSE_UTIL_API std::string Rose::StringUtility::makeOneLine	(	const std::string &	s,
		std::string	replacement = `" "`
	)

Converts a multi-line string to a single line.

This function converts a multi-line string to a single line by replacing line-feeds and carriage-returns (and their surrounding white space) with a user-supplied replacement string (that defaults to a single space). Line termination (and it's surrounding white space) that appears at the front or back of the input string is removed without replacing it.

See roseTests/utilTests/stringTests.C for lots of examples.

A new string is returned.

ROSE_UTIL_API std::string Rose::StringUtility::trim	(	const std::string &	str,
		const std::string &	strip = `" \t\r\n"`,
		bool	at_beginning = `true`,
		bool	at_end = `true`
	)

Trims white space from the beginning and end of a string.

Caller may specify the characters to strip and whether the stripping occurs at the begining, the end, or both.

ROSE_UTIL_API std::string Rose::StringUtility::untab	(	const std::string &	str,
		size_t	tabstops = `8`,
		size_t	firstcol = `0`
	)

Expand horizontal tab characters.

ROSE_UTIL_API std::string Rose::StringUtility::removeRedundantSubstrings ( const std::string & )

Remove redundant and blank lines.

Splits the input string into substrings according to listToString, sorts the substrings and removes duplicates and lines that are empty (a line of only horizontal white space is not considered to be empty), then concatenates the substrings in their sorted order into the return value using listToString, inserting extra white space at the beginning of all but the first line.

The original implementation had a bug (ROSE-304) that caused the first substring to be removed from the return value even if it was non-empty and unique. This happened when it was not followed by a line-feed.

ROSE_UTIL_API std::string Rose::StringUtility::encode_base64	(	const std::vector< uint8_t > &	data,
		bool	do_pad = `true`
	)

Convert binary data to base-64.

The base64 number system uses the characters A-Z, a-z, 0-9, +, and / (in that order). The returned string does not include linefeeds. If do_pad is true then '=' characters may appear at the end to make the total length a multiple of four.

ROSE_UTIL_API std::string Rose::StringUtility::encode_base64	(	const uint8_t *	data,
		size_t	nbytes,
		bool	do_padd = `true`
	)

Convert binary data to base-64.

The base64 number system uses the characters A-Z, a-z, 0-9, +, and / (in that order). The returned string does not include linefeeds. If do_pad is true then '=' characters may appear at the end to make the total length a multiple of four.

ROSE_UTIL_API std::vector<uint8_t> Rose::StringUtility::decode_base64 ( const std::string & encoded )

Convert base-64 to binary.

ROSE_UTIL_API unsigned long Rose::StringUtility::generate_checksum ( std::string s )

Compute a checkshum.

This function returns a unique checksum from the mangled name used it provides a simple means to obtain a unique value for any C++ declaration. At a later date was should use the MD5 Checksum implementation (but we can do that later).

The declaration is the same under One-time Definition Rule (ODR) if and only if the checksum values for each declaration are the same.

bool Rose::StringUtility::isContainedIn	(	const std::string &	longString,
		const std::string &	shortString
	)

inline

Determines whether one string contains another.

Returns true if longString contains shortString as a subsequence.

Definition at line 467 of file StringUtility.h.

ROSE_UTIL_API bool Rose::StringUtility::isLineTerminated ( const std::string & s )

Returns true if the string ends with line termination.

Only common ASCII-based line terminations are recognized: CR+LF, LF+CR, CR (only), or LF (only).

ROSE_UTIL_API std::string Rose::StringUtility::indentMultilineString	(	const std::string &	inputString,
		int	statementColumnNumber
	)

Formatting support for generated code strings.

ROSE_UTIL_API void Rose::StringUtility::add_to_reason_string	(	std::string &	result,
		bool	isset,
		bool	do_pad,
		const std::string &	abbr,
		const std::string &	full
	)

Append an abbreviation or full name to a string.

ROSE_UTIL_API std::string Rose::StringUtility::appendAsmComment	(	const std::string &	s,
		const std::string &	comment
	)

Append an assembly comment to a string.

Assembly comments are surrounded by "<" and ">" characters. If the string already ends with an assembly comment, then the specified comment is inserted before the final ">" and separated from the previous comment with a comma. Assembly comments are usually used for things like printing a decimal representation of a hexadecimal value, etc.

Example: after executing these statements:

std::string s = "0xff";
s = appendAsmComment(s, "255");
s = appendAsmComment(s, "-1");

The variable "s" will contain "0xff<255,-1>"

template<typename T >

std::string Rose::StringUtility::plural	(	T	n,
		const std::string &	plural_phrase,
		const std::string &	singular_phrase = `""`
	)

Helpful way to print singular or plural words.

 size_t n = ...;
 std::cout <<"received " <<plural(n, "values") <<"\n";
@encode
 Output for various values of <em>n</em> will be:
@code
 received 0 values
 received 1 value
 received 2 values

This function uses a handful of grade-school rules and common exceptions for converting the supplied plural word to a singular word when necessary. If these are not enough, then the singular form can be supplied as the third argument.

std::cout <<"graph contains " <<plural(nverts, "vertices", "vertex") <<"\n";

Definition at line 530 of file StringUtility.h.

References numberToString().

Referenced by Rose::BinaryAnalysis::DataFlow::buildGraphPerVertex(), Rose::BinaryAnalysis::TaintedFlow::computeFlowGraphs(), Rose::BinaryAnalysis::DataFlow::Engine< CFG, State, TransferFunction, MergeFunction, PathFeasibility >::runOneIteration(), Rose::BinaryAnalysis::TaintedFlow::runToFixedPoint(), and Rose::BinaryAnalysis::TaintedFlow::vertexFlowGraphs().

std::string Rose::StringUtility::demangledName ( std::string )

Compute demangled version of mangled name.

Runs the c++filt command on the input string and returns the result. If c++filt cannot be run then it prints an error to standard error and another to standard output. The pipes opened to communicate with the c++filt subcommand might not be closed if there's an error.

Description

Classes

Typedefs

Enumerations

Functions

Typedef Documentation

Function Documentation