Arrays and -contains – test for substrings in the elements of an array

by

It looks like your misconception was that you expected PowerShell’s -contains operator to perform substring matching against the elements of the LHS array.
Instead, it performs equality tests – as -eq would – against the array’s elements – see this answer for details.

In order to perform literal substring matching against the elements of an array, use:

# With non-literal search strings:
[bool] $contains = $group -match ([regex]::Escape($someString))

# With a string literal that doesn't contain regex metachars.,
# escaping isn't needed.
[bool] $contains = $group -match 'foo'

# With a string literal with metachars., you must individually \-escape them.
[bool] $contains = $group -match 'foo\.bar'

Note:

  • The above shows a robust, generic way of ensuring that your search string is treated as a literal value using [regex]::Escape(), which is necessary because -match expects a regex (regular expression) as its RHS (the search pattern).

  • Escaping isn’t always necessary; specifically, only the presence of so-called metacharacters (those with special meaning in a regex, such as .) requires it, and when you’re using a string literal, you can opt to directly \-escape them; e.g., to search for literal substring a.b, you can pass 'a\.b'.

    • Chances are that AD group names do not require escaping, but it’s important to be aware of the need for it in general.

  • As with all operators in PowerShell, by default the matching is case-insensitive; use the -cmatch variant for case-sensitive matching.

  • The [bool] type constrained above is used to ensure that the result of the -match operation is converted to a Boolean:

    • While -match directly returns a Boolean with a scalar (non-array) LHS, with an array LHS it acts as a filter, and returns the matching array elements instead; interpreted in a Boolean context, such as in an if conditional, that usually still gives the expected result, because a non-empty array is interpreted as $true, whereas an empty one as $false; again, however it’s important to know the difference.

  • This will rarely be a performance concern in practice, but it is worth noting that -match, due to acting as a filter with arrays, always matches against all array elements – it doesn’t stop once the first match is found, the way that the -contains and -in operators do.

  • On the plus side, you can use -match to obtain the matching elements themselves.

The mistaken expectation of -contains performing substring matching may have arisen from confusion with the similarly named, but unrelated String.Contains() method, which indeed performs literal substring matching; e.g., 'foo'.Contains('o') yields $true.
Also note that .Contains() is case-sensitive – invariably in Windows PowerShell, by default in PowerShell (Core) 7+.

PowerShell has no operator for literal substring matching.

However, you could combine PowerShell’s generic array-filtering features with the .Contains() string method – but note that this will typically perform (potentially much) worse than the -match approach.

A reasonably performant alternative is to use the PSv4+ .Where() array method as follows:

# Note: Substring search is case-sensitive here.
[bool] $contains = $group.Where({ $_.Contains("string") }, 'First')

On the plus side, this approach stops matching once the first match is found.

More Related Contents:

  1. Renaming files by reformatting existing filenames – placeholders in replacement strings used with the -replace operator
  2. Unable to Pause or Sleep after Select-Object
  3. What’s the better (cleaner) way to ignore output in PowerShell? [closed]
  4. Is there a way to create an alias to a cmdlet in a way that it only runs if arguments are passed to the alias?
  5. Is there a way to make a PowerShell script work by double clicking a .ps1 file?
  6. Using Get-ChildItem -Exclude or -Include returns nothing
  7. ‘kubectl patch’ works on Linux Bash but not in Windows Powershell ISE
  8. Ternary operator in PowerShell
  9. CMD pipe different form Powershell pipe?
  10. What’s the difference between single quote and double quote to define a string in powershell
  11. Convert Unix time with PowerShell
  12. How can I get the file system location of a PowerShell script?
  13. If Statement Against Dynamic Variable [duplicate]
  14. You cannot call a method on a null-valued expression
  15. How do I compress files using powershell that are over 2 GB?
  16. DateTime subtraction not working in PowerShell – assignment vs. equality operator
  17. Loading Assemblies from NuGet Packages
  18. How can I run a PowerShell script with white spaces in the path from the command line?
  19. How to pass a custom function inside a ForEach-Object -Parallel
  20. How to speed up Powershell Get-Childitem over UNC
  21. How can I start Powershell script as noprofile in Visual Studio Code
  22. In what conditions does powershell unroll items in the pipeline?
  23. How to execute a PowerShell function several times in parallel?
  24. How to send CTRL or ALT + any other key?
  25. notcontains not working for User objects pulled from AD Groups
  26. Can’t install nuget package because of “Failed to initialize the PowerShell host”
  27. How to run powershell command in batch file
  28. How can I elevate Powershell while keeping the current working directory AND maintain all parameters passed to the script?
  29. Are you able to use PtrToStringAuto to decrypt a secure string in Powershell 7 on macOS?
  30. Prevent trailing newline in PowerShell Out-File command

Leave a Comment