Text and collections — AEL documentation

AEL, the Agent Engineering Language, will have three built-in collections, and each will have a fixed capacity written in its type. Memory use will be predictable: nothing will grow behind your back, a full collection will return an explicit result, and small devices will need no heap.

Status

Planned for AEL Beta 0.0.1. AEL is not available yet.

Type	Holds	Size
`[T; N]`	Exactly `N` values of type `T`.	Fixed: always `N` values.
`Vec<T, N>`	Up to `N` values of type `T`, in order.	From zero to `N` values.
`Str<N>`	UTF-8 text of up to `N` bytes.	From zero to `N` bytes.

Capacity

The capacity N of a list or a text value will be a whole number known when you check your code. It will have to fit a u32, at most 4,294,967,295, and the largest object the target allows.
An array's length N will also be known when you check your code, and will have to fit the largest object the target allows.
A list or a text value will reserve room for its full capacity, whether or not that room is used. A Vec<Order, 100> will take room for 100 orders even when it is empty, so choose capacities that match your data.
Nothing will grow past its capacity, and nothing will be allocated when a value is added.
Lengths and counts will be u32 values.

Lists

A Vec<T, N> will start empty and hold its values in the order they were added. The standard library will provide these operations:

Operation	Returns	When it cannot
Create an empty list	An empty `Vec<T, N>` of the type its place expects.	—
Add a value at the end	`Result<(), T>`	The list is full. The error gives your value back, and the list stays unchanged.
Remove the value at an index	`Result<T, IndexError>`, with the removed value. The values after it move down one place.	The index is not less than the number of values: `IndexError::OutOfBounds`, and the list stays unchanged.
Count the values	`u32`	—

list[i] will read or write one value. The index will be checked against the number of values the list holds before the access; an index out of range, a negative one included, will stop the program. Where an index may be out of range, compare it with the count first.

Text

Str<N> will hold text as UTF-8 bytes, and it will always be valid UTF-8. Its length will be counted in bytes, not characters: "é" is two bytes.

Operation	Returns	When it cannot
Count the bytes	`u32`	—
Read one byte	`Result<u8, IndexError>`	The index is not less than the length: `IndexError::OutOfBounds`.
Append another text value	`Result<(), CapacityError>`	There is not room for all of it: `CapacityError::Full`. Nothing is appended, not even part of it.
Make text from an array of bytes	`Result<Str<N>, StringError>`	The bytes are not valid UTF-8: `StringError::InvalidUtf8`, checked over the whole input first. The text is valid but longer than `N` bytes: `StringError::Full`.

A text literal will have to fit its type. let code: Str<4> = "ABCDE"; will be refused when you check your code.
Text will have no index operator and no slices, and it will never be indexed by character. A byte read from text will be a byte, never taken for a whole character.
The escapes you can write in a text literal are listed in Syntax basics.

Arrays

[T; N] will hold exactly N values, and its length will be part of its type.

An array literal will list every value: [12, 7, 30] will be a [i64; 3] when nothing says otherwise.
[] will be an empty array, and will need a type such as [u8; 0] from its place.
scores[i] will be checked against the length before the access, like a list index.

An example

Preview syntax — may change before launch

struct Ticket {
    id: u64,
    subject: Str<120>,
    tags: Vec<Str<16>, 8>,
}

fn middle(scores: [u32; 3]) -> u32 {
    return scores[1];
}

fn example() -> u32 {
    let scores: [u32; 3] = [12, 7, 30];
    return middle(scores);
}

A Ticket will hold a subject of up to 120 bytes and up to eight tags of up to 16 bytes each, and its size will be known before the program runs.

Moving and copying

Text and lists will move: passing one to a function, assigning it or putting it into a struct or a message will move it, and the old place will not be usable until it receives a new value.
An array will copy when its values copy, such as integers and bool, and move when they move.
Nothing will be lost when an operation fails: a value that cannot be added will come back to you in the error.

Ownership describes moves and borrows in full.

Comparing

== and != will not compare text, lists or arrays. Compare their lengths and values with your own code.

Not in the preview

The preview syntax has these three collections only. Key-value maps and other collections, text slices, and indexing text by character are not part of it.