Package convex.core.data

Class AString

java.lang.Object

convex.core.data.AObject

convex.core.data.ACell

convex.core.data.ACountable<CVMChar>

convex.core.data.ABlobLike<CVMChar>

convex.core.data.AString

All Implemented Interfaces:

IValidated, IWriteable, Comparable<ABlobLike<?>>

Direct Known Subclasses:

StringShort, StringSlice, StringTree

public abstract class AString
extends ABlobLike<CVMChar>

Abstract base Class representing a CVM String. CVM Strings are UTF-8 byte strings with an immutable, fixed count in bytes. CVM Strings are NOT enforced to be valid UTF-8, for reasons of performance, simplicity and consistent behaviour (e.g. in conversions to and from Blobs). It is up to clients to decide how to represent invalid UTF-8 if necessary.

Field Summary

Fields

Modifier and Type	Field	Description
protected long	length

Fields inherited from class convex.core.data.ACell

cachedRef, memorySize

Fields inherited from class convex.core.data.AObject

encoding

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AString(long length)

Method Summary

Modifier and Type	Method	Description
AString	append(AString b)	Append a CVM String to this CVM String.
AString	append(String string)	Convenience method to add a Java String to a CVM String.
abstract byte	byteAt(long i)	Gets a byte at the specified index.
final int	charAt(long i)	Gets the Unicode character at position i, or -1 if not valid
long	count()	Returns the number of elements in this value
final StringShort	empty()	Returns the singleton empty String
int	encode(byte[] bs, int pos)	Writes this Cell's encoding to a byte array, including a tag byte which will be written first.
abstract int	encodeRaw(byte[] bs, int pos)	Encode the data of this String.
final boolean	equals(ACell o)	Checks for equality with another Cell.
abstract boolean	equals(AString b)	Checks for equality between two strings.
CVMChar	get(long i)	Gets the Character at the specified point in the String, or null if there is no valid Character at this position.
int	getBytes(byte[] dest, int destOffset)	Copies the bytes from this instance to a given destination array
Ref<CVMChar>	getElementRef(long i)	Gets a Ref to the element at the specified element index in this collection
final byte	getTag()	Gets the tag byte for this cell.
AType	getType()	Gets the most specific known runtime Type for this Cell.
final int	hashCode()	Gets a Java hashCode for this CVM String.
long	hexMatch(ABlobLike<?> b, long start, long length)	Returns the number of matching hex digits in the given hex range of another Blob.
int	intAt(long index)	Gets 32 bytes integer at given position.
boolean	print(BlobBuilder sb, long limit)	Prints this Object to a readable String Representation.
protected abstract void	printEscaped(BlobBuilder sb, long start, long end)	Prints this string as escaped UTF-8
abstract AString	slice(long start, long end)	Gets a slice of this string, or null if not a valid slice
AVector<AString>	split(CVMChar c)	Splits this string by the given character The result will always have at least one String, and as many additional Strings as the split character occurs.
abstract ABlob	toBlob()	Converts this String to an equivalent Blob representation.
abstract AString	toCanonical()	Converts this Cell to a canonical version.
AString	toCVMString(long limit)	Returns the CVM String representation of this Cell.
String	toString()	Returns the Java String representation of this Cell.
abstract int	writeRawData(byte[] bs, int pos)	Write the raw UTF-8 data of this String to a byte array.

Methods inherited from class convex.core.data.ABlobLike

appendHex, byteAtUnchecked, compareTo, equalsBytes, getBytes, getHexDigit, hexEquals, hexLength, hexMatch, isDataValue, longValue, toFlatBlob, toHexString, toHexString

Methods inherited from class convex.core.data.ACountable

isEmpty, size, slice

Methods inherited from class convex.core.data.ACell

attachMemorySize, attachRef, cachedEncoding, cachedHash, calcMemorySize, createEncoding, createRef, equals, genericEquals, getCanonical, getChildRefs, getEncoding, getEncodingLength, getHash, getMemorySize, getMemorySize, getRef, getRef, getRefCount, isCanonical, isCVMValue, isEmbedded, updateRefs, validate, validateCell

Methods inherited from class convex.core.data.AObject

attachEncoding, print, print

Methods inherited from class java.lang.Object

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

Methods inherited from interface convex.core.data.IWriteable

estimatedEncodingSize

Field Details

length

protected long length

Constructor Details

AString

protected AString(long length)

Method Details

getType

public AType getType()

Description copied from class: ACell

Gets the most specific known runtime Type for this Cell.

Overrides:

getType in class ACell

Returns:

The Type of this Call

print

public boolean print(BlobBuilder sb,
 long limit)

Description copied from class: AObject

Prints this Object to a readable String Representation. SECURITY: Must halt and return false in O(1) time when limit of printing is exceeded otherwise DoS attacks may be possible.

Specified by:

print in class AObject

Parameters:

sb - BlobBuilder to append to. May be partially written if print limit exceeded

limit - Limit of printing in string bytes

Returns:

True if fully printed within limit, false otherwise

count

public long count()

Description copied from class: ACountable

Returns the number of elements in this value

Specified by:

count in class ACountable<CVMChar>

Returns:

Number of elements

printEscaped

protected abstract void printEscaped(BlobBuilder sb,
 long start,
 long end)

Prints this string as escaped UTF-8

Parameters:

sb -

empty

public final StringShort empty()

Returns the singleton empty String

Specified by:

empty in class ABlobLike<CVMChar>

Returns:

An empty Countable value, or null if there is no empty instance

charAt

public final int charAt(long i)

Gets the Unicode character at position i, or -1 if not valid

Parameters:

i - Index into String (byte position)

Returns:

Unicode code point, or -1 if not a valid code point at this position

intAt

public int intAt(long index)

Gets 32 bytes integer at given position. Extends with 255 (invalid UTF-8) if needed. The main purpose of this function is to enable fast peeking at UTF-8 characters

Parameters:

index - Index into String (byte position)

Returns:

Raw integer value

byteAt

public abstract byte byteAt(long i)

Gets a byte at the specified index. Returns -1 (0xff) if outside String.

Specified by:

byteAt in class ABlobLike<CVMChar>

Parameters:

i - Index into String (byte position)

Returns:

Raw byte value

get

public CVMChar get(long i)

Gets the Character at the specified point in the String, or null if there is no valid Character at this position.

Specified by:

get in class ACountable<CVMChar>

Parameters:

i - Index of element to get

Returns:

CVMChar instance, or null for invalid UTF-8 or any character out of the string bounds

getElementRef

public Ref<CVMChar> getElementRef(long i)

Description copied from class: ACountable

Gets a Ref to the element at the specified element index in this collection

Overrides:

getElementRef in class ABlobLike<CVMChar>

Parameters:

i - Index of element to get

Returns:

Element at the specified index

getBytes

public int getBytes(byte[] dest,
 int destOffset)

Description copied from class: ABlobLike

Copies the bytes from this instance to a given destination array

Specified by:

getBytes in class ABlobLike<CVMChar>

Parameters:

dest - Destination array

destOffset - Offset into destination array

Returns:

End position in destination array after writing

toString

public String toString()

Description copied from class: ACell

Returns the Java String representation of this Cell. The String representation is intended to be a easy-to-read textual representation of the Cell's data content.

Overrides:

toString in class ACell

hexMatch

public long hexMatch(ABlobLike<?> b,
 long start,
 long length)

Description copied from class: ABlobLike

Returns the number of matching hex digits in the given hex range of another Blob. Assumes range is valid for both blobs. Returns length if this Blob is exactly equal to the specified hex range.

Specified by:

hexMatch in class ABlobLike<CVMChar>

Parameters:

b - Blob to compare with

start - Start position (in hex digits)

length - Length to compare (in hex digits)

Returns:

The number of matching hex characters

toCVMString

public AString toCVMString(long limit)

Description copied from class: ACell

Returns the CVM String representation of this Cell. Normally, this is as printed, but may be different for some types. SHOULD return null in O(1) time if the length of the CVM String can be proved to exceed the limit. MUST complete in O(limit) time and space otherwise The String representation is intended to be a easy-to-read textual representation of the Cell's data content.

Overrides:

toCVMString in class ACell

Parameters:

limit - Limit of CVM String length in UTF-8 bytes

Returns:

CVM String, or null if limit exceeded

append

public AString append(AString b)

Append a CVM String to this CVM String. Potentially O(n). Concatenates raw UTF-8 bytes.

Parameters:

b - String to append

Returns:

Concatenated String

slice

public abstract AString slice(long start,
 long end)

Gets a slice of this string, or null if not a valid slice

Specified by:

slice in class ACountable<CVMChar>

Parameters:

start - Start index (inclusive)

end - End index (Exclusive)

Returns:

Specified substring

split

public AVector<AString> split(CVMChar c)

Splits this string by the given character The result will always have at least one String, and as many additional Strings as the split character occurs.

Parameters:

c - CMVChar instance with which to split

Returns:

Vector of Strings, excluding the split character.

encode

public int encode(byte[] bs,
 int pos)

Description copied from class: ACell

Writes this Cell's encoding to a byte array, including a tag byte which will be written first. Cell must be canonical, or else an error may occur.

Specified by:

encode in interface IWriteable

Specified by:

encode in class ACell

Parameters:

bs - A byte array to which to write the encoding

pos - The offset into the byte array

Returns:

New position after writing

encodeRaw

public abstract int encodeRaw(byte[] bs,
 int pos)

Encode the data of this String. Assumes tag already written

Specified by:

encodeRaw in class ACell

Parameters:

bs - A byte array to which to write the encoding

pos - The offset into the byte array

Returns:

New position after writing

writeRawData

public abstract int writeRawData(byte[] bs,
 int pos)

Write the raw UTF-8 data of this String to a byte array.

Parameters:

bs - Destination byte array

pos - Position in target array to write to

Returns:

End position in array after writing

getTag

public final byte getTag()

Description copied from class: ACell

Gets the tag byte for this cell. The tag byte is always equal to the first byte of the Cell's canonical Encoding, and is sufficient to distinguish how to read the rest of the encoding.

Specified by:

getTag in class ACell

Returns:

Tag byte for this Cell

hashCode

public final int hashCode()

Gets a Java hashCode for this CVM String. Use the hashcode of underlying Blob

Overrides:

hashCode in class ACell

Returns:

integer hash code.

toBlob

public abstract ABlob toBlob()

Converts this String to an equivalent Blob representation. Must round trip all values.

Specified by:

toBlob in class ABlobLike<CVMChar>

Returns:

Blob representation of UTF-8 String

append

public AString append(String string)

Convenience method to add a Java String to a CVM String. Not particularly efficient.

Parameters:

string - String to append

Returns:

CVM String

equals

public final boolean equals(ACell o)

Description copied from class: ACell

Checks for equality with another Cell. In general, Cells are considered equal if they have the same canonical representation, i.e. an identical encoding with the same hash value. Subclasses SHOULD override this if they have a more efficient equals implementation. MUST NOT require reads from Store.

Specified by:

equals in class ACell

Parameters:

o - Cell to compare with. May be null.

Returns:

True if this cell is equal to the other object

equals

public abstract boolean equals(AString b)

Checks for equality between two strings. Should be optimised

Parameters:

b - Other string (may be null)

Returns:

True if strings are exactly equal, false otherwise

toCanonical

public abstract AString toCanonical()

Description copied from class: ACell

Converts this Cell to a canonical version. Must return this Cell if already canonical, may be O(n) in size of value otherwise. Callers should usually use getCanonical(), which caches canonical instances once created

Specified by:

toCanonical in class ACell

Returns:

Canonical version of Cell