6. Преобразования

Редакционная заметка

Важный

спецификация языка Windows PowerShell 3.0 была опубликована в декабре 2012 года и основана на Windows PowerShell 3.0. Эта спецификация не отражает текущее состояние PowerShell. Нет плана обновить эту документацию, чтобы отразить текущее состояние. Эта документация представлена здесь для получения исторической справки.

Документ спецификации доступен в виде документа Microsoft Word из Центра загрузки Майкрософт: https://www.microsoft.com/download/details.aspx?id=36389. Этот документ Word был преобразован для представления здесь, на платформе Microsoft Learn. Во время преобразования некоторые редакционные изменения были внесены в соответствии с форматированием платформы Docs. Исправлены некоторые опечатки и незначительные ошибки.

Преобразование типа в выполняется, когда значение одного типа используется в контексте, требующем другого типа. Если такое преобразование происходит автоматически, оно называется неявным преобразованием. (Типичным примером этого является некоторые операторы, которые должны преобразовывать одно или несколько значений, назначенных операнды.) Неявное преобразование допускается при сохранении смысла исходного значения, например без потери точности числа при преобразовании.

Оператор приведения (§7.2.9) позволяет выполнять явное преобразование .

Ниже обсуждаются преобразования, и при необходимости дополнительные сведения предоставляются в описании каждого оператора в §6.19.

Явное преобразование значения в тип, который он уже имеет, не приводит к изменению этого значения или его представления.

Правила передачи преобразования при привязке значения выражения к параметру рассматриваются в §6.17.

6.1 Преобразование в void

Значение любого типа можно отменить явным образом путем приведения его к типу void. Нет результата.

6.2 Преобразование в bool

Правила преобразования любого значения в булевский тип следующие:

• Числовое или символьное значение нуля преобразуется в False; Числовое или символьное значение, не равное нулю, преобразуется в True.
• Значение типа NULL преобразуется в False.
• Строка длины 0 преобразуется в False; Строка длины > 0 преобразуется в True.
• Параметр коммутатора со значением $true преобразуется в True, а один со значением $false преобразуется в False.
• Все остальные значения ссылочного типа, отличные от NULL, преобразуются в True.

Если тип реализует IList:

• Если длина объекта > 2, значение преобразуется в True.
• Если длина объекта равна 1, а первый элемент не является IList, то если значение этого элемента имеет значение true, значение преобразуется в True.
• В противном случае, если счетчик первого элемента >= 1, значение преобразуется в True.
• В противном случае значение преобразуется в False.

6.3 Преобразование в char

Правила преобразования любого значения в символ типа приведены следующим образом:

• Преобразование значения типа bool, decimal, float или double содержит ошибку.
• Значение типа NULL преобразуется в символ NULL (U+0000).
• Целочисленное значение, которое может быть представлено в типе char, имеет это значение; в противном случае преобразование будет ошибочным.
• Преобразование строкового значения с длиной, отличной от 1, является ошибкой.
• Строковое значение длиной 1 преобразуется в символ с тем же значением.
• Числовое значение типа, значение которого после округления любой его дробной части может быть представлено в целевом типе с округленным значением; в противном случае преобразование будет ошибочным.
• Для других значений ссылочного типа, если ссылочный тип поддерживает такое преобразование, используется это преобразование; в противном случае преобразование является ошибочным.

6.4 Преобразование в целое число

Правила преобразования любого значения в тип byte, int или long следующие:

• Логическое значение False преобразуется в ноль; логическое значение True преобразуется в 1.
• Значение типа char, если оно может быть представлено в целевом типе, сохраняется; в противном случае происходит ошибка преобразования.
• Числовое значение типа, значение которого после округления любой его дробной части может быть представлено в целевом типе с округленным значением; в противном случае преобразование будет ошибочным.
• Значение типа NULL преобразуется в нулевой.
• Строка, представляющая число, преобразуется, как описано в §6.16. Если после усечения дробной части результат может быть представлен к целевому типу, строка является корректной и соответствует целевому типу; в противном случае преобразование содержит ошибку. Если строка не представляет число, преобразование выполняется с ошибкой.
• Для других значений ссылочного типа, если ссылочный тип поддерживает такое преобразование, используется это преобразование; в противном случае преобразование является ошибочным.

6.5 Преобразование в float и double

Правила преобразования любого значения в тип float или double приведены следующим образом:

• Логическое значение False преобразуется в ноль; логическое значение True преобразуется в 1.
• Значение char представлено точно.
• Числовое значение типа представлено точно, если это возможно; однако для преобразований из int, long и decimal в float, а также для преобразований из long и decimal в double, некоторые из наименее значительных битов целочисленного значения могут быть потеряны.
• Значение типа NULL преобразуется в нулевой.
• Строка, представляющая число, преобразуется, как описано в §6.16; если нет, преобразование выполнено с ошибкой.
• Для других значений ссылочного типа, если ссылочный тип поддерживает такое преобразование, используется это преобразование; в противном случае преобразование является ошибочным.

6.6 Преобразование в десятичное

Правила преобразования любого значения в десятичный тип приведены следующим образом:

• Логическое значение False преобразуется в ноль; логическое значение True преобразуется в 1.
• Значение типа char представлено точно.
• Числовое значение типа представлено точно; однако, если это значение слишком велико или слишком мало, чтобы поместиться в целевой тип, преобразование приводит к ошибке.
• Значение типа NULL преобразуется в нулевой.
• Строка, представляющая число, преобразуется, как описано в §6.16; если нет, преобразование выполнено с ошибкой.
• Для других значений ссылочного типа, если ссылочный тип поддерживает такое преобразование, используется это преобразование; в противном случае преобразование является ошибочным.
• Масштаб результата успешного преобразования заключается в том, что дробная часть не имеет конечных нулей.

6.7 Преобразование в объект

Значение любого типа, кроме типа NULL (4.1.2), можно преобразовать в объект type. Значение сохраняет свой тип и представление.

6.8 Преобразование в строку

Правила преобразования любого значения в строку типа приведены следующим образом:

• Логическое значение, $false преобразуется в false; Логическое значение, $true преобразуется в значение True.
• Значение типа char преобразуется в 1-символьную строку, содержащую этот символ.
• Числовое значение типа преобразуется в строку в форме соответствующего числового литерала. Однако результат не имеет начальных или конечных пробелов, ведущего знака «плюс», целые числа используют десятичную систему, и нет суффикса типа. Для десятичного преобразования масштаб сохраняется. Для значений -∞, +∞ и NaN полученные строки — "-Бесконечность", "Бесконечность" и "NaN" соответственно.
• Значение типа NULL преобразуется в пустую строку.
• Для 1-размерного массива результатом является строка, содержащая значение каждого элемента в этом массиве, начиная с конца, преобразованного в строку, с элементами, разделенными текущим разделителем полей вывода (§2.3.2.2). Для массива с элементами, которые являются сами массивами, преобразуются только элементы верхнего уровня. Строка, используемая для представления значения элемента, являющегося массивом, определяется реализацией. Для многомерного массива он плоский (§9.12) и затем рассматривается как 1-мерный массив.
• Значение типа NULL преобразуется в пустую строку.
• Значение типа scriptblock преобразуется в строку, содержащую текст этого блока без разделителей { и } символов.
• Для значения типа перечисления результатом является строка, содержащая имя каждой константы перечисления, закодированной в этом значении, разделенной запятыми.
• Для других значений ссылочного типа, если ссылочный тип поддерживает такое преобразование, используется это преобразование; в противном случае преобразование является ошибочным.

Строка, используемая для представления значения элемента, являющегося массивом, имеет форму System.Type[], System.Type[,]и т. д. Для других ссылочных типов вызывается метод ToString. Для других перечисляемых типов исходное значение обрабатывается как 1-мерный массив.

6.9 Преобразование в массив

Ниже приведены правила преобразования любого значения в тип массива:

• Целевой тип не может быть многомерным массивом.
• Значение типа NULL сохраняется как есть.
• Для скалярного значения, отличного от $null или значения хэш-файла типа, создается новый массив элементов 1, значение которого является скалярным после преобразования в тип целевого элемента.
• Для 1-мерного значения массива создается новый массив целевого типа, и каждый элемент копируется с преобразованием из исходного массива в соответствующий элемент в целевом массиве.
• Для многомерного значения массива этот массив сначала преобразуется в плоский вид (§9.12), а затем преобразуется в 1-мерное значение массива.
• Строковое значение преобразуется в массив символов, имеющих ту же длину с последовательными символами из строки, занимающей соответствующие позиции в массиве.

Для других перечисляемых типов создается новый массив 1-элементов, значение которого является соответствующим элементом после преобразования в тип целевого элемента, если такое преобразование существует. В противном случае преобразование имеет ошибку.

6.10 Преобразование в xml

Объект преобразуется в строку типа, а затем в объект XML-документа типа xml.

6.11 Преобразование в regex

Выражение, указывающее значение строки типа, может быть преобразовано в тип regex.

6.12 Преобразование в скриптблок

Ниже приведены правила преобразования любого значения в тип scriptblock.

• Строковое значение интерпретируется как имя команды, за которым могут следовать аргументы для вызова этой команды.

6.13 Преобразование в типы перечисления

Правила преобразования любого значения в тип перечисления приведены следующим образом:

• Значение строки типа, содержащей одно из именованных значений (в отношении регистра) для типа перечисления, преобразуется в это именованное значение.
• Значение строкового типа, содержащее разделенный запятыми список именованных значений с учетом регистра для типа перечисления, преобразуется в побитовое ИЛИ всех этих именованных значений.

6.14 Преобразование в другие ссылочные типы

Ниже приведены правила преобразования любого значения в ссылочный тип, отличный от типа массива или строки:

• Значение типа NULL сохраняется как есть.
• В противном случае поведение определяется реализацией.

Ряд механизмов вступает в игру здесь, включая возможное использование конструкторов с одним аргументом или конструкторов по умолчанию, если значение является хэш-таблицей, неявные и явные операторы преобразования, а также методы Parse для целевого типа, использование метода Convert.ConvertTo и механизм преобразования ETS.

6.15 Обычные арифметические преобразования

Если ни один операнд не обозначает значение с числовым типом, то

• Если левый операнд обозначает значение типа bool, преобразование ошибочно.
• В противном случае все операнды, указывающие значение $null, преобразуются в ноль типа int, и процесс продолжается с числовыми преобразованиями, перечисленными ниже.
• В противном случае, если левый операнд обозначает значение типа char, а правый операнд — значение типа bool, преобразование является ошибочным.
• В противном случае, если левый операнд обозначает значение типа строки, но не представляет число (§6.16), преобразование считается ошибочным.
• В противном случае, если правый операнд обозначает значение типа строка, но не представляет число (§6.16), возникает ошибка в преобразовании.
• В противном случае все операнды, указывающие значения строки типа, преобразуются в числа (§6.16), а процесс продолжается с числовыми преобразованиями, перечисленными ниже.
• В противном случае преобразование имеет ошибку.

Числовые преобразования:

• Если один операнд обозначает десятичное значение типа, то при необходимости значение, указанное другим операндом, преобразуется в этот тип. Результат имеет десятичный тип.
• В противном случае, если один операнд обозначает значение типа double, значение, указанное другим операндом, преобразуется в этот тип при необходимости. Результат имеет тип данных double.
• В противном случае, если один операнд обозначает значение типа float, значения, назначенные обоими операндами, преобразуются в тип double, при необходимости. Результат имеет тип данных double.
• В противном случае, если один операнд обозначает значение типа long, значение, указанное другим операндом, преобразуется в этот тип при необходимости. Результат имеет тип, первый в последовательности: long и double, который может представлять его значение.
• В противном случае значения, назначенные обоими операндами, преобразуются в тип int при необходимости. Результат имеет первый в последовательности int, long, double, который может представлять его значение без усечения.

6.16 Преобразование из строки в числовый тип

В зависимости от его содержимого строка может быть преобразована явно или неявно в числовое значение. Конкретно

• Пустая строка преобразуется в нулевое значение.
• Начальные и конечные пробелы игнорируются; однако строка может не состоять только из пробелов.
• Строка, содержащая только пробелы и (или) разделители строк, преобразуется в значение ноль.
• Разрешен один начальный знак + или -.
• Целочисленное число может иметь шестнадцатеричный префикс (0x или 0X).
• Допускается необязательно подписанный экспонент.
• Суффиксы типов и множители не допускаются.
• Отдельные строки регистра "-Бесконечность", "Бесконечность" и "NaN" распознаются как значения -∞, +∞ и NaN соответственно.

6.17 Преобразование во время привязки параметров

Сведения о привязке параметров см. в §8.14.

Если значение выражения привязано к параметру, существуют дополнительные рекомендации по преобразованию, как описано ниже:

• Если тип параметра переключен (§4.2.5, §8.10.5) и параметр не имеет аргумента, значение параметра в вызываемой команде имеет значение $true. Если тип параметра отличается от переключателя, то параметр без аргумента является ошибкой.
• Если тип параметра переключен, а значение аргумента $null, то для параметра задано значение $false.
• Если тип параметра является объектом или совпадает с типом аргумента, значение аргумента передается без преобразования.
• Если тип параметра не является объектом или скриптом, аргумент с типом scriptblock вычисляется, и его результат передается в качестве значения аргумента. (Это называется отложенной привязкой блока скрипта.) Если тип параметра является объектом или скриптблоком, аргумент с типом scriptblock передается как есть.
• Если тип параметра является коллекцией типа T2, а аргумент является скалярным типом T1, скаляр преобразуется в коллекцию типа T2, содержащую один элемент. При необходимости скалярное значение преобразуется в тип T2 с помощью правил преобразования этого раздела.
• Если тип параметра является скалярным типом, отличным от объекта, и аргумент является коллекцией, аргумент находится в ошибке.
• Если ожидаемый тип параметра является коллекцией типа T2, а аргумент является коллекцией типа T1, аргумент преобразуется в коллекцию типа T2 с той же длиной, что и коллекция аргументов. При необходимости значения элементов коллекции аргументов преобразуются в тип T2 с помощью правил преобразования этого раздела.
• Если описанные выше действия и преобразования, указанные ранее в этой главе, недостаточно, применяются правила в §6.18. В случае отказа привязка параметра не удаётся.

Преобразование .NET версии 6.18

При неявном преобразовании сначала используются встроенные механизмы преобразования PowerShell. Если они не могут устранить преобразование, пользовательские преобразователи .NET, приведенные ниже, выполняются в порядке сверху вниз. Если преобразование найдено, но вызывает исключение, преобразование завершилось сбоем.

• PSTypeConverter: существует два способа связывания реализации класса PSTypeConverter с целевым классом: через файл конфигурации типа (types.ps1xml) или путём применения атрибута System.ComponentModel.TypeConverterAttribute к целевому классу. Дополнительные сведения см. в документации по пакету SDK PowerShell.

• TypeConverter: этот тип CLR предоставляет унифицированный способ преобразования типов значений в другие типы, а также для доступа к стандартным значениям и вложенным свойствам. Наиболее распространенный тип преобразователя — это тот, который преобразует в текстовое представление и обратно. Преобразователь типов для класса привязан к классу с System.ComponentModel.TypeConverterAttribute. Если этот атрибут не переопределен, все классы, наследуемые от этого класса, используют тот же преобразователь типов, что и базовый класс. Дополнительные сведения см. в документации по пакету SDK PowerShell и платформе Microsoft .NET Framework.

• метод синтаксического анализа. Если исходный тип является строкой, а тип назначения имеет метод с именем Parse, этот метод вызывается для выполнения преобразования.

• конструкторы: если в целевом типе есть конструктор, принимающий один аргумент, тип которого совпадает с типом источника, этот конструктор вызывается для выполнения преобразования.

• оператор неявного приведения: если исходный тип имеет неявный оператор приведения, который преобразуется в целевой тип, этот оператор вызывается для выполнения преобразования.

• явный оператор приведения: если исходный тип имеет явный оператор приведения, который преобразуется в целевой тип, этот оператор вызывается для выполнения преобразования. Если тип назначения имеет явный оператор приведения, который выполняет преобразование из исходного типа, этот оператор вызывается для выполнения преобразования.

• IConvertable: вызывается System.Convert.ChangeType для выполнения преобразования.

6.19 Преобразование в упорядоченный

Ниже приведены правила преобразования любого значения в упорядоченный псевдотип:

• Если значение является хэш-литерлом (§2.3.5.6), результатом является объект с определенным типом реализации, который ведет себя как хэш-файл, а порядок ключей соответствует порядку, указанному в хэш-литерале.
• В противном случае поведение определяется реализацией.

Только хэш-литералы (§2.3.5.6) могут быть преобразованы в упорядоченный вид. Результатом является экземпляр System.Collections.Specialized.OrderedDictionary.

6.20 Преобразование в pscustomobject

Ниже приведены правила преобразования любого значения в псевдотип pscustomobject:

• Значение типа хэш-таблица преобразуется в объект PowerShell. Каждый ключ в хеш-таблице становится свойством NoteProperty с соответствующим значением.
• В противном случае поведение определяется реализацией.

Преобразование всегда допускается, но не изменяет тип значения.