| `ARRAY[N]=VALUE` | Sets the element `N` of the **indexed** array `ARRAY` to `VALUE`. **`N` can be any valid [arithmetic expression](/syntax/arith_expr)**. |
| `ARRAY[STRING]=VALUE` | Sets the element indexed by `STRING` of the **associative array**`ARRAY`. |
| `ARRAY=VALUE` | As above. If no index is given, as a default the zeroth element is set to `VALUE`. Careful, this is even true of associative arrays - there is no error if no key is specified, and the value is assigned to string index "0". |
| `ARRAY=(E1\ E2\ ...)` | Compound array assignment - sets the whole array `ARRAY` to the given list of elements indexed sequentially starting at zero. The array is unset before assignment unless the += operator is used. When the list is empty (`ARRAY=()`), the array will be set to an empty array. This method obviously does not use explicit indexes. An **associative array** can **not** be set like that! Clearing an associative array using `ARRAY=()` works. |
| `ARRAY=([X]=E1\ [Y]=E2\ ...)` | Compound assignment for indexed arrays with index-value pairs declared individually (here for example `X` and `Y`). X and Y are arithmetic expressions. This syntax can be combined with the above - elements declared without an explicitly specified index are assigned sequentially starting at either the last element with an explicit index, or zero. |
| `ARRAY=([S1]=E1\ [S2]=E2\ ...)` | Individual mass-setting for **associative arrays**. The named indexes (here: `S1` and `S2`) are strings. |
| `ARRAY+=(E1\ E2\ ...)` | Append to ARRAY. |
| `ARRAY=("${ANOTHER_ARRAY[@]}")` | Copy ANOTHER_ARRAY to ARRAY, copying each element. |
As of now, arrays can't be exported.
### Getting values
\<note\> For completeness and details on several parameter expansion
variants, see the [article about parameter expansion](/syntax/pe) and
| `${ARRAY[N]}` | Expands to the value of the index `N` in the **indexed** array `ARRAY`. If `N` is a negative number, it's treated as the offset from the maximum assigned index (can't be used for assignment) - 1 |
| `${ARRAY[S]}` | Expands to the value of the index `S` in the **associative** array `ARRAY`. |
| `"${ARRAY[@]}" ${ARRAY[@]} "${ARRAY[*]}" ${ARRAY[*]}` | Similar to [mass-expanding positional parameters](/scripting/posparams#mass_usage), this expands to all elements. If unquoted, both subscripts `*` and `@` expand to the same result, if quoted, `@` expands to all elements individually quoted, `*` expands to all elements quoted as a whole. |
| `"${ARRAY[@]:N:M}" ${ARRAY[@]:N:M} "${ARRAY[*]:N:M}" ${ARRAY[*]:N:M}` | Similar to what this syntax does for the characters of a single string when doing [substring expansion](/syntax/pe#substring_expansion), this expands to `M` elements starting with element `N`. This way you can mass-expand individual indexes. The rules for quoting and the subscripts `*` and `@` are the same as above for the other mass-expansions. |
For clarification: When you use the subscripts `@` or `*` for
mass-expanding, then the behaviour is exactly what it is for `$@` and
`$*` when [mass-expanding the positional
parameters](/scripting/posparams#mass_usage). You should read this
article to understand what's going on.
### Metadata
<table>
<thead>
<trclass="header">
<th>Syntax</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<trclass="odd">
<td><code>${#ARRAY[N]}</code></td>
<td>Expands to the <strong>length</strong> of an individual array member
at index <code>N</code> (<strong>stringlength</strong>)</td>
</tr>
<trclass="even">
<td><code>${#ARRAY[STRING]}</code></td>
<td>Expands to the <strong>length</strong> of an individual associative
array member at index <code>STRING</code>
(<strong>stringlength</strong>)</td>
</tr>
<trclass="odd">
<td><code>${#ARRAY[@]}</code><br/>
<code>${#ARRAY[*]}</code></td>
<td>Expands to the <strong>number of elements</strong> in
<code>ARRAY</code></td>
</tr>
<trclass="even">
<td><code>${!ARRAY[@]}</code><br/>
<code>${!ARRAY[*]}</code></td>
<td>Expands to the <strong>indexes</strong> in <code>ARRAY</code> since
BASH 3.0</td>
</tr>
</tbody>
</table>
### Destruction
The [unset](commands/builtin/unset) builtin command is used to destroy
(unset) arrays or individual elements of arrays.
<table>
<thead>
<trclass="header">
<th>Syntax</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<trclass="odd">
<td><code>unset -v ARRAY</code><br/>
<code>unset -v ARRAY[@]</code><br/>
<code>unset -v ARRAY[*]</code></td>
<td>Destroys a complete array</td>
</tr>
<trclass="even">
<td><code>unset -v ARRAY[N]</code></td>
<td>Destroys the array element at index <code>N</code></td>
</tr>
<trclass="odd">
<td><code>unset -v ARRAY[STRING]</code></td>
<td>Destroys the array element of the associative array at index
<code>STRING</code></td>
</tr>
</tbody>
</table>
It is best to [explicitly specify
-v](commands/builtin/unset#portability_considerations) when unsetting
You always have to remember that, it seems newbies have problems
sometimes. Please understand that **numerical array indexing begins at 0
(zero)**!
The method above, walking through an array by just knowing its number of
elements, only works for arrays where all elements are set, of course.
If one element in the middle is removed, then the calculation is
nonsense, because the number of elements doesn't correspond to the
highest used index anymore (we call them "*sparse arrays*").
Now, suppose that you want to replace your array `sentence` with the
values in the [previously-declared array](#purpose) `NAMES` . You might
think you could just do
$ unset sentence ; declare -a sentence=NAMES
$ echo ${#sentence[@]}
1
# omit calculating max_index as above, and iterate as one-liner
$ for ((i = 0; i < ${#sentence[@]}; i++)); do echo "Element $i: '${sentence[i]}'" ; done
Element 0: 'NAMES'
Obviously that's wrong. What about
$ unset sentence ; declare -a sentence=${NAMES}
? Again, wrong:
$ echo ${#sentence[*]}
1
$ for ((i = 0; i < ${#sentence[@]}; i++)); do echo "Element $i: '${sentence[i]}'" ; done
Element 0: 'Peter'
So what's the **right** way? The (slightly ugly) answer is, reuse the
enumeration syntax:
$ unset sentence ; declare -a sentence=("${NAMES[@]}")
$ echo ${#sentence[@]}
4
$ for ((i = 0; i < ${#sentence[@]}; i++)); do echo "Element $i: '${sentence[i]}'" ; done
Element 0: 'Peter'
Element 1: 'Anna'
Element 2: 'Greg'
Element 3: 'Jan'
### Associative (Bash 4)
Associative arrays (or *hash tables*) are not much more complicated than
numerical indexed arrays. The numerical index value (in Bash a number
starting at zero) just is replaced with an arbitrary string:
# declare -A, introduced with Bash 4 to declare an associative array
declare -A sentence
sentence[Begin]='Be liberal in what'
sentence[Middle]='you accept, and conservative'
sentence[End]='in what you send'
sentence['Very end']=...
<u>**Beware:**</u> don't rely on the fact that the elements are ordered
in memory like they were declared, it could look like this:
# output from 'set' command
sentence=([End]="in what you send" [Middle]="you accept, and conservative " [Begin]="Be liberal in what " ["Very end"]="...")
This effectively means, you can get the data back with
`"${sentence[@]}"`, of course (just like with numerical indexing), but
you can't rely on a specific order. If you want to store ordered data,
or re-order data, go with numerical indexes. For associative arrays, you
usually query known index values:
for element in Begin Middle End "Very end"; do
Arrays can be expanded indirectly using the indirect parameter expansion
syntax. Parameters whose values are of the form: `name[index]`,
`name[@]`, or `name[*]` when expanded indirectly produce the expected
results. This is mainly useful for passing arrays (especially multiple
arrays) by name to a function.
This example is an "isSubset"-like predicate which returns true if all
key-value pairs of the array given as the first argument to isSubset
correspond to a key-value of the array given as the second argument. It
demonstrates both indirect array expansion and indirect key-passing
without eval using the aforementioned special compound assignment
expansion.
isSubset() {
local -a 'xkeys=("${!'"$1"'[@]}")' 'ykeys=("${!'"$2"'[@]}")'
set -- "${@/%/[key]}"
(( ${#xkeys[@]} <= ${#ykeys[@]} )) || return 1
local key
for key in "${xkeys[@]}"; do
[[ ${!2+_} && ${!1} == ${!2} ]] || return 1
done
}
main() {
# "a" is a subset of "b"
local -a 'a=({0..5})' 'b=({0..10})'
isSubset a b
echo $? # true
# "a" contains a key not in "b"
local -a 'a=([5]=5 {6..11})' 'b=({0..10})'
isSubset a b
echo $? # false
# "a" contains an element whose value != the corresponding member of "b"
local -a 'a=([5]=5 6 8 9 10)' 'b=({0..10})'
isSubset a b
echo $? # false
}
main
This script is one way of implementing a crude multidimensional
associative array by storing array definitions in an array and
referencing them through indirection. The script takes two keys and
dynamically calls a function whose name is resolved from the array.
callFuncs() {
# Set up indirect references as positional parameters to minimize local name collisions.
set -- "${@:1:3}" ${2+'a["$1"]' "$1"'["$2"]'}
# The only way to test for set but null parameters is unfortunately to test each individually.
local x
for x; do
[[ $x ]] || return 0
done
local -A a=(
[foo]='([r]=f [s]=g [t]=h)'
[bar]='([u]=i [v]=j [w]=k)'
[baz]='([x]=l [y]=m [z]=n)'
) ${4+${a["$1"]+"${1}=${!3}"}} # For example, if "$1" is "bar" then define a new array: bar=([u]=i [v]=j [w]=k)
${4+${a["$1"]+"${!4-:}"}} # Now just lookup the new array. for inputs: "bar""v", the function named "j" will be called, which prints "j" to stdout.
}
main() {
# Define functions named {f..n} which just print their own names.
local fun='() { echo "$FUNCNAME"; }' x
for x in {f..n}; do
eval "${x}${fun}"
done
callFuncs "$@"
}
main "$@"
## Bugs and Portability Considerations
- Arrays are not specified by POSIX. One-dimensional indexed arrays are
supported using similar syntax and semantics by most Korn-like shells.
- Associative arrays are supported via `typeset -A` in Bash 4, Zsh, and
Ksh93.
- In Ksh93, arrays whose types are not given explicitly are not
necessarily indexed. Arrays defined using compound assignments which
specify subscripts are associative by default. In Bash, associative
arrays can *only* be created by explicitly declaring them as
associative, otherwise they are always indexed. In addition, ksh93 has
several other compound structures whose types can be determined by the
compound assignment syntax used to create them.
- In Ksh93, using the `=` compound assignment operator unsets the array,
including any attributes that have been set on the array prior to
assignment. In order to preserve attributes, you must use the `+=`
operator. However, declaring an associative array, then attempting an
`a=(...)` style compound assignment without specifying indexes is an
error. I can't explain this
inconsistency.` $ ksh -c 'function f { typeset -a a; a=([0]=foo [1]=bar); typeset -p a; }; f' # Attribute is lost, and since subscripts are given, we default to associative.
typeset -A a=([0]=foo [1]=bar)
$ ksh -c 'function f { typeset -a a; a+=([0]=foo [1]=bar); typeset -p a; }; f' # Now using += gives us the expected results.
typeset -a a=(foo bar)
$ ksh -c 'function f { typeset -A a; a=(foo bar); typeset -p a; }; f' # On top of that, the reverse does NOT unset the attribute. No idea why.
ksh: f: line 1: cannot append index array to associative array a
`
- Only Bash and mksh support compound assignment with mixed explicit
subscripts and automatically incrementing subscripts. In ksh93, in
order to specify individual subscripts within a compound assignment,
all subscripts must be given (or none). Zsh doesn't support specifying
individual subscripts at all.
- Appending to a compound assignment is a fairly portable way to append
elements after the last index of an array. In Bash, this also sets
append mode for all individual assignments within the compound
assignment, such that if a lower subscript is specified, subsequent
elements will be appended to previous values. In ksh93, it causes
subscripts to be ignored, forcing appending everything after the last
element. (Appending has different meaning due to support for
multi-dimensional arrays and nested compound datastructures.)
` $ ksh -c 'function f { typeset -a a; a+=(foo bar baz); a+=([3]=blah [0]=bork [1]=blarg [2]=zooj); typeset -p a; }; f' # ksh93 forces appending to the array, disregarding subscripts
typeset -a a=(foo bar baz '[3]=blah' '[0]=bork' '[1]=blarg' '[2]=zooj')
$ bash -c 'function f { typeset -a a; a+=(foo bar baz); a+=(blah [0]=bork blarg zooj); typeset -p a; }; f' # Bash applies += to every individual subscript.
declare -a a='([0]="foobork" [1]="barblarg" [2]="bazzooj" [3]="blah")'
$ mksh -c 'function f { typeset -a a; a+=(foo bar baz); a+=(blah [0]=bork blarg zooj); typeset -p a; }; f' # Mksh does like Bash, but clobbers previous values rather than appending.
set -A a
typeset a[0]=bork
typeset a[1]=blarg
typeset a[2]=zooj
typeset a[3]=blah
`
- In Bash and Zsh, the alternate value assignment parameter expansion
(`${arr[idx]:=foo}`) evaluates the subscript twice, first to determine
whether to expand the alternate, and second to determine the index to
assign the alternate to. See [evaluation order](#evaluation_order).
` $ : ${_[$(echo $RANDOM >&2)1]:=$(echo hi >&2)}
13574
hi
14485
`
- In Zsh, arrays are indexed starting at 1 in its default mode.
Emulation modes are required in order to get any kind of portability.
- Zsh and mksh do not support compound assignment arguments to
`typeset`.
- Ksh88 didn't support modern compound array assignment syntax. The
original (and most portable) way to assign multiple elements is to use
the `set -A name arg1 arg2 ...` syntax. This is supported by almost
all shells that support ksh-like arrays except for Bash. Additionally,
these shells usually support an optional `-s` argument to `set` which
performs lexicographic sorting on either array elements or the
positional parameters. Bash has no built-in sorting ability other than
the usual comparison operators.
` $ ksh -c 'set -A arr -- foo bar bork baz; typeset -p arr' # Classic array assignment syntax
$ mksh -c 'set -sA arr -- foo "[3]=bar""[2]=baz""[7]=bork"; typeset -p arr' # Probably a bug. I think the maintainer is aware of it.
set -A arr
typeset arr[2]=baz
typeset arr[3]=bar
typeset arr[7]=bork
typeset arr[8]=foo
`
- Evaluation order for assignments involving arrays varies significantly
depending on context. Notably, the order of evaluating the subscript
or the value first can change in almost every shell for both
expansions and arithmetic variables. See [evaluation
order](#evaluation_order) for details.
- Bash 4.1.\* and below cannot use negative subscripts to address array
indexes relative to the highest-numbered index. You must use the
subscript expansion, i.e. `"${arr[@]:(-n):1}"`, to expand the nth-last
element (or the next-highest indexed after `n` if `arr[n]` is unset).
In Bash 4.2, you may expand (but not assign to) a negative index. In
Bash 4.3, ksh93, and zsh, you may both assign and expand negative
offsets.
- ksh93 also has an additional slice notation: `"${arr[n..m]}"` where
`n` and `m` are arithmetic expressions. These are needed for use with
multi-dimensional arrays.
- Assigning or referencing negative indexes in mksh causes wrap-around.
The max index appears to be `UINT_MAX`, which would be addressed by
`arr[-1]`.
- So far, Bash's `-v var` test doesn't support individual array
subscripts. You may supply an array name to test whether an array is
defined, but can't check an element. ksh93's `-v` supports both. Other
shells lack a `-v` test.
### Bugs
- **Fixed in 4.3** Bash 4.2.\* and earlier considers each chunk of a
compound assignment, including the subscript for globbing. The
subscript part is considered quoted, but any unquoted glob characters
on the right-hand side of the `[...]=` will be clumped with the
subscript and counted as a glob. Therefore, you must quote anything on
the right of the `=` sign. This is fixed in 4.3, so that each
subscript assignment statement is expanded following the same rules as
an ordinary assignment. This also works correctly in ksh93.
