Back to Basics: The PowerShell Contains Operator

Published:10 November 2022 - 6 min. read

Nicholas Xuan Nguyen Image

Nicholas Xuan Nguyen

Read more tutorials by Nicholas Xuan Nguyen!

Block over 3 billion compromised passwords & strengthen your Active Directory password policy. Try Specops Password Policy for free!

As more information becomes available, finding what you are looking for is increasingly difficult. When all you need is to determine whether a value exists in a collection, in that case, the PowerShell Contains Operator (-contains) can help accomplish this task.

In this post, you will learn how to use the PowerShell contains operator when determining the existence of value. You’ll also discover its inverse, the -notcontains operator.

Prerequisites

This tutorial will be a hands-on demonstration. If you’d like to follow along, be sure you have Windows PowerShell 5.1 or PowerShell 7+. This tutorial uses v7.2.6.

Using the PowerShell Contains Operator (-contains)

The PowerShell Contains operator is one of the Containment Operators. This operator determines whether a value exists in a given set. The result does not show the matching value. Instead, it returns a Boolean value (True/False), indicating whether or not the test value exists.

The syntax for -contains is as follows:

<Collection> -Contains <Test-Value>
  • <Collection> represents the set of objects for comparison. The set comes before the -contains operator and can be the literal values or a variable containing the set.
  • <Test-Value> is the value to check if it exists in the set. The value should be after the -contains operator (to the right) and can be a literal value, a collection of values, or a variable.

How can you apply the PowerShell contains operator? You’ll learn about them in the next sections.

Testing a Collection of Values as Input

You can directly compare a test object against a collection of values, like a string collection, in this case, using the -contains operator. This method is helpful when you have a list of items and want to know if a specific item is on the list.

The below example shows the PowerShell Contains operator in action to check if a value exists in a collection:

"PowerShell", "CSS", "HTML", "NodeJS" -contains "PowerShell"

Note that each value in the collection is comma-separated and encloses each element in quotation marks. The -Contains operator checks whether the test value exists or is equal to an element of the collection.

In this case, the command returns True because PowerShell exists in the collection, as shown below.

Comparing Strings using the PowerShell Contains Operator
Comparing Strings using the PowerShell Contains Operator

Now, run the following command in PowerShell to test whether Java exists in the collection.

"PowerShell", "CSS", "HTML", "NodeJS" -contains "Java"

The expected result is False because Java does not exist in the collection as shown.

The test value does not exist in the collection of strings
The test value does not exist in the collection of strings

Apart from strings, you can also use integers as the collection and test value. For example, the below command tests whether 3 exists in the collection of integers from 1 through 4.

1,2,3,4 -contains 3

As expected, since 3 exists in the collection, the result should be True.

Testing with integers
Testing with integers

Testing an Array Variable as Input

Variables are common, useful, and often unavoidable, especially in scripts. As such, the PowerShell contains operator can also test against the elements in a variable.

For example, run the below command to create an array containing a list of programming languages and store it in the $languages variable.

$languages = "PowerShell", "CSS", "HTML", "NodeJS"

Now, test whether PowerShell exists as an element in the $languages variable.

$languages -contains "PowerShell"

The result is True because PowerShell is one of the values in the array, as shown below.

Testing an array variable
Testing an array variable

Run the commands below to check for other values in the array, such as Java, CSS, and HTML.

$languages -contains "Java"
$languages -contains "CSS"
$languages -contains "HTML"
Using PowerShell Contains Operator on an array
Using PowerShell Contains Operator on an array

Performing a Case-Sensitive Comparison

By default, the -contains operator is case-insensitive, which means the operator treats uppercase and lowercase characters the same. For instance, the code snippet below creates an array consisting of the names of fruits in all lowercase:

$fruits = "apple", "banana", "cherry"

What do you think is the result of checking APPLe against the collection by running the code below?

$fruits -contains "APPLe"

The result? The test value APPle equals apple, and apple exists in the collection, so the result is True.

Performing In-sensitive Search
Performing In-sensitive Search

What if you don’t want PowerShell to ignore the character case differences? In this instance, replace -contains with -ccontains. Unlike -contains, the -ccontains operator performs case-sensitive containment comparison.

Like the command below, replace -contains with -ccontains and run it in PowerShell.

$fruits -ccontains "Apple"

This time, the result is False because of the case-sensitive comparison.

Performing a Case-Sensitive Search
Performing a Case-Sensitive Search

Using the PowerShell Not Contains Operator (-notcontains)

Simply put -notcontains is the inverse of -contains. As such, the -notcontains operator returns True when the value is not in the collection and $false when the value exists in the collection.

For instance, suppose you create an array of numbers from 1 to 10, as shown below.

$numbers = 1..10

To check if 4 exists in the array, run the -contains operator like so:

$numbers -contains 4

The expected result is True since the number 4 exists in the array.

Using the PowerShell contains operator
Using the PowerShell contains operator

To check if a value does not exist in an array, run the -notcontains operator instead.

$numbers -notcontains 4

This time, the result is False because 4 exists in the array.

Using the -notcontains Operator
Using the -notcontains Operator

Comparing the PowerShell Contains Operator with the Like Operator

The -contains operator and -like operator are both PowerShell comparison operators. But -like is not a containment operator and instead a matching operator.

The -like operator matches the wildcard expression against a string or string array. In contrast, the -contains operator does not work wildcard characters as -like does.

If the input is an array, -like returns the array member that matches the pattern. But if the input is scalar or a single string object, the result is a Boolean value instead. The below snippet shows the -like operator syntax.

<string[]> -like <wildcard-expression> # output is the matching item.
<string> -like <wildcard-expression> # output is Boolean (True/False).

For instance, run the command below to match the pattern *string with the single string input.

"This is a sample string" -like "*string"

As you can see, the result is a Boolean (True) because the input is a single-string object and matches the wildcard pattern.

Using the -like operator
Using the -like operator

If the input is a string array, like the command below.

$inputarray = "This is a sample string", "This is an integer"
$inputarray -like "*string"

The result would return the array member that matches the pattern instead.

The -like operator uses an array as input
The -like operator uses an array as input

For comparison, replace -like with -contains, and the logic fails because -contains does not support wildcard expressions.

"This is a sample string" -contains "*string"
PowerShell Contains operation does not support wildcard expressions
PowerShell Contains operation does not support wildcard expressions

In conclusion, use -contains to check if a value exists in an array and -like operator to check if a string matches a wildcard pattern expression.

Conclusion

The PowerShell contains operator helps check a value’s existence in a collection when all you need is a True or False result. The -contains operator may seem to do so little on its own. But it plays a critical part when it comes to scripting and automation.

But don’t stop with the PowerShell contains operator. With the proper usage, other comparison operators can complement what you’ve learned in this article to help you build fantastic PowerShell scripts!

Hate ads? Want to support the writer? Get many of our tutorials packaged as an ATA Guidebook.

Explore ATA Guidebooks

Looks like you're offline!