llvm::Twine Class Reference

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

#include "llvm/ADT/Twine.h"

Public Member Functions
Predicate Operations
bool	isTriviallyEmpty () const
	Check if this twine is trivially empty; a false return value does not necessarily mean the twine is empty.
bool	isSingleStringLiteral () const
	Check if this twine is guaranteed to refer to single string literal.
bool	isSingleStringRef () const
	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.
LLVM_ABI std::string	str () const
	Return the twine contents as a std::string.
LLVM_ABI 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.
LLVM_ABI StringRef	toNullTerminatedStringRef (SmallVectorImpl< char > &Out) const
	This returns the twine as a single null terminated StringRef if it can be represented as such.
LLVM_ABI void	print (raw_ostream &OS) const
	Write the concatenated string represented by this twine to the stream OS.
LLVM_ABI void	printRepr (raw_ostream &OS) const
	Write the representation of this twine to the stream OS.
LLVM_DUMP_METHOD void	dump () const
	Dump the concatenated string represented by this twine to stderr.
LLVM_DUMP_METHOD void	dumpRepr () const
	Dump the representation of this twine to stderr.

Static Public Member Functions
Numeric Conversions
static Twine	utohexstr (uint64_t Val)

Constructors
	Twine ()
	Construct from an empty string.
	Twine (const Twine &)=default
	Twine (const char *Str)
	Construct from a C string.
	Twine (std::nullptr_t)=delete
	Delete the implicit conversion from nullptr as Twine(const char *) cannot take nullptr.
	Twine (const std::string &Str)
	Construct from an std::string.
	Twine (const std::string_view &Str)
	Construct from an std::string_view by converting it to a pointer and length.
	Twine (const StringRef &Str)
	Construct from a StringRef.
	Twine (const StringLiteral &Str)
	Construct from a StringLiteral.
	Twine (const SmallVectorImpl< char > &Str)
	Construct from a SmallString.
	Twine (const formatv_object_base &Fmt)
	Construct from a formatv_object_base.
	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 (unsigned long Val)
	Construct a twine to print Val as an unsigned decimal integer.
	Twine (long Val)
	Construct a twine to print Val as a signed decimal integer.
	Twine (unsigned long long Val)
	Construct a twine to print Val as an unsigned decimal integer.
	Twine (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.
Twine &	operator= (const Twine &)=delete
	Since the intended use of twines is as temporary objects, assignments when concatenating might cause undefined behavior or stack corruptions.
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 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.

Definition at line 82 of file Twine.h.

Constructor & Destructor Documentation

Twine() [1/21]

llvm::Twine::Twine ( )

inline

Construct from an empty string.

Definition at line 248 of file Twine.h.

References assert().

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

Twine() [2/21]

llvm::Twine::Twine ( const Twine & )

default

Twine() [3/21]

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

References assert().

Twine() [4/21]

llvm::Twine::Twine ( std::nullptr_t )

delete

Delete the implicit conversion from nullptr as Twine(const char *) cannot take nullptr.

Twine() [5/21]

llvm::Twine::Twine ( const std::string & Str )

inline

Construct from an std::string.

Definition at line 272 of file Twine.h.

References assert().

Twine() [6/21]

llvm::Twine::Twine ( const std::string_view & Str )

inline

Construct from an std::string_view by converting it to a pointer and length.

This handles string_views on a pure API basis, and avoids storing one (or a pointer to one) inside a Twine, which avoids problems when mixing code compiled under various C++ standards.

Definition at line 281 of file Twine.h.

References assert().

Twine() [7/21]

llvm::Twine::Twine ( const StringRef & Str )

inline

Construct from a StringRef.

Definition at line 288 of file Twine.h.

References assert().

Twine() [8/21]

llvm::Twine::Twine ( const StringLiteral & Str )

inline

Construct from a StringLiteral.

Definition at line 295 of file Twine.h.

References assert().

Twine() [9/21]

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

inline

Construct from a SmallString.

Definition at line 302 of file Twine.h.

References assert().

Twine() [10/21]

llvm::Twine::Twine ( const formatv_object_base & Fmt )

inline

Construct from a formatv_object_base.

Definition at line 310 of file Twine.h.

References assert().

Twine() [11/21]

llvm::Twine::Twine ( char Val )

inlineexplicit

Construct from a char.

Definition at line 317 of file Twine.h.

Twine() [12/21]

llvm::Twine::Twine ( signed char Val )

inlineexplicit

Construct from a signed char.

Definition at line 320 of file Twine.h.

Twine() [13/21]

llvm::Twine::Twine ( unsigned char Val )

inlineexplicit

Construct from an unsigned char.

Definition at line 325 of file Twine.h.

Twine() [14/21]

llvm::Twine::Twine ( unsigned Val )

inlineexplicit

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

Definition at line 330 of file Twine.h.

Twine() [15/21]

llvm::Twine::Twine ( int Val )

inlineexplicit

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

Definition at line 333 of file Twine.h.

Twine() [16/21]

llvm::Twine::Twine ( unsigned long Val )

inlineexplicit

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

Definition at line 336 of file Twine.h.

Twine() [17/21]

llvm::Twine::Twine ( long Val )

inlineexplicit

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

Definition at line 339 of file Twine.h.

Twine() [18/21]

llvm::Twine::Twine ( unsigned long long Val )

inlineexplicit

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

Definition at line 342 of file Twine.h.

Twine() [19/21]

llvm::Twine::Twine ( long long Val )

inlineexplicit

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

Definition at line 347 of file Twine.h.

Twine() [20/21]

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

inline

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

Definition at line 355 of file Twine.h.

References assert(), llvm::StringRef::data(), and llvm::StringRef::size().

Twine() [21/21]

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

inline

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

Definition at line 364 of file Twine.h.

References assert(), llvm::StringRef::data(), and llvm::StringRef::size().

Member Function Documentation

concat()

Twine llvm::Twine::concat ( const Twine & Suffix ) const

inline

Definition at line 497 of file Twine.h.

References Twine().

Referenced by LiveDebugValues::ValueIDNum::asString(), llvm::SystemZAsmPrinter::emitFunctionEntryLabel(), llvm::COFF::encodeSectionName(), llvm::TargetLoweringObjectFileGOFF::getModuleMetadata(), and LiveDebugValues::MLocTracker::LocIdxToName().

createNull()

Twine llvm::Twine::createNull ( )

inlinestatic

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

Definition at line 378 of file Twine.h.

References Twine().

dump()

LLVM_DUMP_METHOD void Twine::dump

(

)

const

Dump the concatenated string represented by this twine to stderr.

Definition at line 178 of file Twine.cpp.

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

dumpRepr()

LLVM_DUMP_METHOD void Twine::dumpRepr

(

)

const

Dump the representation of this twine to stderr.

Definition at line 180 of file Twine.cpp.

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

getSingleStringRef()

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

References assert(), isSingleStringRef(), and llvm_unreachable.

Referenced by toStringRef().

isSingleStringLiteral()

bool llvm::Twine::isSingleStringLiteral ( ) const

inline

Check if this twine is guaranteed to refer to single string literal.

Definition at line 401 of file Twine.h.

isSingleStringRef()

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

Referenced by getSingleStringRef(), and toStringRef().

isTriviallyEmpty()

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

Referenced by llvm::sys::path::append(), llvm::MCContext::getELFSection(), and llvm::MCContext::getWasmSection().

operator=()

Twine & llvm::Twine::operator= ( const Twine & )

delete

Since the intended use of twines is as temporary objects, assignments when concatenating might cause undefined behavior or stack corruptions.

print()

void Twine::print

(

raw_ostream &

OS

)

const

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

Definition at line 164 of file Twine.cpp.

Referenced by dump(), and toVector().

printRepr()

void Twine::printRepr

(

raw_ostream &

OS

)

const

Write the representation of this twine to the stream OS.

Definition at line 169 of file Twine.cpp.

Referenced by dumpRepr().

str()

std::string Twine::str

(

)

const

Return the twine contents as a std::string.

Definition at line 17 of file Twine.cpp.

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

Referenced by LiveDebugValues::ValueIDNum::asString(), buildFrameDebugInfo(), llvm::IndexedInstrProfReader::create(), llvm::createStringError(), llvm::DiagnosticInfoIROptimization::DiagnosticInfoIROptimization(), llvm::vfs::InMemoryFileSystem::dir_begin(), llvm::vfs::OverlayFileSystem::dir_begin(), llvm::dumpDotGraphToFile(), llvm::CFGMST< Edge, BBInfo >::dumpEdges(), llvm::SystemZAsmPrinter::emitFunctionEntryLabel(), llvm::TargetLoweringObjectFileELF::emitModuleMetadata(), llvm::MIRParserImpl::error(), formatPax(), llvm::MCContext::getELFSection(), llvm::SourceMgr::GetMessage(), llvm::TargetLoweringObjectFileGOFF::getModuleMetadata(), llvm::getVacantFunctionName(), llvm::MCContext::getWasmSection(), llvm::DotCfgChangeReporter::handleFunctionCompare(), llvm::localCache(), LiveDebugValues::MLocTracker::LocIdxToName(), malformedError(), malformedError(), mapNameAndUniqueName(), llvm::Triple::normalize(), llvm::objcopy::elf::OwnedDataSection::OwnedDataSection(), llvm::object::DirectX::parseFailed(), parseFailed(), llvm::prepareTempFiles(), llvm::MCAssembler::recordError(), llvm::report_fatal_error(), llvm::LoopVectorizeHints::setAlreadyVectorized(), llvm::VPBlockBase::setName(), llvm::VPlan::setName(), llvm::splitBlockBefore(), SplitBlockImpl(), llvm::SplitKnownCriticalEdge(), toNullTerminatedStringRef(), and writeDDGToDotFile().

toNullTerminatedStringRef()

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 37 of file Twine.cpp.

References llvm::SmallVectorTemplateCommon< T, typename >::data(), llvm::SmallVectorTemplateBase< T, bool >::pop_back(), llvm::SmallVectorTemplateBase< T, bool >::push_back(), llvm::SmallVectorTemplateCommon< T, typename >::size(), str(), and toVector().

toStringRef()

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

References llvm::SmallVectorTemplateCommon< T, typename >::data(), getSingleStringRef(), isSingleStringRef(), llvm::SmallVectorTemplateCommon< T, typename >::size(), and toVector().

Referenced by llvm::sys::path::append(), llvm::DwarfCompileUnit::createBaseTypeDIEs(), getNameWithPrefixImpl(), llvm::WritableMemoryBuffer::getNewUninitMemBuffer(), llvm::StringSaver::save(), llvm::UniqueStringSaver::save(), and str().

toVector()

void Twine::toVector

(

SmallVectorImpl< char > &

Out

)

const

Append the concatenated string into the given SmallString or SmallVector.

Definition at line 32 of file Twine.cpp.

References print().

Referenced by llvm::MCAsmParser::addErrorSuffix(), llvm::vfs::InMemoryFileSystem::addSymbolicLink(), llvm::vfs::RedirectingFileSystem::dir_begin(), llvm::COFF::encodeSectionName(), llvm::MCAsmParser::Error(), llvm::vfs::RedirectingFileSystem::exists(), llvm::vfs::RedirectingFileSystem::getRealPath(), llvm::object::XCOFFObjectFile::getSectionFileOffsetToRawData(), llvm::vfs::RedirectingFileSystem::isLocal(), llvm::localCache(), llvm::sys::fs::make_absolute(), llvm::vfs::RedirectingFileSystem::openFileForRead(), llvm::vfs::RedirectingFileSystem::status(), toNullTerminatedStringRef(), and toStringRef().

utohexstr()

Twine llvm::Twine::utohexstr ( uint64_t Val )

inlinestatic

Definition at line 385 of file Twine.h.

References Twine().

Referenced by decodeBBAddrMapImpl(), llvm::AppleAcceleratorTable::dump(), llvm::BlockCoverageInference::dump(), llvm::DWARFDebugNames::Abbrev::dump(), llvm::DWARFDebugNames::NameIndex::dump(), llvm::DWARFDebugNames::Entry::dumpParentIdx(), llvm::DWARFYAML::emitDebugRanges(), llvm::AsmPrinter::emitDwarfDIE(), llvm::SystemZAsmPrinter::emitFunctionEntryLabel(), llvm::BTFTypeBase::emitType(), llvm::BTFTypeEnum64::emitType(), llvm::BTFTypeInt::emitType(), llvm::BTFTypeStruct::emitType(), llvm::objcopy::elf::ASCIIHexWriter::finalize(), llvm::objcopy::elf::BinaryWriter::finalize(), llvm::objcopy::elf::ELFWriter< ELFT >::finalize(), fixupIndexV4(), fixupIndexV5(), llvm::object::ELFFile< ELFT >::getEntry(), getGlobalSymtabLocAndSize(), llvm::object::XCOFFObjectFile::getImportFileTable(), llvm::object::getLoaderSecSymNameInStrTbl(), llvm::object::XCOFFObjectFile::getRawData(), llvm::object::XCOFFObjectFile::getSectionContents(), llvm::object::ELFFile< ELFT >::getSectionContentsAsArray(), llvm::object::XCOFFObjectFile::getSectionFileOffsetToRawData(), llvm::object::ELFFile< ELFT >::getSectionName(), llvm::object::ELFFile< ELFT >::getSegmentContents(), llvm::object::XCOFFObjectFile::getStringTableEntry(), llvm::object::ELFFile< ELFT >::getVersionDefinitions(), llvm::object::ELFFile< ELFT >::getVersionDependencies(), handleArgs(), llvm::object::XCOFFSymbolRef::isFunction(), llvm::object::ExportEntry::moveNext(), llvm::object::MachOBindEntry::moveNext(), llvm::object::MachORebaseEntry::moveNext(), llvm::object::ELFFile< ELF32LE >::notes_begin(), llvm::object::ELFFile< ELF32LE >::notes_begin(), llvm::ELFCompactAttrParser::parseAttributeList(), llvm::ELFCompactAttrParser::parseSubsection(), llvm::DemandedBits::print(), llvm::object::WasmSymbol::print(), llvm::MipsAsmPrinter::PrintAsmOperand(), llvm::logicalview::LVElement::printLinkageName(), llvm::object::ELFFile< ELF32LE >::program_headers(), readULEB128As(), llvm::object::XCOFFObjectFile::relocations(), llvm::object::ELFFile< ELFT >::sections(), llvm::symbolize::toHex(), llvm::object::ELFFile< ELFT >::toMappedAddr(), llvm::AMDGPUPALMetadata::toString(), llvm::objcopy::macho::MachOWriter::write(), and llvm::objcopy::xcoff::XCOFFWriter::write().

---

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

• include/llvm/ADT/Twine.h
• lib/Support/Twine.cpp