sm(X;Y)

Returns a boolean value indicating whether a given string matches a particular template, and is case sensitive.

Syntax

sm(X;Y)

Input

Argument Type Description
X text The string on which to apply the function

A scalar value or the name of a column
Y text A string that defines a pattern against which to compare X
Y contains those characters that must appear in X plus special "wildcard" characters:
  • An asterisk (*) represents any zero or more characters.

    For example, 'ab*c' matches 'abc' and 'abwc' and 'abxyzc'.

  • A question mark (?) represents any single character.

    For example, 'ab?c' matches 'abwc' and 'abxc' but not 'abxyzc'.

  • Square brackets ([]) serve two functions:
    1. The contents of the brackets represents a choice of characters. 

      For example, 'ab[cd]e' matches either 'abce' or 'abde'.

      A ^ before the characters in the brackets will match any character except those characters in the brackets.

      For example, '[^abc]def' means that the first character can be any character except a, b, or c. 'ddef', 'edef', 'fdef', and so on would be a match.

    2. Any special character appearing within brackets is taken at face value and not treated as special. 

      For example, 'ab[*]c' matches 'ab*c' but not 'abwc'. To match the character "[", use '[[]'.

Return Value

Returns an integer value of 1 if X fits the pattern defined by Y. Otherwise, returns 0.

If X is N/A, the result is 0.

Sample Usage

value pattern sm(value;pattern)
'abcdefg' 'bcd' 0
'abcdefg' '*bcd*' 1
'abcdefg' '*b*' 1
'abcdefg' '*b?d*' 1
'abcdefg' '*b?e*' 0
'abcdefg' '*[bB][cC][dD]*' 1
'ABCDEFG' '*[bB][cC][dD]*' 1
'abcdefg' '[^abc]bcdefg' 0
'abcdefg' '[^def]bcdefg' 1

Example

In the "Monthly Statewide Seasonally Adjusted Unemployment Statistics" table (pub.fin.fred2.bls.smsa), you can find only those rows whose state abbreviations begin with the letter "N". To do this, create a computed column and apply the sm(X;Y) function to the state column, and specify "N?" as the pattern to match.

<base table="pub.fin.fred2.bls.smsa"/>
<willbe name="example" value="sm(state;'N?')" 
 label="States Beginning`With N"/>
<colord cols="state,example"/>

For those values in the state column that begin with "N", the result is 1. Otherwise, the result is 0.

Additional Information

  • Use sm(X;Y) for pattern matching, unless you have a pattern-matching need that requires a regex function.
  • This function does not work with Unicode (UTF-8) strings.
  • For a Unicode-compliant alternative, consider regex_match(X;L;Y;I).