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

See Also

time_axis_labels, cd_convert, cd_string, cd_calendar, cd_inv_calendar

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)

For using these labels in a plot, see the documentation for time_axis_labels.