# 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. - [Struct `String`](#std_ascii_String) - [Struct `Char`](#std_ascii_Char) - [Constants](#@Constants_0) - [Function `char`](#std_ascii_char) - [Function `string`](#std_ascii_string) - [Function `try_string`](#std_ascii_try_string) - [Function `all_characters_printable`](#std_ascii_all_characters_printable) - [Function `push_char`](#std_ascii_push_char) - [Function `pop_char`](#std_ascii_pop_char) - [Function `length`](#std_ascii_length) - [Function `append`](#std_ascii_append) - [Function `insert`](#std_ascii_insert) - [Function `substring`](#std_ascii_substring) - [Function `as_bytes`](#std_ascii_as_bytes) - [Function `into_bytes`](#std_ascii_into_bytes) - [Function `byte`](#std_ascii_byte) - [Function `is_valid_char`](#std_ascii_is_valid_char) - [Function `is_printable_char`](#std_ascii_is_printable_char) - [Function `is_empty`](#std_ascii_is_empty) - [Function `to_uppercase`](#std_ascii_to_uppercase) - [Function `to_lowercase`](#std_ascii_to_lowercase) - [Function `index_of`](#std_ascii_index_of) - [Function `char_to_uppercase`](#std_ascii_char_to_uppercase) - [Function `char_to_lowercase`](#std_ascii_char_to_lowercase)

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

## 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
}