Package com.oracle.truffle.api.strings
Class TruffleString
java.lang.Object
com.oracle.truffle.api.strings.AbstractTruffleString
com.oracle.truffle.api.strings.TruffleString
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
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 ClassesModifier and TypeClassDescriptionstatic class
Node to get the givenAbstractTruffleString
as a managedTruffleString
, meaning that the resulting string's backing memory is not a native pointer.static class
static class
Node to get the givenAbstractTruffleString
as aTruffleString
.static class
Node to find the index of the first occurrence of any byte from a given array.static class
TruffleString.IndexOfCodePointNode
, but with byte indices.static class
Node to find the byte index of the first occurrence of a codepoint present in a given codepoint set.static class
TruffleString.IndexOfStringNode
, but with byte indices.static class
Node to convert a given byte index to a codepoint index.static class
Node to get the number of bytes occupied by the codepoint starting at a given byte index.static class
Node to find the index of the first occurrence of anychar
from a given array.static class
Node to read a codepoint at a given byte index.static class
Node to read a codepoint at a given codepoint index.static class
Node to convert a given codepoint index to a byte index.static class
Node to get the number of codepoints in a string.static final class
A set of codepoints in a given encoding.static enum
Provides information about a string's content.static class
Node to check if a string's code range is equal to the givenTruffleString.CodeRange
.static enum
Represents a string's compaction level, i.e.static class
Node to compare two strings byte-by-byte.static class
Node to compare two UTF-16 strings.static class
Node to compare two UTF-32 strings.static class
Node to concatenate two strings.static class
Node to copy a region of a string into a byte array.static class
Node to copy a region of a string into native memory.static class
Node to create aTruffleStringIterator
.static class
Node to create aTruffleStringIterator
.static enum
The list of encodings supported byTruffleString
.static class
Node to check two strings for equality.static enum
Error handling instructions for operations that return integer values, such as indices or code points.static class
Node to forcibly assign any encoding to a string.static class
Node to create a newTruffleString
from a byte array.static class
Node to create a new UTF-16TruffleString
from a char array.static class
Node to create a newTruffleString
from a single codepoint.static class
Node to create a new UTF-32TruffleString
from an int-array.static class
Node to create a newTruffleString
from a Java string.static class
Node to create a newTruffleString
from along
value.static class
Node to create a newTruffleString
from an interop object representing a native pointer.static class
Node to get a string's "byte-based"TruffleString.CodeRange
.static class
Node to get a string's possibly impreciseTruffleString.CodeRange
.static class
Node to get a string's preciseTruffleString.CodeRange
.static class
Node to get a string's internal byte array.static class
Node to get anative
string's pointer object.static class
Node to get a string'sTruffleString.CompactionLevel
.static class
Node to get a string's hash code.static final class
static class
Node to find the index of the first occurrence of a given code point.static class
Node to find the index of the first occurrence of a given string.static class
Node to find the index of the first occurrence of anyint
from a given array.static class
Node to check if a string is encoded correctly.static class
TruffleString.LastIndexOfCodePointNode
, but with byte indices.static class
TruffleString.LastIndexOfStringNode
, but with byte indices.static class
Node to find the codepoint index of the last occurrence of a given code point.static class
Node to find the index of the last occurrence of a given string.static class
Node to force materialization of any lazy internal data.static final class
This exception may be thrown byTruffleString.ParseIntNode
,TruffleString.ParseLongNode
orTruffleString.ParseDoubleNode
to indicate that the given string cannot be parsed as an integer, long or double value.static class
Node to parse a given string as a double value.static class
Node to parse a given string as an int value.static class
Node to parse a given string as a long value.static class
Node to read a single byte from a string.static class
Node to read a single char from a UTF-16 string.static class
Node to check for a region match, byte-by-byte.static class
Node to check codepoint equality of two string regions.static class
Node to repeat a given stringN
times.static class
TruffleString.SubstringNode
, but with byte indices.static class
Node to create a substring of a given string.static class
Node to get a given string in a specific encoding.static class
Node to get aString
representation of aTruffleString
.static class
Node to replace all invalid bytes in a given string, such that the resulting string isvalid
.static final class
Extended parameter type for the operationsTruffleString.ByteIndexOfStringNode
,TruffleString.LastByteIndexOfStringNode
andTruffleString.RegionEqualByteIndexNode
. -
Method Summary
Modifier and TypeMethodDescriptionasNativeUncached
(NativeAllocator allocator, TruffleString.Encoding expectedEncoding, boolean useCompaction, boolean cacheResult) Shorthand for calling the uncached version ofTruffleString.AsNativeNode
.static TruffleString
fromByteArrayUncached
(byte[] value, int byteOffset, int byteLength, TruffleString.Encoding encoding, boolean copy) Shorthand for calling the uncached version ofTruffleString.FromByteArrayNode
.static TruffleString
fromByteArrayUncached
(byte[] value, TruffleString.Encoding encoding) Shorthand for calling the uncached version ofTruffleString.FromByteArrayNode
.static TruffleString
fromByteArrayUncached
(byte[] value, TruffleString.Encoding encoding, boolean copy) Shorthand for calling the uncached version ofTruffleString.FromByteArrayNode
.static TruffleString
fromCharArrayUTF16Uncached
(char[] value) Shorthand for calling the uncached version ofTruffleString.FromCharArrayUTF16Node
.static TruffleString
fromCharArrayUTF16Uncached
(char[] value, int charOffset, int charLength) Shorthand for calling the uncached version ofTruffleString.FromCharArrayUTF16Node
.static TruffleString
fromCodePointUncached
(int codepoint, TruffleString.Encoding encoding) Shorthand for calling the uncached version ofTruffleString.FromCodePointNode
.static TruffleString
fromCodePointUncached
(int codepoint, TruffleString.Encoding encoding, boolean allowUTF16Surrogates) Shorthand for calling the uncached version ofTruffleString.FromCodePointNode
.static TruffleString
fromConstant
(String s, TruffleString.Encoding encoding) Shorthand for calling the uncached version ofTruffleString.FromJavaStringNode
.static TruffleString
fromIntArrayUTF32Uncached
(int[] value) Shorthand for calling the uncached version ofTruffleString.FromIntArrayUTF32Node
.static TruffleString
fromIntArrayUTF32Uncached
(int[] value, int intOffset, int intLength) Shorthand for calling the uncached version ofTruffleString.FromIntArrayUTF32Node
.static TruffleString
fromJavaStringUncached
(String s, int charOffset, int length, TruffleString.Encoding encoding, boolean copy) Shorthand for calling the uncached version ofTruffleString.FromJavaStringNode
.static TruffleString
fromJavaStringUncached
(String s, TruffleString.Encoding encoding) Shorthand for calling the uncached version ofTruffleString.FromJavaStringNode
.static TruffleString
fromLongUncached
(long value, TruffleString.Encoding encoding, boolean lazy) Shorthand for calling the uncached version ofTruffleString.FromLongNode
.static TruffleString
fromNativePointerUncached
(Object pointerObject, int byteOffset, int byteLength, TruffleString.Encoding encoding, boolean copy) Shorthand for calling the uncached version ofTruffleString.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
-
Method Details
-
fromCodePointUncached
Shorthand for calling the uncached version ofTruffleString.FromCodePointNode
.- Since:
- 22.1
-
fromCodePointUncached
public static TruffleString fromCodePointUncached(int codepoint, TruffleString.Encoding encoding, boolean allowUTF16Surrogates) Shorthand for calling the uncached version ofTruffleString.FromCodePointNode
.- Since:
- 22.2
-
fromLongUncached
public static TruffleString fromLongUncached(long value, TruffleString.Encoding encoding, boolean lazy) Shorthand for calling the uncached version ofTruffleString.FromLongNode
.- Since:
- 22.1
-
fromByteArrayUncached
Shorthand for calling the uncached version ofTruffleString.FromByteArrayNode
.- Since:
- 22.1
-
fromByteArrayUncached
public static TruffleString fromByteArrayUncached(byte[] value, TruffleString.Encoding encoding, boolean copy) Shorthand for calling the uncached version ofTruffleString.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 ofTruffleString.FromByteArrayNode
.- Since:
- 22.1
-
fromCharArrayUTF16Uncached
Shorthand for calling the uncached version ofTruffleString.FromCharArrayUTF16Node
.- Since:
- 22.1
-
fromCharArrayUTF16Uncached
public static TruffleString fromCharArrayUTF16Uncached(char[] value, int charOffset, int charLength) Shorthand for calling the uncached version ofTruffleString.FromCharArrayUTF16Node
.- Since:
- 22.1
-
fromJavaStringUncached
Shorthand for calling the uncached version ofTruffleString.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 ofTruffleString.FromJavaStringNode
.For constant strings, it is recommended to use
fromConstant(String, Encoding)
instead.- Since:
- 22.1
-
fromConstant
Shorthand for calling the uncached version ofTruffleString.FromJavaStringNode
. This variant also forces the calculation of the string's preciseTruffleString.CodeRange
and hash code.- Since:
- 23.0
-
fromIntArrayUTF32Uncached
Shorthand for calling the uncached version ofTruffleString.FromIntArrayUTF32Node
.- Since:
- 22.1
-
fromIntArrayUTF32Uncached
Shorthand for calling the uncached version ofTruffleString.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 ofTruffleString.FromNativePointerNode
.- Since:
- 22.1
-
asNativeUncached
public TruffleString asNativeUncached(NativeAllocator allocator, TruffleString.Encoding expectedEncoding, boolean useCompaction, boolean cacheResult) Shorthand for calling the uncached version ofTruffleString.AsNativeNode
.- Since:
- 23.0
-