Package convex.core.data

Class Address

java.lang.Object

convex.core.data.AObject

convex.core.data.ACell

convex.core.data.ACountable<CVMLong>

convex.core.data.ABlobLike<CVMLong>

convex.core.data.Address

All Implemented Interfaces:

IValidated, IWriteable, Comparable<ABlobLike<?>>

public final class Address
extends ABlobLike<CVMLong>

Immutable class representing an Address, generally used to uniquely identify an Account. An Address is a specialised 8-byte long blob instance that wraps a non-negative long Account number. This number serves as an index into the vector of accounts for the current state.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	LENGTH
static final int	MAX_ENCODING_LENGTH
static final Address	MAX_VALUE	The maximum possible Address
static final Address	ZERO	The Zero Address

Fields inherited from class convex.core.data.ACell

cachedRef, memorySize

Fields inherited from class convex.core.data.AObject

encoding

Method Summary

Modifier and Type	Method	Description
final byte	byteAt(long i)	Gets the byte at the specified position.
final byte	byteAtUnchecked(long i)	Gets the byte at the specified position in this data object, possibly skipping bounds checking.
protected long	calcMemorySize()	Calculates the Memory Size for this Cell.
protected int	compareTo(long bvalue)
int	compareTo(ABlobLike<?> b)
long	count()	Returns the number of elements in this value
static Address	create(long number)	Obtains an Address.
static Address	create(ABlobLike<?> b)	Obtains an Address from a blob.
Address	empty()	Returns a canonical, singleton empty instance of the same type as this Countable value.
int	encode(byte[] bs, int pos)	Writes this Cell's encoding to a byte array, including a tag byte which will be written first.
int	encodeRaw(byte[] bs, int pos)	Writes this Cell's encoding to a byte array, excluding the tag byte.
boolean	equals(ACell o)	Checks for equality with another Cell.
final boolean	equals(Address o)
boolean	equals(Object a)
boolean	equalsBytes(ABlob b)	Compare the byte content of this BlobLike to a Blob value
int	estimatedEncodingSize()	Estimate the encoded data size for this Cell.
static Address	fromHex(String hexString)	Obtains an Address from a hex string
CVMLong	get(long i)	Gets the element at the specified element index in this value
final int	getBytes(byte[] bs, int pos)	Copies the bytes from this instance to a given destination array
<R extends ACell> Ref<R>	getRef(int i)	Gets a numbered child Ref from within this Cell.
int	getRefCount()	Gets the number of Refs contained within this Cell.
byte	getTag()	Gets the tag byte for this cell.
AType	getType()	Gets the most specific known runtime Type for this Cell.
int	hashCode()	Gets the Java hashCode for this cell.
long	hexMatch(ABlobLike<?> b, long start, long length)	Returns the number of matching hex digits in the given hex range of another Blob.
boolean	isCanonical()	Returns true if this Cell is in a canonical representation.
boolean	isCVMValue()	Returns true if this cell is a first class CVM Value allowable in the CVM state Sub-structural cells that are not themselves first class values should return false Records and types that are not permissible on the CVM should return false.
long	longValue()	Converts this BlobLike to the corresponding long value.
Address	offset(long offset)	Creates a new Address at an offset to this Address
static Address	parse(Object o)	Attempts to parse an address from an arbitrary object.
static Address	parse(String s)	Obtains an Address from an arbitrary String, attempting to parse possible formats '123' '0xc3' or '#123'
boolean	print(BlobBuilder sb, long limit)	Prints this Object to a readable String Representation.
static Address	read(Blob b, int pos)
Blob	slice(long start, long end)	Gets a slice of this data structure
ABlob	toBlob()	Convert this BlobLike object to an ABlob instance, in the most efficient way.
Address	toCanonical()	Converts this Cell to a canonical version.
AString	toCVMString(long limit)	Returns the CVM String representation of this Cell.
Blob	toFlatBlob()	Converts the contents of this value to a flat array-backed Blob instance.
String	toString()	Returns the Java String representation of this Cell.
static Address	unsafeCreate(long number)	Creates an Address without checking.
ACell	updateRefs(IRefFunction func)	Updates all Refs in this object using the given function.
void	validateCell()	Validates the local structure and invariants of this cell.

Methods inherited from class convex.core.data.ABlobLike

appendHex, getBytes, getElementRef, getHexDigit, hexEquals, hexLength, hexMatch, isDataValue, 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, createEncoding, createRef, genericEquals, getCanonical, getChildRefs, getEncoding, getEncodingLength, getHash, getMemorySize, getMemorySize, getRef, isEmbedded, validate

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

Field Details

LENGTH

public static final int LENGTH

See Also:

• Constant Field Values

ZERO

public static final Address ZERO

The Zero Address

MAX_VALUE

public static final Address MAX_VALUE

The maximum possible Address

MAX_ENCODING_LENGTH

public static final int MAX_ENCODING_LENGTH

See Also:

• Constant Field Values

Method Details

create

public static Address create(long number)

Obtains an Address. Number must be a valid non-negative long value.

Parameters:

number - Account number

Returns:

Address instance, or null if not valid

unsafeCreate

public static Address unsafeCreate(long number)

Creates an Address without checking.

Parameters:

number - Account number

Returns:

Address instance, may be invalid

create

public static Address create(ABlobLike<?> b)

Obtains an Address from a blob. Must be a valid long value

Parameters:

b - Blob to convert to an Address

Returns:

Address instance, or null if not valid

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

hashCode

public int hashCode()

Description copied from class: ACell

Gets the Java hashCode for this cell. Must be consistent with equals. Default is the hashCode of the Encoding blob, since this is consistent with encoding-based equality. However, different Types may provide more efficient hashcodes provided that the usual invariants are preserved

Overrides:

hashCode in class ACell

Returns:

integer hash code.

equals

public boolean equals(Object a)

Overrides:

equals in class ACell

equals

public 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 final boolean equals(Address o)

fromHex

public static Address fromHex(String hexString)

Obtains an Address from a hex string

Parameters:

hexString - String to read Address from

Returns:

An Address constructed from the hex string, or null if not a valid hex string

parse

public static Address parse(String s)

Obtains an Address from an arbitrary String, attempting to parse possible formats '123' '0xc3' or '#123'

Parameters:

s - String to parse

Returns:

Address parsed, or null if not valid

parse

public static Address parse(Object o)

Attempts to parse an address from an arbitrary object. Accepts strings and numbers on a best efforts basis.

Parameters:

o - Object to parse as an Address

Returns:

Address parsed, or null if not valid

read

public static Address read(Blob b,
 int pos)
                    throws BadFormatException

Throws:

BadFormatException

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 int encodeRaw(byte[] bs,
 int pos)

Description copied from class: ACell

Writes this Cell's encoding to a byte array, excluding the tag byte.

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

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

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

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

estimatedEncodingSize

public int estimatedEncodingSize()

Description copied from interface: IWriteable

Estimate the encoded data size for this Cell. Used for quickly sizing buffers. Implementations should try to return a size that is highly likely to contain the entire object when encoded, including the tag byte. Should not traverse soft Refs, i.e. must be usable on arbitrary partial data structures

Returns:

The estimated size for the binary representation of this object.

validateCell

public void validateCell()
                  throws InvalidDataException

Description copied from class: ACell

Validates the local structure and invariants of this cell. Called by validate() super implementation. Should validate directly contained data, but should not validate all other structure of this cell. In particular, should not traverse potentially missing child Refs.

Specified by:

validateCell in class ACell

Throws:

InvalidDataException - If the Cell is invalid

slice

public Blob slice(long start,
 long end)

Description copied from class: ACountable

Gets a slice of this data structure

Specified by:

slice in class ACountable<CVMLong>

Parameters:

start - Start index (inclusive)

end - end index (exclusive)

Returns:

Slice of data structure, or null if invalid slice

toFlatBlob

public Blob toFlatBlob()

Description copied from class: ABlobLike

Converts the contents of this value to a flat array-backed Blob instance. Warning: might be O(n) in size of Blob, may not be canonical etc.

Overrides:

toFlatBlob in class ABlobLike<CVMLong>

Returns:

A Blob instance containing the same data as this value. Might be `this` if already a flat Blob.

getTag

public 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

toCanonical

public Address 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

offset

public Address offset(long offset)

Creates a new Address at an offset to this Address

Parameters:

offset - Offset to add to this Address (may be negative)

Returns:

New Address, or null if would be invalid

byteAt

public final byte byteAt(long i)

Description copied from class: ABlobLike

Gets the byte at the specified position. Result is undefined if out of range.

Specified by:

byteAt in class ABlobLike<CVMLong>

Parameters:

i - Index of the byte to get

Returns:

The byte at the specified position

byteAtUnchecked

public final byte byteAtUnchecked(long i)

Description copied from class: ABlobLike

Gets the byte at the specified position in this data object, possibly skipping bounds checking. Only safe if index is known to be in bounds, otherwise result is undefined.

Overrides:

byteAtUnchecked in class ABlobLike<CVMLong>

Parameters:

i - Index of the byte to get

Returns:

The byte at the specified position

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<CVMLong>

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

empty

public Address empty()

Description copied from class: ACountable

Returns a canonical, singleton empty instance of the same type as this Countable value.

Specified by:

empty in class ABlobLike<CVMLong>

Returns:

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

getBytes

public final int getBytes(byte[] bs,
 int pos)

Description copied from class: ABlobLike

Copies the bytes from this instance to a given destination array

Specified by:

getBytes in class ABlobLike<CVMLong>

Parameters:

bs - Destination array

pos - Offset into destination array

Returns:

End position in destination array after writing

longValue

public long longValue()

Description copied from class: ABlobLike

Converts this BlobLike to the corresponding long value. Assumes big-endian format, as if the entire blob is interpreted as an unsigned big integer. Higher bytes outside the Long range will be ignored, i.e. the lowest 64 bits are taken

Specified by:

longValue in class ABlobLike<CVMLong>

Returns:

long value of this blob

toBlob

public ABlob toBlob()

Description copied from class: ABlobLike

Convert this BlobLike object to an ABlob instance, in the most efficient way. May return `this`.

Specified by:

toBlob in class ABlobLike<CVMLong>

Returns:

Blob instance

equalsBytes

public boolean equalsBytes(ABlob b)

Description copied from class: ABlobLike

Compare the byte content of this BlobLike to a Blob value

Specified by:

equalsBytes in class ABlobLike<CVMLong>

Parameters:

b - Blob value to compare with

Returns:

`true` if byte contents are exactly equal, `false` otherwise

compareTo

public int compareTo(ABlobLike<?> b)

Specified by:

compareTo in interface Comparable<ABlobLike<?>>

Specified by:

compareTo in class ABlobLike<CVMLong>

compareTo

protected int compareTo(long bvalue)

count

public long count()

Description copied from class: ACountable

Returns the number of elements in this value

Specified by:

count in class ACountable<CVMLong>

Returns:

Number of elements

get

public CVMLong get(long i)

Description copied from class: ACountable

Gets the element at the specified element index in this value

Specified by:

get in class ACountable<CVMLong>

Parameters:

i - Index of element to get

Returns:

Element at the specified index

isCanonical

public boolean isCanonical()

Description copied from class: ACell

Returns true if this Cell is in a canonical representation. Non-canonical objects may be used on a temporary internal basis, they should be converted to canonical representations for general purpose use.

Specified by:

isCanonical in class ACell

Returns:

true if the object is in canonical format, false otherwise

calcMemorySize

protected long calcMemorySize()

Description copied from class: ACell

Calculates the Memory Size for this Cell. Assumes not already calculated Requires any child Refs to be either direct or of persisted in store at minimum, or you might get a MissingDataException

Overrides:

calcMemorySize in class ACell

Returns:

Memory Size of this Cell

isCVMValue

public boolean isCVMValue()

Description copied from class: ACell

Returns true if this cell is a first class CVM Value allowable in the CVM state Sub-structural cells that are not themselves first class values should return false Records and types that are not permissible on the CVM should return false. Pretty much everything else should return true. Note: CVM values might not be in a canonical format, e.g. temporary data structures

Specified by:

isCVMValue in class ACell

Returns:

true if the object is a CVM Value, false otherwise

getRef

public <R extends ACell> Ref<R> getRef(int i)

Description copied from class: ACell

Gets a numbered child Ref from within this Cell. WARNING: May need to convert to a canonical instance

Overrides:

getRef in class ACell

Type Parameters:

R - Type of referenced Cell

Parameters:

i - Index of ref to get

Returns:

The Ref at the specified index

updateRefs

public ACell updateRefs(IRefFunction func)

Description copied from class: ACell

Updates all Refs in this object using the given function. The function *must not* change the hash value of Refs, in order to ensure structural integrity of modified data structures. The implementation *should* re-attach any original encoding in order to prevent re-encoding or surplus hashing This is a building block for a very sneaky trick that enables use to do a lot of efficient operations on large trees of smart references. Must return the same object if no Refs are altered.

Overrides:

updateRefs in class ACell

Parameters:

func - Ref update function

Returns:

Cell with updated Refs

getRefCount

public int getRefCount()

Description copied from class: ACell

Gets the number of Refs contained within this Cell. This number is final / immutable for any given instance and is defined by the Cell encoding rules. Contained Refs may be either external or embedded.

Overrides:

getRefCount in class ACell

Returns:

The number of Refs in this Cell