Skip to content

12/10/2024 PM Publish #11575

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Dec 10, 2024
Merged

12/10/2024 PM Publish #11575

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b00ec93
Add clarifications from mklement0 (#11573)
sdwheeler Dec 10, 2024
f9bc7a4
More updates (#11574)
sdwheeler Dec 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 55 additions & 11 deletions reference/5.1/Microsoft.PowerShell.Core/About/about_Type_Conversion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: Describes how and when PowerShell performs type conversions.
Locale: en-US
ms.date: 12/05/2024
ms.date: 12/10/2024
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_type_conversion?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Type_Conversion
Expand Down Expand Up @@ -40,11 +40,11 @@ PS> $var.GetType().Name
Int32
```

Type casting ensures that only values of the specified type can be assigned to
the variable. PowerShell performs an implicit conversion if you try to assign a
value of a different type that can be converted to the constrained type. For
more information, see the [Implicit type conversion][03] section of this
article.
Type constraining ensures that only values of the specified type can be
assigned to the variable. PowerShell performs an implicit conversion if you try
to assign a value of a different type that can be converted to the constrained
type. For more information, see the [Implicit type conversion][03] section of
this article.

### Numeric type conversion

Expand All @@ -64,6 +64,21 @@ Byte
The value `42.1` is a **Double**. When you cast it to a **Byte**, PowerShell
truncates it to an integer `42`, which is small enough to fit into a **Byte**.

When converting real numbers to integer types, PowerShell uses rounding rather
than truncation, specifically using the _rounding-to-nearest-even_ method.
The following examples illustrate this behavior. Both values are rounded to the
nearest even integer, `22`.

```powershell
PS> [byte]21.5
22
PS> [byte]22.5
22
```

For more information, see the _Midpoint values and rounding conventions_
section of the [Math.Round][21] method.

### Boolean type conversion

A value of _any_ type can be coerced to a **Boolean**.
Expand All @@ -85,7 +100,7 @@ A value of _any_ type can be coerced to a **Boolean**.
```

- For other types, null values, empty strings, and empty arrays are converted
to `$false`. Other values, including empty hashtables convert to `$true`.
to `$false`.

```powershell
PS> [boolean]''
Expand All @@ -94,7 +109,16 @@ A value of _any_ type can be coerced to a **Boolean**.
False
PS> [boolean]'Hello'
True
PS> [boolean]@(1,'Hello')
```

Other values, including empty hashtables convert to `$true`. Single-element
collections evaluate to the Boolean value of their one and only element.
Collections with more than 1 element are always `$true`.

```powershell
PS> [boolean]@(0)
False
PS> [boolean]@(0,0)
True
PS> [boolean]@{}
True
Expand Down Expand Up @@ -285,8 +309,9 @@ This common code pattern is an instance of _pseudo method syntax_, which
doesn't always work as intended. This syntax translates to:

```powershell
[byte[]] $bytes = 1..16
New-Object -TypeName System.Guid -ArgumentList $bytes # !! BROKEN
PS> [byte[]] $bytes = 1..16
PS> New-Object -TypeName System.Guid -ArgumentList $bytes
New-Object: Cannot find an overload for "Guid" and the argument count: "16".
```

Given that the type of **ArgumentList** is `[object[]]`, a single argument that
Expand All @@ -295,7 +320,8 @@ workaround is to wrap `$bytes` in an outer array so that PowerShell looks for a
constructor with parameters that match the contents of the outer array.

```powershell
PS> $guid = New-Object System.Guid(@(, $bytes))
PS> [byte[]] $bytes = 1..16
PS> $guid = New-Object -TypeName System.Guid -ArgumentList (, $bytes)
PS> $guid

Guid
Expand Down Expand Up @@ -385,6 +411,23 @@ Int64
The `L` suffix on the `1` literal forces the result to be an **Int64**. For
more information, see [about_Numeric_Literals][07].

Using the `L` suffix is the preferred approach because it avoids loss of
accuracy. If the type cast is applied after the calculation, you can lose
accuracy due to the late type conversion. In the following example, the result
is too large to fit into an **Int64** type so it is converted to a **Decimal**.

```powershell
PS> '{0:N0}' -f ([Int64]::MaxValue + 1L)
9,223,372,036,854,775,808
```

Type casting the result after the calculation results in a loss in precision.

```powershell
PS> '{0:N0}' -f [decimal]([Int64]::MaxValue + 1)
9,223,372,036,854,780,000
```

Usually, the left-hand side (LHS) operand of PowerShell operators determines
the data type used in the operation. PowerShell converts (coerces) the
right-hand side (RHS) operand to the required type.
Expand Down Expand Up @@ -490,3 +533,4 @@ For more information, see [about_Comparison_Operators][05].
[18]: xref:System.Management.Automation.PSTypeConverter
[19]: xref:System.Math.DivRem*
[20]: xref:System.Math.Truncate*
[21]: xref:System.Math.Round*#midpoint-values-and-rounding-conventions
66 changes: 55 additions & 11 deletions reference/7.4/Microsoft.PowerShell.Core/About/about_Type_Conversion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: Describes how and when PowerShell performs type conversions.
Locale: en-US
ms.date: 12/05/2024
ms.date: 12/10/2024
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_type_conversion?view=powershell-7.4&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Type_Conversion
Expand Down Expand Up @@ -40,11 +40,11 @@ PS> $var.GetType().Name
Int32
```

Type casting ensures that only values of the specified type can be assigned to
the variable. PowerShell performs an implicit conversion if you try to assign a
value of a different type that can be converted to the constrained type. For
more information, see the [Implicit type conversion][03] section of this
article.
Type constraining ensures that only values of the specified type can be
assigned to the variable. PowerShell performs an implicit conversion if you try
to assign a value of a different type that can be converted to the constrained
type. For more information, see the [Implicit type conversion][03] section of
this article.

### Numeric type conversion

Expand All @@ -64,6 +64,21 @@ Byte
The value `42.1` is a **Double**. When you cast it to a **Byte**, PowerShell
truncates it to an integer `42`, which is small enough to fit into a **Byte**.

When converting real numbers to integer types, PowerShell uses rounding rather
than truncation, specifically using the _rounding-to-nearest-even_ method.
The following examples illustrate this behavior. Both values are rounded to the
nearest even integer, `22`.

```powershell
PS> [byte]21.5
22
PS> [byte]22.5
22
```

For more information, see the _Midpoint values and rounding conventions_
section of the [Math.Round][21] method.

### Boolean type conversion

A value of _any_ type can be coerced to a **Boolean**.
Expand All @@ -85,7 +100,7 @@ A value of _any_ type can be coerced to a **Boolean**.
```

- For other types, null values, empty strings, and empty arrays are converted
to `$false`. Other values, including empty hashtables convert to `$true`.
to `$false`.

```powershell
PS> [boolean]''
Expand All @@ -94,7 +109,16 @@ A value of _any_ type can be coerced to a **Boolean**.
False
PS> [boolean]'Hello'
True
PS> [boolean]@(1,'Hello')
```

Other values, including empty hashtables convert to `$true`. Single-element
collections evaluate to the Boolean value of their one and only element.
Collections with more than 1 element are always `$true`.

```powershell
PS> [boolean]@(0)
False
PS> [boolean]@(0,0)
True
PS> [boolean]@{}
True
Expand Down Expand Up @@ -285,8 +309,9 @@ This common code pattern is an instance of _pseudo method syntax_, which
doesn't always work as intended. This syntax translates to:

```powershell
[byte[]] $bytes = 1..16
New-Object -TypeName System.Guid -ArgumentList $bytes # !! BROKEN
PS> [byte[]] $bytes = 1..16
PS> New-Object -TypeName System.Guid -ArgumentList $bytes
New-Object: Cannot find an overload for "Guid" and the argument count: "16".
```

Given that the type of **ArgumentList** is `[object[]]`, a single argument that
Expand All @@ -295,7 +320,8 @@ workaround is to wrap `$bytes` in an outer array so that PowerShell looks for a
constructor with parameters that match the contents of the outer array.

```powershell
PS> $guid = New-Object System.Guid(@(, $bytes))
PS> [byte[]] $bytes = 1..16
PS> $guid = New-Object -TypeName System.Guid -ArgumentList (, $bytes)
PS> $guid

Guid
Expand Down Expand Up @@ -385,6 +411,23 @@ Int64
The `L` suffix on the `1` literal forces the result to be an **Int64**. For
more information, see [about_Numeric_Literals][07].

Using the `L` suffix is the preferred approach because it avoids loss of
accuracy. If the type cast is applied after the calculation, you can lose
accuracy due to the late type conversion. In the following example, the result
is too large to fit into an **Int64** type so it is converted to a **Decimal**.

```powershell
PS> '{0:N0}' -f ([Int64]::MaxValue + 1L)
9,223,372,036,854,775,808
```

Type casting the result after the calculation results in a loss in precision.

```powershell
PS> '{0:N0}' -f [decimal]([Int64]::MaxValue + 1)
9,223,372,036,854,780,000
```

Usually, the left-hand side (LHS) operand of PowerShell operators determines
the data type used in the operation. PowerShell converts (coerces) the
right-hand side (RHS) operand to the required type.
Expand Down Expand Up @@ -490,3 +533,4 @@ For more information, see [about_Comparison_Operators][05].
[18]: xref:System.Management.Automation.PSTypeConverter
[19]: xref:System.Math.DivRem*
[20]: xref:System.Math.Truncate*
[21]: xref:System.Math.Round*#midpoint-values-and-rounding-conventions
66 changes: 55 additions & 11 deletions reference/7.5/Microsoft.PowerShell.Core/About/about_Type_Conversion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: Describes how and when PowerShell performs type conversions.
Locale: en-US
ms.date: 12/05/2024
ms.date: 12/10/2024
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_type_conversion?view=powershell-7.5&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Type_Conversion
Expand Down Expand Up @@ -40,11 +40,11 @@ PS> $var.GetType().Name
Int32
```

Type casting ensures that only values of the specified type can be assigned to
the variable. PowerShell performs an implicit conversion if you try to assign a
value of a different type that can be converted to the constrained type. For
more information, see the [Implicit type conversion][03] section of this
article.
Type constraining ensures that only values of the specified type can be
assigned to the variable. PowerShell performs an implicit conversion if you try
to assign a value of a different type that can be converted to the constrained
type. For more information, see the [Implicit type conversion][03] section of
this article.

### Numeric type conversion

Expand All @@ -64,6 +64,21 @@ Byte
The value `42.1` is a **Double**. When you cast it to a **Byte**, PowerShell
truncates it to an integer `42`, which is small enough to fit into a **Byte**.

When converting real numbers to integer types, PowerShell uses rounding rather
than truncation, specifically using the _rounding-to-nearest-even_ method.
The following examples illustrate this behavior. Both values are rounded to the
nearest even integer, `22`.

```powershell
PS> [byte]21.5
22
PS> [byte]22.5
22
```

For more information, see the _Midpoint values and rounding conventions_
section of the [Math.Round][21] method.

### Boolean type conversion

A value of _any_ type can be coerced to a **Boolean**.
Expand All @@ -85,7 +100,7 @@ A value of _any_ type can be coerced to a **Boolean**.
```

- For other types, null values, empty strings, and empty arrays are converted
to `$false`. Other values, including empty hashtables convert to `$true`.
to `$false`.

```powershell
PS> [boolean]''
Expand All @@ -94,7 +109,16 @@ A value of _any_ type can be coerced to a **Boolean**.
False
PS> [boolean]'Hello'
True
PS> [boolean]@(1,'Hello')
```

Other values, including empty hashtables convert to `$true`. Single-element
collections evaluate to the Boolean value of their one and only element.
Collections with more than 1 element are always `$true`.

```powershell
PS> [boolean]@(0)
False
PS> [boolean]@(0,0)
True
PS> [boolean]@{}
True
Expand Down Expand Up @@ -285,8 +309,9 @@ This common code pattern is an instance of _pseudo method syntax_, which
doesn't always work as intended. This syntax translates to:

```powershell
[byte[]] $bytes = 1..16
New-Object -TypeName System.Guid -ArgumentList $bytes # !! BROKEN
PS> [byte[]] $bytes = 1..16
PS> New-Object -TypeName System.Guid -ArgumentList $bytes
New-Object: Cannot find an overload for "Guid" and the argument count: "16".
```

Given that the type of **ArgumentList** is `[object[]]`, a single argument that
Expand All @@ -295,7 +320,8 @@ workaround is to wrap `$bytes` in an outer array so that PowerShell looks for a
constructor with parameters that match the contents of the outer array.

```powershell
PS> $guid = New-Object System.Guid(@(, $bytes))
PS> [byte[]] $bytes = 1..16
PS> $guid = New-Object -TypeName System.Guid -ArgumentList (, $bytes)
PS> $guid

Guid
Expand Down Expand Up @@ -385,6 +411,23 @@ Int64
The `L` suffix on the `1` literal forces the result to be an **Int64**. For
more information, see [about_Numeric_Literals][07].

Using the `L` suffix is the preferred approach because it avoids loss of
accuracy. If the type cast is applied after the calculation, you can lose
accuracy due to the late type conversion. In the following example, the result
is too large to fit into an **Int64** type so it is converted to a **Decimal**.

```powershell
PS> '{0:N0}' -f ([Int64]::MaxValue + 1L)
9,223,372,036,854,775,808
```

Type casting the result after the calculation results in a loss in precision.

```powershell
PS> '{0:N0}' -f [decimal]([Int64]::MaxValue + 1)
9,223,372,036,854,780,000
```

Usually, the left-hand side (LHS) operand of PowerShell operators determines
the data type used in the operation. PowerShell converts (coerces) the
right-hand side (RHS) operand to the required type.
Expand Down Expand Up @@ -490,3 +533,4 @@ For more information, see [about_Comparison_Operators][05].
[18]: xref:System.Management.Automation.PSTypeConverter
[19]: xref:System.Math.DivRem*
[20]: xref:System.Math.Truncate*
[21]: xref:System.Math.Round*#midpoint-values-and-rounding-conventions