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
bytes: vector<u8>

Struct Char

An ASCII character.

struct Char has copy, drop, store
byte: u8


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
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
public fun string(bytes: vector<u8>): String {
   let x = try_string(bytes);
   assert!(x.is_some(), EINVALID_ASCII_CHARACTER);

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

Function push_char

public fun push_char(string: &mut ascii::String, char: ascii::Char)
public fun push_char(string: &mut String, char: Char) {

Function pop_char

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

Function length

public fun length(string: &ascii::String): u64
public fun length(string: &String): u64 {

Function as_bytes

Get the inner bytes of the string as a reference

public fun as_bytes(string: &ascii::String): &vector<u8>
public fun as_bytes(string: &String): &vector<u8> {

Function into_bytes

Unpack the string to get its backing bytes

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

Function byte

Unpack the char into its underlying byte.

public fun byte(char: ascii::Char): u8
public fun byte(char: Char): u8 {
   let Char { byte } = char;

Function is_valid_char

Returns true if b is a valid ASCII character. Returns false otherwise.

public fun is_valid_char(b: u8): bool
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
public fun is_printable_char(byte: u8): bool {
   byte >= 0x20 && // Disallow metacharacters
   byte <= 0x7E // Don't allow DEL metacharacter