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_78_0/doc/html/string_algo.html].

Classes
class	FileNameClassification

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

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

typedef std::string	FileNameLibrary

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

enum	FileNameLocation { FILENAME_LOCATION_UNKNOWN , FILENAME_LOCATION_USER , FILENAME_LOCATION_LIBRARY , FILENAME_LOCATION_NOT_EXIST }

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

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

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.

ROSE_UTIL_API std::string	leftJustify (const std::string &input, size_t width, char fill=' ')
	Left justify a string to specified width.

ROSE_UTIL_API std::string	rightJustify (const std::string &input, size_t width, char fill=' ')
	Right justify a string to specified width.

ROSE_UTIL_API std::string	centerJustify (const std::string &input, size_t width, char fill=' ')
	Center a string in a field.

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

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.

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

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

ROSE_UTIL_API std::string	removeAnsiEscapes (const std::string &)
	Remove ANSI escape characters.

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

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

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

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.

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

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.

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

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

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

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

ROSE_UTIL_API std::string	yamlEscape (const std::string &)
	Escapes characters that are special to YAML strings.

ROSE_UTIL_API std::string	jsonEscape (const std::string &)
	Escapes characters that are special inside a JSON string.

ROSE_UTIL_API std::string	csvEscape (const std::string &)
	Escapes characters that are special in CSV tables.

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

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

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

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

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

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

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.

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.

ROSE_UTIL_API std::string	addrToString (const Sawyer::Optional< uint64_t > &, size_t nbits=0)
	Convert an optional virtual address to a string.

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.

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

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

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

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

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

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.

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

template<class IntegralType >
Sawyer::Optional< typename std::enable_if< std::is_integral< IntegralType >::value, IntegralType >::type >	toDigit (char ch, IntegralType radix=10)
	Convert a character to a numeric digit.

template<class IntegralType >
std::enable_if< std::is_integral< IntegralType >::value, Sawyer::Result< IntegralType, std::string > >::type	toNumber (const std::string &s)
	Safely convert a string to a number using C++ style syntax.

template<class IntegralType >
std::enable_if< std::is_integral< IntegralType >::value, IntegralType >::type	toNumberOrThrow (const std::string &s)
	Safely convert a string to a number using C++ style syntax.

ROSE_UTIL_API OSType	getOSType ()
	Obtain operating system type information.

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

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

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

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

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

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

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

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

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

ROSE_UTIL_API std::list< std::string >	findfile (std::string patternString, std::string pathString) __attribute__((deprecated))
	Find file names non-recursively.

ROSE_UTIL_API FileNameClassification	classifyFileName (const std::string &fileName, const std::string &appPath)
	Determine whether a file is source code or system library.

ROSE_UTIL_API FileNameClassification	classifyFileName (const std::string &fileName, const std::string &appPath, OSType os)
	Determine whether a file is source code or system library.

ROSE_UTIL_API FileNameClassification	classifyFileName (const std::string &fileName, const std::string &appPath, const std::map< std::string, std::string > &libPathCollection)
	Determine whether a file is source code or system library.

ROSE_UTIL_API FileNameClassification	classifyFileName (const std::string &fileName, const std::string &appPath, const std::map< std::string, std::string > &libPathCollection, OSType os)
	Determine whether a file is source code or system library.

ROSE_UTIL_API const std::string	stripDotsFromHeaderFileName (const std::string &name)
	Remove leading dots.

ROSE_UTIL_API int	directoryDistance (const std::string &left, const std::string &right)
	Edit distance between two directory names.

ROSE_UTIL_API std::vector< std::string >	readWordsInFile (std::string filename)
	Reads words from a file.

bool	popen_wrapper (const std::string &command, std::vector< std::string > &result)
	Simple wrapper for Unix popen command.

std::ostream &	operator<< (std::ostream &os, const StringWithLineNumber &s)
	Prints a StringWithLineNumber.

ROSE_UTIL_API std::string	toString (const FileWithLineNumbers &strings, const std::string &filename="<unknown>", int line=1)
	Generate C preprocessor #line directives.

FileWithLineNumbers &	operator+= (FileWithLineNumbers &a, const FileWithLineNumbers &b)
	Append strings with source location information to vector of such.

FileWithLineNumbers	operator+ (const FileWithLineNumbers &a, const FileWithLineNumbers &b)
	Concatenate vectors of strings with source location.


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

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


std::string	insertCommas (const std::string &)
	Insert commas into large integers in the specified string.

template<class T >
std::string	insertCommas (const T &x)
	Insert commas into large integers in the specified string.


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

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


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

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

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

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

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

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


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.

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

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

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

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

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


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.

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.


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

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

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

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

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

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

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


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.

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


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

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


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

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.


FileWithLineNumbers &	operator<< (FileWithLineNumbers &f, const std::string &str)
	Append string to vector of strings with location information.

FileWithLineNumbers &	operator<< (FileWithLineNumbers &f, const char *str)
	Append string to vector of strings with location information.


ROSE_UTIL_API std::string	copyEdit (const std::string &inputString, const std::string &oldToken, const std::string &newToken)
	Replace all occurrences of a string with another string.

ROSE_UTIL_API FileWithLineNumbers	copyEdit (const FileWithLineNumbers &inputString, const std::string &oldToken, const std::string &newToken)
	Replace all occurrences of a string with another string.

ROSE_UTIL_API FileWithLineNumbers	copyEdit (const FileWithLineNumbers &inputString, const std::string &oldToken, const FileWithLineNumbers &newToken)
	Replace all occurrences of a string with another string.

Typedef Documentation

◆ FileWithLineNumbers

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.

◆ FileNameLibrary

typedef std::string Rose::StringUtility::FileNameLibrary

Definition at line 168 of file FileUtility.h.

Enumeration Type Documentation

◆ OSType

enum Rose::StringUtility::OSType

Definition at line 25 of file FileUtility.h.

◆ FileNameLocation

enum Rose::StringUtility::FileNameLocation

Definition at line 150 of file FileUtility.h.

Function Documentation

◆ convertToLowerCase()

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.

◆ fixLineTermination()

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.

◆ prefixLines()

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

◆ leftJustify()

ROSE_UTIL_API std::string Rose::StringUtility::leftJustify	(	const std::string &	input,
		size_t	width,
		char	fill = `' '`
	)

Left justify a string to specified width.

The given string is either truncated or extended to make it the specified number of characters. New fill characters are added to the end of the string if necessary.

◆ rightJustify()

ROSE_UTIL_API std::string Rose::StringUtility::rightJustify	(	const std::string &	input,
		size_t	width,
		char	fill = `' '`
	)

Right justify a string to specified width.

The given string is either truncated or extended to make it the specified number of characters. New fill characters are added to the beginning of the string if necessary.

◆ centerJustify()

ROSE_UTIL_API std::string Rose::StringUtility::centerJustify	(	const std::string &	input,
		size_t	width,
		char	fill = `' '`
	)

Center a string in a field.

The given string is either truncated or extended to make it the specified number of characters. New fill characters are added to the beginning and end of the string if necessary.

◆ makeOneLine()

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.

◆ trim()

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.

◆ removeRedundantSubstrings()

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.

◆ removeAnsiEscapes()

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

Remove ANSI escape characters.

Currently handles only the "Control Sequence Introducer" commands, but these are the most common and most useful commands anyway since they include such things as cursor movement, erasing, scrolling, colors, and other graphic renditions.

◆ encode_base64() [1/2]

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.

◆ encode_base64() [2/2]

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.

◆ generate_checksum()

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.

◆ appendAsmComment()

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>"

◆ insertCommas() [1/2]

std::string Rose::StringUtility::insertCommas ( const std::string & )

Insert commas into large integers in the specified string.

Example:

std::string input = "has 1234567 vertices and 345678910 edges, weight 12345.67891";
std::string result = insertCommas(input);
assert(result == "has 1,234,567 vertices and 34,567,890 edges, weight 12,345.67891");

Referenced by insertCommas(), and plural().

◆ insertCommas() [2/2]

template<class T >

std::string Rose::StringUtility::insertCommas ( const T & x )

Insert commas into large integers in the specified string.

Example:

std::string input = "has 1234567 vertices and 345678910 edges, weight 12345.67891";
std::string result = insertCommas(input);
assert(result == "has 1,234,567 vertices and 34,567,890 edges, weight 12,345.67891");

Definition at line 58 of file StringUtility/Diagnostics.h.

References insertCommas().

◆ plural()

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 88 of file StringUtility/Diagnostics.h.

References insertCommas().

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

◆ demangledName()

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.

◆ htmlEscape()

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.

◆ cEscape() [1/2]

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::CommandLine::IntervalParser< Interval >::parse(), Rose::CommandLine::SuffixMultiplierParser< T >::parse(), and Rose::BinaryAnalysis::VxcoreParser::Exception::toString().

◆ cEscape() [2/2]

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.

◆ cUnescape()

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.

◆ bourneEscape()

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.

◆ yamlEscape()

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

Escapes characters that are special to YAML strings.

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

◆ jsonEscape()

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

Escapes characters that are special inside a JSON string.

Assumes that the provided string is already inside double quotes; no additional quotes are added to the return value.

◆ csvEscape()

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

Escapes characters that are special in CSV tables.

Assumes that the context is outside of any quoting and possib9 adds quotes. See RFC 4180 for details.

◆ escapeNewLineCharaters()

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.

◆ numberToString() [1/7]

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(), Rose::BinaryAnalysis::put_ast_node(), and Rose::BinaryAnalysis::DataFlow::Engine< Cfg_, State_, TransferFunction_, MergeFunction_, PathFeasibility_ >::runOneIteration().

◆ numberToString() [2/7]

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

◆ numberToString() [3/7]

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

◆ numberToString() [4/7]

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

◆ numberToString() [5/7]

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

◆ numberToString() [6/7]

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

◆ numberToString() [7/7]

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.

◆ toHex2()

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

◆ signedToHex2()

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

◆ unsignedToHex2()

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

◆ toHex()

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 67 of file NumberToString.h.

References toHex2().

◆ signedToHex()

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 72 of file NumberToString.h.

References signedToHex2().

◆ unsignedToHex()

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 77 of file NumberToString.h.

References unsignedToHex2().

◆ addrToString() [1/4]

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< T >::check_insertion(), Rose::BitPattern< T >::print(), Rose::BitPattern< T >::print(), Rose::CommandLine::IntervalParser< Interval >::toString(), and Rose::BinaryAnalysis::ControlFlow::write_graphviz().

◆ addrToString() [2/4]

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.

◆ addrToString() [3/4]

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.

◆ addrToString() [4/4]

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

Convert an optional virtual address to a string.

Same as the non-optional version of this function, but prints the word "none" if the argument is Sawyer::Nothing.

◆ toBinary()

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 109 of file NumberToString.h.

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

◆ isContainedIn()

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 18 of file Predicate.h.

◆ isLineTerminated()

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

◆ split() [1/2]

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.

◆ split() [2/2]

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.

◆ tokenize()

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.

◆ join_range()

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 54 of file SplitJoin.h.

Referenced by join(), and join().

◆ join() [1/6]

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 62 of file SplitJoin.h.

References join_range().

◆ join() [2/6]

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 67 of file SplitJoin.h.

References join_range().

◆ join() [3/6]

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.

◆ join() [4/6]

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.

◆ join() [5/6]

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.

◆ join() [6/6]

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.

◆ joinEnglish() [1/2]

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.

◆ joinEnglish() [2/2]

ROSE_UTIL_API std::string Rose::StringUtility::joinEnglish	(	const std::set< 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.

◆ listToString() [1/3]

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.

◆ listToString() [2/3]

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.

◆ listToString() [3/3]

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.

◆ stringToList()

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.

◆ splitStringIntoStrings()

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.

◆ hexadecimalToInt()

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.

◆ toStrings()

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 57 of file StringToNumber.h.

References toStrings_range().

◆ toStrings_range()

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 61 of file StringToNumber.h.

Referenced by toStrings().

◆ toDigit()

template<class IntegralType >

Sawyer::Optional< typename std::enable_if< std::is_integral< IntegralType >::value, IntegralType >::type > Rose::StringUtility::toDigit	(	char	ch,
		IntegralType	radix = `10`
	)

Convert a character to a numeric digit.

If the character is valid for the specified radix, then its numeric value is returned, otherwise nothing is returned. The radix must be less than or equal to 16.

Definition at line 75 of file StringToNumber.h.

◆ toNumber()

template<class IntegralType >

std::enable_if< std::is_integral< IntegralType >::value, Sawyer::Result< IntegralType, std::string > >::type Rose::StringUtility::toNumber ( const std::string & s )

Safely convert a string to a number using C++ style syntax.

The input string must parse as a integer without leading white space and without trailing characters. For signed integer types, the integer may be immediately preceded by a minus ("-") or plus ("+") sign. The integer part may be preceded by a radix indicator: "0x" for hexadecimal or "0b" for binary. Octal and other radices are not supported. Digits may be separated from one another (or from the radix specifier) by a single underscore, as in "0b_0001_0010_0011_0100_0101_0110_0111_1000".

The IntegralType must be a signed or unsigned integer type of any width. The uint8_t and int8_t types are also accepted although they're aliases for unsigned char and signed char .

If a syntax error occurs, or if the magnitude of the value is too large to be represented by the specified IntegralType, then an error message is returned. The text of the message begins with either "syntax error:" or "overflow error:".

Definition at line 109 of file StringToNumber.h.

◆ toNumberOrThrow()

template<class IntegralType >

std::enable_if< std::is_integral< IntegralType >::value, IntegralType >::type Rose::StringUtility::toNumberOrThrow ( const std::string & s )

Safely convert a string to a number using C++ style syntax.

This function is identical to toNumber except in the return type and error situation. If an error occurs, then a Rose::Exception is thrown whose message is the error message. On success, the parsed value is returned.

Definition at line 119 of file StringToNumber.h.

◆ writeFile()

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

◆ readFile()

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.

◆ readFileWithPos()

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.

◆ homeDir()

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.

◆ stripPathFromFileName()

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.

◆ getPathFromFileName()

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.

◆ stripFileSuffixFromFileName()

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.

◆ getAbsolutePathFromRelativePath()

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.

◆ fileNameSuffix()

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.

◆ findfile()

ROSE_UTIL_API std::list< std::string > Rose::StringUtility::findfile	(	std::string	patternString,
		std::string	pathString
	)

Find file names non-recursively.

Scans the directory named pathString and returns a list of files in that directory which have patternString as a substring of their name. Note that patternString is not a glob or regular expression. The return value strings are formed by concatenating the pathString and the file name with an intervening slash.

This function does not work for non-POSIX systems. Consider using boost::filesystem instead, which has a directory iterator that works for non-POSIX systems also.

◆ classifyFileName() [1/4]

ROSE_UTIL_API FileNameClassification Rose::StringUtility::classifyFileName	(	const std::string &	fileName,
		const std::string &	appPath
	)

Determine whether a file is source code or system library.

Given a fileName and an appPath that is a path to some application's source code directory, return a FileNameClassification indicating whether the fileName is part of the source code or some system library and automatically determine the operating system from the host uname

◆ classifyFileName() [2/4]

ROSE_UTIL_API FileNameClassification Rose::StringUtility::classifyFileName	(	const std::string &	fileName,
		const std::string &	appPath,
		OSType	os
	)

Determine whether a file is source code or system library.

Given a fileName and an appPath that is a path to some application's source code directory, return a FileNameClassification indicating whether the fileName is part of the source code or some system library

◆ classifyFileName() [3/4]

ROSE_UTIL_API FileNameClassification Rose::StringUtility::classifyFileName	(	const std::string &	fileName,
		const std::string &	appPath,
		const std::map< std::string, std::string > &	libPathCollection
	)

Determine whether a file is source code or system library.

Given a fileName and an appPath that is a path to some application's source code directory, and a collection of library paths, return a FileNameClassification indicating whether the fileName is part of the source code or some system library and automatically determine the operating system from the host uname

◆ classifyFileName() [4/4]

ROSE_UTIL_API FileNameClassification Rose::StringUtility::classifyFileName	(	const std::string &	fileName,
		const std::string &	appPath,
		const std::map< std::string, std::string > &	libPathCollection,
		OSType	os
	)

Determine whether a file is source code or system library.

Given a fileName and an appPath that is a path to some application's source code directory, and a collection of library paths, return a FileNameClassification indicating whether the fileName is part of the source code or some system library

◆ stripDotsFromHeaderFileName()

ROSE_UTIL_API const std::string Rose::StringUtility::stripDotsFromHeaderFileName ( const std::string & name )

Remove leading dots.

Removes leading dots plus a space from a header file name that is given in the format that g++ -H returns

◆ directoryDistance()

ROSE_UTIL_API int Rose::StringUtility::directoryDistance	(	const std::string &	left,
		const std::string &	right
	)

Edit distance between two directory names.

Essentially the edit distance without substituion in directory name tokens between two directories. Returns the "distance" between left and right. The distance is defined as the number of cd's that only move up or down one directory that it would take to move from the directory of the filename to the directory that was given by appPath. This is intended as a heuristic to gage whether or not one believes that the left is related to the right directory. Examples:

Between /a/b/c/file.h and /a/b/d/e/ the distance is 3 because one must cd ..; cd d; cd e

◆ readWordsInFile()

ROSE_UTIL_API std::vector< std::string > Rose::StringUtility::readWordsInFile ( std::string filename )

Reads words from a file.

Opens the specified file for reading and reads all words from the file using std::istream operator>> into std::string. If the file cannot be opened then an error message is printed to standard output (not error) and the program exits with status 1.

◆ popen_wrapper()

bool Rose::StringUtility::popen_wrapper	(	const std::string &	command,
		std::vector< std::string > &	result
	)

Simple wrapper for Unix popen command.

If there is a failure (cannot create pipes, command not found, command terminated abnormally, input buffer too small, etc), then an error is printed to standard error (with or without line termination) and false is returned. When an error occurs the pipes that were opened to communicate with the subcommand might not be closed.

◆ operator<<() [1/3]

std::ostream & Rose::StringUtility::operator<<	(	std::ostream &	os,
		const StringWithLineNumber &	s
	)

inline

Prints a StringWithLineNumber.

Definition at line 284 of file FileUtility.h.

◆ toString()

ROSE_UTIL_API std::string Rose::StringUtility::toString	(	const FileWithLineNumbers &	strings,
		const std::string &	filename = `"<unknown>"`,
		int	line = `1`
	)

Generate C preprocessor #line directives.

Given a vector of strings with source location information, print those strings with intervening C preprocessor #line directives. For strings that have no source location, use the specified filename argument as the name of the file. The physicalLine is the line number to assume for the first line of output (the return value). The #line directives are not emitted into the return value when they're not needed (e.g., two strings are at successive line numbers of the same source file) or if ROSE has been configured to not emit #line directivies (i.e., the SKIP_HASH_LINE_NUMBER_DECLARATIONS_IN_GENERATED_FILES preprocessor symbol is defined). The strings should not have trailing linefeeds or else the output will contain extra blank lines.

◆ operator+=()

FileWithLineNumbers & Rose::StringUtility::operator+=	(	FileWithLineNumbers &	a,
		const FileWithLineNumbers &	b
	)

inline

Append strings with source location information to vector of such.

Modifies a by appending those strings from b.

Definition at line 303 of file FileUtility.h.

◆ operator+()

FileWithLineNumbers Rose::StringUtility::operator+	(	const FileWithLineNumbers &	a,
		const FileWithLineNumbers &	b
	)

inline

Concatenate vectors of strings with source location.

Returns a new vector of strings with location information by concatenating vector a with b.

Definition at line 311 of file FileUtility.h.

◆ operator<<() [2/3]

FileWithLineNumbers & Rose::StringUtility::operator<<	(	FileWithLineNumbers &	f,
		const std::string &	str
	)

inline

Append string to vector of strings with location information.

Appends str to the last string in the vector of strings with location information. If the vector is empty then a new element is created.

The new code is marked as either generated (empty file name) or not generated (non-empty name) based on whether the vector was initially empty or whether the final element of the vector was generated. Adding a string to an empty vector makes it always be a generated string; adding it to a non-empty vector makes it generated or not generated depending on whether the last element of the vector is generated or not generated.

The string str should not include line termination. (see toString).

Definition at line 330 of file FileUtility.h.

◆ operator<<() [3/3]

FileWithLineNumbers & Rose::StringUtility::operator<<	(	FileWithLineNumbers &	f,
		const char *	str
	)

inline

Append string to vector of strings with location information.

Appends str to the last string in the vector of strings with location information. If the vector is empty then a new element is created.

The new code is marked as either generated (empty file name) or not generated (non-empty name) based on whether the vector was initially empty or whether the final element of the vector was generated. Adding a string to an empty vector makes it always be a generated string; adding it to a non-empty vector makes it generated or not generated depending on whether the last element of the vector is generated or not generated.

The string str should not include line termination. (see toString).

Definition at line 339 of file FileUtility.h.

◆ copyEdit() [1/3]

ROSE_UTIL_API std::string Rose::StringUtility::copyEdit	(	const std::string &	inputString,
		const std::string &	oldToken,
		const std::string &	newToken
	)

Replace all occurrences of a string with another string.

Finds all occurrences of the oldToken string in inputString and replaces them each with newToken, returning the result.

◆ copyEdit() [2/3]

ROSE_UTIL_API FileWithLineNumbers Rose::StringUtility::copyEdit	(	const FileWithLineNumbers &	inputString,
		const std::string &	oldToken,
		const std::string &	newToken
	)

Replace all occurrences of a string with another string.

Finds all occurrences of the oldToken string in inputString and replaces them each with newToken, returning the result.

◆ copyEdit() [3/3]

ROSE_UTIL_API FileWithLineNumbers Rose::StringUtility::copyEdit	(	const FileWithLineNumbers &	inputString,
		const std::string &	oldToken,
		const FileWithLineNumbers &	newToken
	)

Replace all occurrences of a string with another string.

Finds all occurrences of the oldToken string in inputString and replaces them each with newToken, returning the result.

Description

Classes

Typedefs

Enumerations

Functions

Typedef Documentation

◆ FileWithLineNumbers

◆ FileNameLibrary

Enumeration Type Documentation

◆ OSType

◆ FileNameLocation

Function Documentation

◆ convertToLowerCase()

◆ fixLineTermination()

◆ prefixLines()

◆ leftJustify()

◆ rightJustify()

◆ centerJustify()

◆ makeOneLine()

◆ trim()

◆ removeRedundantSubstrings()

◆ removeAnsiEscapes()

◆ encode_base64() [1/2]

◆ encode_base64() [2/2]

◆ generate_checksum()

◆ appendAsmComment()

◆ insertCommas() [1/2]

◆ insertCommas() [2/2]

◆ plural()

◆ demangledName()

◆ htmlEscape()

◆ cEscape() [1/2]

◆ cEscape() [2/2]

◆ cUnescape()

◆ bourneEscape()

◆ yamlEscape()

◆ jsonEscape()

◆ csvEscape()

◆ escapeNewLineCharaters()

◆ numberToString() [1/7]

◆ numberToString() [2/7]

◆ numberToString() [3/7]

◆ numberToString() [4/7]

◆ numberToString() [5/7]

◆ numberToString() [6/7]

◆ numberToString() [7/7]

◆ toHex2()

◆ signedToHex2()

◆ unsignedToHex2()

◆ toHex()

◆ signedToHex()

◆ unsignedToHex()

◆ addrToString() [1/4]

◆ addrToString() [2/4]

◆ addrToString() [3/4]

◆ addrToString() [4/4]

◆ toBinary()

◆ isContainedIn()

◆ isLineTerminated()

◆ split() [1/2]

◆ split() [2/2]

◆ tokenize()

◆ join_range()

◆ join() [1/6]

◆ join() [2/6]

◆ join() [3/6]

◆ join() [4/6]

◆ join() [5/6]

◆ join() [6/6]

◆ joinEnglish() [1/2]

◆ joinEnglish() [2/2]

◆ listToString() [1/3]

◆ listToString() [2/3]

◆ listToString() [3/3]

◆ stringToList()

◆ splitStringIntoStrings()

◆ hexadecimalToInt()

◆ toStrings()

◆ toStrings_range()

◆ toDigit()