Skip to main content

Module 0x1::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 0x1::option;

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.

struct String has copy, drop, store
Fields
bytes: vector<u8>

Struct Char​

An ASCII character.

struct Char has copy, drop, store
Fields
byte: u8

Constants​

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

const EINVALID_ASCII_CHARACTER: u64 = 65536;

Function char​

Convert a byte into a Char that is checked to make sure it is valid ASCII.

public fun char(byte: u8): ascii::Char
Implementation
public fun char(byte: u8): Char {
assert!(is_valid_char(byte), EINVALID_ASCII_CHARACTER);
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>): ascii::String
Implementation
public fun string(bytes: vector<u8>): String {
let x = try_string(bytes);
assert!(x.is_some(), EINVALID_ASCII_CHARACTER);
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>): option::Option<ascii::String>
Implementation
public fun try_string(bytes: vector<u8>): Option<String> {
let len = bytes.length();
let mut i = 0;
while (i < len) {
let possible_byte = bytes[i];
if (!is_valid_char(possible_byte)) return option::none();
i = i + 1;
};
option::some(String { bytes })
}

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: &ascii::String): bool
Implementation
public fun all_characters_printable(string: &String): bool {
let len = string.bytes.length();
let mut i = 0;
while (i < len) {
let byte = string.bytes[i];
if (!is_printable_char(byte)) return false;
i = i + 1;
};
true
}

Function push_char​

public fun push_char(string: &mut ascii::String, char: ascii::Char)
Implementation
public fun push_char(string: &mut String, char: Char) {
string.bytes.push_back(char.byte);
}

Function pop_char​

public fun pop_char(string: &mut ascii::String): ascii::Char
Implementation
public fun pop_char(string: &mut String): Char {
Char { byte: string.bytes.pop_back() }
}

Function length​

public fun length(string: &ascii::String): u64
Implementation
public fun length(string: &String): u64 {
string.as_bytes().length()
}

Function as_bytes​

Get the inner bytes of the string as a reference

public fun as_bytes(string: &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: 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 byte.

public fun byte(char: 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 an 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
}