NCL Home > Documentation > Functions > Date routines

cd_inv_string

Converts string time values to numeric values, using the given format string.

Available in version 6.4.0 and later.

Prototype

load "$NCARG_ROOT/lib/ncarg/nclscripts/contrib/cd_inv_string.ncl"

	function cd_inv_string (
		str_time     : numeric,  
		time_format  : string    
	)

	return_val [*] :  numeric

Arguments

str_time

An array containing the values of time as a string, for example, "10/05/2014 06:00:00".

time_format

A string specifying the format of the str_time strings. See the description section below for more details.

Return value

A numeric array of size dimsizes(str_time) containing time in numeric representation. The return array will have a "units" and "calendar" attribute attached.

Description

This function converts time values from formatted strings to numeric values, using cd_inv_calendar under the hood.

This function performs the reverse of cd_string.

For the str_format string, the '%' acts as an escape character. The single character after every '%' is formatted according to the following rules:

D 2-digit day (e.g., 04).
r * 2 digit fractional second (e.g. 25 = 15 seconds)
H 2-digit hour (e.g., 09).
J 3-digit day-of-year (e.g., 091)
M 2 digit minute (e.g., 08).
N 2-digit month (e.g., 06).
S 2 digit second (e.g., 02).
Y 4-digit year (e.g., 2007).
y 2-digit year (e.g., 07).
This will be added to a base of 2000, unless format@century is defined.
c * 3-character month, case insensitive (e.g. jun)
C * 3-character month, case insensitive (e.g. JUN)
f * Full month name, case insensitive (e.g. january)
F * Full month name, case insensitive (e.g. JANUARY)

*These options were added in NCL V6.5.0. In NCL V6.4.0, and earlier, 'r' was 'f'. It was changed to 'r' in NCL V6.5.0 for compatibility with cd_string.

Acknowledgements:

This function was contributed by Alan Brammer of the University at Albany - SUNY. It was modified for NCL V6.5.0 by Jared Lee of NCAR and Alan to add recognition of more formatting options.

See Also

cd_string, time_axis_labels, cd_convert

Examples

Example 1

  instring = "GFS_140621_18_000"
  format   = "GFS_%y%N%D_%H_000"

  time = cd_inv_string(instring, format)
  print(time)

Output: 

Variable: time
Type: double
Total Size: 8 bytes
            1 values
Number of Dimensions: 1
Dimensions and sizes:   [1]
Coordinates: 
Number Of Attributes: 3
  _FillValue :  9.969209968386869e+36
  calendar :    standard
  units :       hours since 1800-01-01 00:00:00
(0)     1880010

You can pass "time" back into cd_calendar to get other desired values: 

  print(cd_calendar(time,0))

Output: 

. . .
(0,0)   2014
(0,1)    6
(0,2)   21
(0,3)   18
(0,4)    0
(0,5)    0

Example 2

Use the special "century" attribute to change the desired base year: 

  instring       = "GFS_140621_18_000"
  format         = "GFS_%y%N%D_%H_000"
  format@century = 1900

  time = cd_inv_string(instring, format)
  print(time)

  format@units = "hours since 1900-01-01 00:00:00"
  print(cd_calendar(time,0))

Output: 

Variable: time
Type: double
Total Size: 8 bytes
            1 values
Number of Dimensions: 1
Dimensions and sizes:   [1]
Coordinates: 
Number Of Attributes: 3
  _FillValue :  9.969209968386869e+36
  calendar :    standard
  units :       hours since 1800-01-01 00:00:00
(0)     1003410
. . .
(0,0)   1914
(0,1)    6
(0,2)   21
(0,3)   18
(0,4)    0
(0,5)    0