About Comparison Operators

SHORT DESCRIPTION

Describes the operators that compare values in PowerShell.

LONG DESCRIPTION

Comparison operators let you specify conditions for comparing values and finding values that match specified patterns. To use a comparison operator, specify the values that you want to compare together with an operator that separates these values.

PowerShell includes the following comparison operators:

Operator Type Operators Description
Equality -eq
-ne
-gt
-ge
-lt
-le
equals
not equals
greater than
greater than or equal
less than
less than or equal
Matching -like
-notlike
-match
-notmatch
Returns true when string matches wildcard pattern
Returns true when string does not match wildcard pattern
Returns true when string matches regex pattern - $matches contains matching strings
Returns true when string does not match regex pattern - $matches contains matching strings
Containment -contains
-notcontains
-in
-notin
Returns true when reference value contained in a collection
Returns true when reference value not contained in a collection
Returns true when test value contained in a collection
Returns true when test value not contained in a collection
Replacement -replace replace a string pattern
Type comparison -is
-isnot
Returns true if both object are the same type
Returns true if the objects are not the same type

By default, all comparison operators are case-insensitive. To make a comparison operator case-sensitive, precede the operator name with a c. For example, the case-sensitive version of -eq is -ceq. To make the case-insensitivity explicit, precede the operator with an i. For example, the explicitly case-insensitive version of -eq is -ieq.

When the input to an operator is a scalar value, comparison operators return a Boolean value. When the input is a collection of values, the comparison operators return any matching values. If there are no matches in a collection, comparison operators do not return anything.

The exceptions are the containment operators (-contains, -notcontains), the In operators (-in, -notin), and the type operators (-is, -isnot), which always return a Boolean value.

Equality Operators

The equality operators (-eq, -ne) return a value of TRUE or the matches when one or more of the input values is identical to the specified pattern. The entire pattern must match an entire value.

Example:

-eq

Description: Equal to. Includes an identical value.

Example:

C:PS> 2 -eq 2
True

C:PS> 2 -eq 3
False

C:PS> 1,2,3 -eq 2
2
PS C:\> "abc" -eq "abc"
True

PS C:\> "abc" -eq "abc", "def"
False

PS C:\> "abc", "def" -eq "abc"
abc

-ne

Description: Not equal to. Includes a different value.

Example:

PS C:\> "abc" -ne "def"
True

PS C:\> "abc" -ne "abc"
False

PS C:\> "abc" -ne "abc", "def"
True

PS C:\> "abc", "def" -ne "abc"
def

-gt

Description: Greater-than.

Example:

PS C:\> 8 -gt 6
True

PS C:\> 7, 8, 9 -gt 8
9

-ge

Description: Greater-than or equal to.

Example:

PS C:\> 8 -ge 8
True

PS C:\> 7, 8, 9 -ge 8
8
9

-lt

Description: Less-than.

Example:


PS C:\> 8 -lt 6
False

PS C:\> 7, 8, 9 -lt 8
7

-le

Description: Less-than or equal to.

Example:

PS C:\> 6 -le 8
True

PS C:\> 7, 8, 9 -le 8
7
8

Matching Operators

The like operators (-like and -notlike) find elements that match or do not match a specified pattern using wildcard expressions.

The syntax is:

<string[]> -like <wildcard-expression>
<string[]> -notlike <wildcard-expression>

The match operators (-match and -notmatch) find elements that match or do not match a specified pattern using regular expressions.

The match operators populate the $Matches automatic variable when the input (the left-side argument) to the operator is a single scalar object. When the input is scalar, the -match and -notmatch operators return a Boolean value and set the value of the $Matches automatic variable to the matched components of the argument.

The syntax is:

<string[]> -match <regular-expression>
<string[]> -notmatch <regular-expression>

-like

Description: Match using the wildcard character (*).

Example:

PS C:\> "PowerShell" -like "*shell"
True

PS C:\> "PowerShell", "Server" -like "*shell"
PowerShell

-notlike

Description: Does not match using the wildcard character (*).

Example:

PS C:\> "PowerShell" -notlike "*shell"
False

PS C:\> "PowerShell", "Server" -notlike "*shell"
Server

-match

Description: Matches a string using regular expressions. When the input is scalar, it populates the $Matches automatic variable.

The match operators search only in strings. They cannot search in arrays of integers or other objects.

If the input is a collection, the -match and -notmatch operators return the matching members of that collection, but the operator does not populate the $Matches variable.

For example, the following command submits a collection of strings to the -match operator. The -match operator returns the items in the collection that match. It does not populate the $Matches automatic variable.

PS C:\> "Sunday", "Monday", "Tuesday" -match "sun"
Sunday

PS C:\> $matches
PS C:\>

In contrast, the following command submits a single string to the -match operator. The -match operator returns a Boolean value and populates the $Matches automatic variable.

PS C:\> "Sunday" -match "sun"
True

PS C:\> $matches

Name                           Value
----                           -----
0                              Sun

The -notmatch operator populates the $Matches automatic variable when the input is scalar and the result is False, that it, when it detects a match.

PS C:\> "Sunday" -notmatch "rain"
True

PS C:\> $matches
PS C:\>

PS C:\> "Sunday" -notmatch "day"
False

PS C:\> $matches

Name                           Value
----                           -----
0                              day

-notmatch

Description: Does not match a string. Uses regular expressions. When the input is scalar, it populates the $Matches automatic variable.

Example:

PS C:\> "Sunday" -notmatch "sun"
False

PS C:\> $matches
Name Value
---- -----
0    sun

PS C:\> "Sunday", "Monday" -notmatch "sun"
Monday

Containment Operators

The containment operators (-contains and -notcontains) are similar to the equality operators. However, the containment operators always return a Boolean value, even when the input is a collection.

Also, unlike the equality operators, the containment operators return a value as soon as they detect the first match. The equality operators evaluate all input and then return all the matches in the collection.

-contains

Description: Containment operator. Tells whether a collection of reference values includes a single test value. Always returns a Boolean value. Returns TRUE only when the test value exactly matches at least one of the reference values.

When the test value is a collection, the Contains operator uses reference equality. It returns TRUE only when one of the reference values is the same instance of the test value object.

In a very large collection, the -contains operator returns results quicker than the equal to operator.

Syntax:

<Reference-values> -contains <Test-value>

Examples:

PS C:\> "abc", "def" -contains "def"
True

PS C:\> "Windows", "PowerShell" -contains "Shell"
False  #Not an exact match

# Does the list of computers in $DomainServers include $ThisComputer?
PS C:\> $DomainServers -contains $thisComputer
True

PS C:\> "abc", "def", "ghi" -contains "abc", "def"
False

PS C:\> $a = "abc", "def"
PS C:\> "abc", "def", "ghi" -contains $a
False
PS C:\> $a, "ghi" -contains $a
True

-notcontains

Description: Containment operator. Tells whether a collection of reference values includes a single test value. Always returns a Boolean value. Returns TRUE when the test value is not an exact matches for at least one of the reference values.

When the test value is a collection, the NotContains operator uses reference equality.

Syntax:

<Reference-values> -notcontains <Test-value>

Examples:

PS C:\> "Windows", "PowerShell" -notcontains "Shell"
True  #Not an exact match

# Get cmdlet parameters, but exclude common parameters
function get-parms ($cmdlet)
{
    $Common = "Verbose", "Debug", "WarningAction", "WarningVariable", "ErrorAction", "ErrorVariable", "OutVariable", "OutBuffer"

    $allparms = (Get-Command $Cmdlet).parametersets | foreach {$_.Parameters} |
      foreach {$_.Name} | Sort-Object | Get-Unique

    $allparms | where {$Common -notcontains $_ }
}

# Find unapproved verbs in the functions in my module
PS C:\> $ApprovedVerbs = Get-Verb | foreach {$_.verb}
PS C:\> $myVerbs = Get-Command -Module MyModule | foreach {$_.verb}
PS C:\> $myVerbs | where {$ApprovedVerbs -notcontains $_}
ForEach
Sort
Tee
Where

-in

Description: In operator. Tells whether a test value appears in a collection of reference values. Always return as Boolean value. Returns TRUE only when the test value exactly matches at least one of the reference values.

When the test value is a collection, the In operator uses reference equality. It returns TRUE only when one of the reference values is the same instance of the test value object.

The -in operator was introduced in PowerShell 3.0.

Syntax:

<Test-value> -in <Reference-values>

Examples:

PS C:\> "def" -in "abc", "def"
True

PS C:\> "Shell" -in "Windows", "PowerShell"
False  #Not an exact match

PS C:\> "Windows" -in "Windows", "PowerShell"
True  #An exact match

PS C:\> "Windows", "PowerShell" -in "Windows", "PowerShell", "ServerManager"
False  #Using reference equality

PS C:\> $a = "Windows", "PowerShell"
PS C:\> $a -in $a, "ServerManager"
True  #Using reference equality

# Does the list of computers in $domainServers include $thisComputer?
PS C:\> $thisComputer -in  $domainServers
True

-notin

Description: Tells whether a test value appears in a collection of reference values. Always returns a Boolean value. Returns TRUE when the test value is not an exact match for at least one of the reference values.

When the test value is a collection, the In operator uses reference equality. It returns TRUE only when one of the reference values is the same instance of the test value object.

The -notin operator was introduced in PowerShell 3.0.

Syntax:

<Test-value> -notin \<Reference-values>

Examples:

PS C:\> "def" -notin "abc", "def"
False

PS C:\> "ghi" -notin "abc", "def"
True

PS C:\> "Shell" -notin "Windows", "PowerShell"
True  #Not an exact match

PS C:\> "Windows" -notin "Windows", "PowerShell"
False  #An exact match

# Find unapproved verbs in the functions in my module
PS C:\> $ApprovedVerbs = Get-Verb | foreach {$_.verb}
PS C:\> $MyVerbs = Get-Command -Module MyModule | foreach {$_.verb}

PS C:\> $MyVerbs | where {$_ -notin $ApprovedVerbs}
ForEach
Sort
Tee
Where

Replacement Operator

The -replace operator replaces all or part of a value with the specified value using regular expressions. You can use the -replace operator for many administrative tasks, such as renaming files. For example, the following command changes the file name extensions of all .gif files to .jpg:

Get-ChildItem | Rename-Item -NewName { $_ -replace '.gif$','.jpg$' }

The syntax of the -replace operator is as follows, where the <original> placeholder represents the characters to be replaced, and the <substitute> placeholder represents the characters that will replace them:

<input> <operator> <original>, <substitute>

By default, the -replace operator is case-insensitive. To make it case sensitive, use -creplace. To make it explicitly case-insensitive, use -ireplace. Consider the following examples:

PS C:\> "book" -replace "B", "C"
Cook
PS C:\> "book" -ireplace "B", "C"
Cook
PS C:\> "book" -creplace "B", "C"
book

Type comparison

The type comparison operators (-is and -isnot) are used to determine if an object is a specific type.

-is

Syntax:

<object> -is <type reference>

Example:

PS C:\> $a = 1
PS C:\> $b = "1"
PS C:\> $a -is [int]
True
PS C:\> $a -is $b.GetType()
False

-isnot

Syntax:

<object> -isnot <type reference>

Example:

PS C:\> $a = 1
PS C:\> $b = "1"
PS C:\> $a -isnot $b.GetType()
True
PS C:\> $b -isnot [int]
True

SEE ALSO

about_Operators

about_Regular_Expressions

about_Wildcards

Compare-Object

Foreach-Object

Where-Object