about_Arrays

Descrição breve

Descreve matrizes, que são estruturas de dados projetadas para armazenar coleções de itens.

Descrição longa

Uma matriz é uma estrutura de dados projetada para armazenar uma coleção de itens. Os itens podem ser do mesmo tipo ou de tipos diferentes.

A partir do Windows PowerShell 3.0, uma coleção de zero ou um objeto tem algumas propriedades de matrizes.

Criando e inicializando uma matriz

Para criar e inicializar uma matriz, atribua vários valores a uma variável. Os valores armazenados na matriz são delimitados com uma vírgula e separados do nome da variável pelo operador de atribuição (=).

Por exemplo, para criar uma matriz chamada $A que contém os sete valores numéricos (inteiros) de 22, 5, 10, 8, 12, 9 e 80, digite:

$A = 22,5,10,8,12,9,80

A vírgula também pode ser usada para inicializar uma única matriz de itens, colocando a vírgula antes do único item.

Por exemplo, para criar uma matriz de item único chamada $B contendo o valor único de 7, digite:

$B = ,7

Você também pode criar e inicializar uma matriz usando o operador de intervalo (..). O exemplo a seguir cria uma matriz contendo os valores de 5 a 8.

$C = 5..8

Como resultado, $C contém quatro valores: 5, 6, 7 e 8.

Quando nenhum tipo de dados é especificado, o PowerShell cria cada matriz como uma matriz de objeto (System.Object[]). Para determinar o tipo de dados de uma matriz, use o GetType() método. Por exemplo:

$A.GetType()

Para criar uma matriz fortemente tipada, ou seja, uma matriz que pode conter apenas valores de um tipo específico, converta a variável como um tipo de matriz, como string[], long[] ou int32[]. Para converter uma matriz, preceda o nome da variável com um tipo de matriz entre colchetes. Por exemplo:

[int32[]]$ia = 1500, 2230, 3350, 4000

Como resultado, a $ia matriz pode conter apenas inteiros.

Você pode criar matrizes que são convertidas em qualquer tipo com suporte no .NET. Por exemplo, os objetos que Get-Process são recuperados para representar processos são do tipo System.Diagnostics.Process . Para criar uma matriz fortemente tipada de objetos de processo, insira o seguinte comando:

[Diagnostics.Process[]]$zz = Get-Process

O operador de subexpressão de matriz

O operador de subexpressão de matriz cria uma matriz a partir das instruções dentro dela. O que quer que a instrução dentro do operador produza, o operador a coloca em uma matriz. Mesmo que haja zero ou um objeto.

A sintaxe do operador de array é a seguinte:

@( ... )

Você pode usar o operador de matriz para criar uma matriz de zero ou um objeto. Por exemplo:

$a = @("Hello World")
$a.Count

1

$b = @()
$b.Count

0

O operador de matriz é útil em scripts quando você está obtendo objetos, mas não sabe quantos esperar. Por exemplo:

$p = @(Get-Process Notepad)

Para obter mais informações sobre o operador de subexpressão de matriz, consulte about_Operators.

Acessando e usando elementos de matriz

Lendo uma matriz

Você pode se referir a uma matriz usando seu nome de variável. Para exibir todos os elementos na matriz, chame o nome da matriz. Por exemplo, $a é uma matriz dos números de 0 a 9:

$a

0
1
2
3
4
5
6
7
8
9

Você pode se referir aos elementos em uma matriz usando um índice. Coloque o número de índice entre parênteses. Os valores do índice começam em 0. Por exemplo, para exibir o first $a elemento na matriz, digite:

$a[0]

0

Para exibir o terceiro elemento na $a matriz, digite:

$a[2]

2

Você pode recuperar parte da matriz usando um operador de intervalo para o índice. Por exemplo, para recuperar do segundo ao quinto elementos da matriz, digite:

$a[1..4]

1
2
3
4

Números count negativos do final da matriz. Por exemplo, -1 refere-se ao last elemento da matriz. Para exibir os last três elementos da matriz, em ordem crescente de índice, digite:

$a = 0 .. 9
$a[-3..-1]

7
8
9

Se você digitar índices negativos em ordem decrescente, sua saída será alterada.

$a = 0 .. 9
$a[-1..-3]

9
8
7

No entanto, seja cauteloso ao usar essa notação. A notação vai do limite final ao início da matriz.

$a = 0 .. 9
$a[2..-2]

2
1
0
9
8

Além disso, um erro comum é supor que $a[0..-2] se refere a todos os elementos da matriz, exceto um last . Refere-se aos firstelementos , last, e second-to-last na matriz.

Você pode usar o operador de adição (+) para combinar intervalos com uma lista de elementos em uma matriz. Por exemplo, para exibir os elementos nas posições de índice 0, 2 e 4 a 6, digite:

$a = 0 .. 9
$a[0,2+4..6]

0
2
4
5
6

Além disso, para listar vários intervalos e elementos individuais, você pode usar o operador de adição. Por exemplo, para listar os elementos de zero a dois, quatro a seis e o elemento no oitavo tipo posicional:

$a = 0..9
$a[+0..2+4..6+8]

0
1
2
4
5
6
8

Iterações sobre elementos de matriz

Você também pode usar construções de loop, como foreach, for, e while loops, para se referir aos elementos em uma matriz. Por exemplo, para usar um foreach loop para exibir os elementos na $a matriz, digite:

$a = 0..9
foreach ($element in $a) {
  $element
}

0
1
2
3
4
5
6
7
8
9

O foreach loop itera pela matriz e retorna cada valor na matriz until atingindo o final da matriz.

O for loop é útil quando você está incrementando contadores enquanto examina os elementos em uma matriz. Por exemplo, para usar um for loop para retornar todos os outros valores em uma matriz, digite:

$a = 0..9
for ($i = 0; $i -le ($a.length - 1); $i += 2) {
  $a[$i]
}

0
2
4
6
8

Você pode usar um while loop para exibir os elementos em uma matriz until em que uma condição definida não é mais verdadeira. Por exemplo, para exibir os elementos na $a matriz enquanto o índice da matriz for menor que 4, digite:

$a = 0..9
$i=0
while($i -lt 4) {
  $a[$i]
  $i++
}

0
1
2
3

Propriedades de matrizes

Count ou Length ou LongLength

Para determinar quantos itens estão em uma matriz, use a Length propriedade ou seu Count alias. Longlength é útil se a matriz contiver mais de 2.147.483.647 elementos.

$a = 0..9
$a.Count
$a.Length

10
10

Rank

Retorna o número de dimensões na matriz. A maioria das matrizes no PowerShell tem apenas uma dimensão. Mesmo quando você pensa que está construindo uma matriz multidimensional como no exemplo a seguir:

$a = @(
  @(0,1),
  @("b", "c"),
  @(Get-Process)
)

"`$a rank: $($a.Rank)"
"`$a length: $($a.Length)"
"`$a[2] length: $($a[2].Length)"
"Process `$a[2][1]: $($a[2][1].ProcessName)"

Neste exemplo, você está criando uma matriz unidimensional que contém outras matrizes. Isso também é conhecido como matriz irregular. A Rank propriedade provou que isso é unidimensional. Para acessar itens em uma matriz irregular, os índices devem estar entre colchetes separados ([]).

$a rank: 1
$a length: 3
$a[2] length: 348
Process $a[2][1]: AcroRd32

As matrizes multidimensionais são armazenadas na ordem principal da linha. O exemplo a seguir mostra como criar uma matriz verdadeiramente multidimensional.

[string[,]]$rank2 = [string[,]]::New(3,2)
$rank2.rank
$rank2.Length
$rank2[0,0] = 'a'
$rank2[0,1] = 'b'
$rank2[1,0] = 'c'
$rank2[1,1] = 'd'
$rank2[2,0] = 'e'
$rank2[2,1] = 'f'
$rank2[1,1]

2
6
d

Para acessar itens em uma matriz multidimensional, separe os índices usando uma vírgula (,) dentro de um único conjunto de colchetes ([]).

Algumas operações em uma matriz multidimensional, como replicação e concatenação, exigem que essa matriz seja nivelada. O nivelamento transforma a matriz em uma matriz 1-dimensional de tipo irrestrito. A matriz resultante assume todos os elementos na ordem principal da linha. Considere o seguinte exemplo:

$a = "red",$true
$b = (New-Object 'int[,]' 2,2)
$b[0,0] = 10
$b[0,1] = 20
$b[1,0] = 30
$b[1,1] = 40
$c = $a + $b
$a.GetType().Name
$b.GetType().Name
$c.GetType().Name
$c

A saída mostra que $c é uma matriz de 1 dimensão que contém os itens de $a e $b na ordem principal da linha.

Object[]
Int32[,]
Object[]
red
True
10
20
30
40

Métodos de arrays

Clear

Define todos os valores de elemento como o default valor do tipo de elemento da matriz. O Clear() método não redefine o tamanho da matriz.

No exemplo $a a seguir está uma matriz de objetos.

$a = 1, 2, 3
$a.Clear()
$a | % { $null -eq $_ }

True
True
True

Neste exemplo, $intA é explicitamente digitado para conter números inteiros.

[int[]] $intA = 1, 2, 3
$intA.Clear()
$intA

0
0
0

ForEach()

Permite iterar sobre todos os elementos do array e realizar uma determinada operação para cada elemento do array.

O ForEach() método possui várias sobrecargas que executam operações diferentes.

ForEach(scriptblock expression)
ForEach(scriptblock expression, object[] arguments)
ForEach(type convertToType)
ForEach(string propertyName)
ForEach(string propertyName, object[] newValue)
ForEach(string methodName)
ForEach(string methodName, object[] arguments)

ForEach(expressão scriptblock)

ForEach(expressão scriptblock, argumentos object [])

Esse método foi adicionado no PowerShell v4.

O exemplo a seguir mostra como usar o ForEach() método. Nesse caso, a intenção é gerar o valor quadrado dos elementos na matriz.

$a = @(0 .. 3)
$a.ForEach({ $_ * $_})

0
1
4
9

Assim como o parâmetro ArgumentList de ForEach-Object, o arguments parâmetro permite a passagem de uma matriz de argumentos para um bloco de script configurado para aceitá-los.

Para obter mais informações sobre o comportamento de ArgumentList, consulte about_Splatting.

ForEach(tipo convertToType)

O ForEach() método pode ser usado para converter os elementos em um tipo diferente; o exemplo a seguir mostra como converter uma lista de datas de cadeia de caracteres em [DateTime] tipo.

("1/1/2017", "2/1/2017", "3/1/2017").ForEach([datetime])

Sunday, January 1, 2017 12:00:00 AM
Wednesday, February 1, 2017 12:00:00 AM
Wednesday, March 1, 2017 12:00:00 AM

ForEach(string propertyName)

ForEach(string propertyName, object[] newValue)

O ForEach() método também pode ser usado para recuperar ou definir valores de propriedade para cada item na coleção.

# Set all LastAccessTime properties of files to the current date.
(dir 'C:\Temp').ForEach('LastAccessTime', (Get-Date))
# View the newly set LastAccessTime of all items, and find Unique entries.
(dir 'C:\Temp').ForEach('LastAccessTime') | Get-Unique

Wednesday, June 20, 2018 9:21:57 AM

ForEach(string methodName)

ForEach(string methodName, object[] argumentos)

Por fim, ForEach() os métodos podem ser usados para executar um método em cada item da coleção.

("one", "two", "three").ForEach("ToUpper")

ONE
TWO
THREE

Assim como o parâmetro ArgumentList de ForEach-Object, o arguments parâmetro permite a passagem de uma matriz de valores para um bloco de script configurado para aceitá-los.

Where()

Permite filtrar ou selecionar os elementos da matriz. O script deve ser avaliado como algo diferente de: zero (0), cadeia de caracteres $false vazia ou $null para que o elemento seja exibido após o Where(). Para obter mais informações sobre a avaliação booleana, consulte about_Booleans.

Há uma definição para o Where() método.

Where(scriptblock expression[, WhereOperatorSelectionMode mode
                            [, int numberToReturn]])

O Expression é um scriptblock necessário para filtragem, o mode argumento opcional permite recursos de seleção adicionais e o numberToReturn argumento opcional permite a capacidade de limitar quantos itens são retornados do filtro.

O valor de deve ser um valor de mode enumeração WhereOperatorSelectionMode:

• Default (0) - Devolver todos os itens
• First (1) - Devolva o first item
• Last (2) - Devolva o last item
• SkipUntil (3) - A condição de ignorar itens until é verdadeira, retorna todos os itens restantes (incluindo o item para o first qual a condição é verdadeira)
• Until (4) - A condição de devolução de todos os itens until é verdadeira
• Split (5) - Retorna uma matriz de dois elementos
  • O first elemento contém itens correspondentes
  • O segundo elemento contém os itens restantes

O exemplo a seguir mostra como selecionar todos os números ímpares da matriz.

(0..9).Where{ $_ % 2 }

1
3
5
7
9

O exemplo a seguir mostra como selecionar todas as cadeias de caracteres não vazias.

('hi', '', 'there').Where{ $_ }

hi
there

Default

O Default modo filtra itens usando o Expression scriptblock.

Se a numberToReturn for fornecido, ele especifica o número máximo de itens a serem devolvidos.

# Get the zip files in the current users profile, sorted by LastAccessTime
$Zips = dir $env:userprofile -Recurse '*.zip' | Sort-Object LastAccessTime
# Get the least accessed file over 100MB
$Zips.Where({$_.Length -gt 100MB}, 'Default', 1)

Last

$h = (Get-Date).AddHours(-1)
$logs = dir 'C:\' -Recurse '*.log' | Sort-Object CreationTime
# Find the last 5 log files created in the past hour
$logs.Where({$_.CreationTime -gt $h}, 'Last', 5)

SkipUntil

O SkipUntil modo ignora todos os objetos em uma coleção until , um objeto passa o filtro de expressão de bloco de script. Em seguida, ele retorna TODOS os itens de coleção restantes sem testá-los. Apenas um item aprovado é testado.

Isso significa que a coleção retornada contém itens aprovados e não aprovados que NÃO foram testados.

O número de itens retornados pode ser limitado passando um valor para o numberToReturn argumento.

$computers = "Server01", "Server02", "Server03", "localhost", "Server04"
# Find the first available online server.
$computers.Where({ Test-Connection $_ }, 'SkipUntil', 1)

localhost

Until

O Until modo inverte o SkipUntil modo. Ele retorna TODOS os itens em uma coleção until , um item passa a expressão de bloco de script. Depois que um item passa a expressão scriptblock, o Where() método para de processar itens.

Isso significa que você recebe o first conjunto de itens que não são aprovados do Where() método. Depois que um item passa, o resto NÃO é testado ou devolvido.

O número de itens retornados pode ser limitado passando um valor para o numberToReturn argumento.

# Retrieve the first set of numbers less than or equal to 10.
(1..50).Where({$_ -gt 10}, 'Until')
# This would perform the same operation.
(1..50).Where({$_ -le 10})

1
2
3
4
5
6
7
8
9
10

Split

O Split modo divide ou agrupa itens de coleção em duas coleções separadas. Aqueles que passam a expressão scriptblock e aqueles que não.

Se a numberToReturn for especificado, a first coleção conterá os itens de passagem , para não exceder o valor especificado.

Os objetos restantes, mesmo aqueles que PASSAM o filtro de expressão, são retornados na segunda coleção.

$running, $stopped = (Get-Service).Where({$_.Status -eq 'Running'}, 'Split')
$running

Status   Name               DisplayName
------   ----               -----------
Running  Appinfo            Application Information
Running  AudioEndpointBu... Windows Audio Endpoint Builder
Running  Audiosrv           Windows Audio
...

$stopped

Status   Name               DisplayName
------   ----               -----------
Stopped  AJRouter           AllJoyn Router Service
Stopped  ALG                Application Layer Gateway Service
Stopped  AppIDSvc           Application Identity
...

Obter os membros de uma matriz

Para obter as propriedades e os métodos de uma matriz, como a Length propriedade e o método SetValue , use o parâmetro InputObject do Get-Member cmdlet.

Quando você canaliza uma matriz para o Get-Member, o PowerShell envia os itens um de cada vez e Get-Member retorna o tipo de cada item na matriz (ignorando duplicatas).

Quando você usa o parâmetro InputObject , Get-Member retorna os membros da matriz.

Por exemplo, o comando a seguir obtém os membros da variável de $a matriz.

Get-Member -InputObject $a

Você também pode obter os membros de uma matriz digitando uma vírgula (,) antes do valor que é canalizado para o Get-Member cmdlet. A vírgula torna a matriz o segundo item em uma matriz de matrizes. O PowerShell canaliza as matrizes uma de cada vez e Get-Member retorna os membros da matriz. Como os próximos dois exemplos.

,$a | Get-Member

,(1,2,3) | Get-Member

Manipulando uma matriz

Você pode alterar os elementos em uma matriz, adicionar um elemento a uma matriz e combinar os valores de duas matrizes em uma terceira matriz.

Para alterar o valor de um elemento específico em uma matriz, especifique o nome da matriz e o índice do elemento que você deseja alterar e, em seguida, use o operador de atribuição (=) para especificar um novo valor para o elemento. Por exemplo, para alterar o valor do segundo item na $a matriz (posição 1 do índice) para 10, digite:

$a[1] = 10

Você também pode usar o método SetValue de uma matriz para alterar um valor. O exemplo a seguir altera o segundo valor (posição de índice 1) da $a matriz para 500:

$a.SetValue(500,1)

Você pode usar o += operador para adicionar um elemento a uma matriz. O exemplo a seguir mostra como adicionar um elemento à $a matriz.

$a = @(0..4)
$a += 5

Não é fácil excluir elementos de uma matriz, mas você pode criar uma nova matriz que contenha apenas elementos selecionados de uma matriz existente. Por exemplo, para criar a $t matriz com todos os elementos da matriz, exceto o valor na posição 2 do $a índice, digite:

$t = $a[0,1 + 3..($a.length - 1)]

Para combinar duas matrizes em uma única matriz, use o operador de adição (+). O exemplo a seguir cria duas matrizes, combina-as e exibe a matriz combinada resultante.

$x = 1,3
$y = 5,9
$z = $x + $y

Como resultado, a $z matriz contém 1, 3, 5 e 9.

Para excluir uma matriz, atribua um valor de $null à matriz. O comando a seguir exclui a matriz na $a variável.

$a = $null

Você também pode usar o Remove-Item cmdlet, mas atribuir um valor de $null é mais rápido, especialmente para matrizes grandes.

Matrizes de zero ou um

A partir do Windows PowerShell 3.0, uma coleção de zero ou um objeto tem as Count propriedades and Length . Além disso, você pode indexar em uma matriz de um objeto. Esse recurso ajuda a evitar erros de script que ocorrem quando um comando que espera uma coleção obtém menos de dois itens.

O exemplo a seguir mostra que uma variável que não contém objetos tem um Count e Length de 0.

PS> $a = $null
PS> $a.Count
0
PS> $a.Length
0

O exemplo a seguir mostra que uma variável que contém um objeto tem um Count e Length de 1. Você também pode usar a indexação de matriz para acessar o valor do objeto.

PS> $a = 4
PS> $a.Count
1
PS> $a.Length
1
PS> $a[0]
4
PS> $a[-1]
4

Ao executar um comando que pode retornar uma coleção ou um único objeto, você pode usar a indexação de matriz para acessar o valor do objeto sem precisar testar as Count propriedades or Length . No entanto, se o resultado for um único objeto (singleton) e esse objeto tiver uma Count propriedade or Length , o valor dessas propriedades pertencerá ao objeto singleton e não representará o número de itens na coleção.

No exemplo a seguir, o comando retorna um único objeto de cadeia de caracteres. O Length dessa string é 4.

PS> $result = 'one','two','three','four' | Where-Object {$_ -like 'f*'}
PS> $result.GetType().FullName
System.String
PS> $result
four
PS> $result.Count
1
PS❯ $result.Length
4

Se você quiser $result ser um array de strings, você precisa declarar a variável como um array.

Neste exemplo, $result é uma matriz de cadeias de caracteres. O Count e Length da matriz é 1, e o Length first do elemento é 4.

PS> [string[]]$result = 'one','two','three','four' |
    Where-Object {$_ -like 'f*'}
PS> $result.GetType().FullName
System.String[]
PS> $result
four
PS> $result.Count
1
PS> $result.Length
1
PS> $result[0].Length
4

Suporte de indexação para System.Tuple Objetos

O PowerShell 6.1 adicionou o suporte para acesso indexado de Tuple objetos, semelhante a matrizes. Por exemplo:

PS> $tuple = [Tuple]::Create(1, 'test')
PS> $tuple[0]
1
PS> $tuple[1]
test
PS> $tuple[0..1]
1
test
PS> $tuple[-1]
test

Ao contrário de matrizes e outros objetos de coleção, Tuple os objetos são tratados como um único objeto quando passados pelo pipeline ou por parâmetros que dão suporte a matrizes de objetos.

Para obter mais informações, consulte System.Tuple.

Indexação de tipos .NET que implementam IDictionary<TKey, TValue>

O PowerShell não chama o indexador true de um tipo para tipos que implementam a interface genérica IDictionary<TKey, TValue> . Em vez disso, quando recebe uma chave, o PowerShell testa a existência da chave usando TryGetValue(), que retorna $null quando a chave não existe.

Por outro lado, se você chamar o indexador true do tipo usando Item(<key>), o método lançará uma exceção quando a chave não existir.

O exemplo a seguir ilustra a diferença.

PS> [Collections.Generic.Dictionary[string, int]]::new()['nosuchkey']
# No output ($null)

PS> [Collections.Generic.Dictionary[string, int]]::new().Item('nosuchkey')
GetValueInvocationException: Exception getting "Item": "The given key 'nosuchkey'
 was not present in the dictionary."

Enumeração de acesso a membro

A partir do PowerShell 3.0, quando você usa o operador de acesso de membro para acessar um membro que não existe em uma coleção de listas, o PowerShell enumera automaticamente os itens na coleção e tenta acessar o membro especificado em cada item. Para obter mais informações, consulte about_Member-Access_Enumeration.

Exemplos

O exemplo a seguir cria dois novos arquivos e armazena os objetos resultantes na variável $filesde matriz. Como o objeto de matriz não tem o membro LastWriteTime , o valor de LastWriteTime é retornado para cada item na matriz.

$files = (New-Item -Type File -Force '/temp/t1.txt'),
         (New-Item -Force -Type File '/temp/t2.txt')
$files.LastWriteTime

Friday, June 25, 2021 1:21:17 PM
Friday, June 25, 2021 1:21:17 PM

A enumeração de acesso de membro permite que você obtenha valores de itens em uma coleção, mas não defina valores em itens em uma coleção. Por exemplo:

$files.LastWriteTime = (Get-Date).AddDays(-1)

InvalidOperation: The property 'LastWriteTime' cannot be found on this object.
Verify that the property exists and can be set.

Para definir os valores, você deve usar um método.

$files.set_LastWriteTime((Get-Date).AddDays(-1))
$files.LastWriteTime

Thursday, June 24, 2021 1:23:30 PM
Thursday, June 24, 2021 1:23:30 PM

O set_LastWriteTime() método é um membro oculto do objeto FileInfo . O exemplo a seguir mostra como localizar métodos ocultosset.

$files | Get-Member -Force -Name set_*

   TypeName: System.IO.FileInfo

Name              MemberType Definition
----              ---------- ----------
Attributes        Property   System.IO.FileAttributes Attributes {get;set;}
CreationTime      Property   datetime CreationTime {get;set;}
CreationTimeUtc   Property   datetime CreationTimeUtc {get;set;}
IsReadOnly        Property   bool IsReadOnly {get;set;}
LastAccessTime    Property   datetime LastAccessTime {get;set;}
LastAccessTimeUtc Property   datetime LastAccessTimeUtc {get;set;}
LastWriteTime     Property   datetime LastWriteTime {get;set;}
LastWriteTimeUtc  Property   datetime LastWriteTimeUtc {get;set;}

Confira também

• about_For
• about_ForEach
• about_Hash_Tables
• about_Member-Access_Enumeration
• about_Operators
• about_Assignment_Operators
• about_While