Module std::string

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

• Struct String
• Constants
• Function utf8
• Function from_ascii
• Function to_ascii
• Function try_utf8
• Function as_bytes
• Function into_bytes
• Function is_empty
• Function length
• Function append
• Function append_utf8
• Function insert
• Function substring
• Function index_of
• Function internal_check_utf8
• Function internal_is_char_boundary
• Function internal_sub_string
• Function internal_index_of
• Function bytes
• Function sub_string

use std::ascii;
use std::option;
use std::vector;

Struct String

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

public struct String has copy, drop, store

Fields

bytes: vector<u8>

Constants

Index out of range.

const EInvalidIndex: u64 = 2;

An invalid UTF8 encoding.

const EInvalidUTF8: u64 = 1;

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>): std::string::String

Implementation

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

Function from_ascii

Convert an ASCII string to a UTF8 string

public fun from_ascii(s: std::ascii::String): std::string::String

Implementation

public fun from_ascii(s: ascii::String): String {
String { bytes: s.into_bytes() }
}

Function to_ascii

Convert an UTF8 string to an ASCII string. Aborts if s is not valid ASCII

public fun to_ascii(s: std::string::String): std::ascii::String

Implementation

public fun to_ascii(s: String): ascii::String {
let String { bytes } = s;
bytes.to_ascii_string()
}

Function try_utf8

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

public fun try_utf8(bytes: vector<u8>): std::option::Option<std::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 as_bytes

Returns a reference to the underlying byte vector.

public fun as_bytes(s: &std::string::String): &vector<u8>

Implementation

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

Function into_bytes

Unpack the string to get its underlying bytes.

public fun into_bytes(s: std::string::String): vector<u8>

Implementation

public fun into_bytes(s: String): vector<u8> {
let String { bytes } = s;
bytes
}

Function is_empty

Checks whether this string is empty.

public fun is_empty(s: &std::string::String): bool

Implementation

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

Function length

Returns the length of this string, in bytes.

public fun length(s: &std::string::String): u64

Implementation

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

Function append

Appends a string.

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

Implementation

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

Function append_utf8

Appends bytes which must be in valid utf8 format.

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

Implementation

public fun append_utf8(s: &mut String, bytes: vector<u8>) {
s.append(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 std::string::String, at: u64, o: std::string::String)

Implementation

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

Function substring

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 substring(s: &std::string::String, i: u64, j: u64): std::string::String

Implementation

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

Function index_of

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

public fun index_of(s: &std::string::String, r: &std::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;

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;

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

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;

Function bytes

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

Implementation

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

Function sub_string

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

Implementation

public fun sub_string(s: &String, i: u64, j: u64): String {
s.substring(i, j)
}