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-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 True because 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 False because 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 through 4.
1,2,3,4 -contains 3As expected, since 3 exists in the collection, the result should be True.
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.
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"
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.
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.
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..10To check if 4 exists in the array, run the -contains operator like so:
$numbers -contains 4The 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 4This time, the result is False because 4 exists in the array.
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.
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 -like with -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.
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!
