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
Click to open
Fields
bytes: vector<u8>

Struct Char​

An ASCII character.

public struct Char has copy, drop, store
Click to open
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
Click to open
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
Click to open
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>
Click to open
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 
String
s are printable strings.

public fun all_characters_printable(string: &std::ascii::String): bool
Click to open
Implementation

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)
Click to open
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
Click to open
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
Click to open
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)
Click to open
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)
Click to open
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
Click to open
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>
Click to open
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>
Click to open
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
Click to open
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
Click to open
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
Click to open
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
Click to open
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
Click to open
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
Click to open
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
Click to open
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
Click to open
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
Click to open
Implementation
fun char_to_lowercase(byte: u8): u8 {
    if (byte >= 0x41 && byte <= 0x5A) byte + 0x20 else byte
}