Package com.oracle.truffle.api.strings

Class TruffleString

java.lang.Object

com.oracle.truffle.api.strings.AbstractTruffleString

com.oracle.truffle.api.strings.TruffleString

public final class TruffleString
extends AbstractTruffleString

Represents a primitive String type, which can be reused across languages. Language implementers are encouraged to use Truffle Strings as their language's string type for easier interoperability and better performance. Truffle strings can be encoded in a number of encodings. A TruffleString object can cache multiple representations (in multiple encodings) of the same string in the string object itself. A single TruffleString instance can also represent the same string in multiple encodings, if the string's content would be equal in all such encodings (e.g. a string containing only ASCII characters can be viewed as being encoded in almost any encoding, since the encoded bytes would be equal). To facilitate this, all methods have an expectedEncoding parameter to indicate which encoding a given string should be viewed in.

TruffleString instances can be created via one of the following nodes, or via TruffleStringBuilder.

• TruffleString.FromByteArrayNode
• TruffleString.FromCharArrayUTF16Node
• TruffleString.FromJavaStringNode
• TruffleString.FromIntArrayUTF32Node
• TruffleString.FromNativePointerNode
• TruffleString.FromCodePointNode
• TruffleString.FromLongNode

For iteration use TruffleStringIterator. There is a version of TruffleString that is also mutable. See MutableTruffleString for details.

Please see the tutorial for further usage instructions.

Since:

22.1

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	TruffleString.AsManagedNode	Node to get the given AbstractTruffleString as a managed TruffleString, meaning that the resulting string's backing memory is not a native pointer.
static class	TruffleString.AsNativeNode	Node to convert a potentially managed TruffleString to a native string.
static class	TruffleString.AsTruffleStringNode	Node to get the given AbstractTruffleString as a TruffleString.
static class	TruffleString.ByteIndexOfAnyByteNode	Node to find the index of the first occurrence of any byte from a given array.
static class	TruffleString.ByteIndexOfCodePointNode	TruffleString.IndexOfCodePointNode, but with byte indices.
static class	TruffleString.ByteIndexOfCodePointSetNode	Node to find the byte index of the first occurrence of a codepoint present in a given codepoint set.
static class	TruffleString.ByteIndexOfStringNode	TruffleString.IndexOfStringNode, but with byte indices.
static class	TruffleString.ByteIndexToCodePointIndexNode	Node to convert a given byte index to a codepoint index.
static class	TruffleString.ByteLengthOfCodePointNode	Node to get the number of bytes occupied by the codepoint starting at a given byte index.
static class	TruffleString.CharIndexOfAnyCharUTF16Node	Node to find the index of the first occurrence of any char from a given array.
static class	TruffleString.CodePointAtByteIndexNode	Node to read a codepoint at a given byte index.
static class	TruffleString.CodePointAtIndexNode	Node to read a codepoint at a given codepoint index.
static class	TruffleString.CodePointIndexToByteIndexNode	Node to convert a given codepoint index to a byte index.
static class	TruffleString.CodePointLengthNode	Node to get the number of codepoints in a string.
static final class	TruffleString.CodePointSet	A set of codepoints in a given encoding.
static enum	TruffleString.CodeRange	Provides information about a string's content.
static class	TruffleString.CodeRangeEqualsNode	Node to check if a string's code range is equal to the given TruffleString.CodeRange.
static enum	TruffleString.CompactionLevel	Represents a string's compaction level, i.e.
static class	TruffleString.CompareBytesNode	Node to compare two strings byte-by-byte.
static class	TruffleString.CompareCharsUTF16Node	Node to compare two UTF-16 strings.
static class	TruffleString.CompareIntsUTF32Node	Node to compare two UTF-32 strings.
static class	TruffleString.ConcatNode	Node to concatenate two strings.
static class	TruffleString.CopyToByteArrayNode	Node to copy a region of a string into a byte array.
static class	TruffleString.CopyToNativeMemoryNode	Node to copy a region of a string into native memory.
static class	TruffleString.CreateBackwardCodePointIteratorNode	Node to create a TruffleStringIterator.
static class	TruffleString.CreateCodePointIteratorNode	Node to create a TruffleStringIterator.
static enum	TruffleString.Encoding	The list of encodings supported by TruffleString.
static class	TruffleString.EqualNode	Node to check two strings for equality.
static enum	TruffleString.ErrorHandling	Error handling instructions for operations that return integer values, such as indices or code points.
static class	TruffleString.ForceEncodingNode	Node to forcibly assign any encoding to a string.
static class	TruffleString.FromByteArrayNode	Node to create a new TruffleString from a byte array.
static class	TruffleString.FromCharArrayUTF16Node	Node to create a new UTF-16 TruffleString from a char array.
static class	TruffleString.FromCodePointNode	Node to create a new TruffleString from a single codepoint.
static class	TruffleString.FromIntArrayUTF32Node	Node to create a new UTF-32 TruffleString from an int-array.
static class	TruffleString.FromJavaStringNode	Node to create a new TruffleString from a Java string.
static class	TruffleString.FromLongNode	Node to create a new TruffleString from a long value.
static class	TruffleString.FromNativePointerNode	Node to create a new TruffleString from an interop object representing a native pointer.
static class	TruffleString.GetByteCodeRangeNode	Node to get a string's "byte-based" TruffleString.CodeRange.
static class	TruffleString.GetCodeRangeImpreciseNode	Node to get a string's possibly imprecise TruffleString.CodeRange.
static class	TruffleString.GetCodeRangeNode	Node to get a string's precise TruffleString.CodeRange.
static class	TruffleString.GetInternalByteArrayNode	Node to get a string's internal byte array.
static class	TruffleString.GetInternalNativePointerNode	Node to get a native string's pointer object.
static class	TruffleString.GetStringCompactionLevelNode	Node to get a string's TruffleString.CompactionLevel.
static class	TruffleString.HashCodeNode	Node to get a string's hash code.
static final class	TruffleString.IllegalByteArrayLengthException	This exception is thrown when any operation tries to create a UTF-16 or UTF-32 string with an invalid byte length (not a multiple of 2/4 bytes).
static class	TruffleString.IndexOfCodePointNode	Node to find the index of the first occurrence of a given code point.
static class	TruffleString.IndexOfStringNode	Node to find the index of the first occurrence of a given string.
static class	TruffleString.IntIndexOfAnyIntUTF32Node	Node to find the index of the first occurrence of any int from a given array.
static class	TruffleString.IsValidNode	Node to check if a string is encoded correctly.
static class	TruffleString.LastByteIndexOfCodePointNode	TruffleString.LastIndexOfCodePointNode, but with byte indices.
static class	TruffleString.LastByteIndexOfStringNode	TruffleString.LastIndexOfStringNode, but with byte indices.
static class	TruffleString.LastIndexOfCodePointNode	Node to find the codepoint index of the last occurrence of a given code point.
static class	TruffleString.LastIndexOfStringNode	Node to find the index of the last occurrence of a given string.
static class	TruffleString.MaterializeNode	Node to force materialization of any lazy internal data.
static final class	TruffleString.NumberFormatException	This exception may be thrown by TruffleString.ParseIntNode, TruffleString.ParseLongNode or TruffleString.ParseDoubleNode to indicate that the given string cannot be parsed as an integer, long or double value.
static class	TruffleString.ParseDoubleNode	Node to parse a given string as a double value.
static class	TruffleString.ParseIntNode	Node to parse a given string as an int value.
static class	TruffleString.ParseLongNode	Node to parse a given string as a long value.
static class	TruffleString.ReadByteNode	Node to read a single byte from a string.
static class	TruffleString.ReadCharUTF16Node	Node to read a single char from a UTF-16 string.
static class	TruffleString.RegionEqualByteIndexNode	Node to check for a region match, byte-by-byte.
static class	TruffleString.RegionEqualNode	Node to check codepoint equality of two string regions.
static class	TruffleString.RepeatNode	Node to repeat a given string N times.
static class	TruffleString.SubstringByteIndexNode	TruffleString.SubstringNode, but with byte indices.
static class	TruffleString.SubstringNode	Node to create a substring of a given string.
static class	TruffleString.SwitchEncodingNode	Node to get a given string in a specific encoding.
static class	TruffleString.ToJavaStringNode	Node to get a String representation of a TruffleString.
static class	TruffleString.ToValidStringNode	Node to replace all invalid bytes in a given string, such that the resulting string is valid.
static final class	TruffleString.WithMask	Extended parameter type for the operations TruffleString.ByteIndexOfStringNode, TruffleString.LastByteIndexOfStringNode and TruffleString.RegionEqualByteIndexNode.

Method Summary

Modifier and Type	Method	Description
TruffleString	asNativeUncached(NativeAllocator allocator, TruffleString.Encoding expectedEncoding, boolean useCompaction, boolean cacheResult)	Shorthand for calling the uncached version of TruffleString.AsNativeNode.
static TruffleString	fromByteArrayUncached(byte[] value, int byteOffset, int byteLength, TruffleString.Encoding encoding, boolean copy)	Shorthand for calling the uncached version of TruffleString.FromByteArrayNode.
static TruffleString	fromByteArrayUncached(byte[] value, TruffleString.Encoding encoding)	Shorthand for calling the uncached version of TruffleString.FromByteArrayNode.
static TruffleString	fromByteArrayUncached(byte[] value, TruffleString.Encoding encoding, boolean copy)	Shorthand for calling the uncached version of TruffleString.FromByteArrayNode.
static TruffleString	fromCharArrayUTF16Uncached(char[] value)	Shorthand for calling the uncached version of TruffleString.FromCharArrayUTF16Node.
static TruffleString	fromCharArrayUTF16Uncached(char[] value, int charOffset, int charLength)	Shorthand for calling the uncached version of TruffleString.FromCharArrayUTF16Node.
static TruffleString	fromCodePointUncached(int codepoint, TruffleString.Encoding encoding)	Shorthand for calling the uncached version of TruffleString.FromCodePointNode.
static TruffleString	fromCodePointUncached(int codepoint, TruffleString.Encoding encoding, boolean allowUTF16Surrogates)	Shorthand for calling the uncached version of TruffleString.FromCodePointNode.
static TruffleString	fromConstant(String s, TruffleString.Encoding encoding)	Shorthand for calling the uncached version of TruffleString.FromJavaStringNode.
static TruffleString	fromIntArrayUTF32Uncached(int[] value)	Shorthand for calling the uncached version of TruffleString.FromIntArrayUTF32Node.
static TruffleString	fromIntArrayUTF32Uncached(int[] value, int intOffset, int intLength)	Shorthand for calling the uncached version of TruffleString.FromIntArrayUTF32Node.
static TruffleString	fromJavaStringUncached(String s, int charOffset, int length, TruffleString.Encoding encoding, boolean copy)	Shorthand for calling the uncached version of TruffleString.FromJavaStringNode.
static TruffleString	fromJavaStringUncached(String s, TruffleString.Encoding encoding)	Shorthand for calling the uncached version of TruffleString.FromJavaStringNode.
static TruffleString	fromLongUncached(long value, TruffleString.Encoding encoding, boolean lazy)	Shorthand for calling the uncached version of TruffleString.FromLongNode.
static TruffleString	fromNativePointerUncached(Object pointerObject, int byteOffset, int byteLength, TruffleString.Encoding encoding, boolean copy)	Shorthand for calling the uncached version of TruffleString.FromNativePointerNode.

Methods inherited from class com.oracle.truffle.api.strings.AbstractTruffleString

asManagedMutableTruffleStringUncached, asManagedTruffleStringUncached, asManagedTruffleStringUncached, asMutableTruffleStringUncached, asTruffleStringUncached, byteIndexOfAnyByteUncached, byteIndexOfCodePointUncached, byteIndexOfStringUncached, byteIndexOfStringUncached, byteIndexToCodePointIndexUncached, byteLength, byteLengthOfCodePointUncached, byteLengthOfCodePointUncached, charIndexOfAnyCharUTF16Uncached, codePointAtByteIndexUncached, codePointAtByteIndexUncached, codePointAtIndexUncached, codePointAtIndexUncached, codePointIndexToByteIndexUncached, codePointLengthUncached, codeRangeEqualsUncached, compareBytesUncached, compareCharsUTF16Uncached, compareIntsUTF32Uncached, concatUncached, copyToByteArrayNodeUncached, copyToByteArrayUncached, copyToByteArrayUncached, copyToNativeMemoryNodeUncached, copyToNativeMemoryUncached, createBackwardCodePointIteratorUncached, createCodePointIteratorUncached, equals, equalsUncached, forceEncodingUncached, getByteCodeRangeUncached, getCodeRangeImpreciseUncached, getCodeRangeUncached, getInternalByteArrayUncached, getInternalNativePointerUncached, getStringCompactionLevelUncached, hashCode, hashCodeUncached, indexOfCodePointUncached, indexOfStringUncached, intIndexOfAnyIntUTF32Uncached, isCompatibleTo, isCompatibleToUncached, isEmpty, isImmutable, isManaged, isMutable, isNative, isValidUncached, lastByteIndexOfCodePointUncached, lastByteIndexOfStringUncached, lastByteIndexOfStringUncached, lastIndexOfCodePointUncached, lastIndexOfStringUncached, materializeUncached, parseDoubleUncached, parseIntUncached, parseIntUncached, parseLongUncached, parseLongUncached, readByteUncached, readCharUTF16Uncached, regionEqualByteIndexUncached, regionEqualByteIndexUncached, regionEqualsUncached, repeatUncached, substringByteIndexUncached, substringUncached, switchEncodingUncached, switchEncodingUncached, toJavaStringUncached, toString, toStringDebug, toValidStringUncached

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Details

fromCodePointUncached

public static TruffleString fromCodePointUncached(int codepoint,
 TruffleString.Encoding encoding)

Shorthand for calling the uncached version of TruffleString.FromCodePointNode.

Since:

22.1

fromCodePointUncached

public static TruffleString fromCodePointUncached(int codepoint,
 TruffleString.Encoding encoding,
 boolean allowUTF16Surrogates)

Shorthand for calling the uncached version of TruffleString.FromCodePointNode.

Since:

22.2

fromLongUncached

public static TruffleString fromLongUncached(long value,
 TruffleString.Encoding encoding,
 boolean lazy)

Shorthand for calling the uncached version of TruffleString.FromLongNode.

Since:

22.1

fromByteArrayUncached

public static TruffleString fromByteArrayUncached(byte[] value,
 TruffleString.Encoding encoding)

Shorthand for calling the uncached version of TruffleString.FromByteArrayNode.

Since:

22.1

fromByteArrayUncached

public static TruffleString fromByteArrayUncached(byte[] value,
 TruffleString.Encoding encoding,
 boolean copy)

Shorthand for calling the uncached version of TruffleString.FromByteArrayNode.

Since:

22.1

fromByteArrayUncached

public static TruffleString fromByteArrayUncached(byte[] value,
 int byteOffset,
 int byteLength,
 TruffleString.Encoding encoding,
 boolean copy)

Shorthand for calling the uncached version of TruffleString.FromByteArrayNode.

Since:

22.1

fromCharArrayUTF16Uncached

public static TruffleString fromCharArrayUTF16Uncached(char[] value)

Shorthand for calling the uncached version of TruffleString.FromCharArrayUTF16Node.

Since:

22.1

fromCharArrayUTF16Uncached

public static TruffleString fromCharArrayUTF16Uncached(char[] value,
 int charOffset,
 int charLength)

Shorthand for calling the uncached version of TruffleString.FromCharArrayUTF16Node.

Since:

22.1

fromJavaStringUncached

public static TruffleString fromJavaStringUncached(String s,
 TruffleString.Encoding encoding)

Shorthand for calling the uncached version of TruffleString.FromJavaStringNode.

For constant strings, it is recommended to use fromConstant(String, Encoding) instead.

Since:

22.1

fromJavaStringUncached

public static TruffleString fromJavaStringUncached(String s,
 int charOffset,
 int length,
 TruffleString.Encoding encoding,
 boolean copy)

Shorthand for calling the uncached version of TruffleString.FromJavaStringNode.

For constant strings, it is recommended to use fromConstant(String, Encoding) instead.

Since:

22.1

fromConstant

public static TruffleString fromConstant(String s,
 TruffleString.Encoding encoding)

Shorthand for calling the uncached version of TruffleString.FromJavaStringNode. This variant also forces the calculation of the string's precise TruffleString.CodeRange and hash code.

Since:

23.0

fromIntArrayUTF32Uncached

public static TruffleString fromIntArrayUTF32Uncached(int[] value)

Shorthand for calling the uncached version of TruffleString.FromIntArrayUTF32Node.

Since:

22.1

fromIntArrayUTF32Uncached

public static TruffleString fromIntArrayUTF32Uncached(int[] value,
 int intOffset,
 int intLength)

Shorthand for calling the uncached version of TruffleString.FromIntArrayUTF32Node.

Since:

22.1

fromNativePointerUncached

public static TruffleString fromNativePointerUncached(Object pointerObject,
 int byteOffset,
 int byteLength,
 TruffleString.Encoding encoding,
 boolean copy)

Shorthand for calling the uncached version of TruffleString.FromNativePointerNode.

Since:

22.1

asNativeUncached

public TruffleString asNativeUncached(NativeAllocator allocator,
 TruffleString.Encoding expectedEncoding,
 boolean useCompaction,
 boolean cacheResult)

Shorthand for calling the uncached version of TruffleString.AsNativeNode.

Since:

23.0