LLVM API Documentation

llvm::Twine Class Reference

#include <Twine.h>

Collaboration diagram for llvm::Twine:
[legend]

List of all members.

Constructors

 Twine ()
 Construct from an empty string.
 Twine (const char *Str)
 Twine (const std::string &Str)
 Construct from an std::string.
 Twine (const StringRef &Str)
 Construct from a StringRef.
 Twine (const unsigned int &Val)
 Construct a twine to print.
 Twine (const 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 ()

Public Member Functions

Predicate Operations
bool isTriviallyEmpty () const
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
void print (raw_ostream &OS) const
void dump () const
 dump - Dump the concatenated string represented by this twine to stderr.
void printRepr (raw_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)


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

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.

Definition at line 80 of file Twine.h.


Constructor & Destructor Documentation

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

Construct from an empty string.

Definition at line 229 of file Twine.h.

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

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 238 of file Twine.h.

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

Construct from an std::string.

Definition at line 250 of file Twine.h.

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

Construct from a StringRef.

Definition at line 256 of file Twine.h.

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

Construct a twine to print.

  • Val as an unsigned decimal integer.

Definition at line 262 of file Twine.h.

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

Construct a twine to print.

  • Val as a signed decimal integer.

Definition at line 267 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 272 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 277 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 282 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 287 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 297 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 303 of file Twine.h.


Member Function Documentation

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 310 of file Twine.h.

References Twine().

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

Definition at line 319 of file Twine.h.

References Twine().

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.

Definition at line 329 of file Twine.h.

Referenced by llvm::Value::setName().

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

Definition at line 369 of file Twine.h.

References getLHSKind(), isEmpty(), isNull(), isUnary(), LHS, and Twine().

Referenced by llvm::operator+().

std::string Twine::str (  )  const

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

Definition at line 15 of file Twine.cpp.

References llvm::SmallVectorImpl< char >::begin(), llvm::SmallVectorImpl< char >::end(), and toVector().

Referenced by Error(), llvm::llvm_report_error(), and llvm::Triple::setTriple().

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

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

Definition at line 21 of file Twine.cpp.

References OS, and print().

Referenced by llvm::Value::setName(), and str().

void Twine::print ( raw_ostream &  OS  )  const

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

  • OS.

Definition at line 114 of file Twine.cpp.

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

void Twine::dump (  )  const

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

Definition at line 127 of file Twine.cpp.

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

void Twine::printRepr ( raw_ostream &  OS  )  const

print - Write the representation of this twine to the stream

  • OS.

Definition at line 119 of file Twine.cpp.

Referenced by dumpRepr().

void Twine::dumpRepr (  )  const

dumpRepr - Dump the representation of this twine to stderr.

Definition at line 131 of file Twine.cpp.

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


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