## `assignElements` -- assign values to entries of an array, a list, or a table

#### Introduction

`assignElements(`L, [index1] = value1, [index2] = value2, ...`)` returns a copy of `L` with `value1` stored at `index1`, `value2` stored at `index2`, etc.

#### Call(s)

`assignElements(L, [index1] = value1, [index2] = value2, ...)`
`assignElements(L, [[index1], value1], [[index2], value2], ...)`

#### Parameters

`L` | - | an array, a list, or a table
`index1, index2, ...` | - | valid indices for `L`
`value1, value2, ...` | - | any MuPAD objects

#### Returns

an object of the same type as `L`.

#### Related Functions

`:=`, `_assign`, `_index`, `array`, `assign`, `delete`, `DOM_ARRAY`, `DOM_LIST`, `DOM_TABLE`, `evalassign`, `table`

#### Details

- `R:=``assignElements(`L,[index1]=value1,[index2]=value2,...`)` has the same effect as the sequence of assignments `R:=L: R[index1]:=value1: R[index2]:=value2: ... R`, but is more efficient.
- `assignElements` returns a modified copy of its first argument, which remains unchanged. See example 1.
- The second variant of the `assignElements` call, with lists instead of equations, is equivalent to the first variant. In fact, both equations and lists may be mixed in a single call. See example 1.
- All assignments are performed simultaneously, i.e., the order of the arguments is irrelevant. See example 3.
- All rules for indexed assignments apply, in particular with respect to the validity of indices. If `L` is a list, the indices must be positive integers not exceeding the length of `L`. If `L` is an array, the indices must be (sequences of) integers matching the dimension and lying within the valid ranges of the array. If `L` is a table, the indices may be arbitrary objects.
- `assignElements` is a function of the system kernel.

#### Example 1

Assignments may given as equations or lists, and both forms may be mixed in a single call:

    >> L := array(1..3, [3, 4, 5]);
       assignElements(L, [1] = one, [2] = two, [3] = three);
       assignElements(L, [[1], one], [[2], two], [[3], three]);
       assignElements(L, [1] = one, [[2], two], [3] = three);

                                    +-       -+
                                    | 3, 4, 5 |
                                    +-       -+

                                +-               -+
                                | one, two, three |
                                +-               -+

                                +-               -+
                                | one, two, three |
                                +-               -+

                                +-               -+
                                | one, two, three |
                                +-               -+

The array `L` itself is not modified by `assignElements`:

    >> L

                                    +-       -+
                                    | 3, 4, 5 |
                                    +-       -+

#### Example 2

Sequences, too, may be assigned as values to array elements, but they must be put in parentheses:

    >> R := assignElements(array(1..2), [1] = (1, 7), [2] = PI)

                                   +-        -+
                                   | 1, 7, PI |
                                   +-        -+

    >> [R[1]], [R[2]]

                                   [1, 7], [PI]

#### Example 3

The sequence generator `$` is useful to create sequences of assignments:

    >> L := [i $ i = 1..10];
       assignElements(L, [i] = L[i] + L[i + 1] $ i = 1..9)

                          [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

                       [3, 5, 7, 9, 11, 13, 15, 17, 19, 10]

The order of the arguments is irrelevant:

    >> assignElements(L, [10 - i] = L[10 - i] + L[11 - i] $ i = 1..9)

                       [3, 5, 7, 9, 11, 13, 15, 17, 19, 10]

#### Example 4

The indices of a table may be arbitrary objects, for example, strings:

    >> assignElements(table(), [expr2text(i)] = i^2 $ i = 1..4)

                                    table(
                                      "4" = 16,
                                      "3" = 9,
                                      "2" = 4,
                                      "1" = 1
                                    )

#### Example 5

For arrays of dimension greater than one, the indices are sequences of as many integers as determined by the dimension of the array:

    >> assignElements(array(1..3, 1..3),
         ([i, j] = i + j $ i = 1..3) $ j = 1..3)

                                   +-         -+
                                   |  2, 3, 4  |
                                   |           |
                                   |  3, 4, 5  |
                                   |           |
                                   |  4, 5, 6  |
                                   +-         -+

#### Changes

- used to be called `assign_elems`

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000