Merge branch 'sdw-w351599-i10688' of https://github.com/sdwheeler/PowerShell-Docs into sdw-w351599-i10688

Author: sdwheeler

reference/7.5/Microsoft.PowerShell.Core/About/about_Type_Conversion.md

@@ -21,13 +21,13 @@ must understand how it works to avoid unexpected results.
 By default, PowerShell _variables_ aren't _type-constrained_. You can create a
 variable containing an instance of one type and later assign values of any
 other type. Also, PowerShell automatically converts values to other types, both
-explicitly and implicitly. While implicit type conversion is usually helpful,
-there are pitfalls, especially for users more familiar with languages have
-stricter type handling.
+explicitly and implicitly. While implicit type conversion can be helpful, there
+are pitfalls, especially for users more familiar with languages have stricter
+type handling.
 
-## Type-contrained variables and explicit types conversion
+## Type-constrained variables and explicit types conversion
 
-To _type-constrain_ a variables place a type literal to the left of the
+To type-constrain a variable, place a type literal to the left of the
 variable name in an assignment. For example:
 
 ```powershell
@@ -43,11 +43,11 @@ PS> $var.GetType().Name
 Int32
 ```
 
-This ensures that only values of the specified type can be assigned to the
-variable. If you try to assign a value of a different type that can be
+Type casting ensures that only values of the specified type can be assigned to
+the variable. If you try to assign a value of a different type that can be
 converted to the constrained type, PowerShell performs an implicit conversion.
-This is covered in more detail in the [Implicit type conversion][15] section of
-this article.
+For more information, see the [Implicit type conversion][03] section of this
+article.
 
 ### Numeric type conversion
 
@@ -67,7 +67,6 @@ Byte
 The value `42.1` is a **Double**. When you convert it to a **Byte**, the value
 is truncated to an integer `42`, which is small enough to fit into a **Byte**.
 
-
 ### Boolean type conversion
 
 A value of _any_ type can be coerced to a **Boolean**.
@@ -106,11 +105,10 @@ A value of _any_ type can be coerced to a **Boolean**.
 
 ### String type conversion
 
-A value of _any_ type can be coerced to a **String**.
-
-The default conversion is to call the `ToString()` method on the object.
+A value of _any_ type can be coerced to a **String**. The default conversion is
+to call the `ToString()` method on the object.
 
-Array are converted to strings. Each element in the array is converted to a
+Arrays are converted to strings. Each element in the array is converted to a
 string, individually and joined to the resulting string. By default, the
 converted values are separated by a space. The separator can be changed by
 setting the `$OFS` preference variable.
@@ -120,10 +118,9 @@ PS> [string] @(1, 2, 3)
 1 2 3
 ```
 
-For more information, see the entry for `$OFS` in
-[about_Preference_Variables][12].
+For more information about `$OFS`, see [about_Preference_Variables][09].
 
-A single string value can converted to an instance of a type if the type
+A single string value can be converted to an instance of a type if the type
 implements a static `Parse()` method. For example, `[bigint]'42'` is the same
 as `[bigint]::Parse('42', [cultureinfo]::InvariantCulture)`. The optional
 `[cultureinfo]::InvariantCulture` value binds to an `IFormatProvider` type
@@ -132,18 +129,18 @@ conversion. Not all implementations of `Parse()` methods have this parameter.
 
 > [!NOTE]
 > Conversion to and from strings is usually performed using the
-> [invariant culture][04]. Invariant culture is based on, but not identical to,
-> the US-English culture. Notably, it uses the periond (`.`) as the decimal
+> [invariant culture][16]. Invariant culture is based on, but not identical to,
+> the US-English culture. Notably, it uses the period (`.`) as the decimal
 > mark and US-style month-first dates by default. However, _binary cmdlets_
 > perform culture-sensitive conversion during parameter binding.
 
 ### Enum type conversion
 
-PowerShell can convert [System.Enum][03] types to and from **String**
-instances. For example, the typecast string `[System.PlatformId]'Unix'` is the
-same as the enum value `[System.PlatformId]::Unix`. PowerShell also handles
-flag-based enums correctly for comma-separated values inside a string or as an
-array of strings. Consider the following examples:
+PowerShell can convert [Enum][15] types to and from **String** instances. For
+example, the typecast string `[System.PlatformId]'Unix'` is the same as the
+enum value `[System.PlatformId]::Unix`. PowerShell also handles flag-based
+enums correctly for comma-separated values inside a string or as an array of
+strings. Consider the following examples:
 
 ```powershell
 [System.Reflection.TypeAttributes]'Public, Abstract'
@@ -159,10 +156,12 @@ These examples are equivalent to the enum expression:
 
 ### Other type conversions
 
-A single value (non-array) can be converted to an instance of a type if that
-type has a (public) single-parameter constructor of the same type (or a type
-that the value can be coerced to). For example, the following two lines are
-equivalent:
+A single value (non-array) can be converted to an instance of a type if:
+
+- That type has a (public) single-parameter constructor
+- And the value is same type or can be coerced to the type of the parameter
+
+For example, the following two lines are equivalent:
 
 ```powershell
 [regex]'a|b'
@@ -179,7 +178,7 @@ and `1.2` is stored as a **Double**. Integers larger than `[Int32]::MaxValue`
 are stored as **Int64**. While `42` can be stored as a **Byte** and `1.2` can
 be stored as a **Single** type, the implicit typing uses **Int32** and
 **Double** respectively. For more information, see
-[about_Numeric_Literals][10].
+[about_Numeric_Literals][07].
 
 Literal strings are implicitly typed as **String**. Single-character **String**
 instances can be converted to and from the **Char** type. However, PowerShell
@@ -195,13 +194,14 @@ These contexts include:
 - Expressions using operators
 - Boolean contexts - PowerShell converts the conditional expressions of `if`,
   `while`, `do`, or `switch` statements to **Boolean** values, as previously
-  described. For more information, see [about_Booleans][08].
-- ETS type definitions - Type conversions can be defined in several ways:
-  - Using the **TypeConverter** parameter of [Update-TypeData][14]
-  - In [`Types.ps1xml`][13] files
-  - In compiled code for types decorated with a [`TypeConverterAttribute`][02]
+  described. For more information, see [about_Booleans][04].
+- Extended Type System (ETS) type definitions - Type conversions can be defined
+  in several ways:
+  - Using the **TypeConverter** parameter of [Update-TypeData][12]
+  - In [Types.ps1xml][10] files
+  - In compiled code for types decorated with a [TypeConverterAttribute][14]
     attribute
-  - Via classes derived from [`TypeConverter`][01] or [`PSTypeConverter`][06]
+  - Via classes derived from [TypeConverter][13] or [PSTypeConverter][18]
 
 ### Parameter binding conversions
 
@@ -211,19 +211,19 @@ functions, scripts, scriptblocks, or .NET method where the parameter is
 declared with a specific type. Declaring a parameter with the type `[object]`
 or not defining a specific type allows any value type to be passed to a
 parameter. Parameters can also have custom conversions defined by decorating
-parameters with [ArgumentTransformationAttribute][05] attribute.
+parameters with [ArgumentTransformationAttribute][17] attribute.
 
-For more information about parameter binding, see [about_Parameter_Binding][11].
+For more information, see [about_Parameter_Binding][08].
 
-### Best practices for parameter bindin
+### Best practices for parameter binding
 
 For .NET methods, it's better to pass the exact type expected using a type
 casts where needed. Without exact types, PowerShell can select the wrong method
 overload. And, new method overloads added in future versions of .NET can break
-existing code. For an an extreme example of this problem see this
-[Stack Overflow question][21].
+existing code. For an extreme example of this problem, see this
+[Stack Overflow question][11].
 
-If you pass an arrary to a `[string]` typed parameter, PowerShell might convert
+If you pass an array to a `[string]` typed parameter, PowerShell might convert
 the array to a string as previously described. Consider the following basic
 function:
 
@@ -237,7 +237,7 @@ Test-String -String 1, 2
 ```
 
 This function outputs `1 2` because the array is converted to a string. To
-avoid this behavior, create an advanced function by adding the
+avoid this behavior, create an [advanced function][06] by adding the
 `[CmdletBinding()]` attribute.
 
 ```powershell
@@ -272,28 +272,28 @@ PS> (Get-Date).ToString(@(1, 2))
 PowerShell converts the array to the string `"1 2"`, which is passed to the
 **Format** parameter of the `ToString()` method.
 
-This is another example of an array conversion problem.
+The following example shows another instance of the array conversion problem.
 
 ```powershell
 PS> $bytes = [byte[]] @(1..16)
 PS> $guid = New-Object System.Guid($bytes)
 New-Object: Cannot find an overload for "Guid" and the argument count: "16".
 ```
 
-PowerShell treats the `$bytes` array as a list of individual parameters. even
+PowerShell treats the `$bytes` array as a list of individual parameters. Even
 though `$bytes` is an array of bytes and `System.Guid` has a `Guid(Byte[])`
 constructor.
 
-This very common code pattern is instance of _pseudo method syntax_, which
-doesn't always still works as intended. What it translates to is:
+This common code pattern is 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
 ```
 
-Given that `-ArgumentList` is types as `[object[]]`, a _single_ argument that
-happens to be an array (of any type) binds to it _element by element_. The
+Given that the type of **ArgumentList** is `[object[]]`, a single argument
+that happens to be an array (of any type) binds to it _element by element_. The
 workaround is to wrap `$bytes` in an outer array so that PowerShell looks for
 constructor with parameters that match the contents of the outer array.
 
@@ -347,7 +347,7 @@ behaviors.
 #### Numeric operations
 
 In numeric operations, even if both operands are the same numeric type, the
-result may be a different type, due to automatic _type-widening_ to accommodate
+result can be a different type, due to automatic _type-widening_ to accommodate
 the result.
 
 ```powershell
@@ -362,8 +362,8 @@ Double
 
 Even though both operands are integers, the result is _widened_ to a **Double**
 to support the fractional result. To get true integer division, use the
-`[int][Math]::Truncate()` or `[Math]::DivRem()` static methods. For more
-information, see [Truncate()][16] and [DivRem()][17].
+`[int]::Truncate()` or `[Math]::DivRem()` static methods. For more
+information, see [Truncate()][20] and [DivRem()][19].
 
 In integer arithmetic, when the result overflows the size of the operands,
 PowerShell defaults to using **Double** for the results, even when the result
@@ -388,7 +388,7 @@ Int64
 ```
 
 The `L` suffix on the `1` literal forces the result to be an **Int64**. For
-more information, see [about_Numeric_Literals][10].
+more information, see [about_Numeric_Literals][07].
 
 Usually, it's the left-hand side (LHS) operand of PowerShell operators that
 determines the data type used in the operation. PowerShell converts (coerces)
@@ -401,7 +401,7 @@ PS> 10 - ' 9 '
 
 In this example, the RHS operand is the string `' 9 '`, which is implicitly
 converted to an integer before the subtraction operation. The same is true for
-the comparision operators.
+the comparison operators.
 
 ```powershell
 PS> 10 -eq ' 10'
@@ -433,15 +433,16 @@ PS> '10' * '2'
 1010
 ```
 
-When you use `[bool]` values with arithmetic operators, PowerShell converts the
-values to integers where `$true` becomes `[int]1` and `$false` becomes `[int]0`.
+When you use **Boolean** values with arithmetic operators, PowerShell converts
+the values to integers: `$true` becomes `[int]1` and `$false` becomes
+`[int]0`.
 
 ```powershell
 PS> $false - $true
 -1
 ```
 
-The one excecption is the multiplication (`*`) of two booleans.
+The one exception is the multiplication (`*`) of two booleans.
 
 ```powershell
 PS> $false * $true
@@ -450,7 +451,7 @@ defined.
 ```
 
 For other LHS types, arithmetic operators only succeed if a given type
-custom-defines these operators via [operator overloading][07].
+custom-defines these operators via [operator overloading][02].
 
 #### Comparison operations
 
@@ -461,7 +462,7 @@ depends on whether the LHS type implements interfaces such as `IEquatable` and
 
 The collection-based comparison operators (`-in` and `-contains`) perform per
 element `-eq` comparisons until a match is found. It's each individual element
-of the collection operand that drives any type coersion.
+of the collection operand that drives any type coercion.
 
 ```powershell
 PS> $true -in 'true', 'false'
@@ -472,25 +473,25 @@ True
 
 Both examples return true because `'true' -eq $true` yields `$true`.
 
+For more information, see [about_Comparison_Operators][05].
+
 <!-- link references -->
-[01]: xref:System.ComponentModel.TypeConverter
-[02]: xref:System.ComponentModel.TypeConverterAttribute
-[03]: xref:System.Enum
-[04]: xref:System.Globalization.CultureInfo.InvariantCulture*
-[05]: xref:System.Management.Automation.ArgumentTransformationAttribute
-[06]: xref:System.Management.Automation.PSTypeConverter
-[07]: /dotnet/csharp/programming-guide/statements-expressions-operators/overloadable-operators
-[08]: /powershell/module/microsoft.powershell.core/about/about_Booleans
-[09]: /powershell/module/microsoft.powershell.core/about/about_Functions_Advanced
-[10]: /powershell/module/microsoft.powershell.core/about/about_Numeric_Literals
-[11]: /powershell/module/microsoft.powershell.core/about/about_parameter_binding
-[12]: /powershell/module/microsoft.powershell.core/about/about_preference_variables#ofs
-[13]: /powershell/module/microsoft.powershell.core/about/about_Types.ps1xml
-[14]: /powershell/module/microsoft.powershell.utility/update-typedata
-[15]: #implicit-type-conversion
-[16]: xref:System.Math.Truncate*
-[17]: xref:System.Math.DivRem*
-[19]: https://stackoverflow.com/a/76615570/45375
-[20]: https://stackoverflow.com/questions/73223637/passing-an-array-parameter-value
-[21]: https://stackoverflow.com/questions/76241804/how-does-powershell-split-consecutive-strings-not-a-single-letter
-[20816]: https://github.com/PowerShell/PowerShell/issues/20816
+[02]: /dotnet/csharp/programming-guide/statements-expressions-operators/overloadable-operators
+[03]: #implicit-type-conversion
+[04]: about_Booleans.md
+[05]: about_Comparison_Operators.md
+[06]: about_Functions_Advanced.md
+[07]: about_Numeric_Literals.md
+[08]: about_parameter_binding.md
+[09]: about_preference_variables.md#ofs
+[10]: about_Types.ps1xml.md
+[11]: https://stackoverflow.com/questions/76241804/how-does-powershell-split-consecutive-strings-not-a-single-letter
+[12]: xref:Microsoft.PowerShell.Utility.Update-TypeData
+[13]: xref:System.ComponentModel.TypeConverter
+[14]: xref:System.ComponentModel.TypeConverterAttribute
+[15]: xref:System.Enum
+[16]: xref:System.Globalization.CultureInfo.InvariantCulture*
+[17]: xref:System.Management.Automation.ArgumentTransformationAttribute
+[18]: xref:System.Management.Automation.PSTypeConverter
+[19]: xref:System.Math.DivRem*
+[20]: xref:System.Math.Truncate*