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

Synopsis

Declared in <llvm/ADT/Twine.h>

class Twine;

Description

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

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

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 Functions

Name

Description

Twine [constructor]

Constructors

operator= [deleted]

Deleted assignment; Twines are temporary and must not be reassigned.

concat

Return a twine that concatenates this twine with Suffix.

dump

Dump the concatenated string represented by this twine to stderr.

dumpRepr

Dump the representation of this twine to stderr.

getSingleStringRef

This returns the twine as a single StringRef. This method is only valid if isSingleStringRef() is true.

isSingleStringLiteral

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

isSingleStringRef

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

isTriviallyEmpty

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

print

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

printRepr

Write the representation of this twine to the stream OS.

str

Return the twine contents as a std::string.

toNullTerminatedStringRef

Return this twine as a null‐terminated StringRef, using Out if needed.

toStringRef

Return this twine as a StringRef, using Out as scratch if needed.

toVector

Append the concatenated string into the given SmallString or SmallVector.

Static Member Functions

Name

Description

createNull

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

utohexstr

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

Non-Member Functions

Name

Description

PrintError

Print an error diagnostic with message Msg and no source location.

PrintFatalError

Print an error with message Msg and then exit the process.

PrintFatalNote

Print a note with message Msg and then exit the process.

PrintNote

Print a note diagnostic with message Msg and no source location.

PrintWarning

Print a warning diagnostic with message Msg and no source location.

createFileError

Create a StringError with the specified error code and prepend the file path to it.

createFileError

Concatenate a source file path and/or name with line number and std::error_code to form an Error object.

createFileError

Deleted overload: a successful Error cannot be wrapped as a FileError.

createFileError

Concatenate a source file path and/or name with a std::error_code to form an Error object.

createFileError

Create a StringError with the specified error code and prepend the file path to it.

createFileError

Concatenate a source file path and/or name with an Error. The resulting Error is unchecked.

createFileError

Concatenate a source file path and/or name with line number and an Error. The resulting Error is unchecked.

createGraphFilename

Create a temporary file name suitable for writing a DOT graph.

createStringError

Create a StringError with an inconvertible error code.

identify_magic

Get and identify path's type based on its content.

localCache

Create a local file system cache which uses the given cache name, temporary file prefix, cache directory and file callback.

needConversion

Query whether a file needs conversion to the UTF‐8 codepage.

operator+

Concatenate LHS and RHS into a new Twine.

operator+

Concatenate a C string and a StringRef with simplified codegen.

operator+

Concatenate a StringRef and a C string with simplified codegen.

reportFatalInternalError

Report a fatal internal error with message reason.

reportFatalUsageError

Report a fatal usage error with message reason.

report_fatal_error

Report a fatal error from a Twine reason.

set_thread_name

Set the name of the current thread.

to_float

Parse T as a double into Num.

to_float

Parse T as a long double into Num.

to_float

Parse T as a float into Num.

MachO::shouldSkipSymLink

Determine whether to skip over symlink due to either too many symlink levels or is cyclic.

cas::createOnDiskCAS

Create a persistent on‐disk CAS at Path.

cgdata::warn

Report a codegen‐data warning with message Message.

dwarf_linker::isPathAbsoluteOnWindowsOrPosix

True if Path is absolute under POSIX or Windows path rules.

object::createError

Create a parse_failed StringError with message Err.

vfs::convertToOutputError

Return Error::success() or use OutputPath to create an OutputError, depending on EC.

vfs::convertToTempFileOutputError

Return Error::success() or use TempPath and OutputPath to create a TempFileOutputError, depending on EC.

sys::fs::access

Can the file be accessed?

sys::fs::can_execute

Can we execute this file?

sys::fs::can_write

Can we write this file?

sys::fs::copy_file

Copy the contents of From to To.

sys::fs::copy_file

Copy the contents of From to To.

sys::fs::createTemporaryFile

Create an empty temporary file without returning an open descriptor.

sys::fs::createTemporaryFile

Create a file in the system temporary directory.

sys::fs::createUniqueDirectory

Create a unique directory whose name starts with Prefix.

sys::fs::createUniqueFile

Create a uniquely named empty file without returning an open descriptor.

sys::fs::createUniqueFile

Create a uniquely named file.

sys::fs::createUniquePath

Create a potentially unique file name but does not create it.

sys::fs::create_directories

Create all the non‐existent directories in path.

sys::fs::create_directory

Create the directory in path.

sys::fs::create_hard_link

Create a hard link from from to to, or return an error.

sys::fs::create_link

Create a link from from to to.

sys::fs::create_symlink

Create a symbolic link from from to to.

sys::fs::disk_space

Get disk space usage information.

sys::fs::equivalent

Return whether paths A and B refer to the same entity, ignoring errors.

sys::fs::equivalent

Do paths represent the same thing?

sys::fs::exists

Does file exist?

sys::fs::expand_tilde

Expands ~ expressions to the user's home directory. On Unix ~user directories are resolved as well.

sys::fs::file_size

Get file size.

sys::fs::getPermissions

Get file permissions.

sys::fs::getPotentiallyUniqueFileName

Get a unique name, not currently exisiting in the filesystem. Subject to race conditions, prefer to use createUniqueFile instead.

sys::fs::getPotentiallyUniqueTempFileName

Get a unique temporary file name, not currently exisiting in the filesystem. Subject to race conditions, prefer to use createTemporaryFile instead.

sys::fs::getUniqueID

Fill Result with the unique ID of the filesystem object at Path.

sys::fs::get_file_type

Does status represent a directory?

sys::fs::is_directory

Is path a directory?

sys::fs::is_directory

Return whether Path is a directory, ignoring errors as false.

sys::fs::is_local

Return whether Path is on a local filesystem, ignoring errors as false.

sys::fs::is_local

Is the file mounted on a local filesystem?

sys::fs::is_other

Is path something that exists but is not a directory, regular file, or symlink?

sys::fs::is_regular_file

Is path a regular file?

sys::fs::is_regular_file

Return whether Path is a regular file, ignoring errors as false.

sys::fs::is_symlink_file

Return whether Path is a symbolic link, ignoring errors as false.

sys::fs::is_symlink_file

Is path a symlink file?

sys::fs::md5_contents

Compute an MD5 hash of the file at Path.

sys::fs::openFile

Opens a file with the specified creation disposition, access mode, and flags and returns a file descriptor.

sys::fs::openFileForRead

Opens the file with the given name in a read‐only mode, returning its open file descriptor.

sys::fs::openFileForReadWrite

Opens the file for read‐write, creating it if it does not exist.

sys::fs::openFileForWrite

Opens the file for write, creating it if it does not exist.

sys::fs::openNativeFile

Opens a file with the specified creation disposition, access mode, and flags and returns a platform‐specific file object.

sys::fs::openNativeFileForRead

Opens the file with the given name in a read‐only mode, returning its open file descriptor.

sys::fs::openNativeFileForReadWrite

Opens the file for read‐write, creating it if it does not exist.

sys::fs::openNativeFileForWrite

Opens the file for write, creating it if it does not exist.

sys::fs::readlink

Read the target of a symbolic link.

sys::fs::real_path

Collapse all . and .. patterns, resolve all symlinks, and optionally expand ~ expressions to the user's home directory.

sys::fs::remove

Remove path. Equivalent to POSIX remove().

sys::fs::remove_directories

Recursively delete a directory.

sys::fs::rename

Rename from to to.

sys::fs::setLastAccessAndModificationTime

Set the file modification and access time, by path.

sys::fs::setLastAccessAndModificationTime

Set both access and modification time by path to the same value.

sys::fs::setPermissions

Set file permissions.

sys::fs::set_current_path

Set the current path.

sys::fs::status

Get file status as if by POSIX stat().

sys::fs::status_known

Is status available?

sys::path::has_extension

Has extension?

sys::path::has_filename

Has filename?

sys::path::has_parent_path

Has parent path?

sys::path::has_relative_path

Has relative path?

sys::path::has_root_directory

Has root directory?

sys::path::has_root_name

Has root name?

sys::path::has_root_path

Has root path?

sys::path::has_stem

Has stem?

sys::path::is_absolute

Is path absolute?

sys::path::is_absolute_gnu

Is path absolute using GNU rules?

sys::path::is_relative

Is path relative?

sys::path::make_absolute

Make path an absolute path.

sys::path::native

Convert path to the native form as a std::string.

sys::path::native

Convert path to the native form.

See Also

isNullary(),

isUnary(), and

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

isValid().

Created with MrDocs