Struct std::bytes::Bytes

pub struct Bytes {
    /// A barebones struct for the bytes.
    buf: RawBytes,
    /// The number of bytes being stored.
    len: u64,
}
Expand description

A type used to represent raw bytes. It has ownership over its buffer.

Fields

buf: RawBytes

A barebones struct for the bytes.

len: u64

The number of bytes being stored.

Implementations

pub fn new() -> Self

Constructs a new, empty Bytes.

Additional Information

The struct will not allocate until elements are pushed onto it.

Returns

  • [Bytes] - A new, empty Bytes.

Examples

use std::bytes::Bytes;

fn foo() {
    let bytes = Bytes::new();
    assert(bytes.len() == 0);
    assert(bytes.capacity() == 0);
}

pub fn with_capacity(capacity: u64) -> Self

Constructs a new, empty Bytes with the specified capacity.

Additional Information

The Bytes will be able to hold exactly capacity bytes without
reallocating. If capacity is zero, the Bytes will not allocate.

It is important to note that although the returned Bytes has the
capacity specified, the type will have a zero length.

Arguments

  • capacity: [u64] - The capacity with which to initialize the Bytes.

Returns

  • [Bytes] - A new, empty Bytes with the specified capacity.

Examples

use std::bytes::Bytes;

fn foo() {
    let mut bytes = Bytes::with_capacity(2);
    // does not allocate
    bytes.push(5);
    // does not re-allocate
    bytes.push(10);
}

pub fn from_moved_raw_slice(slice: raw_slice) -> Self

Constructs a new Bytes that takes the ownership of the slice.

Additional Information

slice must point to a heap-allocated memory.
slice, or its owner, like, e.g., Vec, must not be used
after the ownership is transferred to the newly created Bytes.

Violating the above restrictions results in an undefined behavior.

To create a new Bytes from a raw_slice that copies the slice content
and does not take the ownership, use Bytes::from(raw_slice).

Arguments

  • slice: [raw_slice] - The heap-allocated slice whose ownership is transferred to the Bytes.

Returns

  • [Bytes] - A new Bytes whose content is the original content of the slice.

Examples

use std::bytes::Bytes;
use std::vec::Vec;

fn foo() {
    let mut source = Vec::<u8>::new();
    source.push(1u8);

    let bytes = Bytes::from_moved_raw_slice(source.as_raw_slice());

    // ** `source` must not be used after this point. **

    assert_eq(bytes.get(0).unwrap(), 1u8);
}

pub fn push(refmut self, byte: u8)

Appends an element to the back of a Bytes collection.

Arguments

  • byte: [u8] - The element to be pushed onto the Bytes.

Examples

use std::bytes::Bytes;

fn foo() {
    let mut bytes = Bytes::new();
    let a = 5u8;
    let b = 7u8;
    bytes.push(a);
    bytes.push(b);
    assert(bytes.len() == 2);
}

pub fn pop(refmut self) -> Option<u8>

Removes the last element from a Bytes and returns it, or None if it
is empty.

Returns

  • [Option] - The last element of the Bytes, or None if it is empty.

Examples

use std::bytes::Bytes;

fn foo() {
    let mut bytes = Bytes::new();

    let res = bytes.pop();
    assert(res.is_none());

    bytes.push(5);
    let res = bytes.pop();
    assert(res.unwrap() == 5);
    assert(bytes.is_empty());
}

pub fn get(self, index: u64) -> Option<u8>

Returns Some(byte) at index, or None if index is out of
bounds.

Arguments

  • index: [u64] - The index of the element to be returned.

Returns

  • [Option] - The element at the specified index, or None if the index is out of bounds.

Examples

use std::bytes::Byte;

fn foo() {
    let mut bytes = Bytes::new();
    bytes.push(5u8);
    bytes.push(10u8);
    bytes.push(15u8);
    let item = bytes.get(1).unwrap();
    assert(item == 10u8);
    let opt = bytes.get(10);
    assert(opt.is_none()); // index out of bounds
}

fn get_unchecked(self, index: u64) -> u8

Fetches the element stored at index without bounds checking.

pub fn set(
refmut self,
index: u64,
value: u8,
)

Updates an element at position index with a new element value.

Arguments

  • index: [u64] - The index of the element to be set.
  • value: [u8] - The value of the element to be set.

Reverts

  • When index is greater than or equal to the length of Bytes.

Examples

use std::bytes::Bytes;

fn foo() {
    let mut bytes = Bytes::new();
    let a = 5u8;
    let b = 7u8;
    let c = 9u8;
    bytes.push(a);
    bytes.push(b);
    bytes.push(c);

    let d = 11u8;

    bytes.set(1, d);

    assert(bytes.len() == 3);
    assert(bytes.get(0).unwrap() == a);
    assert(bytes.get(1).unwrap() == d);
    assert(bytes.get(2).unwrap() == c);
}

pub fn insert(
refmut self,
index: u64,
element: u8,
)

Inserts an element at position index within the Bytes, shifting all
elements after it to the right.

Arguments

  • index: [u64] - The index at which to insert the element.
  • element: [u8] - The element to be inserted.

Reverts

  • When index > len.

Examples

use std::bytes::Byte;

fn foo() {
    let mut bytes = Bytes::new();
    let a = 11u8;
    let b = 11u8;
    let c = 11u8;
    let d = 11u8;
    bytes.push(a);
    bytes.push(b);
    bytes.push(c);
    bytes.insert(1, d);

    assert(bytes.get(0).unwrap() == a);
    assert(bytes.get(1).unwrap() == d);
    assert(bytes.get(2).unwrap() == b);
    assert(bytes.get(3).unwrap() == c);
}

pub fn remove(refmut self, index: u64) -> u8

Removes and returns the element at position index within the Bytes,
shifting all elements after it to the left.

Arguments

  • index: [u64] - The index of the element to be removed.

Returns

  • [u8] - The element at the specified index.

Reverts

  • When index >= self.len.

Examples

use std::bytes::Byte;

fn foo() {
    let mut bytes = Byte::new();
    bytes.push(5);
    bytes.push(10);
    bytes.push(15);
    let item = bytes.remove(1);
    assert(item == 10);
    assert(bytes.get(0).unwrap() == 5);
    assert(bytes.get(1).unwrap() == 15);
    assert(bytes.get(2).is_none());
}

pub fn swap(
refmut self,
element1_index: u64,
element2_index: u64,
)

Swaps two elements.

Arguments

  • element1_index: [u64] - The index of the first element.
  • element2_index: [u64] - The index of the second element.

Reverts

  • When element1_index or element2_index is greater than or equal to the length of Bytes.

Examples

use std::bytes::Bytes;

fn foo() {
    let mut bytes = Bytes::new();
    let a = 5u8;
    let b = 7u8;
    let c = 9u8;
    bytes.push(a);
    bytes.push(b);
    bytes.push(c);

    bytes.swap(0, 1);

    assert(bytes.get(0).unwrap() == b);
    assert(bytes.get(1).unwrap() == a);
    assert(bytes.get(2).unwrap() == c);
}

pub fn capacity(self) -> u64

Gets the capacity of the allocation.

Returns

  • [u64] - The capacity of the allocation.

Examples

use std::bytes::Bytes;

fn foo() {
    let bytes = Bytes::with_capacity(5);
    let cap = bytes.capacity();
    assert(cap == 5);
}

pub fn len(self) -> u64

Gets the length of the Bytes.

Returns

  • [u64] - The length of the Bytes.

Examples

use std::bytes::Bytes;

fn foo() {
    let mut bytes = Bytes::new();
    assert(bytes.len() == 0);
    bytes.push(5);
    assert(bytes.len() == 1);
}

pub fn clear(refmut self)

Clears the Bytes, removing all values.

Note that this method has no effect on the allocated capacity
of the Bytes.

Examples

use std:bytes::Bytes;

fn foo() {
    let mut bytes = Bytes::new();
    bytes.push(5);
    bytes.clear()
    assert(bytes.is_empty());
}

pub fn is_empty(self) -> bool

Returns true if the type contains no elements.

Returns

  • [bool] - true if the type contains no elements, false otherwise.

Examples

use std:bytes::Bytes;

fn foo() {
    let mut bytes = Bytes::new();
    assert(bytes.is_empty());
    bytes.push(5);
    assert(!bytes.is_empty());
    bytes.clear()
    assert(bytes.is_empty());
}

pub fn ptr(self) -> raw_ptr

Gets the pointer of the allocation.

Returns

[raw_ptr] - The location in memory that the allocated bytes live.

Examples

use std::bytes::Bytes;

fn foo() {
    let bytes = Bytes::new();
    assert(!bytes.ptr().is_null());
}

pub fn split_at(self, mid: u64) -> (Self, Self)

Divides one Bytes into two at an index.

Additional Information

The first will contain all indices from [0, mid) (excluding the index
mid itself) and the second will contain all indices from [mid, len)
(excluding the index len itself).

Arguments

  • mid: [u64] - Index at which the Bytes is to be split.

Reverts

  • When mid > self.len.

Examples

use std:bytes::Bytes;

fn foo() {
    let mut bytes = Bytes::new();
    bytes.push(5u8);
    bytes.push(7u8);
    bytes.push(9u8);
    assert(bytes.len() == 3);
    let mid = 1;
    let (left, right) = bytes.split_at(mid);
    assert(left.capacity() == mid);
    assert(right.capacity() == bytes.len() - mid);
    assert(left.len() == 1);
    assert(right.len() == 2);
}

pub fn append(
refmut self,
refmut other: Self,
)

Appends copies of all elements of other into self.

Additional Information

NOTE: Appending self to itself will duplicate the Bytes. i.e. [0, 1, 2] => [0, 1, 2, 0, 1, 2]
This function differs from the Rust append function in that it does not clear the other Bytes.

Arguments

  • other: [Bytes] - The Bytes to append to self.

Examples


use std:bytes::Bytes;

fn foo() {
    let mut bytes = Bytes::new();
    bytes.push(5u8);
    bytes.push(7u8);
    bytes.push(9u8);
    assert(bytes.len() == 3);

    let mut bytes2 = Bytes::new();
    bytes2.push(5u8);
    bytes2.push(7u8);
    bytes2.push(9u8);
    assert(bytes2.len() == 3);

    let first_length = bytes.len();
    let second_length = bytes2.len();

    bytes.append(bytes2);

    assert(bytes.len() == first_length + second_length);
    assert(bytes2.len() == second_length);
}

pub fn append_raw_slice(
refmut self,
slice: raw_slice,
)

Appends copies of all bytes from the slice into self.

Arguments

  • slice: [raw_slice] - The raw_slice from which to append to self.

Examples


use std:bytes::Bytes;

fn foo() {
    let mut bytes = Bytes::new();
    bytes.push(5u8);
    bytes.push(7u8);
    bytes.push(9u8);

    let mut bytes2 = Bytes::new();
    bytes2.push(5u8);
    bytes2.push(7u8);
    bytes2.push(9u8);

    let first_length = bytes.len();
    let second_length = bytes2.len();

    bytes.append_raw_slice(bytes2.as_raw_slice());

    assert(bytes.len() == first_length + second_length);
}

pub fn splice(refmut self, start: u64, end: u64, replace_with: Bytes) -> Bytes

Removes and returns a range of elements from the Bytes (i.e. indices [start, end)),
then replaces that range with the contents of replace_with.

Arguments

  • start: [u64] - The starting index for the splice (inclusive).
  • end: [u64] - The ending index for the splice (exclusive).
  • replace_with: [Bytes] - The elements to insert in place of the removed range.

Returns

  • [Bytes] - A new Bytes containing all of the elements from start up to (but not including) end.

Reverts

  • When start > end.
  • When end > self.len.

Examples

use std::bytes::Bytes;

fn foo() {
    let mut bytes = Bytes::new();
    bytes.push(5u8);  // index 0
    bytes.push(7u8);  // index 1
    bytes.push(9u8);  // index 2

    // Replace the middle item (index 1) with two new items
    let mut replacement = Bytes::new();
    replacement.push(42u8);
    replacement.push(100u8);

    // Splice out range [1..2) => removes the single element 7u8,
    // then inserts [42, 100] there
    let spliced = bytes.splice(1, 2, replacement);

    // `spliced` has the element [7u8]
    assert(spliced.len() == 1);
    assert(spliced.get(0).unwrap() == 7u8);

    // `bytes` is now [5u8, 42u8, 100u8, 9u8]
    assert(bytes.len() == 4);
    assert(bytes.get(0).unwrap() == 5u8);
    assert(bytes.get(1).unwrap() == 42u8);
    assert(bytes.get(2).unwrap() == 100u8);
    assert(bytes.get(3).unwrap() == 9u8);
}

pub fn resize(
refmut self,
new_len: u64,
value: u8,
)

Resizes the Bytes in-place so that len is equal to new_len.

Additional Information

If new_len is greater than len, the Bytes is extended by the difference, with each additional slot filled with value. If new_len is less than len, the Bytes is simply truncated.

Arguments

  • new_len: [u64] - The new length of the Bytes.
  • value: [u8] - The value to fill the new length.

Examples

fn foo() {
    let bytes = Bytes::new();
    bytes.resize(1, 7u8);
    assert(bytes.len() == 1);
    assert(bytes.get(0).unwrap() == 7u8);

    bytes.resize(2, 9u8);
    assert(bytes.len() == 2);
    assert(bytes.get(0).unwrap() == 7u8);
    assert(bytes.get(1).unwrap() == 9u8);

    bytes.resize(1, 0);
    assert(bytes.len() == 1);
    assert(bytes.get(0).unwrap() == 7u8);
    assert(bytes.get(1) == None);
}

pub fn iter(self) -> BytesIter

Returns an [Iterator] to iterate over this Bytes.

Returns

  • [BytesIter] - The struct which can be iterated over.

Examples

fn foo() {
    let mut bytes = Bytes::new();
    bytes.push(5_u8);
    bytes.push(10_u8);
    bytes.push(15_u8);

    // Get the iterator
    let iter = bytes.iter();

    assert_eq(5_u8, iter.next().unwrap());
    assert_eq(10_u8, iter.next().unwrap());
    assert_eq(15_u8, iter.next().unwrap());

    for elem in bytes.iter() {
        log(elem);
    }
}

# Undefined Behavior

Modifying vector during iteration is a logical error and
results in undefined behavior. E.g.:

```sway
fn foo() {
    let mut bytes = Bytes::new();
    bytes.push(5_u8);
    bytes.push(10_u8);
    bytes.push(15_u8);

    for elem in bytes.iter() {
        bytes.push(20_u8); // Modification causes undefined behavior.
    }
}

pub fn are_all_zero(self) -> bool

Returns true if all the bytes within the Bytes are zero.

Additional Information

If Bytes is empty, this function will return true.

Examples

fn foo() {
    let bytes = Bytes::new();
    bytes.resize(10, 0u8);
    assert(bytes.are_all_zero() == true);

    bytes.resize(20, 42u8);
    assert(bytes.are_all_zero() == false);

    bytes.resize(0, 42u8);
    assert(bytes.are_all_zero() == true);
}

Trait Implementations

pub fn as_raw_slice(self) -> raw_slice

Returns a raw slice of all of the elements in the Bytes.

pub fn eq(self, other: Self) -> bool

pub fn neq(self, other: Self) -> bool

Evaluates if two values of the same type are not equal.

Additional Information

This function is inherited when eq() is implemented.

Arguments

  • other: [Self] - The value of the same type.

Returns

  • [bool] - true if the two values are not equal, otherwise false.

Examples

struct MyStruct {
    val: u64,
}

impl PartialEq for MyStruct {
    fn eq(self, other: Self) -> bool {
         self.val == other.val
    }
}

fn foo() {
    let struct1 = MyStruct { val: 10 };
    let struct2 = MyStruct { val: 2 };
    let result = struct1 != struct2;
    assert(result);
}

pub fn from(b: b256) -> Self

pub fn try_into(self) -> Option<b256>

pub fn from(slice: raw_slice) -> Self

Creates a Bytes from a raw_slice.

Additional Information

The content of the slice gets copied to a newly created Bytes
that allocates its own buffer.

To take the ownership of the slice and move it to the newly
created Bytes without copying the content, use Bytes::from_moved_raw_slice.

Examples

use std:bytes::Bytes;

let mut vec = Vec::new();
let a = 5u8;
let b = 7u8;
let c = 9u8

vec.push(a);
vec.push(b);
vec.push(c);

let vec_as_raw_slice = vec.as_raw_slice();
let bytes = Bytes::from(vec_as_raw_slice);

assert_eq(bytes.len, 3);
assert_eq(bytes.get(0).unwrap(), a);
assert_eq(bytes.get(1).unwrap(), b);
assert_eq(bytes.get(2).unwrap(), c);

pub fn from(vec: Vec<u8>) -> Self

Creates a Bytes from a Vec<u8>.

Examples

use std:bytes::Bytes;

let mut vec = Vec::new();
let a = 5u8;
let b = 7u8;
let c = 9u8

vec.push(a);
vec.push(b);
vec.push(c);

let bytes = Bytes::from(vec);

assert(bytes.len == 3);
assert(bytes.get(0).unwrap() == a);
assert(bytes.get(1).unwrap() == b);
assert(bytes.get(2).unwrap() == c);

pub fn clone(self) -> Self

pub fn abi_encode(self, buffer: Buffer) -> Buffer

pub fn is_encode_trivial() -> bool

pub fn abi_decode(refmut buffer: BufferReader) -> Bytes

pub fn is_decode_trivial() -> bool

pub fn fmt(self, refmut f: Formatter)

pub fn hash(
self,
refmut state: Hasher,
)

pub fn is_hash_trivial() -> bool

pub fn from(s: String) -> Bytes