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

union  Child

## Public Member Functions

bool isTriviallyEmpty () const
Check if this twine is trivially empty; a false return value does not necessarily mean the twine is empty.
bool isSingleStringRef () const
Return true if this twine can be dynamically accessed as a single StringRef value with getSingleStringRef().
std::string str () const
Return the twine contents as a std::string.
void toVector (SmallVectorImpl< char > &Out) const
Append the concatenated string into the given SmallString or SmallVector.
StringRef getSingleStringRef () const
This returns the twine as a single StringRef.
StringRef toStringRef (SmallVectorImpl< char > &Out) const
This returns the twine as a single StringRef if it can be represented as such.
StringRef toNullTerminatedStringRef (SmallVectorImpl< char > &Out) const
This returns the twine as a single null terminated StringRef if it can be represented as such.
void print (raw_ostream &OS) const
Write the concatenated string represented by this twine to the stream OS.
void dump () const
Dump the concatenated string represented by this twine to stderr.
void printRepr (raw_ostream &OS) const
Write the representation of this twine to the stream OS.
void dumpRepr () const
Dump the representation of this twine to stderr.
Twine Inline Implementations
Twine concat (const Twine &Suffix) const

## Static Public Member Functions

static Twine utohexstr (const uint64_t &Val)

## Constructors

Twine ()
Construct from an empty string.
Twine (const Twine &)
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 (const SmallVectorImpl< char > &Str)
Construct from a SmallString.
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 Val as an unsigned decimal integer.
Twine (int Val)
Construct a twine to print Val as a signed decimal integer.
Twine (const unsigned long &Val)
Construct a twine to print Val as an unsigned decimal integer.
Twine (const long &Val)
Construct a twine to print Val as a signed decimal integer.
Twine (const unsigned long long &Val)
Construct a twine to print Val as an unsigned decimal integer.
Twine (const long long &Val)
Construct a twine to print Val as a signed decimal integer.
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

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

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.

Definition at line 79 of file Twine.h.

## Constructor & Destructor Documentation

 llvm::Twine::Twine ( )  [inline]

Construct from an empty string.

Definition at line 255 of file Twine.h.

Referenced by concat(), createNull(), and utohexstr().

 llvm::Twine::Twine ( const Twine & )
 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.

Definition at line 266 of file Twine.h.

 llvm::Twine::Twine ( const std::string & Str )  [inline]

Construct from an std::string.

Definition at line 278 of file Twine.h.

 llvm::Twine::Twine ( const StringRef & Str )  [inline]

Construct from a StringRef.

Definition at line 285 of file Twine.h.

 llvm::Twine::Twine ( const SmallVectorImpl< char > & Str )  [inline]

Construct from a SmallString.

Definition at line 292 of file Twine.h.

 llvm::Twine::Twine ( char Val )  [inline, explicit]

Construct from a char.

Definition at line 299 of file Twine.h.

 llvm::Twine::Twine ( signed char Val )  [inline, explicit]

Construct from a signed char.

Definition at line 305 of file Twine.h.

 llvm::Twine::Twine ( unsigned char Val )  [inline, explicit]

Construct from an unsigned char.

Definition at line 311 of file Twine.h.

 llvm::Twine::Twine ( unsigned Val )  [inline, explicit]

Construct a twine to print Val as an unsigned decimal integer.

Definition at line 317 of file Twine.h.

 llvm::Twine::Twine ( int Val )  [inline, explicit]

Construct a twine to print Val as a signed decimal integer.

Definition at line 323 of file Twine.h.

 llvm::Twine::Twine ( const unsigned long & Val )  [inline, explicit]

Construct a twine to print Val as an unsigned decimal integer.

Definition at line 329 of file Twine.h.

 llvm::Twine::Twine ( const long & Val )  [inline, explicit]

Construct a twine to print Val as a signed decimal integer.

Definition at line 335 of file Twine.h.

 llvm::Twine::Twine ( const unsigned long long & Val )  [inline, explicit]

Construct a twine to print Val as an unsigned decimal integer.

Definition at line 341 of file Twine.h.

 llvm::Twine::Twine ( const long long & Val )  [inline, explicit]

Construct a twine to print Val as a signed decimal integer.

Definition at line 347 of file Twine.h.

 llvm::Twine::Twine ( const char * LHS, const StringRef & RHS )  [inline]

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

Definition at line 358 of file Twine.h.

 llvm::Twine::Twine ( const StringRef & LHS, const char * RHS )  [inline]

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

Definition at line 366 of file Twine.h.

## Member Function Documentation

 Twine llvm::Twine::concat ( const Twine & Suffix ) const [inline]

Definition at line 485 of file Twine.h.

References Twine().

Referenced by llvm::operator+().

 static Twine llvm::Twine::createNull ( )  [inline, static]

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

Definition at line 375 of file Twine.h.

References Twine().

 void Twine::dump ( ) const

Dump the concatenated string represented by this twine to stderr.

Definition at line 164 of file Twine.cpp.

References llvm::dbgs(), and print().

 void Twine::dumpRepr ( ) const

Dump the representation of this twine to stderr.

Definition at line 168 of file Twine.cpp.

References llvm::dbgs(), and printRepr().

 StringRef llvm::Twine::getSingleStringRef ( ) const [inline]

This returns the twine as a single StringRef.

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

Definition at line 428 of file Twine.h.

Referenced by llvm::sys::path::native().

 bool llvm::Twine::isSingleStringRef ( ) const [inline]

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

Definition at line 399 of file Twine.h.

Referenced by llvm::sys::path::native().

 bool llvm::Twine::isTriviallyEmpty ( ) const [inline]

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

Definition at line 393 of file Twine.h.

Referenced by llvm::sys::path::append().

 void Twine::print ( raw_ostream & OS ) const

Write the concatenated string represented by this twine to the stream OS.

Definition at line 151 of file Twine.cpp.

Referenced by dump(), llvm::DiagnosticPrinterRawOStream::operator<<(), llvm::operator<<(), and toVector().

 void Twine::printRepr ( raw_ostream & OS ) const

Write the representation of this twine to the stream OS.

Definition at line 156 of file Twine.cpp.

Referenced by dumpRepr().

 std::string Twine::str ( ) const

Return the twine contents as a std::string.

Definition at line 16 of file Twine.cpp.

References llvm::StringRef::str(), and toStringRef().

 StringRef Twine::toNullTerminatedStringRef ( SmallVectorImpl< char > & Out ) const

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.

Definition at line 31 of file Twine.cpp.

Referenced by llvm::sys::fs::createTemporaryFile().

 StringRef llvm::Twine::toStringRef ( SmallVectorImpl< char > & Out ) const [inline]

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.

Definition at line 444 of file Twine.h.

 void Twine::toVector ( SmallVectorImpl< char > & Out ) const

Append the concatenated string into the given SmallString or SmallVector.

Definition at line 26 of file Twine.cpp.

References print().

 static Twine llvm::Twine::utohexstr ( const uint64_t & Val )  [inline, static]

Definition at line 382 of file Twine.h.

References Twine().

Referenced by llvm::AsmPrinter::emitDwarfDIE().

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