NCL Home > Documentation > Functions > Date routines

ut_string

Converts time values into nicely formatted strings (deprecated; use cd_string)

Available in version 5.2.0 and later.

Prototype

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

	function ut_string (
		time      : numeric,  
		inFormat  : string    
	)

Arguments

time

An array containing the values of time. This variable must have an attribute named "units".

inFormat

A string specifying the format of the tick labels. See the description section below for more details.

Return value

A string array representing the time(s) in the specified format.

Description

Unidata no longers supports the internal code that ut_string is based on. We therefore strongly recommend that you use the cd_string function instead.

This function converts time values to nicely formatted strings, based on the inFormat format string.

Note: this function behaves the same as cd_string, except it uses ut_calendar to initially convert the time format. ut_calendar has been deprecated, and cd_calendar supports more calendars, so you may want to use cd_string.

Known bug in NCL V6.4.0 and earlier: Many users have reported a "60 second" bug in several of NCL's date conversion routines, in which you get a value of "n minutes, 60 seconds" instead of "n+1 minutes, 0 seconds". See the 6.4.0 release notes for details. If you encounter this bug, please email the ncl-talk group with the details. Meanwhile, you can try the temporary ut_string_fix, which was added in NCL V6.4.0 for test purposes and potentially as a replacement function. A decision will be made about this function in a future release of NCL.

The '%' acts as an escape character. The single character after every '%' is formatted according to the rules:

Y	=>	4-digit year (e.g., 2007).
y	=>	2-digit year (e.g., 07).
C	=>	CAPITAL month abbreviation (e.g., JUN).
c	=>	Small month abbreviation (e.g., Jun).
F	=>	CAPITAL full month (e.g., JUNE).
f	=>	Small full month (e.g., June).
N	=>	2-digit month (e.g., 06).
n	=>	1 or 2 digit month (e.g., 6 for June, 12 for December).
D	=>	2-digit day (e.g., 04).
d	=>	1 or 2 digit day (e.g., 4)
H	=>	2-digit hour (e.g., 09).
h	=>	1 or 2 digit hour (e.g., 9 or 11).
M	=>	2 digit minute (e.g., 08).
m	=>	1 or 2 digit minute (e.g., 07 or 56).
S	=>	2 digit second (e.g., 02).
s	=>	1 or 2 digit second (e.g., 2 or 23).
J	=>	3-digit day-of-year (e.g., 091) (added in v6.0.0)
j	=>	1, 2, or 3 digit day-of-year (e.g., 4, 91, or 181) (added in v6.0.0)

Any character at any other place in the format string is drawn as is.

NOTE: a '%' can be drawn using "%%".

If inFormat is set to an empty string (""), it will default to "%H%M UTC %d %c %Y" (e.g. "1800 UTC 4 Jul 1776").

Acknowledgements:

This function is based on the time_axis_labels procedure, written by Arindam Chakraborty, Centre for Atmospheric and Oceanic Sciences (Indian Institute of Science). It was adapted by:

Carl J. Schreck, III
PhD Student
Department of Atmospheric and Environmental Sciences
University at Albany

Examples

For all the following examples, assume that time is an array of time values.

Example 1

Using the default format string of "" will result in "HHMM UTC D Mon YYYY" (e.g., 1800 UTC 4 Jul 1776):

  format = ""
  stime  = ut_string(time,format)

Example 2

To format the time values as "CccYy" (Apr98, May98, etc):

  format = "%c%y"
  stime  = ut_string(time,format)

Example 3

To format the time values as "NN/YYYY" (04/1998, 05/1998, etc):

  format = "%N/%Y"
  stime  = ut_string(time,format)

Example 4

To format the time values as "HH:MM:SS":

  format = "%H:%M:%S"
  stime  = ut_string(time,format)

To specify month/day as well, use:

  format = "%N/%D %H:%M:%S"

Example 5

To format the hour values as "HH:00 Hours" use:

  format = "%H:00 Hours"
  stime  = ut_string(time,format)

Example 6

To format the time values as "29 Jun", "4 Jul", etc:

 format = "%d %c"
 stime  = ut_string( time, format)