Corrections needed in the new `about_Type_Conversion` help topic.

[mklement0]

Prerequisites

• Existing Issue: Search the existing issues for this repository. If there is an issue that fits your needs do not file a new one. Subscribe, react, or comment on that issue instead.
• Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Typo in Get-Foo cmdlet" instead of "Typo."
• Verify Version: If there is a mismatch between documentation and the behavior on your system, ensure that the version you are using is the same as the documentation. Check this box if they match or the issue you are reporting is not version specific.

Links

• https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_type_conversion?view=powershell-5.1&WT.mc_id=ps-gethelp
• https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_type_conversion?view=powershell-7.4&WT.mc_id=ps-gethelp
• https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_type_conversion?view=powershell-7.5&WT.mc_id=ps-gethelp

Summary

Thankfully, PR #11568 introduced an about_Type_Conversion conceptual help topic.

Below are some corrections.

Details

Type casting ensures that only values of the specified type can be assigned to
the variable

This should be "Type constraining" (or "Type constraints ensure ...").

---

When you cast it (42.1) to a Byte, PowerShell truncates it to an integer 42

While that is technically true in this particular case, it would be helpful to explain that rounding is generally performed when converting to an integer type, specifically half-to-even rounding; e.g. [byte] 21.5 and [byte] 22.5 are both rounded to 22.

---

empty arrays are converted to $false. Other values, including empty hashtables convert to $true.

This is missing an important edge case: a single-element array (enumerable) is coerced by the value of that element, so that [bool] @(0) is $false, for instance.

---

PS> $guid = New-Object System.Guid(@(, $bytes))

This example stil uses pseudo method syntax; the proper form is either PS> $guid = New-Object System.Guid (, $bytes) (spelled out: PS> $guid = New-Object -TypeName System.Guid -ArgumentList (, $bytes))

---

PS> ([Int64]([int]::MaxValue + 1)).GetType().Name
PS> ([int]::MaxValue + 1L).GetType().Name

It is important to note that the 2nd approach is preferable, as it avoids loss of accuracy:
If the cast is applied after the calculation, loss of accuracy may already have occurred, namely with integer values that cannot be represented accurately as [double]s:

# OK - no loss of accuracy due to using a [decimal] literal as an operand:
[long]::maxvalue + 1d  # -> 9223372036854775808

# !! Loss of accuracy, due to the intermediate to-[double] conversion.
[decimal] ([long]::maxvalue + 1)  # -> 9223372036854780000

Suggested Fix

No response

[sdwheeler]

This is missing an important edge case: a single-element array (enumerable) is coerced by the value of that element, so that [bool] @(0) is $false, for instance.

This is not a corner case as much as it is a case where each element of the array is inspected for conversion.

[sdwheeler]

This example still uses pseudo method syntax; the proper form is either PS> $guid = New-Object System.Guid (, $bytes) (spelled out: PS> $guid = New-Object -TypeName System.Guid -ArgumentList (, $bytes))

Is it important that the workaround is also pseudo method syntax or not? The important part is using the @(,) wrapper or the new() method to workaround the issue.

[mklement0]

Thanks for the update.

This is not a corner case

It is a corner case in that a single-element array is the only array where the element determines the "truthiness":

[bool] @(0) is $false, but [bool] @(0, 0) is $true

This is correctly pointed out in about_Booleans, and I think deserves a mention here too, along with a link to the latter topic; from the latter:

Single-element collections evaluate to the Boolean value of their one and only element.
Collections with more than 1 element are always $true.

---

Is it important that the workaround is also pseudo method syntax or not?

I do think it is important not to use any instances of pseudo method syntax in the official documentation - except to illustrate why it shouldn't be used.

In the case at hand, proper argument-mode syntax has the added advantage of not needing @(...), just (...):
New-Object System.Guid (, $bytes)

[sdwheeler]

OK, I see your point here. I have submitted further updates.