Why is a leading comma required when creating an array?

Question

I want to create an array containing arrays of two numbers. Pretty straightforward. However, If I do not provide a leading comma before the first array, it is incorrect. Why is this leading comma required?

PS C:\src\powershell> Get-Content .\fr-btest.ps1
$files1 = @(
@(4, 1024)
, @((7), (16))
)

$files1
$files1.GetType()
$files1.Length
$files1.Count
'========'

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

$files2
$files2.GetType()
$files2.Length
$files2.Count

PS C:\src\powershell> .\fr-btest.ps1
4
1024
7
16

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     Object[]                                 System.Array
3
3
========
4
1024
7
16
True     True     Object[]                                 System.Array
2
2

Answer 1

@() 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.

Answer 2

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.

Answer 3

Powershell uses both a comma and a line break as an array separator. Your first declare:

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

Creates the following:

$files1[0] = 4
$files1[1] = 1024
$files1[2] = @(7,16)

Your second declare

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

Creates the following:

$files1[0] = @(4, 1024)
$files1[1] = @(7, 16)

As to the parsing decision, it is dependent on the first non-white space character encountered on a line: Array Literals In PowerShell and Understanding PowerShell Parsing Modes