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 and 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 class	TruffleString.CodePointSet A set of codepoints in a given encoding.
static class	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 class	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 class	TruffleString.Encoding The list of encodings supported by TruffleString.
static class	TruffleString.EqualNode Node to check two strings for equality.
static class	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 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 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.WithMask Extended parameter type for the operations TruffleString.ByteIndexOfStringNode, TruffleString.LastByteIndexOfStringNode and TruffleString.RegionEqualByteIndexNode.

Method Summary

Modifier and Type	Method and 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, copyToByteArrayUncached, copyToByteArrayUncached, copyToNativeMemoryUncached, createBackwardCodePointIteratorUncached, createCodePointIteratorUncached, equals, equalsUncached, forceEncodingUncached, getByteCodeRangeUncached, getCodeRangeImpreciseUncached, getCodeRangeUncached, getInternalByteArrayUncached, getInternalNativePointerUncached, getStringCompactionLevelUncached, hashCode, hashCodeUncached, indexOfCodePointUncached, indexOfStringUncached, intIndexOfAnyIntUTF32Uncached, 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

Methods inherited from class java.lang.Object

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

Method Detail

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 TruffleString.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 TruffleString.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