Arrays

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