.TOSEC - obtain time number.

Alternate Entry Name: _tosec

Usage:

B:
   %b/manif/t_ctrl
   timenum = .tosec(statptr,string[,control,default,
                    tzloc,parstbl]);

C:
   #include <t_ctrl.h>
   time_t _tosec(int *statptr, const char *string,
                 [ long control, time_t default,
                 _T_locale tzloc, _T_parse *parstbl] );

Where:

statptr

points to an integer where .TOSEC may store a status. The status is zero if .TOSEC successfully converts the given string to a time number. Otherwise, .TOSEC constructs a return status by ORing together two values:

One plus the number of characters that .TOSEC successfully read from "string" before finding a construct that could not be part of any recognized date/time format. For example, if .TOSEC reads two characters, this part of the return status is 3. If .TOSEC reads no characters, this part of the return status is 1.
Control flags to indicate any ambiguity found in the date. See below for more details.

You may specify a "statptr" value of 0 (or NULL in C). In this case, .TOSEC will terminate the program with an error message if it can't convert the given string into a time number. Ambiguities don't count as errors in this context; .TOSEC just makes its best guess to resolve the ambiguities and the program keeps running.

string

expresses a date and/or time in almost any form. See below for examples.

control

is an integer that may have bits set as flags. These bits specify hints and preferences for converting the given string to a time number. This argument is optional; if omitted, the default is no flags.

default

tells what time of day should be used if "string" gives a date but not a time. The time is given as a number of seconds from midnight at the beginning of the day. For example, a value of 12*3600 asks to use noon on the given date. A value of negative infinity (1<<35) stands for the current time (i.e. the time at which .TOSEC is called). This argument is optional; if omitted, the default is zero.

tzloc

refers to a time zone locale; see "expl b tz" for more information. If this is zero, "string" is assumed to be a date/time in the "default" time zone locale. If it is non-zero, the value is taken to be a locale reference value and "string" is interpreted as a date/time in that time zone. This argument is optional; if omitted, the default is zero.

parstbl

points to a date/time parsing table. For more information on such tables, see "expl b time". This argument is optional; if omitted, the default is the most recent parsing table set via .TLANG.

timenum

is the number of seconds of the given date and time from 0:00 a.m. Greenwich Mean Time on January 1, 1970.

Description:

.TOSEC converts a date/time string into a time number. It recognizes a huge number of date/time formats, such as

1993/12/25
12/25/93
January 10, 1955, 6:55 p.m. EST
The 21st of July
3 o'clock p.m. yesterday

For more information on the possible formats, see "expl b time".

Control Values:

Control values can be used to state preferences, in case the string is ambiguous in some way. For example, a control value can tell .TOSEC whether

01/02/03

should be interpreted as

mm/dd/yy
yy/mm/dd
dd/mm/yy

Control values are represented by manifests, defined in

b/manif/t_ctrl      -- for B programs
<t_ctrl.h>          -- for C programs

Several manifests may be OR'ed together to create a "control" argument. Below we list the manifests you're most likely to find useful:

_T_FUTURE: You prefer to interpret non-specific dates as the nearest corresponding date in the future. For example, "January 1" would be interpreted as the start of next year, while "Tuesday" is interpreted as next Tuesday.
_T_PAST: You prefer to interpret non-specific dates as the nearest corresponding date in the past. For example, "January 1" would be interpreted as the start of the current year, while "Tuesday" is interpreted as last Tuesday.

If you don't specify either _T_FUTURE or _T_PAST, .TOSEC chooses the appropriate date that is closest to the current date. For example, "Tuesday" refers to the closest Tuesday to today.

In addition to _T_FUTURE and _T_PAST, there are several other flags you might occasionally use. However, these are much less frequently relevant:

_T_SEC, _T_MIN, _T_HOUR, _T_DAY, _T_MONTH, _T_YEAR

are all "negative" flags, indicating how numbers without units should NOT be interpreted. For example, suppose a string is supposed to contain a time of day, with no date information. By specifying

_T_DAY | _T_MONTH | _T_YEAR

you tell .TOSEC not to pick up anything that would be interpreted as a day, a month, or a year. If .TOSEC finds something like "January" in the string, .TOSEC refuses to recognize it and stops interpreting the string.

_T_HHMM, _T_YYMMDD, _T_YYYYMMDD

are "negative" flags similar to the previous ones, indicating that numbers without units should not be interpreted in various ways. For example, specifying _T_HHMM tells .TOSEC not to interpret 4-digit numbers as times in the form HHMM. For example, "1944" would be interpreted as a year rather than the time "19:44".

_T_DAY_PLUS

is another negative flag, telling .TOSEC not to recognize days of the week, like "Monday", "Tuesday", etc.

_T_TODAY_PLUS

is yet another negative flag, telling .TOSEC not to recognize strings relative to today, such as "today", "tomorrow", "yesterday", etc.

_T_OFFSET

is a negative flag, telling .TOSEC not to interpret numbers as positive offsets from the current time. For example, .TOSEC wouldn't recognize strings like "2 days ago".

_T_NEG_OFFSET

is a negative flag, telling .TOSEC not to interpret numbers as negative offsets from the current time. If you specify 0 for the "control" argument, .TOSEC makes its best guess based on defaults specified in its time parsing rules -- see "expl b time".

Return Status:

.TOSEC writes a return status to the integer pointed to by "statptr". If this status is non-zero, it indicates that the given date/time "string" was invalid, or ambiguous in some way. .TOSEC uses the control flags to indicate the type of ambiguity.

For example, consider the string "4 Jan 1930". The 1930 could be interpreted as a year, but since that year is well before the computer age, .TOSEC recognizes the possibility that it might also be a time in the format HHMM (as in 19:30, 7:30 p.m.). .TOSEC therefore ORs in

_T_YEAR | _T_HHMM

with the return value to show the ambiguity. A string like "01/02/97" would generate the result

_T_MON | _T_DAY

indicating an ambiguity in distinguishing the month from the day (either January 2 or February 1). A string like "01/02/03" would generate the result

_T_MON | _T_DAY | _T_YEAR

indicating an ambiguity in distinguishing which value is month, day, and year. On the other hand, "01/01/95" would not turn on any ambiguity flags, since it doesn't matter whether .TOSEC interprets this as MM/DD/YY or DD/MM/YY.

If you want to get rid of any control flags in the return value, AND it with the manifest "_T_USED_MASK". For example, if "*statptr" contains the return value

(*statptr) & _T_USED_MASK

tells the number of characters .TOSEC read before finding something that couldn't be part of the date/time string. If .TOSEC accepted the whole string, this value is zero. If the string is completely unrecognizable as a date/time, the above value is 1 (indicating that .TOSEC did not read any characters successfully).