Why is a leading comma required when creating an array?

The key to understanding the Array subexpression operator @( ) is the realization that you don't need it to create arrays, instead arrays are created with the Comma operator ,

As a binary operator, the comma creates an array. As a unary operator, the comma creates an array with one member. Place the comma before the member.

$myArray = 1,2,3
$SingleArray = ,1
$xs = (1,2,3), (4,5,6)       # Count: 2    
$ys = (1,2,3),
(4,5,6)                      # Count: 2

Now consider

# A - two expressions, each expression yields one array of size 3
(1,2,3)
(4,5,6)

# B - one expression resulting in an array of two elements
(1,2,3),
(4,5,6)

# C - similar to A except the sizes are 3 and 1 
#     (the second array contains a single element)
(1,2,3)
,(4,5,6)

And the final step is to realize that

in essence, the @(...) operation is syntactic sugar for [array] $(...)

as explained by the PowerShell Team Blog (The link was given by Christopher G. Lewis answer). Although the meaning and limitations of in essence is not entirely clear to me.


@() is the array subexpression operator, which works differently than array construction operators you may be used to from other languages. The operator evaluates the nested subexpression and returns the output of that expression as an array. Meaning you can do something like this:

@(
Write-Output 'foo'
Get-Content 'C:\some\file.txt'
Test-Connection '192.168.23.42' -Count 1
)

and have an array come out.

For your first example this means that the two statements @(4, 1024) and , @((7), (16)) are evaluated individually, and the collective output of the two statements is then returned as an array.

The first statement (@(4, 1024)) outputs two integers, but the second statement (, @((7), (16))) outputs an array of two integers. That is because the leading comma in that statement is interpreted as the unary array construction operator (or comma operator), so you get an array nested in another array, and only the outer array is unrolled during output.

Essentially, your expression is the same as

$files1 = @(
4
1024
, @(7, 16)
)

or

$files1 = 4, 1024, @(7, 16)

Your second example avoids this pitfall, because both nested arrays are prepended with the unary array construction operator and thus protected from being completely unrolled.

With that said, I would recommend to define arrays in a more clear-cut way, e.g. like this:

$files1 = @(4, 1024),
          @(7, 16)

or (using grouping expressions instead of array subexpressions) like this:

$files1 = (4, 1024),
          (7, 16)

to avoid surprises like the one you observed. The outer @() isn't necessary for defining an array here. PowerShell automatically detects that via the trailing comma at the end of the first line.

For further information see about_Operators.