about_Comparison_Operators

TOPIC
    about_Comparison_Operators

SHORT DESCRIPTION
    Describes the operators that compare values in Windows 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.


    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".


    All comparison operators except the containment operators
    (-contains, -notcontains) and type operators (-is, -isnot) return a Boolean
    value when the input to the operator (the value on the left side of the
    operator) is a single value (a scalar). When the input is a collection of
    values, the containment operators and the type operators return any
    matching values. If there are no matches in a collection, these operators
    do not return anything. The containment operators and type operators always
    return a Boolean value.


    Windows PowerShell supports the following comparison operators.


    -eq
      Description: Equal to. Includes an identical value.
      Example:


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


    -ne
      Description: Not equal to. Includes a different value.
      Example:


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


    -gt
      Description: Greater-than.
      Example:


          C:/PS> 8 -gt 6
          True



    -ge
      Description: Greater-than or equal to.
      Example:


          C:/PS> 8 -ge 8
          True        


    -lt
      Description: Less-than.
      Example:


          C:/PS> 8 -lt 6
          False


    -le
      Description: Less-than or equal to.
      Example:


          C:/PS> 6 -le 8
          True


    -like
      Description: Match using the wildcard character (*).
      Example:


          C:/PS> "Windows PowerShell" -like "*shell"
          True


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


          C:/PS> "Windows PowerShell" -notlike "*shell"
          False
              

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

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

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


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


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

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


    -contains
      Description: Containment operator. Tells whether a single test value appears
      in a set of reference values. Returns TRUE only when the test value exactly
      matches at least one of the reference values. Contains uses reference equality
      and returns a Boolean value.

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

     
      Examples:

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

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


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


      

    -notcontains
      Description: Containment operator. Tells whether a single (scalar) test
      value appears in a set of reference values. Returns TRUE when the test
      value is not an exact match for any of the reference values. Always
      returns a Boolean value.

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

      Examples:

          C:/PS> "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
          # -------------------------------------------
          C:/PS> $approvedVerbs = get-verb | foreach {$_.verb}
          C:/PS> $myVerbs = get-command -module MyModule | foreach {$_.verb}

          C:/PS> $myVerbs | where {$approvedVerbs -notcontains $_}     
          ForEach
          Sort
          Tee
          Where

    

    -replace
      Description: Replace operator. Changes the specified elements of a value.
      Example:


          C:/PS> "Get-Process" -replace "Get", "Stop"
          Stop-Process

          # Change all .GIF file name extension to .JPG
          C:/PS> dir *.gif | foreach {$_ -replace ".gif", ".jpg"}
              

  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.


      The following examples show the effect of the equal to operator:


          C:PS> 1,2,3 -eq 2
          2

          C:PS> "PowerShell" -eq "Shell"
          False

          C:PS> "Windows", "PowerShell" -eq "Shell"
          C:PS>

          C:/PS> "abc", "def", "123" -eq "def"
          def


  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.
      The following examples show the effect of the -contains operator:


          C:PS> 1,2,3 -contains 2
          True

          C:PS> "PowerShell" -contains "Shell"
          False

          C:PS> "Windows", "PowerShell" -contains "Shell"
          False

          C:/PS> "abc", "def", "123" -contains "def"
          True

          C:/PS> "true", "blue", "six" -contains "true"
          True


      The following example shows how the containment operators differ from the
      equal to operator. The containment operators return a value of TRUE on the
      first match.


          C:/PS> 1,2,3,4,5,4,3,2,1 -eq 2
          2
          2

          C:/PS> 1,2,3,4,5,4,3,2,1 -contains 2
          True

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


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

      The syntax is:

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


      The following examples show some uses of the -match operator:


          C:/PS> "Windows", "PowerShell" -match ".shell"
          PowerShell

          C:/PS> (get-command get-member -syntax) -match "-view"
          True

          C:/PS> (get-command get-member -syntax) -notmatch "-path"
          True

          C:/PS> (get-content servers.txt) -match "^Server/d/d"
          Server01
          Server02

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

      The -match and -notmatch 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.

      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.

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

          C:/PS> $matches
          C:/PS>


      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.

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

          C:/PS> $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.


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

          C:/PS> $matches
          C:/PS>
         
          C:/PS> "Sunday" -notmatch "day"
          False

          C:/PS> $matches
          C:/PS>

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

       
  Replace 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:


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


  Bitwise Operators
      Windows PowerShell supports the standard bitwise operators, including
      bitwise-AND (-bAnd), the inclusive and exclusive bitwise-OR operators
      (-bOr and -bXor), and bitwise-NOT (-bNot). Beginning in Windows
      PowerShell 2.0, all bitwise operators work with 64-bit integers.


      Windows PowerShell supports the following bitwise operators.


      Operator  Description               Example 
      --------  ----------------------    -------------------
      -bAnd     Bitwise AND               C:/PS> 10 -band 3
                                          2

      -bOr      Bitwise OR (inclusive)    C:/PS> 10 -bor 3
                                          11   

      -bXor     Bitwise OR (exclusive)    C:/PS> 10 -bxor 3
                                          9

      -bNot     Bitwise NOT               C:/PS> -bNot 10
                                          -11

   

      Bitwise operators act on the binary format of a value. For example, the
      bit structure for the number 10 is 00001010 (based on 1 byte), and the
      bit structure for the number 3 is 00000011. When you use a bitwise
      operator to compare 10 to 3, the individual bits in each byte are
      compared.


      In a bitwise AND operation, the resulting bit is set to 1 only when both
      input bits are 1.


          1010      (10)
          0011      ( 3)
          --------------  bAND
          0010      ( 2)


      In a bitwise OR (inclusive) operation, the resulting bit is set to 1
      when either or both input bits are 1. The resulting bit is set to 0 only
      when both input bits are set to 0.


          1010      (10)
          0011      ( 3)
          --------------  bOR (inclusive)
          1011      (11)


      In a bitwise OR (exclusive) operation, the resulting bit is set to 1 only
      when one input bit is 1.


          1010      (10)
          0011      ( 3)
          --------------  bXOR (exclusive)
          1001      ( 9)


      The bitwise NOT operator is a unary operator that produces the binary
      complement of the value. A bit of 1 is set to 0 and a bit of 0 is set
      to 1.

      For example, the binary complement of 0 is -1, the maximum unsigned
      integer (0xffffffff), and the binary complement of -1 is 0.


          C:/PS> -bNOT 10
          -11


          0000 0000 0000 1010  (10)
          ------------------------- bNOT
          1111 1111 1111 0101  (-11, xfffffff5)


SEE ALSO
    about_Operators
    about_Regular_Expressions
    about_Wildcards
    Compare-Object