\[ \newcommand{\ListType}{{\text{List}}} \newcommand{\ListEmpty}{{\left[\right]}} \newcommand{\ListLength}[1]{{\ell\left(#1\right)}} \newcommand{\ListAt}[2]{{{#1}_{#2}}} \]
Home

Michael Heilmann's Arcadia Collections

This is the documentation for Michael Heilmann's Arcadia Collections. Arcadia Collections provides collections like lists, deques, and maps. Arcadia Collections is available at michaelheilmann.com/Arcadia/Ring2.

Files

You can find the sources of Arcadia Collections in my GitHub repository https://github.com/michaelheilmann/arcadia. The subdirectory of Arcadia Collections in the repository is here https://github.com/michaelheilmann/arcadia/tree/main/Runtime/Collections.

Arcadia Ring 2 supports various platforms (including but not restricted to Windows, Linux, and many more), however, we currently only officially support Windows. For instructions on how to build, test, and use Arcadia Collections, refer to README.md in the root folder of the repository.

Further References

Arcadia Ring 2 relies on Arcadia Ring 1 and Arcadia ARMS.

Documentation

Objects

ArrayList

Arcadia_ArrayList extends Arcadia_List.

An Arcadia_List implemented using arrays.

Arcadia_ArrayList_create

Arcadia_ArrayList*
Arcadia_ArrayList_create
  (
    Arcadia_Thread* thread
  ) Create an array list.

Parameters

A pointer to the Arcadia_Thread object.

Errors

Arcadia_Status_AllocationFailed
An allocation failed.

Return value

A pointer to the Arcadia_ArrayList object.

Collection

Arcadia_Collection extends Arcadia_Object.

Arcadia_Collection represents a collection of Arcadia_Value objects.

Arcadia_Collection_clear

void
Arcadia_Collection_clear
  (
    Arcadia_Thread* thread,
    Arcadia_Collection* self
  ) Clear this collection.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_Collection* self
A pointer to this collection.

Arcadia_Collection_getSize

Arcadia_SizeValue
Arcadia_Collection_getSize
  (
    Arcadia_Thread* thread,
    Arcadia_Collection* self
  ) Get the size of this collection.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_Collection* self
A pointer to this collection.

Return value

The size of this collection.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.

Arcadia_Collection_isEmpty

Arcadia_BooleanValue
Arcadia_Collection_isEmpty
  (
    Arcadia_Thread* thread,
    Arcadia_Collection* self
  ) Get if this collection is empty.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_Collection* self
A pointer to this collection.

Return value

Arcadia_BooleanValue_True if this collection is empty. Arcadia_BooleanValue_False otherwise.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.

HashMap

Arcadia_HashMap extends Arcadia_Map.

An Arcadia_Map implemented using hash tables.

Arcadia_HashMap_create

Arcadia_HashMap*
Arcadia_HashMap_create
  (
    Arcadia_Thread* thread,
    Arcadia_Value value
  ) Create a hash map.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_Value value
A void value or a hash map value.

Errors

Arcadia_Status_AllocationFailed
An allocation failed.

Return value

A pointer to the Arcadia_HashMap object.

Remarks

If value is a hash map value, then the hash map entries of that hash map are added to the hash map which is created.

HashSet

Arcadia_HashSet extends Arcadia_Set.

An Arcadia_Set implemented using hash tables.

Arcadia_HashSet_create

Arcadia_HashSet*
Arcadia_HashSet_create
  (
    Arcadia_Thread* thread
  ) Create a hash set.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.

Errors

Arcadia_Status_AllocationFailed
An allocation failed.

Return value

A pointer to the Arcadia_HashSet value.

Arcadia_List

Arcadia_List extends Arcadia_Collection.

Arcadia_List represents a list of Arcadia_Value objects.

Arcadia_List_getAt

Arcadia_Value
Arcadia_List_getAt
  (
    Arcadia_Thread* thread,
    Arcadia_List* self,
    Arcadia_SizeValue index
  ) Get the value at the specifie index in this list.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_List* self
A pointer to this list.
Arcadia_SizeValue index
The index. Must be within the bounds [0,n) where n is the size of this list.

Errors

Arcadia_Status_ArgumentValueInvalid
index is out of bounds.

Return value

The value.

Arcadia_List_insertAt

void
Arcadia_List_insertAt
  (
    Arcadia_Thread* thread,
    Arcadia_List* self,
    Arcadia_SizeValue index,
    Arcadia_Value value
  ) Insert a value at the specified position in this list. If the value is Void value, then the list is not modified.

Parameters

Arcadia_Thread* threadA pointer to the Arcadia_Thread object. Arcadia_List* self A pointer to this list. Arcadia_SizeValue index The index at which to insert the value. Must be within the bounds of [0,n] where n is the size of thie list. Arcadia_Value value The value to insert.

Errors

Arcadia_Status_ArgumentValueInvalid
index is out of bounds.
Arcadia_Status_ArgumentTypeInvalid
value is a Void value.

Arcadia_List_insertBack

void
Arcadia_List_insertBack
  (
    Arcadia_Thread* thread,
    Arcadia_List* self,
    Arcadia_Value value
  ) Insert a value at the back of this list.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_List* self
A pointer to this list.
Arcadia_Value value
The value to insert at the back of this list.

Errors

Arcadia_Status_ArgumentTypeInvalid
value is a Void value.

Arcadia_List_insertFront

void
Arcadia_List_insertFront
  (
    Arcadia_Thread* thread,
    Arcadia_List* self,
    Arcadia_Value value
  ) Insert a value at the front of this list.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_List* self
A pointer to this list.
Arcadia_Value value
The value to insert at the front of this list.

Errors

Arcadia_Status_ArgumentTypeInvalid
value is a Void value.

Arcadia_List_removeAt

void
Arcadia_List_removeAt
  (
    Arcadia_Thread* thread,
    Arcadia_List* self,
    Arcadia_SizeValue start,
    Arcadia_SizeValue length
  ) Remove length values starting with element at index start.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_List* self
A pointer to this list.
Arcadia_SizeValue start
The index of the first element to remove.
Arcadia_SizeValue length
The number of elements to remove.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.
Arcadia_Status_ArgumentValueInvalid
index + length > n where n is the length of the list.

Map

Arcadia_Map extends Arcadia_Collection.

Arcadia_Map represents a map from Arcadia_Value objects, the keys, to Arcadia_Value objects, the values.

Arcadia_Map_get

Arcadia_Value
Arcadia_Map_get
  (
    Arcadia_Thread* thread,
    Arcadia_Map* self,
    Arcadia_Value key
  )

Get the value of an entry for a given key in this map.

More formally: Let \(x\) be the specified key.

  • If there exist an entry \(x' \mapsto y'\) in the map such that \(x\) is equivalent to \(x'\), then y' is returned.
  • Otherwise (if there exists no such entry in the map), then a Void value is returned.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_Map* self
A pointer to this Arcadia_Map object.
Arcadia_Value key
The key \(k\).

Return value

The value for the given key if it was found. A Void value otherwise.

Errors

Arcadia_Status_ArgumentTypeInvalid
key is a Void value.

Arcadia_Map_remove

Arcadia_Value
Arcadia_Map_set   (
    Arcadia_Thread* thread,
    Arcadia_Stack* self,
    Arcadia_Value key
  )

Remove an entry for a given key from this map.

More formally: Let \(x\) be the specified key and \(y\) be the specified value.

  • If \(y\) is an Void value then there are two cases:
    • If there exist an entry \((x' \mapsto y')\) in the map such that \(x\) is equivalent to \(x'\), then this entry is removed and y' is returned.
    • Otherwise (if there exists no such entry in the map), then a Void value is returned.
    • Otherwise (\(y\) is not an Void value) then there are two cases:
    • If there exist one \((x' \mapsto y')\) in the map such that \(x\) is equivalent to \(x'\), then this entry is replaced by the entry \((x' \mapsto y)\) and y' is returned.
    • Otherwise the entry \((x \mapsto y)\) is added and an Void value is returned.

    Parameters

    Arcadia_Thread* thread
    A pointer to the Arcadia_Thread object.
    Arcadia_Map* self
    A pointer to this stack.
    Arcadia_Value key
    The key \(x\).
    Arcadia_Value value
    The value \(y\).

    Return value

    The value of the removed entry \((x \mapsto y)\) such an entry was found. A Void value otherwise.

    Errors

    Arcadia_Status_ArgumentTypeInvalid
    key is a Void value.

Arcadia_Map_set

void
Arcadia_Map_set   (
    Arcadia_Thread* thread,
    Arcadia_Stack* self,
    Arcadia_Value key,
    Arcadia_Value value
    Arcadia_Value* oldKey,
    Arcadia_Value* oldValue,
  )

Set the value for the given key in this map.

More formally: Let \(x\) be the specified key and \(y\) be the specified value.

  • If \(x\) is an Void value, then an Argument Type Invalid error is raised.
  • If \(y\) is an Void value then there are two cases:
    • If there exist an entry \((x' \mapsto y')\) in the map such that \(x\) is equivalent to \(x'\), then this entry is removed. \(x'\) is returned in *oldKey if oldKey is not null. \(y'\) is returned in *oldValue if oldValue is not null.
    • Otherwise (if there exists no such entry in the map): Void value is returned in *oldKey if oldKey is not null. Void value is returned in *oldValue if oldValue is not null.
    • Otherwise (\(y\) is not an Void value) then there are two cases:
    • If there exist one \(x' \mapsto y'\) in the map such that \(x\) is equivalent to \(x'\), then this entry is replaced by the entry \(x \mapsto y\). \(x'\) is returned in *oldKey if oldKey is not null. \(y'\) is returned in *oldValue if oldValue is not null.
    • Otherwise the entry \(x \mapsto y\) is added. Void value is returned in *oldKey if oldKey is not null. Void value is returned in *oldValue if oldValue is not null.

    Parameters

    Arcadia_Thread* thread
    A pointer to the Arcadia_Thread object.
    Arcadia_Map* self
    A pointer to this stack.
    Arcadia_Value key
    The key \(k\).
    Arcadia_Value value
    The value \(v\).

    Return value

    The value of the removed entry \((x' \mapsto y')\) if an entry for the given key if it was found. A Void value otherwise.

    Errors

    Arcadia_Status_ArgumentTypeInvalid
    key is a Void value.

Set

Arcadia_Set extends Arcadia_Collection.

Arcadia_Set represents a set of Arcadia_Value objects.

Arcadia_Set_contains

Arcadia_BooleanValue
Arcadia_Set_contains
  (
    Arcadia_Thread* thread,
    Arcadia_Set* self,
    Arcadia_Value value
  ) Get if this set contains a value. More formally: Let \(x\) be the value to be tested.

  • If \(x\) is an Void value, then an Argument Type Invalid error is raised.
  • Otherwise (that is, if \(x\) is not an Void value):
    • If there exist one \(x'\) in the map such that \(x\) is equivalent to \(x'\), then Arcadia_BooleanValue_True is returned.
    • Otherwise Arcadia_BooleanValue_False is returned.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_Set* self
A pointer to this Arcadia_Set object.
Arcadia_Value value
The value \(x\).

Return value

Arcadia_BooleanValue_True if \(x\) contained in this set. Arcadia_BooleanValue_False otherwise.

Arcadia_Set_get

Arcadia_Value
Arcadia_Set_get   (
    Arcadia_Thread* thread,
    Arcadia_Set self,
    Arcadia_Value value
  )

Get the value in this set.

More formally: Let \(x\) be the value to get.

  • If \(x\) is an Void value, then an Argument Type Invalid error is raised.
  • Otherwise (\(x\) is not an Void value) then there are two cases:
  • If there exist one \(x'\) in the map such that \(x\) is equivalent to \(x'\), then \(x'\) is returned.
  • Otherwise the Void value is returned.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_Set* self
A pointer to this set.
Arcadia_Value value
The value \(x\).

Return value

The value \(x'\) or the Void value.

Arcadia_Set_add

void
Arcadia_Set_add   (
    Arcadia_Thread* thread,
    Arcadia_Set self,
    Arcadia_Value value,
    Arcadia_Value* oldValue
  )

Add value to this set.

More formally: Let \(x\) be the value to be added.

  • If \(x\) is an Void value, then an Argument Type Invalid error is raised.
  • Otherwise (\(x\) is not an Void value) then there are two cases:
  • If there exist one \(x'\) in the map such that \(x\) is equivalent to \(x'\), \(x'\) is replaced by \(x\) in this set. \(x'\) is returned in *oldValue if oldValue is not null.
  • Otherwise \(x\) is added to this set. Void value is returned in *oldValue if oldValue is not a null pointer.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_Set* self
A pointer to this set.
Arcadia_Value value
The value \(x\).
Arcadia_Value* oldValue
A pointer to a Arcadia_Value object or a null pointer.

Return value

Arcadia_BooleanValue_True if \(x\) was added to this set. Arcadia_BooleanValue_False otherwise.

Arcadia_Set_remove

void
Arcadia_Set_remove
  (
    Arcadia_Thread* thread,
    Arcadia_Set* self,
    Arcadia_Value value,
    Arcadia_Value *oldValue
  )

Remove a value from this set.

More formally: Let \(x\) be the value to be removed.

  • If \(x\) is an Void value, then an Argument Type Invalid error is raised.
  • Otherwise (\(x\) is not an Void value) then there are two cases:
  • If there exist one \(x'\) in the map such that \(x\) is equivalent to \(x'\), \(x'\) is removed from this set. \(x'\) is returned in *oldValue if oldValue is not null.
  • Void value is returned in *oldValue if oldValue is not a null pointer.
Otherwise an Void value is returned.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_Set* self
A pointer to this set.
Arcadia_Value value
The value \(x\).
Arcadia_Value *oldValue
A pointer to an Arcadia_Value object or a null pointer.

Return value

Arcadia_BooleanValue_Trueif value was removed to this set. Arcadia_BooleanValue_False otherwise.

Stack

Arcadia_Stack extends Arcadia_Collection.

Arcadia_Stack represents a stack of Arcadia_Value objects.

Arcadia_Stack_create

Arcadia_Stack*
Arcadia_Stack_create
  (
    Arcadia_Thread* thread
  ) Create a stack.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.

Errors

Arcadia_Status_AllocationFailed
An allocation failed.

Return value

A pointer to the Arcadia_Stack value.

Arcadia_Stack_peek

Arcadia_Value
Arcadia_Stack_peek
  (
    Arcadia_Thread* thread,
    Arcadia_Stack* self
  ) Peek at the value on top of this stack.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_Stack* self
A pointer to this stack.

Return value

The value.

Errors

Arcadia_Status_OperationInvalid
The stack is empty.

Arcadia_Stack_pop

Arcadia_Value
Arcadia_Stack_pop   (
    Arcadia_Thread* thread,
    Arcadia_Stack* self
  ) Pop the value from the top of this stack.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_Stack* self
A pointer to this stack.

Return value

The value.

Errors

Arcadia_Status_OperationInvalid
The stack is empty.

Arcadia_Stack_push

void
Arcadia_Stack_push
  (
    Arcadia_Thread* thread,
    Arcadia_Stack* self,
    Arcadia_Value value
  ) Push a value on the top of this stack.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_Stack* self
A pointer to this stack.
Arcadia_Value value
The value to push.

Errors

Arcadia_Status_ArgumentTypeInvalid
value is a Void value.