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 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.

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.

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(bytes.len == 3);
assert(bytes.get(0).unwrap() == a);
assert(bytes.get(1).unwrap() == b);
assert(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 abi_decode(refmut buffer: BufferReader) -> Bytes

pub fn fmt(self, refmut f: Formatter)

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

pub fn from(s: String) -> Bytes