NCL Home > Documentation > Functions > String manipulation

str_match

Returns a list of strings that contain the given substring (case sensitive).

Available in version 5.2.0 and later.

Prototype

	function str_match (
		string_array   : string,  
		sub_string [1] : string   
	)

	return_val [*] :  string

Arguments

string_array

A string array of any dimensionality.

sub_string

The substring to be matched.

Return value

Note that the return value will always be a one-dimensional array, regardless of the dimensionality of the input array. See the examples below.

Description

This function returns an array of strings with every occurrence of sub_string matched in string_array.

If there is no sub_string matched in string_array, the default string missing value ("missing") will be returned.

Please note, str_match is case SENSITIVE as of version 6.0.0. There's a bug in versions 6.0.0-beta and earlier in which this function is not case sensitive.

Use str_match_ic if you need case insensitivity.

See Also

str_index_of_substr, str_sub_str, str_match_ic, str_match_ind, str_match_ind_ic, str_match_regex, str_match_ic_regex, str_match_ind_regex, str_match_ind_ic_regex

Examples

Example 1

Get all the strings containing "cnConst" from the list of contour resources: 

 class_out = NhlGetClassResources("contourPlotClass", "")

 cnConst = str_match(class_out, "cnConst")

 print(cnConst)
Output: 
(0)     cnConstFLabelAngleF
(1)     cnConstFLabelBackgroundColor
(2)     cnConstFLabelConstantSpacingF
(3)     cnConstFLabelFont
(4)     cnConstFLabelFontAspectF
(5)     cnConstFLabelFontColor
(6)     cnConstFLabelFontHeightF
(7)     cnConstFLabelFontQuality
(8)     cnConstFLabelFontThicknessF
(9)     cnConstFLabelFormat
(10)    cnConstFLabelFuncCode
(11)    cnConstFLabelJust
(12)    cnConstFLabelOn
(13)    cnConstFLabelOrthogonalPosF
(14)    cnConstFLabelParallelPosF
(15)    cnConstFLabelPerimColor
(16)    cnConstFLabelPerimOn
(17)    cnConstFLabelPerimSpaceF
(18)    cnConstFLabelPerimThicknessF
(19)    cnConstFLabelSide
(20)    cnConstFLabelString
(21)    cnConstFLabelTextDirection
(22)    cnConstFLabelZone
(23)    cnConstFUseInfoLabelRes
Example 2

Create a 3 x 10 string array with dummy year and month values. str_match always returns a 1D array regardless of the input array dimensionality: 

;---Create dummy input array
  months       = (/"Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec"/)
  array2d      = new((/3,10/),string)
  array2d(0,:) = months(0:9) + " 1999"
  array2d(1,:) = months(2:11) + " 2000"
  array2d(2,:) = "Jan 20" + sprinti("%02i",ispan(1,10,1))

;---Print dummy input array
  slist = [/array2d(0,:),array2d(1,:),array2d(2,:)/]
  print_table([/"================================"/],"%s")
  print_table([/"            array2d"/],"%s")
  print_table([/"================================"/],"%s")
  print_table(slist,"  %s   %s   %s")
  print_table([/"================================"/],"%s")

;---Match all strings that contain 'A', 'Mar', and '2000'
  a_strs    = str_match(array2d,"A")
  mar_strs  = str_match(array2d,"Mar")
  year_strs = str_match(array2d,"2000")

;---Print results of various string matching statements
  print("a_strs    = " + str_join(a_strs,","))
  print("mar_strs  = " + str_join(mar_strs,","))
  print("year_strs = " + str_join(year_strs,","))

Output: 

================================
            array2d
================================
  Jan 1999   Mar 2000   Jan 2001
  Feb 1999   Apr 2000   Jan 2002
  Mar 1999   May 2000   Jan 2003
  Apr 1999   Jun 2000   Jan 2004
  May 1999   Jul 2000   Jan 2005
  Jun 1999   Aug 2000   Jan 2006
  Jul 1999   Sep 2000   Jan 2007
  Aug 1999   Oct 2000   Jan 2008
  Sep 1999   Nov 2000   Jan 2009
  Oct 1999   Dec 2000   Jan 2010
================================
a_strs    = Apr 1999,Aug 1999,Apr 2000,Aug 2000
mar_strs  = Mar 1999,Mar 2000
year_strs = Mar 2000,Apr 2000,May 2000,Jun 2000,Jul 2000,Aug 2000,Sep 2000,Oct 2000,Nov 2000,Dec 2000
Example 2

Create a 3 x 10 string array with dummy year and month values. str_match always returns a 1D array regardless of the input array dimensionality: 

;---Create dummy input array
  months       = (/"Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec"/)
  array2d      = new((/3,10/),string)
  array2d(0,:) = months(0:9) + " 1999"
  array2d(1,:) = months(2:11) + " 2000"
  array2d(2,:) = "Jan 20" + sprinti("%02i",ispan(1,10,1))

;---Print dummy input array
  slist = [/array2d(0,:),array2d(1,:),array2d(2,:)/]
  print_table([/"================================"/],"%s")
  print_table([/"            array2d"/],"%s")
  print_table([/"================================"/],"%s")
  print_table(slist,"  %s   %s   %s")
  print_table([/"================================"/],"%s")

;---Match all strings that contain 'A', 'Mar', and '2000'
  a_strs    = str_match(array2d,"A")
  mar_strs  = str_match(array2d,"Mar")
  year_strs = str_match(array2d,"2000")

;---Print results of various string matching statements
  print("a_strs    = " + str_join(a_strs,","))
  print("mar_strs  = " + str_join(mar_strs,","))
  print("year_strs = " + str_join(year_strs,","))

Output: 

================================
            array2d
================================
  Jan 1999   Mar 2000   Jan 2001
  Feb 1999   Apr 2000   Jan 2002
  Mar 1999   May 2000   Jan 2003
  Apr 1999   Jun 2000   Jan 2004
  May 1999   Jul 2000   Jan 2005
  Jun 1999   Aug 2000   Jan 2006
  Jul 1999   Sep 2000   Jan 2007
  Aug 1999   Oct 2000   Jan 2008
  Sep 1999   Nov 2000   Jan 2009
  Oct 1999   Dec 2000   Jan 2010
================================
a_strs    = Apr 1999,Aug 1999,Apr 2000,Aug 2000
mar_strs  = Mar 1999,Mar 2000
year_strs = Mar 2000,Apr 2000,May 2000,Jun 2000,Jul 2000,Aug 2000,Sep 2000,Oct 2000,Nov 2000,Dec 2000