starcoin-framework

Module 0x1::String

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

use 0x1::Errors;
use 0x1::Option;
use 0x1::Vector;

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

Constants

An invalid UTF8 encoding.

const EINVALID_UTF8: u64 = 1;

Index out of range.

const EINVALID_INDEX: u64 = 2;

Function 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), Errors::invalid_state(EINVALID_UTF8));
    String{bytes}
}

Function 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()
    }
}

Function bytes

Returns a reference to the underlying byte vector.

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

Function is_empty

Checks whether this string is empty.

public fun is_empty(s: &String::String): bool
Implementation 
public fun is_empty(s: &String): bool {
    Vector::is_empty(&s.bytes)
}

Function length

Returns the length of this string, in bytes.

public fun length(s: &String::String): u64
Implementation 
public fun length(s: &String): u64 {
    Vector::length(&s.bytes)
}

Function append

Appends a string.

public fun append(s: &mut String::String, r: String::String)
Implementation 
public fun append(s: &mut String, r: String) {
    Vector::append(&mut s.bytes, *&r.bytes)
}

Function append_utf8

Appends bytes which must be in valid utf8 format.

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

Function 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(s: &mut String::String, at: u64, o: String::String)
Implementation 
public fun insert(s: &mut String, at: u64, o: String) {
    let bytes = &s.bytes;
    assert!(at <= Vector::length(bytes) && internal_is_char_boundary(bytes, at), Errors::invalid_state(EINVALID_INDEX));
    let l = length(s);
    let front = sub_string(s, 0, at);
    let end = sub_string(s, at, l);
    append(&mut front, o);
    append(&mut front, end);
    *s = front;
}

Function 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(s: &String::String, i: u64, j: u64): String::String
Implementation 
public fun sub_string(s: &String, i: u64, j: u64): String {
    let bytes = &s.bytes;
    let l = Vector::length(bytes);
    assert!(
        j <= l && i <= j && internal_is_char_boundary(bytes, i) && internal_is_char_boundary(bytes, j),
        Errors::invalid_state(EINVALID_INDEX)
    );
    String{bytes: internal_sub_string(bytes, i, j)}
}

Function index_of

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

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

Function internal_check_utf8

fun internal_check_utf8(v: &vector<u8>): bool
Implementation 
native fun internal_check_utf8(v: &vector<u8>): bool;
Specification 
pragma opaque;
aborts_if [abstract] false;
ensures [abstract] result == spec_internal_check_utf8(v);

Function 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;
Specification 
pragma opaque;
aborts_if [abstract] false;
ensures [abstract] result == spec_internal_is_char_boundary(v, i);

Function 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>;
Specification 
pragma opaque;
aborts_if [abstract] false;
ensures [abstract] result == spec_internal_sub_string(v, i, j);

Function 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 
pragma opaque;
aborts_if [abstract] false;
ensures [abstract] result == spec_internal_index_of(v, r);

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;

Module Specification

fun spec_utf8(bytes: vector<u8>): String {
   String{bytes}
}
This site is open source. Improve this page.