A.2 Converting character string to calendar time

The function str2time(s, f) converts a character string (timestamp) specified by its first argument s, which must be a symbolic expression, to the calendar time suitable for arithmetic calculations. The conversion is controlled by the specified format string f (the second argument), which also must be a symbolic expression.

The result of conversion returned by str2time has the same meaning as the value returned by the function gmtime (See Obtaining current calendar time). Note that str2time does not correct the calendar time returned for the local timezone, i.e. being applied to 00:00:00 on January 1, 1970 it always returns 0.

For example, the model statements:

param s, symbolic, := "07/14/98 13:47";
param t := str2time(s, "%m/%d/%y %H:%M");
display t;

produce the following printout:

t = 900424020

where the calendar time printed corresponds to 13:47:00 on July 14, 1998.

The format string passed to the function str2time consists of conversion specifiers and ordinary characters. Each conversion specifier begins with a ‘%’ character followed by a letter.

The following conversion specifiers may be used in the format string:

%b

The abbreviated month name (case insensitive). At least three first letters of the month name must appear in the input string.

%d

The day of the month as a decimal number (range 1 to 31). Leading zero is permitted, but not required.

%h

The same as %b.

%H

The hour as a decimal number, using a 24-hour clock (range 0 to 23). Leading zero is permitted, but not required.

%m

The month as a decimal number (range 1 to 12). Leading zero is permitted, but not required.

%M

The minute as a decimal number (range 0 to 59). Leading zero is permitted, but not required.

%S

The second as a decimal number (range 0 to 60). Leading zero is permitted, but not required.

%y

The year without a century as a decimal number (range 0 to 99). Leading zero is permitted, but not required. Input values in the range 0 to 68 are considered as the years 2000 to 2068 while the values 69 to 99 as the years 1969 to 1999.

%z

The offset from GMT in ISO 8601 format.

%%

A literal ‘%’ character.

All other (ordinary) characters in the format string must have a matching character in the input string to be converted. Exceptions are spaces in the input string which can match zero or more space characters in the format string.

If some date and/or time component(s) are missing in the format and, therefore, in the input string, the function str2time uses their default values corresponding to 00:00:00 on January 1, 1970, that is, the default value of the year is 1970, the default value of the month is January, etc.

The function str2time is applicable to all calendar times in the range 00:00:00 on January 1, 0001 to 23:59:59 on December 31, 4000 of the Gregorian calendar.