llvm::Twine Class Reference

Twine - A lightweight data structure for efficiently representing the concatenation of temporary values as strings. More...

#include <Twine.h>

List of all members.

Classes
union	Child
Public Member Functions
Predicate Operations
bool	isTriviallyEmpty () const
	isTriviallyEmpty - Check if this twine is trivially empty; a false return value does not necessarily mean the twine is empty.
bool	isSingleStringRef () const
	isSingleStringRef - Return true if this twine can be dynamically accessed as a single StringRef value with getSingleStringRef().
String Operations
Twine	concat (const Twine &Suffix) const
Output & Conversion.
std::string	str () const
	str - Return the twine contents as a std::string.
void	toVector (SmallVectorImpl< char > &Out) const
	toVector - Write the concatenated string into the given SmallString or SmallVector.
StringRef	getSingleStringRef () const
	getSingleStringRef - This returns the twine as a single StringRef.
StringRef	toStringRef (SmallVectorImpl< char > &Out) const
	toStringRef - This returns the twine as a single StringRef if it can be represented as such.
StringRef	toNullTerminatedStringRef (SmallVectorImpl< char > &Out) const
	toNullTerminatedStringRef - This returns the twine as a single null terminated StringRef if it can be represented as such.
void	print (std::ostream &OS) const
	print - Write the concatenated string represented by this twine to the stream
void	dump () const
	dump - Dump the concatenated string represented by this twine to stderr.
void	printRepr (std::ostream &OS) const
	print - Write the representation of this twine to the stream
void	dumpRepr () const
	dumpRepr - Dump the representation of this twine to stderr.
Static Public Member Functions
Numeric Conversions
static Twine	utohexstr (const uint64_t &Val)
Private Types
enum	NodeKind {   NullKind, EmptyKind, TwineKind, CStringKind,   StdStringKind, StringRefKind, CharKind, DecUIKind,   DecIKind, DecULKind, DecLKind, DecULLKind,   DecLLKind, UHexKind }
	NodeKind - Represent the type of an argument. More...
Private Member Functions
	Twine (NodeKind Kind)
	Construct a nullary twine; the kind must be NullKind or EmptyKind.
	Twine (const Twine &_LHS, const Twine &_RHS)
	Construct a binary twine.
	Twine (Child _LHS, NodeKind _LHSKind, Child _RHS, NodeKind _RHSKind)
	Construct a twine from explicit values.
bool	isNull () const
	isNull - Check for the null twine.
bool	isEmpty () const
	isEmpty - Check for the empty twine.
bool	isNullary () const
	isNullary - Check if this is a nullary twine (null or empty).
bool	isUnary () const
	isUnary - Check if this is a unary twine.
bool	isBinary () const
	isBinary - Check if this is a binary twine.
bool	isValid () const
	isValid - Check if this is a valid twine (satisfying the invariants on order and number of arguments).
NodeKind	getLHSKind () const
	getLHSKind - Get the NodeKind of the left-hand side.
NodeKind	getRHSKind () const
	getRHSKind - Get the NodeKind of the left-hand side.
void	printOneChild (std::ostream &OS, Child Ptr, NodeKind Kind) const
	printOneChild - Print one child from a twine.
void	printOneChildRepr (std::ostream &OS, Child Ptr, NodeKind Kind) const
	printOneChildRepr - Print the representation of one child from a twine.
Private Attributes
Child	LHS
	LHS - The prefix in the concatenation, which may be uninitialized for Null or Empty kinds.
Child	RHS
	RHS - The suffix in the concatenation, which may be uninitialized for Null or Empty kinds.
unsigned char	LHSKind
	LHSKind - The NodeKind of the left hand side,.
unsigned char	RHSKind
	RHSKind - The NodeKind of the left hand side,.
Constructors
	Twine ()
	Construct from an empty string.
	Twine (const char *Str)
	Construct from a C string.
	Twine (const std::string &Str)
	Construct from an std::string.
	Twine (const StringRef &Str)
	Construct from a StringRef.
	Twine (char Val)
	Construct from a char.
	Twine (signed char Val)
	Construct from a signed char.
	Twine (unsigned char Val)
	Construct from an unsigned char.
	Twine (unsigned Val)
	Construct a twine to print.
	Twine (int Val)
	Construct a twine to print.
	Twine (const unsigned long &Val)
	Construct a twine to print.
	Twine (const long &Val)
	Construct a twine to print.
	Twine (const unsigned long long &Val)
	Construct a twine to print.
	Twine (const long long &Val)
	Construct a twine to print.
	Twine (const char *_LHS, const StringRef &_RHS)
	Construct as the concatenation of a C string and a StringRef.
	Twine (const StringRef &_LHS, const char *_RHS)
	Construct as the concatenation of a StringRef and a C string.
static Twine	createNull ()
	Create a 'null' string, which is an empty string that always concatenates to form another empty string.

---

Detailed Description

Twine - A lightweight data structure for efficiently representing the concatenation of temporary values as strings.

A Twine is a kind of rope, it represents a concatenated string using a binary-tree, where the string is the preorder of the nodes. Since the Twine can be efficiently rendered into a buffer when its result is used, it avoids the cost of generating temporary values for intermediate string results -- particularly in cases when the Twine result is never required. By explicitly tracking the type of leaf nodes, we can also avoid the creation of temporary strings for conversions operations (such as appending an integer to a string).

A Twine is not intended for use directly and should not be stored, its implementation relies on the ability to store pointers to temporary stack objects which may be deallocated at the end of a statement. Twines should only be used accepted as const references in arguments, when an API wishes to accept possibly-concatenated strings.

Twines support a special 'null' value, which always concatenates to form itself, and renders as an empty string. This can be returned from APIs to effectively nullify any concatenations performed on the result.

Implementation

Given the nature of a Twine, it is not possible for the Twine's concatenation method to construct interior nodes; the result must be represented inside the returned value. For this reason a Twine object actually holds two values, the left- and right-hand sides of a concatenation. We also have nullary Twine objects, which are effectively sentinel values that represent empty strings.

Thus, a Twine can effectively have zero, one, or two children. The

See also:

isNullary(),

isUnary(), and

isBinary() predicates exist for testing the number of children.

We maintain a number of invariants on Twine objects (FIXME: Why):

• Nullary twines are always represented with their Kind on the left-hand side, and the Empty kind on the right-hand side.
• Unary twines are always represented with the value on the left-hand side, and the Empty kind on the right-hand side.
• If a Twine has another Twine as a child, that child should always be binary (otherwise it could have been folded into the parent).

These invariants are check by

See also:

isValid().

Efficiency Considerations

The Twine is designed to yield efficient and small code for common situations. For this reason, the concat() method is inlined so that concatenations of leaf nodes can be optimized into stores directly into a single stack allocated object.

In practice, not all compilers can be trusted to optimize concat() fully, so we provide two additional methods (and accompanying operator+ overloads) to guarantee that particularly important cases (cstring plus StringRef) codegen as desired.

---

Member Enumeration Documentation

enum llvm::Twine::NodeKind [private]

NodeKind - Represent the type of an argument.

Enumerator:

NullKind	An empty string; the result of concatenating anything with it is also empty.
EmptyKind	The empty string.
TwineKind	A pointer to a Twine instance.
CStringKind	A pointer to a C string instance.
StdStringKind	A pointer to an std::string instance.
StringRefKind	A pointer to a StringRef instance.
CharKind	A char value reinterpreted as a pointer, to render as a character.
DecUIKind	An unsigned int value reinterpreted as a pointer, to render as an unsigned decimal integer.
DecIKind	An int value reinterpreted as a pointer, to render as a signed decimal integer.
DecULKind	A pointer to an unsigned long value, to render as an unsigned decimal integer.
DecLKind	A pointer to a long value, to render as a signed decimal integer.
DecULLKind	A pointer to an unsigned long long value, to render as an unsigned decimal integer.
DecLLKind	A pointer to a long long value, to render as a signed decimal integer.
UHexKind	A pointer to a uint64_t value, to render as an unsigned hexadecimal integer.

---

Constructor & Destructor Documentation

llvm::Twine::Twine

(

NodeKind

Kind

)

[inline, explicit, private]

Construct a nullary twine; the kind must be NullKind or EmptyKind.

llvm::Twine::Twine	(	const Twine &	_LHS,
		const Twine &	_RHS
	)			[inline, explicit, private]

Construct a binary twine.

llvm::Twine::Twine	(	Child	_LHS,
		NodeKind	_LHSKind,
		Child	_RHS,
		NodeKind	_RHSKind
	)			[inline, explicit, private]

Construct a twine from explicit values.

llvm::Twine::Twine

(

)

[inline]

Construct from an empty string.

llvm::Twine::Twine

(

const char *

Str

)

[inline]

Construct from a C string.

We take care here to optimize "" into the empty twine -- this will be optimized out for string constants. This allows Twine arguments have default "" values, without introducing unnecessary string constants.

llvm::Twine::Twine

(

const std::string &

Str

)

[inline]

Construct from an std::string.

llvm::Twine::Twine

(

const StringRef &

Str

)

[inline]

Construct from a StringRef.

llvm::Twine::Twine

(

char

Val

)

[inline, explicit]

Construct from a char.

llvm::Twine::Twine

(

signed char

Val

)

[inline, explicit]

Construct from a signed char.

llvm::Twine::Twine

(

unsigned char

Val

)

[inline, explicit]

Construct from an unsigned char.

llvm::Twine::Twine

(

unsigned

Val

)

[inline, explicit]

Construct a twine to print.

• Val as an unsigned decimal integer.

llvm::Twine::Twine

(

int

Val

)

[inline, explicit]

Construct a twine to print.

• Val as a signed decimal integer.

llvm::Twine::Twine

(

const unsigned long &

Val

)

[inline, explicit]

Construct a twine to print.

• Val as an unsigned decimal integer.

llvm::Twine::Twine

(

const long &

Val

)

[inline, explicit]

Construct a twine to print.

• Val as a signed decimal integer.

llvm::Twine::Twine

(

const unsigned long long &

Val

)

[inline, explicit]

Construct a twine to print.

• Val as an unsigned decimal integer.

llvm::Twine::Twine

(

const long long &

Val

)

[inline, explicit]

Construct a twine to print.

• Val as a signed decimal integer.

llvm::Twine::Twine	(	const char *	_LHS,
		const StringRef &	_RHS
	)			[inline]

Construct as the concatenation of a C string and a StringRef.

llvm::Twine::Twine	(	const StringRef &	_LHS,
		const char *	_RHS
	)			[inline]

Construct as the concatenation of a StringRef and a C string.

---

Member Function Documentation

Twine llvm::Twine::concat

(

const Twine &

Suffix

)

const [inline]

static Twine llvm::Twine::createNull

(

)

[inline, static]

Create a 'null' string, which is an empty string that always concatenates to form another empty string.

void Twine::dump

(

)

const

dump - Dump the concatenated string represented by this twine to stderr.

void Twine::dumpRepr

(

)

const

dumpRepr - Dump the representation of this twine to stderr.

NodeKind llvm::Twine::getLHSKind

(

)

const [inline, private]

getLHSKind - Get the NodeKind of the left-hand side.

NodeKind llvm::Twine::getRHSKind

(

)

const [inline, private]

getRHSKind - Get the NodeKind of the left-hand side.

StringRef llvm::Twine::getSingleStringRef

(

)

const [inline]

getSingleStringRef - This returns the twine as a single StringRef.

This method is only valid if isSingleStringRef() is true.

bool llvm::Twine::isBinary

(

)

const [inline, private]

isBinary - Check if this is a binary twine.

bool llvm::Twine::isEmpty

(

)

const [inline, private]

isEmpty - Check for the empty twine.

bool llvm::Twine::isNull

(

)

const [inline, private]

isNull - Check for the null twine.

bool llvm::Twine::isNullary

(

)

const [inline, private]

isNullary - Check if this is a nullary twine (null or empty).

bool llvm::Twine::isSingleStringRef

(

)

const [inline]

isSingleStringRef - Return true if this twine can be dynamically accessed as a single StringRef value with getSingleStringRef().

bool llvm::Twine::isTriviallyEmpty

(

)

const [inline]

isTriviallyEmpty - Check if this twine is trivially empty; a false return value does not necessarily mean the twine is empty.

bool llvm::Twine::isUnary

(

)

const [inline, private]

isUnary - Check if this is a unary twine.

bool llvm::Twine::isValid

(

)

const [inline, private]

isValid - Check if this is a valid twine (satisfying the invariants on order and number of arguments).

void Twine::print

(

std::ostream &

OS

)

const

print - Write the concatenated string represented by this twine to the stream

• OS.

void Twine::printOneChild	(	std::ostream &	OS,
		Child	Ptr,
		NodeKind	Kind
	)			const [private]

printOneChild - Print one child from a twine.

void Twine::printOneChildRepr	(	std::ostream &	OS,
		Child	Ptr,
		NodeKind	Kind
	)			const [private]

printOneChildRepr - Print the representation of one child from a twine.

void Twine::printRepr

(

std::ostream &

OS

)

const

print - Write the representation of this twine to the stream

• OS.

std::string Twine::str

(

)

const

str - Return the twine contents as a std::string.

StringRef Twine::toNullTerminatedStringRef

(

SmallVectorImpl< char > &

Out

)

const

toNullTerminatedStringRef - This returns the twine as a single null terminated StringRef if it can be represented as such.

Otherwise the twine is written into the given SmallVector and a StringRef to the SmallVector's data is returned.

The returned StringRef's size does not include the null terminator.

StringRef Twine::toStringRef

(

SmallVectorImpl< char > &

Out

)

const

toStringRef - This returns the twine as a single StringRef if it can be represented as such.

Otherwise the twine is written into the given SmallVector and a StringRef to the SmallVector's data is returned.

void Twine::toVector

(

SmallVectorImpl< char > &

Out

)

const

toVector - Write the concatenated string into the given SmallString or SmallVector.

static Twine llvm::Twine::utohexstr

(

const uint64_t &

Val

)

[inline, static]

---

Member Data Documentation

Child llvm::Twine::LHS [private]

LHS - The prefix in the concatenation, which may be uninitialized for Null or Empty kinds.

unsigned char llvm::Twine::LHSKind [private]

LHSKind - The NodeKind of the left hand side,.

See also:

getLHSKind().

Child llvm::Twine::RHS [private]

RHS - The suffix in the concatenation, which may be uninitialized for Null or Empty kinds.

unsigned char llvm::Twine::RHSKind [private]

RHSKind - The NodeKind of the left hand side,.

See also:

getLHSKind().

---

The documentation for this class was generated from the following files:

• Twine.h
• Twine.cpp