diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md index f39dc49e904..211f7a30b95 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that compare values in PowerShell. Locale: en-US -ms.date: 01/27/2022 +ms.date: 05/18/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Comparison Operators @@ -18,34 +18,47 @@ elements of a collection against an input value. Comparison operators let you compare values or finding values that match specified patterns. PowerShell includes the following comparison operators: -| Type | Operator | Comparison test | -| ----------- | ------------ | ----------------------------------------- | -| Equality | -eq | equals | -| | -ne | not equals | -| | -gt | greater than | -| | -ge | greater than or equal | -| | -lt | less than | -| | -le | less than or equal | -| Matching | -like | string matches wildcard pattern | -| | -notlike | string does not match wildcard pattern | -| | -match | string matches regex pattern | -| | -notmatch | string does not match regex pattern | -| Replacement | -replace | replaces strings matching a regex pattern | -| Containment | -contains | collection contains a value | -| | -notcontains | collection does not contain a value | -| | -in | value is in a collection | -| | -notin | value is not in a collection | -| Type | -is | both objects are the same type | -| | -isnot | the objects are not the same type | +**Equality** + +- `-eq`, `-ieq`, `-ceq` - equals +- `-ne`, `-ine`, `-cne` - not equals +- `-gt`, `-igt`, `-igt` - greater than +- `-ge`, `-ige`, `-cge` - greater than or equal +- `-lt`, `-ilt`, `-clt` - less than +- `-le`, `-ile`, `-cle` - less than or equal + +**Matching** + +- `-like`, `-ilike`, `-clike` - string matches wildcard pattern +- `-notlike`, `-inotlike`, `-cnotlike` - string does not match wildcard pattern +- `-match`, `-imatch`, `-cmatch` - string matches regex pattern +- `-notmatch`, `-inotmatch`, `-cnotmatch` - string does not match regex pattern + +**Replacement** + +- `-replace`, `-ireplace`, `-creplace` - replaces strings matching a regex + pattern + +**Containment** + +- `-contains`, `-icontains`, `-ccontains` - collection contains a value +- `-notcontains`, `-inotcontains`, `-cnotcontains` - collection does not + contain a value +- `-in` - value is in a collection +- `-notin` - value is not in a collection + +**Type** + +- `-is` - both objects are the same type +- `-isnot` - the objects are not the same type ## Common features -By default, string comparisons are case-insensitive. The equality operators have -explicit case-sensitive and case-insensitive forms. To make a comparison -operator case-sensitive, add a `c` after the `-`. For example, `-ceq` is the -case-sensitive version of `-eq`. To make the case-insensitivity explicit, add -an `i` after `-`. For example, `-ieq` is the explicitly case-insensitive -version of `-eq`. +String comparisons are case-insensitive unless you use the explicit +case-sensitive operator. To make a comparison operator case-sensitive, add a +`c` after the `-`. For example, `-ceq` is the case-sensitive version of `-eq`. +To make the case-insensitivity explicit, add an `i` after `-`. For example, +`-ieq` is the explicitly case-insensitive version of `-eq`. When the input of an operator is a scalar value, the operator returns a **Boolean** value. When the input is a collection, the operator returns the @@ -157,8 +170,8 @@ equality test result is **False** because they are different objects. To create comparable classes, you need to implement [System.IEquatable\][2] in your class. The following example demonstrates the partial implementation of a **MyFileInfoSet** class that implements [System.IEquatable\][2] and has two -properties, **File** and **Size**. The `Equals()` method returns **True** if the -File and Size properties of two **MyFileInfoSet** objects are the same. +properties, **File** and **Size**. The `Equals()` method returns **True** if +the File and Size properties of two **MyFileInfoSet** objects are the same. ```powershell class MyFileInfoSet : System.IEquatable[Object] { @@ -219,10 +232,10 @@ they return **True** or **False** depending on how the two sides compare: | Operator | Returns True when... | | -------- | -------------------------------------- | -| -gt | The left-hand side is greater | -| -ge | The left-hand side is greater or equal | -| -lt | The left-hand side is smaller | -| -le | The left-hand side is smaller or equal | +| `-gt` | The left-hand side is greater | +| `-ge` | The left-hand side is greater or equal | +| `-lt` | The left-hand side is smaller | +| `-le` | The left-hand side is smaller or equal | In the following examples, all statements return **True**. @@ -444,7 +457,7 @@ or when the input is a collection, the `$Matches` automatic variable is not overwritten. Consequently, it will contain the previously set value, or `$null` if the variable has not been set. When referencing `$Matches` after invoking one of these operators, consider verifying that the variable was set by the -current operator invocation by using a condition statement. +current operator invocation using a condition statement. Example: @@ -503,8 +516,8 @@ using capturing groups, and substitutions. Capture groups can be referenced in the `` string using the dollar sign (`$`) character before the group identifier. -In the following example, the `-replace` operator accepts a username in the form -of `DomainName\Username` and converts to the `Username@DomainName` format: +In the following example, the `-replace` operator accepts a username in the +form of `DomainName\Username` and converts to the `Username@DomainName` format: ```powershell $SearchExp = '^(?[\w-.]+)\\(?[\w-.]+)$' @@ -549,8 +562,8 @@ include a literal `$` in the resulting replacement. For example: '5.72' -replace '(.+)', '$$1' # Output: $1 ``` -To learn more, see [about_Regular_Expressions](about_Regular_Expressions.md) and -[Substitutions in Regular Expressions][4]. +To learn more, see [about_Regular_Expressions](about_Regular_Expressions.md) +and [Substitutions in Regular Expressions][4]. ### Substituting in a collection @@ -568,12 +581,12 @@ a5 ## Containment operators -The containment operators (`-contains`, `-notcontains`, `-in`, and `-notin`) are -similar to the equality operators, except that they always return a **Boolean** -value, even when the input is a collection. These operators stop comparing as -soon as they detect the first match, whereas the equality operators evaluate all -input members. In a very large collection, these operators return quicker than -the equality operators. +The containment operators (`-contains`, `-notcontains`, `-in`, and `-notin`) +are similar to the equality operators, except that they always return a +**Boolean** value, even when the input is a collection. These operators stop +comparing as soon as they detect the first match, whereas the equality +operators evaluate all input members. In a very large collection, these +operators return quicker than the equality operators. Syntax: @@ -587,10 +600,10 @@ Syntax: ### -contains and -notcontains These operators tell whether a set includes a certain element. `-contains` -returns **True** when the right-hand side (test object) matches one of the elements -in the set. `-notcontains` returns False instead. When the test object is a -collection, these operators use reference equality, i.e. they check whether one -of the set's elements is the same instance of the test object. +returns **True** when the right-hand side (test object) matches one of the +elements in the set. `-notcontains` returns False instead. When the test object +is a collection, these operators use reference equality, i.e. they check +whether one of the set's elements is the same instance of the test object. Examples: @@ -627,8 +640,8 @@ elements in the set. `-notin` returns **False** instead. When the test object is a set, these operators use reference equality to check whether one of the set's elements is the same instance of the test object. -The following examples do the same thing that the examples for `-contains` -and `-notcontains` do, but they are written with `-in` and `-notin` instead. +The following examples do the same thing that the examples for `-contains` and +`-notcontains` do, but they are written with `-in` and `-notin` instead. ```powershell "def" -in "abc", "def" # Output: True diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md index b1ff223ecee..4a871471c5c 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that compare values in PowerShell. Locale: en-US -ms.date: 01/27/2022 +ms.date: 05/18/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Comparison Operators @@ -18,34 +18,47 @@ elements of a collection against an input value. Comparison operators let you compare values or finding values that match specified patterns. PowerShell includes the following comparison operators: -| Type | Operator | Comparison test | -| ----------- | ------------ | ----------------------------------------- | -| Equality | -eq | equals | -| | -ne | not equals | -| | -gt | greater than | -| | -ge | greater than or equal | -| | -lt | less than | -| | -le | less than or equal | -| Matching | -like | string matches wildcard pattern | -| | -notlike | string does not match wildcard pattern | -| | -match | string matches regex pattern | -| | -notmatch | string does not match regex pattern | -| Replacement | -replace | replaces strings matching a regex pattern | -| Containment | -contains | collection contains a value | -| | -notcontains | collection does not contain a value | -| | -in | value is in a collection | -| | -notin | value is not in a collection | -| Type | -is | both objects are the same type | -| | -isnot | the objects are not the same type | +**Equality** + +- `-eq`, `-ieq`, `-ceq` - equals +- `-ne`, `-ine`, `-cne` - not equals +- `-gt`, `-igt`, `-igt` - greater than +- `-ge`, `-ige`, `-cge` - greater than or equal +- `-lt`, `-ilt`, `-clt` - less than +- `-le`, `-ile`, `-cle` - less than or equal + +**Matching** + +- `-like`, `-ilike`, `-clike` - string matches wildcard pattern +- `-notlike`, `-inotlike`, `-cnotlike` - string does not match wildcard pattern +- `-match`, `-imatch`, `-cmatch` - string matches regex pattern +- `-notmatch`, `-inotmatch`, `-cnotmatch` - string does not match regex pattern + +**Replacement** + +- `-replace`, `-ireplace`, `-creplace` - replaces strings matching a regex + pattern + +**Containment** + +- `-contains`, `-icontains`, `-ccontains` - collection contains a value +- `-notcontains`, `-inotcontains`, `-cnotcontains` - collection does not + contain a value +- `-in` - value is in a collection +- `-notin` - value is not in a collection + +**Type** + +- `-is` - both objects are the same type +- `-isnot` - the objects are not the same type ## Common features -By default, string comparisons are case-insensitive. The equality operators have -explicit case-sensitive and case-insensitive forms. To make a comparison -operator case-sensitive, add a `c` after the `-`. For example, `-ceq` is the -case-sensitive version of `-eq`. To make the case-insensitivity explicit, add -an `i` after `-`. For example, `-ieq` is the explicitly case-insensitive -version of `-eq`. +String comparisons are case-insensitive unless you use the explicit +case-sensitive operator. To make a comparison operator case-sensitive, add a +`c` after the `-`. For example, `-ceq` is the case-sensitive version of `-eq`. +To make the case-insensitivity explicit, add an `i` after `-`. For example, +`-ieq` is the explicitly case-insensitive version of `-eq`. When the input of an operator is a scalar value, the operator returns a **Boolean** value. When the input is a collection, the operator returns the @@ -157,8 +170,8 @@ equality test result is **False** because they are different objects. To create comparable classes, you need to implement [System.IEquatable\][2] in your class. The following example demonstrates the partial implementation of a **MyFileInfoSet** class that implements [System.IEquatable\][2] and has two -properties, **File** and **Size**. The `Equals()` method returns **True** if the -File and Size properties of two **MyFileInfoSet** objects are the same. +properties, **File** and **Size**. The `Equals()` method returns **True** if +the File and Size properties of two **MyFileInfoSet** objects are the same. ```powershell class MyFileInfoSet : System.IEquatable[Object] { @@ -219,10 +232,10 @@ they return **True** or **False** depending on how the two sides compare: | Operator | Returns True when... | | -------- | -------------------------------------- | -| -gt | The left-hand side is greater | -| -ge | The left-hand side is greater or equal | -| -lt | The left-hand side is smaller | -| -le | The left-hand side is smaller or equal | +| `-gt` | The left-hand side is greater | +| `-ge` | The left-hand side is greater or equal | +| `-lt` | The left-hand side is smaller | +| `-le` | The left-hand side is smaller or equal | In the following examples, all statements return **True**. @@ -444,7 +457,7 @@ or when the input is a collection, the `$Matches` automatic variable is not overwritten. Consequently, it will contain the previously set value, or `$null` if the variable has not been set. When referencing `$Matches` after invoking one of these operators, consider verifying that the variable was set by the -current operator invocation by using a condition statement. +current operator invocation using a condition statement. Example: @@ -503,8 +516,8 @@ using capturing groups, and substitutions. Capture groups can be referenced in the `` string using the dollar sign (`$`) character before the group identifier. -In the following example, the `-replace` operator accepts a username in the form -of `DomainName\Username` and converts to the `Username@DomainName` format: +In the following example, the `-replace` operator accepts a username in the +form of `DomainName\Username` and converts to the `Username@DomainName` format: ```powershell $SearchExp = '^(?[\w-.]+)\\(?[\w-.]+)$' @@ -549,8 +562,8 @@ include a literal `$` in the resulting replacement. For example: '5.72' -replace '(.+)', '$$1' # Output: $1 ``` -To learn more, see [about_Regular_Expressions](about_Regular_Expressions.md) and -[Substitutions in Regular Expressions][4]. +To learn more, see [about_Regular_Expressions](about_Regular_Expressions.md) +and [Substitutions in Regular Expressions][4]. ### Substituting in a collection @@ -582,8 +595,8 @@ text being replaced and other useful information. This variable's class type is [System.Text.RegularExpressions.Match][3]. The following example replaces each sequence of three digits with the character -equivalents. The script block runs for each set of three digits that needs to be -replaced. +equivalents. The script block runs for each set of three digits that needs to +be replaced. ```powershell "072101108108111" -replace "\d{3}", {return [char][int]$_.Value} @@ -595,12 +608,12 @@ Hello ## Containment operators -The containment operators (`-contains`, `-notcontains`, `-in`, and `-notin`) are -similar to the equality operators, except that they always return a **Boolean** -value, even when the input is a collection. These operators stop comparing as -soon as they detect the first match, whereas the equality operators evaluate all -input members. In a very large collection, these operators return quicker than -the equality operators. +The containment operators (`-contains`, `-notcontains`, `-in`, and `-notin`) +are similar to the equality operators, except that they always return a +**Boolean** value, even when the input is a collection. These operators stop +comparing as soon as they detect the first match, whereas the equality +operators evaluate all input members. In a very large collection, these +operators return quicker than the equality operators. Syntax: @@ -614,10 +627,10 @@ Syntax: ### -contains and -notcontains These operators tell whether a set includes a certain element. `-contains` -returns **True** when the right-hand side (test object) matches one of the elements -in the set. `-notcontains` returns False instead. When the test object is a -collection, these operators use reference equality, i.e. they check whether one -of the set's elements is the same instance of the test object. +returns **True** when the right-hand side (test object) matches one of the +elements in the set. `-notcontains` returns False instead. When the test object +is a collection, these operators use reference equality, i.e. they check +whether one of the set's elements is the same instance of the test object. Examples: @@ -654,8 +667,8 @@ elements in the set. `-notin` returns **False** instead. When the test object is a set, these operators use reference equality to check whether one of the set's elements is the same instance of the test object. -The following examples do the same thing that the examples for `-contains` -and `-notcontains` do, but they are written with `-in` and `-notin` instead. +The following examples do the same thing that the examples for `-contains` and +`-notcontains` do, but they are written with `-in` and `-notin` instead. ```powershell "def" -in "abc", "def" # Output: True diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md index 161e2e2fc7c..e32e2811cdb 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that compare values in PowerShell. Locale: en-US -ms.date: 01/27/2022 +ms.date: 05/18/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Comparison Operators @@ -18,34 +18,47 @@ elements of a collection against an input value. Comparison operators let you compare values or finding values that match specified patterns. PowerShell includes the following comparison operators: -| Type | Operator | Comparison test | -| ----------- | ------------ | ----------------------------------------- | -| Equality | -eq | equals | -| | -ne | not equals | -| | -gt | greater than | -| | -ge | greater than or equal | -| | -lt | less than | -| | -le | less than or equal | -| Matching | -like | string matches wildcard pattern | -| | -notlike | string does not match wildcard pattern | -| | -match | string matches regex pattern | -| | -notmatch | string does not match regex pattern | -| Replacement | -replace | replaces strings matching a regex pattern | -| Containment | -contains | collection contains a value | -| | -notcontains | collection does not contain a value | -| | -in | value is in a collection | -| | -notin | value is not in a collection | -| Type | -is | both objects are the same type | -| | -isnot | the objects are not the same type | +**Equality** + +- `-eq`, `-ieq`, `-ceq` - equals +- `-ne`, `-ine`, `-cne` - not equals +- `-gt`, `-igt`, `-igt` - greater than +- `-ge`, `-ige`, `-cge` - greater than or equal +- `-lt`, `-ilt`, `-clt` - less than +- `-le`, `-ile`, `-cle` - less than or equal + +**Matching** + +- `-like`, `-ilike`, `-clike` - string matches wildcard pattern +- `-notlike`, `-inotlike`, `-cnotlike` - string does not match wildcard pattern +- `-match`, `-imatch`, `-cmatch` - string matches regex pattern +- `-notmatch`, `-inotmatch`, `-cnotmatch` - string does not match regex pattern + +**Replacement** + +- `-replace`, `-ireplace`, `-creplace` - replaces strings matching a regex + pattern + +**Containment** + +- `-contains`, `-icontains`, `-ccontains` - collection contains a value +- `-notcontains`, `-inotcontains`, `-cnotcontains` - collection does not + contain a value +- `-in` - value is in a collection +- `-notin` - value is not in a collection + +**Type** + +- `-is` - both objects are the same type +- `-isnot` - the objects are not the same type ## Common features -By default, string comparisons are case-insensitive. The equality operators have -explicit case-sensitive and case-insensitive forms. To make a comparison -operator case-sensitive, add a `c` after the `-`. For example, `-ceq` is the -case-sensitive version of `-eq`. To make the case-insensitivity explicit, add -an `i` after `-`. For example, `-ieq` is the explicitly case-insensitive -version of `-eq`. +String comparisons are case-insensitive unless you use the explicit +case-sensitive operator. To make a comparison operator case-sensitive, add a +`c` after the `-`. For example, `-ceq` is the case-sensitive version of `-eq`. +To make the case-insensitivity explicit, add an `i` after `-`. For example, +`-ieq` is the explicitly case-insensitive version of `-eq`. When the input of an operator is a scalar value, the operator returns a **Boolean** value. When the input is a collection, the operator returns the @@ -157,8 +170,8 @@ equality test result is **False** because they are different objects. To create comparable classes, you need to implement [System.IEquatable\][2] in your class. The following example demonstrates the partial implementation of a **MyFileInfoSet** class that implements [System.IEquatable\][2] and has two -properties, **File** and **Size**. The `Equals()` method returns **True** if the -File and Size properties of two **MyFileInfoSet** objects are the same. +properties, **File** and **Size**. The `Equals()` method returns **True** if +the File and Size properties of two **MyFileInfoSet** objects are the same. ```powershell class MyFileInfoSet : System.IEquatable[Object] { @@ -219,10 +232,10 @@ they return **True** or **False** depending on how the two sides compare: | Operator | Returns True when... | | -------- | -------------------------------------- | -| -gt | The left-hand side is greater | -| -ge | The left-hand side is greater or equal | -| -lt | The left-hand side is smaller | -| -le | The left-hand side is smaller or equal | +| `-gt` | The left-hand side is greater | +| `-ge` | The left-hand side is greater or equal | +| `-lt` | The left-hand side is smaller | +| `-le` | The left-hand side is smaller or equal | In the following examples, all statements return **True**. @@ -444,7 +457,7 @@ or when the input is a collection, the `$Matches` automatic variable is not overwritten. Consequently, it will contain the previously set value, or `$null` if the variable has not been set. When referencing `$Matches` after invoking one of these operators, consider verifying that the variable was set by the -current operator invocation by using a condition statement. +current operator invocation using a condition statement. Example: @@ -503,8 +516,8 @@ using capturing groups, and substitutions. Capture groups can be referenced in the `` string using the dollar sign (`$`) character before the group identifier. -In the following example, the `-replace` operator accepts a username in the form -of `DomainName\Username` and converts to the `Username@DomainName` format: +In the following example, the `-replace` operator accepts a username in the +form of `DomainName\Username` and converts to the `Username@DomainName` format: ```powershell $SearchExp = '^(?[\w-.]+)\\(?[\w-.]+)$' @@ -549,8 +562,8 @@ include a literal `$` in the resulting replacement. For example: '5.72' -replace '(.+)', '$$1' # Output: $1 ``` -To learn more, see [about_Regular_Expressions](about_Regular_Expressions.md) and -[Substitutions in Regular Expressions][4]. +To learn more, see [about_Regular_Expressions](about_Regular_Expressions.md) +and [Substitutions in Regular Expressions][4]. ### Substituting in a collection @@ -582,8 +595,8 @@ text being replaced and other useful information. This variable's class type is [System.Text.RegularExpressions.Match][3]. The following example replaces each sequence of three digits with the character -equivalents. The script block runs for each set of three digits that needs to be -replaced. +equivalents. The script block runs for each set of three digits that needs to +be replaced. ```powershell "072101108108111" -replace "\d{3}", {return [char][int]$_.Value} @@ -595,12 +608,12 @@ Hello ## Containment operators -The containment operators (`-contains`, `-notcontains`, `-in`, and `-notin`) are -similar to the equality operators, except that they always return a **Boolean** -value, even when the input is a collection. These operators stop comparing as -soon as they detect the first match, whereas the equality operators evaluate all -input members. In a very large collection, these operators return quicker than -the equality operators. +The containment operators (`-contains`, `-notcontains`, `-in`, and `-notin`) +are similar to the equality operators, except that they always return a +**Boolean** value, even when the input is a collection. These operators stop +comparing as soon as they detect the first match, whereas the equality +operators evaluate all input members. In a very large collection, these +operators return quicker than the equality operators. Syntax: @@ -614,10 +627,10 @@ Syntax: ### -contains and -notcontains These operators tell whether a set includes a certain element. `-contains` -returns **True** when the right-hand side (test object) matches one of the elements -in the set. `-notcontains` returns False instead. When the test object is a -collection, these operators use reference equality, i.e. they check whether one -of the set's elements is the same instance of the test object. +returns **True** when the right-hand side (test object) matches one of the +elements in the set. `-notcontains` returns False instead. When the test object +is a collection, these operators use reference equality, i.e. they check +whether one of the set's elements is the same instance of the test object. Examples: @@ -654,8 +667,8 @@ elements in the set. `-notin` returns **False** instead. When the test object is a set, these operators use reference equality to check whether one of the set's elements is the same instance of the test object. -The following examples do the same thing that the examples for `-contains` -and `-notcontains` do, but they are written with `-in` and `-notin` instead. +The following examples do the same thing that the examples for `-contains` and +`-notcontains` do, but they are written with `-in` and `-notin` instead. ```powershell "def" -in "abc", "def" # Output: True diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md index b2a85b2b7f3..1cecbeae6c7 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that compare values in PowerShell. Locale: en-US -ms.date: 01/27/2022 +ms.date: 05/18/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Comparison Operators @@ -18,34 +18,47 @@ elements of a collection against an input value. Comparison operators let you compare values or finding values that match specified patterns. PowerShell includes the following comparison operators: -| Type | Operator | Comparison test | -| ----------- | ------------ | ----------------------------------------- | -| Equality | -eq | equals | -| | -ne | not equals | -| | -gt | greater than | -| | -ge | greater than or equal | -| | -lt | less than | -| | -le | less than or equal | -| Matching | -like | string matches wildcard pattern | -| | -notlike | string does not match wildcard pattern | -| | -match | string matches regex pattern | -| | -notmatch | string does not match regex pattern | -| Replacement | -replace | replaces strings matching a regex pattern | -| Containment | -contains | collection contains a value | -| | -notcontains | collection does not contain a value | -| | -in | value is in a collection | -| | -notin | value is not in a collection | -| Type | -is | both objects are the same type | -| | -isnot | the objects are not the same type | +**Equality** + +- `-eq`, `-ieq`, `-ceq` - equals +- `-ne`, `-ine`, `-cne` - not equals +- `-gt`, `-igt`, `-igt` - greater than +- `-ge`, `-ige`, `-cge` - greater than or equal +- `-lt`, `-ilt`, `-clt` - less than +- `-le`, `-ile`, `-cle` - less than or equal + +**Matching** + +- `-like`, `-ilike`, `-clike` - string matches wildcard pattern +- `-notlike`, `-inotlike`, `-cnotlike` - string does not match wildcard pattern +- `-match`, `-imatch`, `-cmatch` - string matches regex pattern +- `-notmatch`, `-inotmatch`, `-cnotmatch` - string does not match regex pattern + +**Replacement** + +- `-replace`, `-ireplace`, `-creplace` - replaces strings matching a regex + pattern + +**Containment** + +- `-contains`, `-icontains`, `-ccontains` - collection contains a value +- `-notcontains`, `-inotcontains`, `-cnotcontains` - collection does not + contain a value +- `-in` - value is in a collection +- `-notin` - value is not in a collection + +**Type** + +- `-is` - both objects are the same type +- `-isnot` - the objects are not the same type ## Common features -By default, string comparisons are case-insensitive. The equality operators have -explicit case-sensitive and case-insensitive forms. To make a comparison -operator case-sensitive, add a `c` after the `-`. For example, `-ceq` is the -case-sensitive version of `-eq`. To make the case-insensitivity explicit, add -an `i` after `-`. For example, `-ieq` is the explicitly case-insensitive -version of `-eq`. +String comparisons are case-insensitive unless you use the explicit +case-sensitive operator. To make a comparison operator case-sensitive, add a +`c` after the `-`. For example, `-ceq` is the case-sensitive version of `-eq`. +To make the case-insensitivity explicit, add an `i` after `-`. For example, +`-ieq` is the explicitly case-insensitive version of `-eq`. When the input of an operator is a scalar value, the operator returns a **Boolean** value. When the input is a collection, the operator returns the @@ -157,8 +170,8 @@ equality test result is **False** because they are different objects. To create comparable classes, you need to implement [System.IEquatable\][2] in your class. The following example demonstrates the partial implementation of a **MyFileInfoSet** class that implements [System.IEquatable\][2] and has two -properties, **File** and **Size**. The `Equals()` method returns **True** if the -File and Size properties of two **MyFileInfoSet** objects are the same. +properties, **File** and **Size**. The `Equals()` method returns **True** if +the File and Size properties of two **MyFileInfoSet** objects are the same. ```powershell class MyFileInfoSet : System.IEquatable[Object] { @@ -219,10 +232,10 @@ they return **True** or **False** depending on how the two sides compare: | Operator | Returns True when... | | -------- | -------------------------------------- | -| -gt | The left-hand side is greater | -| -ge | The left-hand side is greater or equal | -| -lt | The left-hand side is smaller | -| -le | The left-hand side is smaller or equal | +| `-gt` | The left-hand side is greater | +| `-ge` | The left-hand side is greater or equal | +| `-lt` | The left-hand side is smaller | +| `-le` | The left-hand side is smaller or equal | In the following examples, all statements return **True**. @@ -444,7 +457,7 @@ or when the input is a collection, the `$Matches` automatic variable is not overwritten. Consequently, it will contain the previously set value, or `$null` if the variable has not been set. When referencing `$Matches` after invoking one of these operators, consider verifying that the variable was set by the -current operator invocation by using a condition statement. +current operator invocation using a condition statement. Example: @@ -503,8 +516,8 @@ using capturing groups, and substitutions. Capture groups can be referenced in the `` string using the dollar sign (`$`) character before the group identifier. -In the following example, the `-replace` operator accepts a username in the form -of `DomainName\Username` and converts to the `Username@DomainName` format: +In the following example, the `-replace` operator accepts a username in the +form of `DomainName\Username` and converts to the `Username@DomainName` format: ```powershell $SearchExp = '^(?[\w-.]+)\\(?[\w-.]+)$' @@ -549,8 +562,8 @@ include a literal `$` in the resulting replacement. For example: '5.72' -replace '(.+)', '$$1' # Output: $1 ``` -To learn more, see [about_Regular_Expressions](about_Regular_Expressions.md) and -[Substitutions in Regular Expressions][4]. +To learn more, see [about_Regular_Expressions](about_Regular_Expressions.md) +and [Substitutions in Regular Expressions][4]. ### Substituting in a collection @@ -582,8 +595,8 @@ text being replaced and other useful information. This variable's class type is [System.Text.RegularExpressions.Match][3]. The following example replaces each sequence of three digits with the character -equivalents. The script block runs for each set of three digits that needs to be -replaced. +equivalents. The script block runs for each set of three digits that needs to +be replaced. ```powershell "072101108108111" -replace "\d{3}", {return [char][int]$_.Value} @@ -595,12 +608,12 @@ Hello ## Containment operators -The containment operators (`-contains`, `-notcontains`, `-in`, and `-notin`) are -similar to the equality operators, except that they always return a **Boolean** -value, even when the input is a collection. These operators stop comparing as -soon as they detect the first match, whereas the equality operators evaluate all -input members. In a very large collection, these operators return quicker than -the equality operators. +The containment operators (`-contains`, `-notcontains`, `-in`, and `-notin`) +are similar to the equality operators, except that they always return a +**Boolean** value, even when the input is a collection. These operators stop +comparing as soon as they detect the first match, whereas the equality +operators evaluate all input members. In a very large collection, these +operators return quicker than the equality operators. Syntax: @@ -614,10 +627,10 @@ Syntax: ### -contains and -notcontains These operators tell whether a set includes a certain element. `-contains` -returns **True** when the right-hand side (test object) matches one of the elements -in the set. `-notcontains` returns False instead. When the test object is a -collection, these operators use reference equality, i.e. they check whether one -of the set's elements is the same instance of the test object. +returns **True** when the right-hand side (test object) matches one of the +elements in the set. `-notcontains` returns False instead. When the test object +is a collection, these operators use reference equality, i.e. they check +whether one of the set's elements is the same instance of the test object. Examples: @@ -654,8 +667,8 @@ elements in the set. `-notin` returns **False** instead. When the test object is a set, these operators use reference equality to check whether one of the set's elements is the same instance of the test object. -The following examples do the same thing that the examples for `-contains` -and `-notcontains` do, but they are written with `-in` and `-notin` instead. +The following examples do the same thing that the examples for `-contains` and +`-notcontains` do, but they are written with `-in` and `-notin` instead. ```powershell "def" -in "abc", "def" # Output: True diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md index a84b52369c7..abb0c70654d 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that compare values in PowerShell. Locale: en-US -ms.date: 01/27/2022 +ms.date: 05/18/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Comparison Operators @@ -18,34 +18,47 @@ elements of a collection against an input value. Comparison operators let you compare values or finding values that match specified patterns. PowerShell includes the following comparison operators: -| Type | Operator | Comparison test | -| ----------- | ------------ | ----------------------------------------- | -| Equality | -eq | equals | -| | -ne | not equals | -| | -gt | greater than | -| | -ge | greater than or equal | -| | -lt | less than | -| | -le | less than or equal | -| Matching | -like | string matches wildcard pattern | -| | -notlike | string does not match wildcard pattern | -| | -match | string matches regex pattern | -| | -notmatch | string does not match regex pattern | -| Replacement | -replace | replaces strings matching a regex pattern | -| Containment | -contains | collection contains a value | -| | -notcontains | collection does not contain a value | -| | -in | value is in a collection | -| | -notin | value is not in a collection | -| Type | -is | both objects are the same type | -| | -isnot | the objects are not the same type | +**Equality** + +- `-eq`, `-ieq`, `-ceq` - equals +- `-ne`, `-ine`, `-cne` - not equals +- `-gt`, `-igt`, `-igt` - greater than +- `-ge`, `-ige`, `-cge` - greater than or equal +- `-lt`, `-ilt`, `-clt` - less than +- `-le`, `-ile`, `-cle` - less than or equal + +**Matching** + +- `-like`, `-ilike`, `-clike` - string matches wildcard pattern +- `-notlike`, `-inotlike`, `-cnotlike` - string does not match wildcard pattern +- `-match`, `-imatch`, `-cmatch` - string matches regex pattern +- `-notmatch`, `-inotmatch`, `-cnotmatch` - string does not match regex pattern + +**Replacement** + +- `-replace`, `-ireplace`, `-creplace` - replaces strings matching a regex + pattern + +**Containment** + +- `-contains`, `-icontains`, `-ccontains` - collection contains a value +- `-notcontains`, `-inotcontains`, `-cnotcontains` - collection does not + contain a value +- `-in` - value is in a collection +- `-notin` - value is not in a collection + +**Type** + +- `-is` - both objects are the same type +- `-isnot` - the objects are not the same type ## Common features -By default, string comparisons are case-insensitive. The equality operators have -explicit case-sensitive and case-insensitive forms. To make a comparison -operator case-sensitive, add a `c` after the `-`. For example, `-ceq` is the -case-sensitive version of `-eq`. To make the case-insensitivity explicit, add -an `i` after `-`. For example, `-ieq` is the explicitly case-insensitive -version of `-eq`. +String comparisons are case-insensitive unless you use the explicit +case-sensitive operator. To make a comparison operator case-sensitive, add a +`c` after the `-`. For example, `-ceq` is the case-sensitive version of `-eq`. +To make the case-insensitivity explicit, add an `i` after `-`. For example, +`-ieq` is the explicitly case-insensitive version of `-eq`. When the input of an operator is a scalar value, the operator returns a **Boolean** value. When the input is a collection, the operator returns the @@ -157,8 +170,8 @@ equality test result is **False** because they are different objects. To create comparable classes, you need to implement [System.IEquatable\][2] in your class. The following example demonstrates the partial implementation of a **MyFileInfoSet** class that implements [System.IEquatable\][2] and has two -properties, **File** and **Size**. The `Equals()` method returns **True** if the -File and Size properties of two **MyFileInfoSet** objects are the same. +properties, **File** and **Size**. The `Equals()` method returns **True** if +the File and Size properties of two **MyFileInfoSet** objects are the same. ```powershell class MyFileInfoSet : System.IEquatable[Object] { @@ -219,10 +232,10 @@ they return **True** or **False** depending on how the two sides compare: | Operator | Returns True when... | | -------- | -------------------------------------- | -| -gt | The left-hand side is greater | -| -ge | The left-hand side is greater or equal | -| -lt | The left-hand side is smaller | -| -le | The left-hand side is smaller or equal | +| `-gt` | The left-hand side is greater | +| `-ge` | The left-hand side is greater or equal | +| `-lt` | The left-hand side is smaller | +| `-le` | The left-hand side is smaller or equal | In the following examples, all statements return **True**. @@ -444,7 +457,7 @@ or when the input is a collection, the `$Matches` automatic variable is not overwritten. Consequently, it will contain the previously set value, or `$null` if the variable has not been set. When referencing `$Matches` after invoking one of these operators, consider verifying that the variable was set by the -current operator invocation by using a condition statement. +current operator invocation using a condition statement. Example: @@ -503,8 +516,8 @@ using capturing groups, and substitutions. Capture groups can be referenced in the `` string using the dollar sign (`$`) character before the group identifier. -In the following example, the `-replace` operator accepts a username in the form -of `DomainName\Username` and converts to the `Username@DomainName` format: +In the following example, the `-replace` operator accepts a username in the +form of `DomainName\Username` and converts to the `Username@DomainName` format: ```powershell $SearchExp = '^(?[\w-.]+)\\(?[\w-.]+)$' @@ -549,8 +562,8 @@ include a literal `$` in the resulting replacement. For example: '5.72' -replace '(.+)', '$$1' # Output: $1 ``` -To learn more, see [about_Regular_Expressions](about_Regular_Expressions.md) and -[Substitutions in Regular Expressions][4]. +To learn more, see [about_Regular_Expressions](about_Regular_Expressions.md) +and [Substitutions in Regular Expressions][4]. ### Substituting in a collection @@ -582,8 +595,8 @@ text being replaced and other useful information. This variable's class type is [System.Text.RegularExpressions.Match][3]. The following example replaces each sequence of three digits with the character -equivalents. The script block runs for each set of three digits that needs to be -replaced. +equivalents. The script block runs for each set of three digits that needs to +be replaced. ```powershell "072101108108111" -replace "\d{3}", {return [char][int]$_.Value} @@ -595,12 +608,12 @@ Hello ## Containment operators -The containment operators (`-contains`, `-notcontains`, `-in`, and `-notin`) are -similar to the equality operators, except that they always return a **Boolean** -value, even when the input is a collection. These operators stop comparing as -soon as they detect the first match, whereas the equality operators evaluate all -input members. In a very large collection, these operators return quicker than -the equality operators. +The containment operators (`-contains`, `-notcontains`, `-in`, and `-notin`) +are similar to the equality operators, except that they always return a +**Boolean** value, even when the input is a collection. These operators stop +comparing as soon as they detect the first match, whereas the equality +operators evaluate all input members. In a very large collection, these +operators return quicker than the equality operators. Syntax: @@ -614,10 +627,10 @@ Syntax: ### -contains and -notcontains These operators tell whether a set includes a certain element. `-contains` -returns **True** when the right-hand side (test object) matches one of the elements -in the set. `-notcontains` returns False instead. When the test object is a -collection, these operators use reference equality, i.e. they check whether one -of the set's elements is the same instance of the test object. +returns **True** when the right-hand side (test object) matches one of the +elements in the set. `-notcontains` returns False instead. When the test object +is a collection, these operators use reference equality, i.e. they check +whether one of the set's elements is the same instance of the test object. Examples: @@ -654,8 +667,8 @@ elements in the set. `-notin` returns **False** instead. When the test object is a set, these operators use reference equality to check whether one of the set's elements is the same instance of the test object. -The following examples do the same thing that the examples for `-contains` -and `-notcontains` do, but they are written with `-in` and `-notin` instead. +The following examples do the same thing that the examples for `-contains` and +`-notcontains` do, but they are written with `-in` and `-notin` instead. ```powershell "def" -in "abc", "def" # Output: True