Skip to main content

Module std::ascii

The ASCII module defines basic string and char newtypes in Move that verify that characters are valid ASCII, and that strings consist of only valid ASCII characters.

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

Struct `String`

The String struct holds a vector of bytes that all represent valid ASCII characters. Note that these ASCII characters may not all be printable. To determine if a String contains only "printable" characters you should use the all_characters_printable predicate defined in this module. 
public struct String has copy, drop, store
Fields
bytes: vector<u8>

Struct `Char`

An ASCII character. 
public struct Char has copy, drop, store
Fields
byte: u8

Constants

An invalid ASCII character was encountered when creating an ASCII string.

const EInvalidASCIICharacter: u64 = 65536;

An invalid index was encountered when creating a substring.

const EInvalidIndex: u64 = 65537;

Function `char`

Convert a byte into a Char that is checked to make sure it is valid ASCII. 
public fun char(byte: u8): std::ascii::Char
Implementation 
public fun char(byte: u8): Char {
    assert!(is_valid_char(byte), EInvalidASCIICharacter);
    Char { byte }
}

Function `string`

Convert a vector of bytes bytes into an String. Aborts if bytes contains non-ASCII characters. 
public fun string(bytes: vector<u8>): std::ascii::String
Implementation 
public fun string(bytes: vector<u8>): String {
    let x = try_string(bytes);
    assert!(x.is_some(), EInvalidASCIICharacter);
    x.destroy_some()
}

Function `try_string`

Convert a vector of bytes bytes into an String. Returns Some(<ascii_string>) if the bytes contains all valid ASCII characters. Otherwise returns None. 
public fun try_string(bytes: vector<u8>): std::option::Option<std::ascii::String>
Implementation 
public fun try_string(bytes: vector<u8>): Option<String> {
    let is_valid = bytes.all!(|byte| is_valid_char(*byte));
    if (is_valid) option::some(String { bytes }) else option::none()
}

Function `all_characters_printable`

Returns true if all characters in string are printable characters Returns false otherwise. Not all Strings are printable strings. 
public fun all_characters_printable(string: &std::ascii::String): bool
Implementation 
public fun all_characters_printable(string: &String): bool {
    string.bytes.all!(|byte| is_printable_char(*byte))
}

Function `push_char`

Push a Char to the end of the string. 
public fun push_char(string: &mut std::ascii::String, char: std::ascii::Char)
Implementation 
public fun push_char(string: &mut String, char: Char) {
    string.bytes.push_back(char.byte);
}

Function `pop_char`

Pop a Char from the end of the string. 
public fun pop_char(string: &mut std::ascii::String): std::ascii::Char
Implementation 
public fun pop_char(string: &mut String): Char {
    Char { byte: string.bytes.pop_back() }
}

Function `length`

Returns the length of the string in bytes. 
public fun length(string: &std::ascii::String): u64
Implementation 
public fun length(string: &String): u64 {
    string.as_bytes().length()
}

Function `append`

Append the other string to the end of string. 
public fun append(string: &mut std::ascii::String, other: std::ascii::String)
Implementation 
public fun append(string: &mut String, other: String) {
    string.bytes.append(other.into_bytes())
}

Function `insert`

Insert the other string at the at index of string. 
public fun insert(s: &mut std::ascii::String, at: u64, o: std::ascii::String)
Implementation 
public fun insert(s: &mut String, at: u64, o: String) {
    assert!(at <= s.length(), EInvalidIndex);
    o.into_bytes().destroy!(|e| s.bytes.insert(e, at));
}

Function `substring`

Copy the slice of the string from i to j into a new String. 
public fun substring(string: &std::ascii::String, i: u64, j: u64): std::ascii::String
Implementation 
public fun substring(string: &String, i: u64, j: u64): String {
    assert!(i <= j && j <= string.length(), EInvalidIndex);
    let mut bytes = vector[];
    i.range_do!(j, |i| bytes.push_back(string.bytes[i]));
    String { bytes }
}

Function `as_bytes`

Get the inner bytes of the string as a reference 
public fun as_bytes(string: &std::ascii::String): &vector<u8>
Implementation 
public fun as_bytes(string: &String): &vector<u8> {
    &string.bytes
}

Function `into_bytes`

Unpack the string to get its backing bytes 
public fun into_bytes(string: std::ascii::String): vector<u8>
Implementation 
public fun into_bytes(string: String): vector<u8> {
    let String { bytes } = string;
    bytes
}

Function `byte`

Unpack the char into its underlying bytes. 
public fun byte(char: std::ascii::Char): u8
Implementation 
public fun byte(char: Char): u8 {
    let Char { byte } = char;
    byte
}

Function `is_valid_char`

Returns true if b is a valid ASCII character. Returns false otherwise. 
public fun is_valid_char(b: u8): bool
Implementation 
public fun is_valid_char(b: u8): bool {
    b <= 0x7F
}

Function `is_printable_char`

Returns true if byte is a printable ASCII character. Returns false otherwise. 
public fun is_printable_char(byte: u8): bool
Implementation 
public fun is_printable_char(byte: u8): bool {
    byte >= 0x20 && // Disallow metacharacters
        byte <= 0x7E // Don't allow DEL metacharacter
}

Function `is_empty`

Returns true if string is empty. 
public fun is_empty(string: &std::ascii::String): bool
Implementation 
public fun is_empty(string: &String): bool {
    string.bytes.is_empty()
}

Function `to_uppercase`

Convert a string to its uppercase equivalent. 
public fun to_uppercase(string: &std::ascii::String): std::ascii::String
Implementation 
public fun to_uppercase(string: &String): String {
    let bytes = string.as_bytes().map_ref!(|byte| char_to_uppercase(*byte));
    String { bytes }
}

Function `to_lowercase`

Convert a string to its lowercase equivalent. 
public fun to_lowercase(string: &std::ascii::String): std::ascii::String
Implementation 
public fun to_lowercase(string: &String): String {
    let bytes = string.as_bytes().map_ref!(|byte| char_to_lowercase(*byte));
    String { bytes }
}

Function `index_of`

Computes the index of the first occurrence of the substr in the string. Returns the length of the string if the substr is not found. Returns 0 if the substr is empty. 
public fun index_of(string: &std::ascii::String, substr: &std::ascii::String): u64
Implementation 
public fun index_of(string: &String, substr: &String): u64 {
    let mut i = 0;
    let (n, m) = (string.length(), substr.length());
    if (n < m) return n;
    while (i <= n - m) {
        let mut j = 0;
        while (j < m && string.bytes[i + j] == substr.bytes[j]) j = j + 1;
        if (j == m) return i;
        i = i + 1;
    };
    n
}

Function `char_to_uppercase`

Convert a char to its lowercase equivalent. 
fun char_to_uppercase(byte: u8): u8
Implementation 
fun char_to_uppercase(byte: u8): u8 {
    if (byte >= 0x61 && byte <= 0x7A) byte - 0x20 else byte
}

Function `char_to_lowercase`

Convert a char to its lowercase equivalent. 
fun char_to_lowercase(byte: u8): u8
Implementation 
fun char_to_lowercase(byte: u8): u8 {
    if (byte >= 0x41 && byte <= 0x5A) byte + 0x20 else byte
}