Output an XFL as a serialized object

Concepts

Behaviour

  • Read an XFL floating point number and optionally a field code and currency code
  • Write a serialized amount to write_ptr according to the parameters provided

Definition

int64_t float_sto (
    uint32_t write_ptr,
    uint32_t write_len,
    uint32_t cread_ptr,
    uint32_t cread_len,  
    uint32_t iread_ptr,
    uint32_t iread_len,  
    int64_t float1,
    uint32_t field_code
);

Example

#define SBUF(str) (uint32_t)(str), sizeof(str)
uint8_t amt_out[48];                                                       if (float_sto(SBUF(amt_out),
    SBUF(currency), SBUF(hook_accid), pusd_to_send, -1) < 0)
        rollback(SBUF("Peggy: Could not dump pusd amount into sto"), 1);

Parameters

Name

Type

Description

write_ptr

uint32_t

Pointer to a buffer of a suitable size to store the serialized amount field. Recommend at least 48 bytes.

write_len

uint32_t

The length of the output buffer.

cread_ptr

uint32_t

Pointer to a buffer contianing the currency code to serialize into the output. May be null.

cread_len

uint32_t

The length of the currency code. This must be 20 or 0 (null).

iread_ptr

uint32_t

Pointer to a buffer containing the issuer's Account ID to serialize into the output. May be null.

iread_len

uint32_t

The length of the issuer's Account ID. This must be either 20 or 0 (null).

float1

int64_t

An XFL floating point enclosing number to serialize.

field_code

uint32_t

The sf field code to prefix the serialized amount with. E.g. sfAmount.
If this field is 0xFFFFFFFFU (i.e. (uint32_t)(-1)) then no field code is prepended to the output, and no issuer or currency code is appended, but serialization proceeds as a floating point amount.
If this field is 0 no field code is prepended to the output, and no issuer or currency code is appended, but serialization proceeds as though the amount is an XRP native amount rather than a floating point.

📘

Hint

To output an XRP amount prepopulate the field code in the output buffer then pass the output buffer incremented to the new start and 0 as field_code

🚧

Subject to change

The exact parameters and functionality of this API is still under review and subject to change in future, however most likely these changes will be backward compatibile with the API as it is documented here.

Return Code

Type

Description

int64_t

The number of bytes written to the output buffer.

If negative, an error:
INVALID_FLOAT

  • the supplied float was not a valid XFL enclosing number

OUT_OF_BOUNDS

  • pointers/lengths specified outside of hook memory.

INVALID_ARGUMENT

  • If instructed to output as XRP or without field code then all non-write pointers and lengths should be 0 (null).

TOO_SMALL

  • The output buffer was too small to receive the serialized object.