6. Conversões

Nota editorial

Importante

A Especificação da Linguagem do Windows PowerShell 3.0 foi publicada em dezembro de 2012 e é baseada no Windows PowerShell 3.0. Essa especificação não reflete o estado atual do PowerShell. Não há nenhum plano para atualizar essa documentação para refletir o estado atual. Esta documentação é apresentada aqui para referência histórica.

O documento de especificação está disponível como um documento do Microsoft Word do Centro de Download da Microsoft em: https://www.microsoft.com/download/details.aspx?id=36389 esse documento do Word foi convertido para apresentação aqui no Microsoft Learn. Durante a conversão, algumas alterações editoriais foram feitas para acomodar a formatação para a plataforma Docs. Alguns erros de digitação e pequenos foram corrigidos.

Uma conversão de tipo é executada quando um valor de um tipo é usado em um contexto que requer um tipo diferente. Se essa conversão ocorrer automaticamente, ela será conhecida como conversão implícita. (Um exemplo comum disso é com alguns operadores que precisam converter um ou mais dos valores designados por seus operandos.) A conversão implícita é permitida desde que o sentido do valor de origem seja preservado, como nenhuma perda de precisão de um número quando ele é convertido.

O operador de conversão (seção 7.2.9) permite a conversão explícita.

As conversões são discutidas abaixo, com informações complementares sendo fornecidas conforme necessário na descrição de cada operador em §6.19.

A conversão explícita de um valor para o tipo que ele já tem não causa nenhuma alteração nesse valor ou em sua representação.

As regras para manipulação de conversão quando o valor de uma expressão está sendo vinculado a um parâmetro são abordadas na seção 6.17.

6.1 Conversão em nulo

Um valor de qualquer tipo pode ser descartado explicitamente por meio da conversão dele para o tipo nulo. Não há resultado.

6.2 Conversão em bool

As regras para converter qualquer valor em tipo bool são as seguintes:

• Um valor numérico ou char de zero é convertido em False; um valor numérico ou char diferente de zero é convertido em True.
• Um valor de tipo nulo é convertido em False.
• Uma cadeia de caracteres de comprimento 0 é convertida em False; uma cadeia de caracteres de comprimento > 0 é convertida em True.
• Um parâmetro de comutador com valor $true é convertido em Verdadeiro, e um com valor $false é convertido em Falso.
• Todos os outros valores de tipo de referência não nulos são convertidos em True.

Se o tipo implementar IList:

• Se o comprimento do objeto for igual a > 2, o valor será convertido em True.
• Se o comprimento do objeto for 1 e esse primeiro elemento não for um IList, se o valor desse elemento for true, o valor será convertido em True.
• Caso contrário, se a contagem do primeiro elemento >= 1, o valor será convertido para True.
• Caso contrário, o valor será convertido em False.

6.3 Conversão em char

As regras para converter qualquer valor no tipo char são as seguintes:

• A conversão de um valor do tipo bool, decimal, float ou double está em erro.
• Um valor de tipo nulo é convertido no caractere nulo (U+0000).
• Um valor de tipo inteiro cujo valor pode ser representado no tipo char tem esse valor; caso contrário, a conversão está em erro.
• A conversão de um valor de cadeia de caracteres com um comprimento diferente de 1 está em erro.
• Um valor de cadeia de caracteres de comprimento 1 é convertido em um caractere com o valor correspondente a esse único caractere.
• Um valor de tipo numérico cujo valor após o arredondamento de qualquer parte fracionária pode ser representado no tipo de destino tem esse valor arredondado; caso contrário, a conversão está em erro.
• Para outros valores de tipo de referência, se o tipo de referência der suporte a essa conversão, essa conversão será usada; caso contrário, a conversão está em erro.

6.4 Conversão em inteiro

As regras para converter qualquer valor em byte, int ou long são as seguintes:

• O valor bool False é convertido em zero; o valor bool True é convertido em 1.
• Um valor de tipo char cujo valor pode ser representado no tipo de destino tem esse valor; caso contrário, a conversão está em erro.
• Um valor de tipo numérico cujo valor após o arredondamento de qualquer parte fracionária pode ser representado no tipo de destino tem esse valor arredondado; caso contrário, a conversão está em erro.
• Um valor de tipo nulo é convertido em zero.
• Uma cadeia de caracteres que representa um número é convertida conforme descrito em §6.16. Se após o truncamento da parte fracionária o resultado puder ser representado no tipo de destino, a cadeia de caracteres está bem formada e tem o tipo de destino; caso contrário, a conversão está em erro. Se a cadeia de caracteres não representar um número, a conversão estará em erro.
• Para outros valores de tipo de referência, se o tipo de referência der suporte a essa conversão, essa conversão será usada; caso contrário, a conversão está em erro.

6.5 Conversão em float e double

As regras para converter qualquer valor em tipo flutuante ou duplo são as seguintes:

• O valor bool False é convertido em zero; o valor bool True é convertido em 1.
• Um valor char é representado exatamente.
• Um valor de tipo numérico será representado com precisão, se possível; no entanto, para conversões de int, long e decimal em float e para conversões de long e decimal em double, alguns dos bits menos significativos do valor inteiro poderão ser perdidos.
• Um valor de tipo nulo é convertido em zero.
• Uma cadeia de caracteres que representa um número é convertida conforme descrito em §6.16; caso contrário, a conversão está em erro.
• Para outros valores de tipo de referência, se o tipo de referência der suporte a essa conversão, essa conversão será usada; caso contrário, a conversão está em erro.

6.6 Conversão em decimal

As regras para converter qualquer valor em decimal de tipo são as seguintes:

• O valor bool False é convertido em zero; o valor bool True é convertido em 1.
• Um valor de tipo char é representado exatamente.
• Um valor de tipo numérico é representado exatamente; no entanto, se esse valor for muito grande ou muito pequeno para caber no tipo de destino, a conversão estará em erro.
• Um valor de tipo nulo é convertido em zero.
• Uma cadeia de caracteres que representa um número é convertida conforme descrito em §6.16; caso contrário, a conversão está em erro.
• Para outros valores de tipo de referência, se o tipo de referência der suporte a essa conversão, essa conversão será usada; caso contrário, a conversão está em erro.
• A escala do resultado de uma conversão bem-sucedida é tal que a parte fracionária não tem zeros finais.

6.7 Conversão em objeto

O valor de qualquer tipo, exceto o tipo nulo (4.1.2) pode ser convertido em objeto type. O valor mantém seu tipo e representação.

6.8 Conversão em cadeia de caracteres

As regras para converter qualquer valor em cadeia de caracteres de tipo são as seguintes:

• O valor bool $false é convertido em "False"; o valor bool $true é convertido em "True".
• Um valor de tipo char é convertido em uma cadeia de caracteres de 1 caractere que contém esse caractere.
• Um valor de tipo numérico é convertido em uma cadeia de caracteres que tem a forma de um literal numérico correspondente. No entanto, o resultado não terá espaços à esquerda ou à direita, nenhum sinal de adição à esquerda, os inteiros terão base 10 e não haverá nenhum sufixo de tipo. Para uma conversão decimal, a escala é preservada. Para valores de -∞, +∞ e NaN, as cadeias de caracteres resultantes são "-Infinity", "Infinity" e "NaN", respectivamente.
• Um valor de tipo nulo é convertido na cadeia de caracteres vazia.
• Para uma matriz unidimensional, o resultado é uma cadeia de caracteres que contém o valor de cada elemento nessa matriz, do início ao fim, convertido em cadeia de caracteres, com elementos sendo separados pelo Separador de Campo de Saída atual (§2.3.2.2). Para uma matriz que tem elementos que são matrizes próprias, somente os elementos de nível superior são convertidos. A cadeia de caracteres usada para representar o valor de um elemento que é uma matriz é definida pela implementação. Para uma matriz multidimensional, ela é nivelada (§9,12) e, em seguida, tratada como uma matriz unidimensional.
• Um valor de tipo nulo é convertido na cadeia de caracteres vazia.
• Um valor de tipo de bloco de script é convertido em uma cadeia de caracteres que contém o texto desse bloco sem os caracteres { e } delimitadores.
• Para um valor de tipo de enumeração, o resultado é uma cadeia de caracteres que contém o nome de cada constante de enumeração codificada nesse valor, separada por vírgulas.
• Para outros valores de tipo de referência, se o tipo de referência der suporte a essa conversão, essa conversão será usada; caso contrário, a conversão está em erro.

A cadeia de caracteres usada para representar o valor de um elemento que é uma matriz tem o formulário System.Type[], System.Type[,]e assim por diante. Para outros tipos de referência, o método ToString será chamado. Para outros tipos enumeráveis, o valor de origem é tratado como uma matriz unidimensional.

6.9 Conversão em matriz

As regras para converter qualquer valor em um tipo de matriz são as seguintes:

• O tipo de destino pode não ser uma matriz multidimensional.
• Um valor de tipo nulo é mantido como está.
• Para um valor escalar diferente de $null ou um valor do tipo hashtable, uma nova matriz de 1 elemento é criada cujo valor é o escalar após a conversão para o tipo de elemento de destino.
• Para um valor de matriz unidimensional, uma nova matriz do tipo de destino é criada e cada elemento é copiado com conversão da matriz de origem para o elemento correspondente na matriz de destino.
• Para um valor de matriz multidimensional, essa matriz é primeiro nivelada (§9,12) e, em seguida, tratada como um valor de matriz unidimensional.
• Um valor de cadeia de caracteres é convertido em uma matriz de caracteres com o mesmo comprimento com caracteres sucessivos da cadeia de caracteres ocupando posições correspondentes na matriz.

Para outros tipos enumeráveis, uma nova matriz de 1 elemento é criada cujo valor é o elemento correspondente após a conversão para o tipo de elemento de destino, se essa conversão existir. Caso contrário, a conversão está em erro.

6.10 Conversão em xml

O objeto é convertido em cadeia de caracteres de tipo e, em seguida, em um objeto de documento XML do tipo xml.

6.11 Conversão em regex

Uma expressão que designa um valor de cadeia de caracteres de tipo pode ser convertida em tipo regex.

6.12 Conversão em scriptblock

As regras para converter qualquer valor no tipo scriptblock são as seguintes:

• Um valor de cadeia de caracteres é tratado como o nome de um comando, seguido opcionalmente por argumentos para uma chamada a esse comando.

6.13 Conversão em tipos de enumeração

As regras para converter qualquer valor em um tipo de enumeração são as seguintes:

• Um valor do tipo cadeia de caracteres que contém um dos valores nomeados (em relação a maiúsculas e minúsculas) para um tipo de enumeração será convertido nesse valor nomeado.
• Um valor do tipo cadeia de caracteres que contém uma lista separada por vírgulas de valores nomeados (com relação a maiúsculas e minúsculas) para um tipo de enumeração será convertido no OR bit a bit de todos os valores nomeados.

6.14 Conversão para outros tipos de referência

As regras para converter qualquer valor em um tipo de referência diferente de um tipo de matriz ou cadeia de caracteres são as seguintes:

• Um valor de tipo nulo é mantido como está.
• Caso contrário, o comportamento será definido pela implementação.

Vários mecanismos entram em jogo aqui; isso inclui o possível uso de construtores de argumento único ou construtores padrão, caso o valor seja uma tabela de hash, operadores de conversão implícita e explícita e métodos Parse para o tipo de destino; o uso de Convert.ConvertTo; e o mecanismo de conversão ETS.

6.15 Conversões aritméticas habituais

Se nenhum dos operandos designar um valor com tipo numérico, então

• Se o operando esquerdo designar um valor do tipo bool, a conversão estará em erro.
• Caso contrário, todos os operandos que designam o valor $null serão convertidos em zero do tipo int e o processo continuará com as conversões numéricas listadas abaixo.
• Caso contrário, se o operando esquerdo designar um valor do tipo char e o operando direito designar um valor do tipo bool, a conversão estará em erro.
• Caso contrário, se o operando esquerdo designar um valor de cadeia de caracteres de tipo, mas não representar um número (§6,16), a conversão estará em erro.
• Caso contrário, se o operando direito designar um valor do tipo cadeia de caracteres, mas não representar um número (§6,16), a conversão estará incorreta.
• Caso contrário, todos os operandos que designam valores de cadeia de caracteres de tipo são convertidos em números (§6,16) e o processo continua com as conversões numéricas listadas abaixo.
• Caso contrário, a conversão está em erro.

Conversões numéricas:

• Se um operando designar um valor de tipo decimal, o valor designado pelo outro operando será convertido para esse tipo, se necessário. O resultado terá o tipo decimal.
• Caso contrário, se um operando designar um valor do tipo duplo, o valor designado pelo outro operando será convertido nesse tipo, se necessário. O resultado terá o tipo double.
• Caso contrário, se um operando designar um valor do tipo float, os valores designados pelos dois operandos serão convertidos no tipo double, se necessário. O resultado terá o tipo double.
• Caso contrário, se um operando designar um valor de tipo longo, o valor designado pelo outro valor de operando será convertido nesse tipo, se necessário. O resultado terá o primeiro tipo da sequência long e double que poderá representar seu valor.
• Caso contrário, os valores designados por ambos os operandos serão convertidos para o tipo int, se necessário. O resultado terá o primeiro na sequência int, long, double que puder representar seu valor sem truncamento.

6.16 Conversão de cadeia de caracteres para tipo numérico

Dependendo de seu conteúdo, uma cadeia de caracteres pode ser convertida explicitamente ou implicitamente em um valor numérico. Especificamente

• Uma cadeia de caracteres vazia é convertida no valor zero.
• Os espaços à esquerda e à direita são ignorados; no entanto, uma cadeia de caracteres pode não consistir apenas em espaços.
• Uma cadeia de caracteres que contém apenas espaço em branco e/ou terminadores de linha é convertida no valor zero.
• É permitido um sinal de + ou - à esquerda.
• Um número inteiro pode ter um prefixo hexadecimal (0x ou 0X).
• Um expoente com sinal opcional é permitido.
• Sufixos de tipo e multiplicadores não são permitidos.
• As cadeias de caracteres distintas de caso "-Infinity", "Infinity" e "NaN" são reconhecidas como os valores -∞, +∞ e NaN, respectivamente.

6.17 Conversão durante a associação de parâmetro

Para obter informações sobre a associação de parâmetros, consulte §8.14.

Quando o valor de uma expressão está sendo associado a um parâmetro, há considerações adicionais de conversão, conforme descrito abaixo:

• Se o tipo de parâmetro for switch (§4.2.5, §8.10.5) e o parâmetro não tiver argumentos, o valor do parâmetro no comando chamado será definido como $true. Se o tipo de parâmetro for diferente de switch, um parâmetro sem argumentos resultará em erro.
• Se o tipo de parâmetro for do tipo "switch" e o valor do argumento for $null, o valor do parâmetro será definido como $false.
• Se o tipo de parâmetro for objeto ou for o mesmo que o tipo do argumento, o valor do argumento será passado sem conversão.
• Se o tipo de parâmetro não for objeto ou scriptblock, um argumento do tipo scriptblock será avaliado e o resultado será passado como o valor do argumento. (Isso é conhecido como associação de bloco de script atrasada). Se o tipo do parâmetro for object ou scriptblock, um argumento com o tipo scriptblock será passado como está.
• Se o tipo de parâmetro for uma coleção do tipo T2 e o argumento for um escalar do tipo T1, esse escalar será convertido em uma coleção do tipo T2 que contém um elemento. Se necessário, o valor escalar é convertido no tipo T2 usando as regras de conversão desta seção.
• Se o tipo de parâmetro for um tipo escalar diferente de objeto e o argumento for uma coleção, o argumento estará em erro.
• Se o tipo de parâmetro esperado for uma coleção do tipo T2 e o argumento for uma coleção do tipo T1, o argumento será convertido em uma coleção do tipo T2 com o mesmo comprimento que a coleção de argumentos. Se necessário, os valores do elemento de coleção de argumentos são convertidos para o tipo T2 usando as regras de conversão desta seção.
• Se as etapas acima e as conversões especificadas anteriormente neste capítulo não forem suficientes, as regras em §6.18 serão aplicadas. Se eles falharem, a associação de parâmetro falhará.

6.18 Conversão do .NET

Para uma conversão implícita, as conversões internas do PowerShell são tentadas primeiro. Se eles não puderem resolver a conversão, os conversores personalizados do .NET abaixo serão tentados, em ordem, de cima para baixo. Se for encontrada uma conversão, mas ela gerar uma exceção, a conversão falhará.

• PSTypeConverter: há duas maneiras de associar a implementação da classe PSTypeConverter com sua classe de destino: por meio do arquivo de configuração de tipo (types.ps1xml) ou aplicando o atributo System.ComponentModel.TypeConverterAttribute à classe de destino. Consulte a documentação do SDK do PowerShell para obter mais informações.

• TypeConverter: esse tipo CLR fornece uma maneira unificada de converter tipos de valores em outros tipos, bem como para acessar valores padrão e sub-propriedades. O tipo mais comum de conversor é aquele que converte de e para uma representação de texto. O conversor de tipo de uma classe está vinculado à classe por meio de um System.ComponentModel.TypeConverterAttribute. A menos que esse atributo seja substituído, todas as classes que herdam dessa classe usam o mesmo conversor de tipo que a classe base. Consulte o SDK do PowerShell e a documentação do Microsoft .NET Framework para obter mais informações.

• Método de Análise: se o tipo de origem for cadeia de caracteres e o tipo de destino tiver um método chamado Parse, esse método será chamado para executar a conversão.

• Construtores: se o tipo de destino tiver um construtor usando um único argumento cujo tipo é o do tipo de origem, esse construtor será chamado para executar a conversão.

• Operador de Conversão Implícita: Se o tipo de origem tiver um operador de conversão implícita que converte para o tipo de destino, esse operador será chamado para realizar a conversão.

• Operador de Conversão Explícita: Se o tipo de origem tiver um operador de conversão explícita que converta para o tipo de destino, esse operador será chamado para executar a conversão. Se o tipo de destino tiver um operador de conversão explícita que converte do tipo de origem, esse operador será chamado para executar a conversão.

• IConvertable: System.Convert.ChangeType é chamado para executar a conversão.

6.19 Conversão em ordered

As regras para converter qualquer valor no pseudo-tipo ordenado são as seguintes:

• Se o valor for um literal de hash (§2.3.5.6), o resultado será um objeto com um tipo definido por implementação que se comporta como uma tabela hash, e a ordem das chaves corresponde à ordem especificada no literal de hash.
• Caso contrário, o comportamento será definido pela implementação.

Somente literais de hash (seção 2.3.5.6) podem ser convertidos em ordered. O resultado será uma instância de System.Collections.Specialized.OrderedDictionary.

6.20 Conversão em pscustomobject

As regras para converter qualquer valor no pseudo-tipo pscustomobject são as seguintes:

• Um valor do tipo hashtable é convertido em um objeto do PowerShell. Cada chave no hashtable se torna um NoteProperty com o valor correspondente.
• Caso contrário, o comportamento será definido pela implementação.

A conversão é sempre permitida, mas não altera o tipo do valor.