Arrays

Arrays are ordered lists of values. Resource attributes which accept multiple values (including the relationship metaparameters) generally expect those values in an array. Many functions also take arrays, including the iteration functions.

Arrays are written as comma-separated lists of values surrounded by square brackets, []. An optional trailing comma is allowed between the final value and the closing square bracket.

[ 'one', 'two', 'three' ]
# Equivalent:
[ 'one', 'two', 'three', ]

The values in an array can be any data type.

Array values are immutable — they cannot be changed once they are created.

Accessing items in an array

You can access items in an array by their numerical index, counting from zero. Square brackets are used for accessing. For example:

$my_array = [ 'one', 'two', 'three' ]
notice( $my_array[1] )

This manifest would log two as a notice. The value of $my_array[0] would be one, because indexes count from zero.

The opening square bracket must not be preceded by white space:

$my_array = [ 'one', 'two', 'three', 'four', 'five' ]
notice( $my_array[2] )  # ok
notice( $my_array [2] ) # syntax error

Nested arrays and hashes can be accessed by chaining indexes:

$my_array = [ 'one', {'second' => 'two', 'third' => 'three'} ]
notice( $my_array[1]['third'] )

This manifest would log three as a notice. $my_array[1] is a hash, and we access a key named 'third'.

Arrays support negative indexes, counting backward from the last element, with -1 being the last element of the array:

$my_array = [ 'one', 'two', 'three', 'four', 'five' ]
notice( $my_array[2] )
notice( $my_array[-2] )

The first notice would log three, and the second notice would log four.

If you try to access an element beyond the bounds of the array, its value is undef:

$my_array = [ 'one', 'two', 'three', 'four', 'five' ]
$cool_value = $my_array[6] # value is undef

When testing with a regular expression whether an Array[<TYPE>] data type matches a given array, empty arrays match if the type accepts zero-length arrays.

$my_array = []
if $my_array =~ Array[String] {
  notice( 'my_array' )
}

This manifest would log my_array as a notice, because the expression matches the empty array.

Accessing sections of an array

You can access sections of an array by numerical index. Like accessing individual items, accessing sections uses square brackets, but it uses two indexes, separated by a comma. For example: $array[3,10].

The result of an array section is always another array.

The first number of the index is the start position. Positive numbers count forward from the start of the array, starting at zero. Negative numbers count backward from the end of the array, starting at -1.

The second number of the index is the stop position. Positive numbers are lengths, counting forward from the start position. Negative numbers are absolute positions, counting backward from the end of the array starting at -1.

For example:

$my_array = [ 'one', 'two', 'three', 'four', 'five' ]
notice( $my_array[2,1] )  # evaluates to ['three']
notice( $my_array[2,2] )  # evaluates to ['three', 'four']
notice( $my_array[2,-1] ) # evaluates to ['three', 'four', 'five']
notice( $my_array[-2,1] ) # evaluates to ['four']

Array operators

You can use operators with arrays to create new arrays:

append with <<
concatenate with +
remove elements with -

or to convert arrays to comma-separated lists with * (splat). See the Array operators section of Expressions for more information.

Additional functions for arrays

The puppetlabs-stdlib module contains useful functions for working with arrays, including:


`delete`	`member`	`sort`
`delete_at`	`prefix`	`unique`
`flatten`	`range`	`validate_array`
`grep`	`reverse`	`values_at`
`hash`	`shuffle`	`zip`
`is_array`	`size`

The `Array` data type

The data type of arrays is Array. By default, Array matches arrays of any length, provided all values in the array match the abstract data type Data. You can use parameters to restrict which values Array matches.

Parameters

The full signature for Array is:

Array[<CONTENT TYPE>, <MIN SIZE>, <MAX SIZE>]

These parameters are optional. They must be listed in order; if you need to specify a later parameter, you must also specify values for any prior ones.


Position	Parameter	Data type	Default value	Description
1	Content type	`Type`	`Data`	The kind of values the array contains. You can specify only one data type per array, and every value in the array must match that type. Use an abstract type to allow multiple data types. If the order of elements matters, use the `Tuple` type instead of `Array`.
2	Minimum size	`Integer`	0	The minimum number of elements in the array. This parameter accepts the special value `default`, which uses its default value.
3	Maximum size	`Integer`	infinite	The maximum number of elements in the array. This parameter accepts the special value `default`, which uses its default value.

Examples:

Array: Matches an array of any length. All elements in the array must match Data.
Array[String]: Matches an array of any size that contains only strings.
Array[Integer, 6]: Matches an array containing at least six integers.
Array[Float, 6, 12]: Matches an array containing at least six and at most 12 floating-point numbers.
Array[Variant[String, Integer]]: Matches an array of any size that contains only strings or integers, or both.
Array[Any, 2]: Matches an array containing at least two elements, allowing any data type (including Type and Resource).

The abstract Tuple data type lets you specify data types for every element in an array, in order. Abstract types, such as Variant and Enum, are useful when specifying content types for arrays that include multiple kinds of data.