about_Arrays

Breve descrição

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 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 nomeada $A que contenha 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 item colocando a vírgula antes do item único.

Por exemplo, para criar uma única matriz de item 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 objetos (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 para qualquer tipo suportado no .NET. Por exemplo, os objetos que Get-Process recupera para representar processos são do tipo System.Diagnostics.Process . Para criar uma matriz fortemente tipada de objetos de processo, digite 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. Qualquer que seja 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 matriz é 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á recebendo 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.

Acesso e uso de 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, invoque 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 fazer referência aos elementos em uma matriz usando um índice. Coloque o número de índice entre parênteses. Os valores de í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 o segundo a 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, tenha cuidado ao usar esta notação. Os ciclos de notação desde o limite final até o início da matriz.

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

2
1
0
9
8

Além disso, um erro comum é assumir 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 plus (+) para combinar um intervalo 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 plus. Por exemplo, para listar os elementos 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 looping, como foreach, fore 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 através da matriz e retorna cada valor na matriz until chegando ao 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 , 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

Devolve o número de dimensões na matriz. A maioria das matrizes no PowerShell tem apenas uma dimensão. Mesmo quando você acha que está construindo uma matriz multidimensional, como o 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 uma 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 em ordem de linha principal. 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 um array multidimensional, como replicação e concatenação, exigem que o array seja nivelado. O achatamento transforma a matriz em uma matriz de 1 dimensão de tipo sem restrições. A matriz resultante assume todos os elementos em ordem de linha principal. 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 em ordem de linha maior.

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

Métodos de matrizes

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 inteiros.

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

0
0
0

ForEach()

Permite iterar sobre todos os elementos da matriz e executar uma determinada operação para cada elemento da matriz.

O ForEach() método tem 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. Neste 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(digite convertToType)

O ForEach() método pode ser usado para converter os elementos para um tipo diferente, o exemplo a seguir mostra como converter uma lista de datas de cadeia de caracteres para [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.

Em que()

Permite filtrar ou selecionar os elementos da matriz. O script deve avaliar qualquer coisa 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 enum mode WhereOperatorSelectionMode:

• Default (0) - Devolver todos os artigos
• First (1) - Devolver o first artigo
• Last (2) - Devolver o last artigo
• SkipUntil (3) - Ignorar itens until condição é true, devolver 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) - Retornar 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 próximo exemplo 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 um 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 pelo 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 pela expressão scriptblock, o método para de Where() processar itens.

Isso significa que você recebe o first conjunto de itens não aprovados do Where() método. Depois que um item passa, o restante 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 passam.

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 Get-Membero , 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 dois exemplos seguintes.

,$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 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 de índice 1) 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 na $a matriz, exceto o valor na posição de índice 2, digite:

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

Para combinar duas matrizes em uma única matriz, use o operador plus (+). 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 e 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 ou Length . No entanto, se o resultado for um único objeto (singleton) e esse objeto tiver uma Count Length ou propriedade, 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 uma matriz de cadeias de caracteres, você precisa declarar a variável como uma matriz.

Neste exemplo, $result é uma matriz de cadeias de caracteres. O Count e Length da matriz é 1, e o Length do first 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 Sistema.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 suportam 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 verdadeiro 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 de 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 $filesarray . 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 obter valores de itens em uma coleção, mas não definir 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;}

Consulte também

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