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
Table of Contents
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 (
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
-containsoperator 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
-containsoperator (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
PowerShell exists in the collection, as shown below.
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
Java does not exist in the collection as shown.
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,2,3,4 -contains 3
As expected, since
3 exists in the collection, the result should be
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 = "PowerShell", "CSS", "HTML", "NodeJS"
Now, test whether
PowerShell exists as an element in the
$languages -contains "PowerShell"
The result is
PowerShell is one of the values in the array, as shown below.
Run the commands below to check for other values in the array, such as
$languages -contains "Java" $languages -contains "CSS" $languages -contains "HTML"
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 exists in the collection, so the result is
What if you don’t want PowerShell to ignore the character case differences? In this instance, replace
-ccontains operator performs case-sensitive containment comparison.
Like the command below, replace
-ccontains and run it in PowerShell.
$fruits -ccontains "Apple"
This time, the result is
False because of the case-sensitive comparison.
Using the PowerShell Not Contains Operator (
-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.
To check if a value does not exist in an array, run the
-notcontains operator instead.
$numbers -notcontains 4
This time, the result is
4 exists in the array.
Comparing the PowerShell Contains Operator with the Like Operator
-contains operator and
-like operator are both PowerShell comparison operators. But
-like is not a containment operator and instead a matching operator.
-like operator matches the wildcard expression against a string or string array. In contrast, the
-contains operator does not work wildcard characters as
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.
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.
For comparison, replace
-contains, and the logic fails because
-contains does not support wildcard expressions.
"This is a sample string" -contains "*string"
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.
The PowerShell contains operator helps check a value’s existence in a collection when all you need is a
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!