sto_subfield

Index into a xahaud serialized object and return the location and length of a subfield

Concepts

• Serialized Objects

Behaviour

C

• Parse a STObject pointed to by read_ptr

• Find the field specified by field_id

• If the field is found, and:

• 1. It is an array, then return the start and length of the array including the leadin/leadout bytes, or

• 1. It is not an array, then return the start and length of the PAYLOAD of the field (excluding the leadin bytes).

🚧Field ID encoding

The sto_ apis accept a field_id parameter encoded as follows: (type << 16U) + field Thus type 1 field 2 would be 0x10002U.

Javascript

• Parse a STObject into sto variable

• Find the field specified by field_id

Definition

C

int64_t sto_subfield (
    uint32_t read_ptr,
    uint32_t read_len,
    uint32_t field_id
);

Javascript

function sto_subfield(
    sto: ByteArray | HexString,
    field_id: number
  ): ErrorCode | bigint

Example

C

#define SUB_OFFSET(x) ((int32_t)(x >> 32))
#define SUB_LENGTH(x) ((int32_t)(x & 0xFFFFFFFFULL))
int64_t memos_lookup =
    sto_subfield(txn_ptr, txn_len, sfMemos);
if (memos_lookup < 0)
{
    // sfMemos was not found in the STObject pointed at by memo_ptr
}
else
{
    // sfMemos was found and its location is as follows:
    uint8_t* memos_ptr = SUB_OFFSET(memos_lookup) + memos_ptr;
    int64_t  memos_len = SUB_LENGTH(memos_lookup);
}

📘

hookmacro.h already contains the SUB_OFFSET and SUB_LENGTH macros.

Javascript

const SUB_OFFSET = (x) => Number(x >> 32n)
const SUB_LENGTH = (x) => Number(x & 0xFFFFFFFFn)
const memos_lookup = sto_subfield(txn, sfMemos);
if (typeof memos_lookup === 'number')
{
    // sfMemos was not found in the STObject pointed at by memo_ptr
}
else
{
    // sfMemos was found and its location is as follows:
    const memo_start = SUB_OFFSET(memos_lookup)
    const memo_len = SUB_LENGTH(memos_lookup)
    const memo = txn.slice(memo_start, memo_len)
}

Parameters

C

Name	Type	Description
read_ptr	uint32_t	Pointer to the buffer containing the STObject
read_len	uint32_t	Length of STObject
field_id	uint32_t	The sf code of the field you are searching for. To compute this manually take the serialized type and shift it into the 16 highest bits of uint32_t, then take the field and place it in the 16 lowest bits. For example: sfEmitNonce has type 5 and field 11 thus its value is 0x050BU

Javascript

Name	Type	Description
sto	ByteArray or HexString	The STO object (binary encoded ledger data) from which to extract the subfield.
field_id	number	The ID of the field to be extracted.

Return Code

C

Type

Description

int64_t

The location of the field within the specified buffer: - The high 32 bits are the offset location. - The low 32 bits are the length. If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_SMALL - Input buffer isn't large enough to possibly contain a valid STObject. DOESNT_EXIST - The searched for field isn't present in the supplied STObject. PARSE_ERROR - The supplied STObject is malformed or not an STObject.

Javascript

Type	Description
bigint / ErrorCode	The location of the field within the specified buffer: - The high 32 bits are the offset location. - The low 32 bits are the length. or an error code if the extraction fails.