sto_emplace

Emplace a field into an existing STObject at its canonical placement

Concepts

• Serialized Objects

Behaviour

C

• Parse an STObject S (source object) pointed to by sread_ptr

• Parse an STObject F (to inject/emplace) pointed to by fread_ptr

• Write a new STObject to write_ptr which places F into S at the canonical position field_id

🚧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

• Ask for the STO object by the param sto

• Ask for the bytes representing the field to be added by the param field_bytes

• Ask for the ID of the field to be added by the param field_id

• Return the updated STO object in binary encoded ledger data format, or an error code if the operation fails.

Definition

C

C

int64_t sto_emplace (
    uint32_t write_ptr,
    uint32_t write_len,
    uint32_t sread_ptr,
    uint32_t sread_len,
    uint32_t fread_ptr,
    uint32_t fread_len,
    uint32_t field_id
);

Javascript

function sto_emplace(
    sto: ByteArray | HexString,
    field_bytes: ByteArray | HexString,
    field_id: number
  ): ErrorCode | ByteArray

Example

C

uint8_t tx_out[1024];

int64_t tx_len =
    sto_emplace(tx_out, sizeof(tx_out),
                tx_in, tx_len,
                sequence_field, 5, sfSequence);

if (tx_len <= 0)
    rollback("Emplacing failed.", 17, 1);

Javascript

const tx_out = sto_emplace(tx_in, sequence_field, sfSequence)
if (typeof tx_out === 'number')
    rollback("Emplacing failed.", 1)

Parameters

C

Name	Type	Description
write_ptr	uint32_t	The buffer to write the modified STObject to
write_len	uint32_t	The length of the output buffer
sread_ptr	uint32_t	The buffer to read the source STObject from
sread_len	uint32_t	The Length of the source object
fread_ptr	uint32_t	The buffer to read the field to be emplaced/injected from
fread_len	uint32_t	The length of the field to be emplaced/injected
field_id	uint32_t	The sf code (location) to form the emplacement. If this already exists in the source object then the existing field is overriden. If it doesn't exist it is inserted.

Javascript

Name	Type	Description
sto	ByteArray | HexString	The STO object (binary encoded ledger data) to which the field will be added.
field_bytes	ByteArray | HexString	The bytes representing the field to be added.
field_id	number	The ID of the field to be added.

Return Code

C

Type	Description
int64_t	The number of bytes written to write_ptr If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_SMALL - Output buffer must be at least as large as the source object + the injected field, even if the field is only being overriden. TOO_BIG - Field you are attempting to emplace is too large PARSE_ERROR - The supplied STObject is malformed or not an STObject.

Javascript

Type	Description
ErrorCode | ByteArray	The updated STO object in binary encoded ledger data format, or an error code if the operation fails.