string - [mainnet]

The string module defines the String type which represents UTF8 encoded strings.

use 0x1::option;
use 0x1::vector;

Constants

Index out of range.

const EINVALID_INDEX: u64 = 2;

An invalid UTF8 encoding.

const EINVALID_UTF8: u64 = 1;

Structs

`String`

A String holds a sequence of bytes which is guaranteed to be in utf8 format.

struct String has copy, drop, store

Fields

bytes: vector<u8>

Functions

`utf8`

Creates a new string from a sequence of bytes. Aborts if the bytes do not represent valid utf8.

public fun utf8(bytes: vector<u8>): string::String

Implementation

public fun utf8(bytes: vector<u8>): String {
    assert!(internal_check_utf8(&bytes), EINVALID_UTF8);
    String{bytes}
}

`try_utf8`

Tries to create a new string from a sequence of bytes.

public fun try_utf8(bytes: vector<u8>): option::Option<string::String>

Implementation

public fun try_utf8(bytes: vector<u8>): Option<String> {
    if (internal_check_utf8(&bytes)) {
        option::some(String{bytes})
    } else {
        option::none()
    }
}

`bytes`

Returns a reference to the underlying byte vector.

public fun bytes(self: &string::String): &vector<u8>

Implementation

public fun bytes(self: &String): &vector<u8> {
    &self.bytes
}

`is_empty`

Checks whether this string is empty.

public fun is_empty(self: &string::String): bool

Implementation

public fun is_empty(self: &String): bool {
    self.bytes.is_empty()
}

`length`

Returns the length of this string, in bytes.

public fun length(self: &string::String): u64

Implementation

public fun length(self: &String): u64 {
    self.bytes.length()
}

`append`

Appends a string.

public fun append(self: &mut string::String, r: string::String)

Implementation

public fun append(self: &mut String, r: String) {
    self.bytes.append(r.bytes)
}

`append_utf8`

Appends bytes which must be in valid utf8 format.

public fun append_utf8(self: &mut string::String, bytes: vector<u8>)

Implementation

public fun append_utf8(self: &mut String, bytes: vector<u8>) {
    self.append(utf8(bytes))
}

`insert`

Insert the other string at the byte index in given string. The index must be at a valid utf8 char boundary.

public fun insert(self: &mut string::String, at: u64, o: string::String)

Implementation

public fun insert(self: &mut String, at: u64, o: String) {
    let bytes = &self.bytes;
    assert!(at <= bytes.length() && internal_is_char_boundary(bytes, at), EINVALID_INDEX);
    let l = self.length();
    let front = self.sub_string(0, at);
    let end = self.sub_string(at, l);
    front.append(o);
    front.append(end);
    *self = front;
}

`sub_string`

Returns a sub-string using the given byte indices, where i is the first byte position and j is the start of the first byte not included (or the length of the string). The indices must be at valid utf8 char boundaries, guaranteeing that the result is valid utf8.

public fun sub_string(self: &string::String, i: u64, j: u64): string::String

Implementation

public fun sub_string(self: &String, i: u64, j: u64): String {
    let bytes = &self.bytes;
    let l = bytes.length();
    assert!(
        j <= l && i <= j && internal_is_char_boundary(bytes, i) && internal_is_char_boundary(bytes, j),
        EINVALID_INDEX
    );
    String { bytes: internal_sub_string(bytes, i, j) }
}

`index_of`

Computes the index of the first occurrence of a string. Returns length(s) if no occurrence found.

public fun index_of(self: &string::String, r: &string::String): u64

Implementation

public fun index_of(self: &String, r: &String): u64 {
    internal_index_of(&self.bytes, &r.bytes)
}

`internal_check_utf8`

public fun internal_check_utf8(v: &vector<u8>): bool

Implementation

public native fun internal_check_utf8(v: &vector<u8>): bool;

`internal_is_char_boundary`

fun internal_is_char_boundary(v: &vector<u8>, i: u64): bool

Implementation

native fun internal_is_char_boundary(v: &vector<u8>, i: u64): bool;

`internal_sub_string`

fun internal_sub_string(v: &vector<u8>, i: u64, j: u64): vector<u8>

Implementation

native fun internal_sub_string(v: &vector<u8>, i: u64, j: u64): vector<u8>;

`internal_index_of`

fun internal_index_of(v: &vector<u8>, r: &vector<u8>): u64

Implementation

native fun internal_index_of(v: &vector<u8>, r: &vector<u8>): u64;

Specification

`internal_check_utf8`

public fun internal_check_utf8(v: &vector<u8>): bool

pragma opaque;
aborts_if [abstract] false;
ensures [abstract] result == spec_internal_check_utf8(v);

`internal_is_char_boundary`

fun internal_is_char_boundary(v: &vector<u8>, i: u64): bool

pragma opaque;
aborts_if [abstract] false;
ensures [abstract] result == spec_internal_is_char_boundary(v, i);

`internal_sub_string`

fun internal_sub_string(v: &vector<u8>, i: u64, j: u64): vector<u8>

pragma opaque;
aborts_if [abstract] false;
ensures [abstract] result == spec_internal_sub_string(v, i, j);

`internal_index_of`

fun internal_index_of(v: &vector<u8>, r: &vector<u8>): u64

pragma opaque;
aborts_if [abstract] false;
ensures [abstract] result == spec_internal_index_of(v, r);

fun spec_utf8(bytes: vector<u8>): String {
   String{bytes}
}

fun spec_internal_check_utf8(v: vector<u8>): bool;

fun spec_internal_is_char_boundary(v: vector<u8>, i: u64): bool;

fun spec_internal_sub_string(v: vector<u8>, i: u64, j: u64): vector<u8>;

fun spec_internal_index_of(v: vector<u8>, r: vector<u8>): u64;