---
title: sto_erase
description: Remove a field from an STObject
---
import { Tabs, TabItem, LinkButton, Aside } from '@astrojs/starlight/components';

### Concepts

<LinkButton href="/docs/hooks/concepts/serialized-objects">Serialized Objects</LinkButton>

### Behaviour

<Tabs>
<TabItem label="C">
* Parse an STObject pointed to by `read_ptr`
* Write a new STObject to `write_ptr` but without `field_id` if it was present in the original object.
</TabItem>

<TabItem label="JavaScript">
* It will look for the STO object (binary encoded ledger data) from which the field will be removed.
* It will look for the ID of the field to be erased.
* Returns the updated STO object in binary encoded ledger data format, or an error code if the operation fails.
</TabItem>
</Tabs>

### Definition

<Tabs>
<TabItem label="C">
```c
int64_t sto_erase (
    uint32_t write_ptr,
    uint32_t write_len,
    uint32_t read_ptr,
    uint32_t read_len,
    uint32_t field_id
);
```

<Aside type="caution" title="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`.
</Aside>
</TabItem>

<TabItem label="JavaScript">
```javascript
function sto_erase(
    sto: ByteArray | HexString,
    field_id: number
  ): ErrorCode | ByteArray
```
</TabItem>
</Tabs>



### Example

<Tabs>
<TabItem label="C">
```c
int64_t result = 
  sto_erase(tx_out, sizeof(tx_out),
            tx_in, tx_len, sfSigners);

if (tx_len <= 0)
    rollback("Erasing failed.", 15, 1);
```

<Aside type="tip" title="Emplace equivalence">
`sto_erase` is the same as `sto_emplace` with `0,0` for `field_ptr, field_len` parameters.
</Aside>
</TabItem>

<TabItem label="JavaScript">
```javascript
const tx_out = sto_erase(tx_in, sfSigners)

if (typeof tx_out === 'number')
    rollback("Erasing failed.", 1)
```
</TabItem>
</Tabs>

### Parameters

<Tabs>
<TabItem label="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              |
| read_ptr  | uint32_t | The buffer to read the source STObject from  |
| read_len  | uint32_t | The Length of the source object              |
| field_id  | uint32_t | The `sf` code (location) to erase            |


</TabItem>

<TabItem label="JavaScript">
| Name      | Type                   | Description                                                                       |
| --------- | ---------------------- | --------------------------------------------------------------------------------- |
| sto       | ByteArray \| HexString | The STO object (binary encoded ledger data) from which the field will be removed. |
| field_id | number                 | The ID of the field to be erased.                                                 |
</TabItem>
</Tabs>



### Return Code

<Tabs>
<TabItem label="C">
| Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------- |   |
| int64_t | <p>The number of bytes written to <code>write_ptr</code><br /><br />If negative, an error:<br /><code>OUT_OF_BOUNDS</code><br />- pointers/lengths specified outside of hook memory.<br /><br /><code>TOO_SMALL</code><br />- Output buffer must be at least as large as the source object.<br /><br /><code>TOO_BIG</code><br />- Field you are attempting to erase from is too large<br /><br /><code>PARSE_ERROR</code><br />- The supplied STObject is malformed or not an STObject.<br /><br /><code>DOESNT_EXIST</code><br />- The specified <code>field_id</code> isn't present in the STObject.</p> |


</TabItem>

<TabItem label="JavaScript">
| Type                   | Description                                                                                           |
| ---------------------- | ----------------------------------------------------------------------------------------------------- |
| ErrorCode \| ByteArray | The updated STO object in binary encoded ledger data format, or an error code if the operation fails. |
</TabItem>
</Tabs>

