---
title: "Operations"
canonical: "https://docs.magma-maths.org/v2.30-1/SetsSequencesMappings/AssociativeArrays/operations.html"
source: "https://docs.magma-maths.org/v2.30-1/SetsSequencesMappings/AssociativeArrays/operations.md"
part: "Sets, Sequences, and Mappings"
chapter: "Associative Arrays"
breadcrumbs:
  - {"title": "Magma Handbook", "source": "https://docs.magma-maths.org/v2.30-1/index.md"}
  - {"title": "Sets, Sequences, and Mappings", "source": "https://docs.magma-maths.org/v2.30-1/SetsSequencesMappings/index-sets-sequences-mappings.md"}
  - {"title": "Associative Arrays", "source": "https://docs.magma-maths.org/v2.30-1/SetsSequencesMappings/AssociativeArrays/index-associative-arrays.md"}
prev: {"title": "Introduction", "source": "https://docs.magma-maths.org/v2.30-1/SetsSequencesMappings/AssociativeArrays/introduction.md"}
next: {"title": "Iteration", "source": "https://docs.magma-maths.org/v2.30-1/SetsSequencesMappings/AssociativeArrays/Iteration.md"}
intrinsics:
  - {"name": "AssociativeArray", "signature": "AssociativeArray() -> Assoc"}
  - {"name": "AssociativeArray", "signature": "AssociativeArray(I): Str -> Assoc"}
  - {"name": "A[x] := y", "signature": "A[x] := y: Assoc, Elt, Elt"}
  - {"name": "A[x]", "signature": "A[x]: Assoc, Elt -> Elt"}
  - {"name": "IsDefined", "signature": "IsDefined(A, x): Assoc, Elt -> Bool, Elt"}
  - {"name": "IsInKeys", "signature": "IsInKeys(A, x): Assoc, Elt -> Bool, Elt"}
  - {"name": "Remove", "signature": "Remove(~A, x): Assoc, Elt"}
  - {"name": "Universe", "signature": "Universe(A): Assoc -> Str"}
  - {"name": "#", "signature": "# A: Assoc -> RngIntElt"}
  - {"name": "Keys", "signature": "Keys(A): Assoc -> SetEnum"}
  - {"name": "Values", "signature": "Values(A): Assoc -> List"}
examples:
  - "ex-c3ad44"
---

# Operations

<a id="function-associativearray"></a>
## `AssociativeArray() -> Assoc`

```magma
Default: Any                    Default: 
```

Create the null associative array $A$ with no index universe. The first assignment to $A$ will determine its index universe. The optional parameter `Default := D` allows one to associate the default value $D$ to $A$ (so $A[x]$ will return $D$ if $x$ is not in the keys of $A$).

<a id="function-associativearray-str"></a>
## `AssociativeArray(I): Str -> Assoc`

```magma
Default: Any                    Default: 
```

Create the empty associative array $A$ with index universe $I$. The optional parameter `Default := D` allows one to associate the default value $D$ to $A$ (so $A[x]$ will return $D$ if $x$ is not in the keys of $A$).

<a id="literal-literal-a-x-y-assoc-elt-elt"></a>
## `A[x] := y: Assoc, Elt, Elt`

Set the value in $A$ associated with index $x$ to be $y$. If $x$ is not coercible into the current index universe $I$ of $A$, then an attempt is first made to lift the index universe of $A$ to contain both $I$ and $x$.

In a nested assignment such as `A[x][z] := y`, if $x$ is not in the keys of $A$ but a default value $D$ was specified when $A$ was created, then $A[x]$ is first set to $D$ and the assignment then proceeds on that value. Thus arrays of arrays may be built up without initializing each level explicitly (see the example below).

<a id="literal-literal-a-x-assoc-elt-elt"></a>
## `A[x]: Assoc, Elt -> Elt`

Given an index $x$ coercible into the index universe $I$ of $A$, return the value associated with $x$. If $x$ is not in the keys of $A$, then: (1) if a default value $D$ was specified when $A$ was created, then $D$ is returned; (2) otherwise, an error is raised.

<a id="function-isdefined-assoc-elt"></a>
## `IsDefined(A, x): Assoc, Elt -> Bool, Elt`

Given an index $x$ coercible into the index universe $I$ of $A$, return whether $A[x]$ is currently defined, and if so, return also the value $A[x]$. This is the case if $x$ is in the keys of $A$ or $A$ has a default value.

<a id="function-isinkeys-assoc-elt"></a>
## `IsInKeys(A, x): Assoc, Elt -> Bool, Elt`

Given an index $x$ coercible into the index universe $I$ of $A$, return whether $x$ is explicitly in the keys of $A$ and if so, return also the value $A[x]$.

<a id="procedure-remove-assoc-elt-ref"></a>
## `Remove(~A, x): Assoc, Elt`

(Procedure.) Destructively remove the value indexed by $x$ from the array $A$. If $x$ is not present as an index, then nothing happens (i.e., an error is not raised).

<a id="function-universe-assoc"></a>
## `Universe(A): Assoc -> Str`

Given an associative array $A$, return the index universe $I$ of $A$, in which the keys of $A$ currently lie.

<a id="operation-operation-assoc-rngintelt"></a>
## `# A: Assoc -> RngIntElt`

Given an associative array $A$, return the number of items stored in $A$.

<a id="function-keys-assoc"></a>
## `Keys(A): Assoc -> SetEnum`

Given an associative array $A$, return the current keys of $A$ as a set. Warning: this constructs a new copy of the set of keys, so should only be called when that is needed; it is not meant to be used as a quick access function.

<a id="function-values-assoc"></a>
## `Values(A): Assoc -> List`

Given an associative array $A$, return the current values of $A$ as an unsorted list (a list is returned since the values need not lie in a fixed universe but may be of any type). Warning: this constructs a new copy of the list of values, so should only be called when that is needed; it is not meant to be used as a quick access function.

<a id="example-ex-c3ad44"></a>
## `Example: Creating an Associative Array (ex-c3ad44)`

This example shows simple use of associative arrays. First we create an array indexed by rationals.

```magma
> A := AssociativeArray();
> A[1/2] := 7;
> A[3/8] := "abc";
> A[3] := 3/8;
> A[1/2];
7
> IsDefined(A, 3);
true 3/8
> IsDefined(A, 4);
false
> IsDefined(A, 3/8);
true abc
> Keys(A);
{ 3/8, 1/2, 3 }
> Values(A);
[* 7, abc, 3/8 *]
> for x in Keys(A) do x, A[x]; end for;
1/2 7
3/8 abc
3 3/8
> Remove(~A, 3/8);
> IsDefined(A, 3/8);
false
> Keys(A);
{ 1/2, 3 }
> Values(A);
[* 7, 3/8 *]
> Universe(A);
Rational Field
```

We repeat that an associative array can be indexed by elements of any structure. We now index an array by elements of the symmetric group $S_3$.

```magma
> G := Sym(3);
> A := AssociativeArray(G);
> v := 1; for x in G do A[x] := v; v +:= 1; end for;
> A;
Associative Array with index universe GrpPerm: G, Degree 3, Order 2 * 3
> Keys(A);
{
    (1, 3, 2),
    (2, 3),
    (1, 3),
    (1, 2, 3),
    (1, 2),
    Id(G)
}
> A[G!(1,3,2)];
3
```

The following shows how the parameter `Default` can be used when an associative array $A$ is created.

```magma
> A := AssociativeArray(: Default := []);
> x := 3; y := 5;
> Append(~A[x], y);
> assert A[x] eq [y];
> assert Keys(A) eq {x};
> assert Values(A) eq [* [ y ] *];
> IsDefined(A, x);
true [ 5 ]
> IsInKeys(A, x);
true [ 5 ]
> IsDefined(A, 4);
true []
> IsInKeys(A, 4);
false
```

Here we can append an element to $A[x]$ even when $x$ is not yet in the keys of $A$; in such a case, $A[x]$ is initially taken to be $[]$ and so can be appended to without error.

Since the default may itself be an associative array with a default, nested arrays may be built up in the same way, without initializing any of the intermediate levels.

```magma
> A := AssociativeArray(: Default := AssociativeArray(: Default := []));
> Append(~A[1][2], 3);
> Append(~A[1][2], 4);
> Append(~A[5][6], 7);
> A[1][2];
[ 3, 4 ]
> Keys(A);
{ 1, 5 }
> Keys(A[5]);
{ 6 }
```

An index is only added to the keys of $A$ when something is actually assigned to it, so simply reading a value leaves $A$ unchanged.

```magma
> A[9][9];
[]
> Keys(A);
{ 1, 5 }
```
