.TMFMT - format time structure into date/time string.

Alternate Entry Name: _TMFMT

Usage:

B:
   %b/manif/t_ctrl
   size = .tmfmt(string, ssize, format, tsptr, parse);

C:
   #include <time.h>
   #include <t_ctrl.h>
   size_t _tmfmt(char *string, size_t ssize,
                const char *format,
                const struct tm *tsptr,
                const _D_ctrl *parse);

Where:

string: points to a region of memory where .TMFMT can store the date/time string it produces.
ssize: is the maximum number of bytes that .TMFMT may store in "string".
format: points to a string which describes the format of the date/time string you want .TMFMT to produce. This string is similar to a "printf"-style format string, with "%" placeholders to stand for date/time values. See "Format Strings" below.
tsptr: points to a time structure, as created by .TM, containing the date/time you want to express as a string.
parse: points to a table of names: names of the days ("Monday", "Tuesday", etc.), names of months ("January", "February", etc.) and so on. If you supply a NULL pointer for this argument, you get names in the default locale (as set by .DLANG). See the "Names Table" section below for information on supplying your own name lists.
size: is the number of characters in the string that .TMFMT produces. If the date/time string that .TMFMT produces is too big to fit in "string", .TMFMT returns zero and the contents of "string" are indeterminate.

Description:

.TMFMT creates a date/time string of a given "format", based on the time structure indicated by "tsptr". All names (e.g. names of months or days) are based on a structure of names indicated by the "parse"

Format Strings:

A format string consists of normal characters and placeholders. Placeholders consist of '%' followed by another character. The following placeholders are recognized:

%a: day of the week, using abbreviated names (Mon, Tue, etc.)
%A: day of the week, using full names (Monday, Tuesday, etc.)
%b: month, using abbreviated names (Jan, Feb, etc.)
%B: month using full names (January, February, etc.)
%c: date and time in format %x %X (see below)
%C: date and time in long-format date and time representation, as given in names table (see below)
%d: day of month (01-31)
%D: date as %m/%d/%y
%e: day of month (1-31); single digits are preceded by a blank
%h: same as %b
%H: hour (00-23)
%I: hour (00-12)
%j: day number of year (001-366)
%k: hour (0-23); single digits are preceded by a blank
%l: hour (0-12); single digits are preceded by a blank
%m: month number (01-12)
%M: minute (00-59)
%n: new-line character (\n)
%p: the equivalent of AM or PM, as given by the name table
%r: time expressed as %I:%M:%S %p
%R: time expressed as %H:%M
%S: seconds (00-59)
%t: horizontal tab (\t)
%T: time expressed as %H:%M:%S
%U: week number of year (01-52), with Sunday counted as the first day of the week
%w: day of week as number; Sunday as 0
%W: week number of year (01-52), with Monday counted as the first day of the week
%x: date, using the standard date format given in the names table
%X: time, using the standard time format given in the names table
%y: year within the century (00-99)
%Y: full year, including century (e.g. 1993)
%Z: time zone abbreviation

For both %U and %W, week one of the year is the first week with four or more days of January in it.

For example, a format string of the form

"%A %B %e, %Y; %Hh %Mm %Ss"

might produce an output "string" like

Friday July 23, 1993; 10h 32m 27s

Names Tables:

The names table provides extra information for the formatting process, including the names of months and days, and some default date/time formats. Below we give the format in the form of a declaration from the C programming language:

typedef struct {
    char *percent_A[7];  /* weekday names for %A       */
    char *percent_a[7];  /* short weekday names for %a */
    char *percent_B[12]; /* month names for %B         */
    char *percent_b[12]; /* short month names for %b   */
    char *percent_p[2];  /* AM and PM strings for %p   */
    char *percent_c;     /* date and time string, %c   */
    char *percent_C;     /* date and time string, %C   */
    char *percent_X;     /* standard time format, %X   */
    char *percent_x;     /* standard date format, %x   */
} _D_ctrl;

In addition to the fields given above, there may be additional undocumented fields. Therefore C programmers should always declare such structures using the "_D_ctrl" typedef. B programmers should be aware that all the pointers in the structure have the format of C pointers: the upper half contains the word address, and the lower half contains a byte offset.

The last four elements shown above are given as standard format strings. For example, the string corresponding to "percent_X" might be

"%H:%M:%S"

As mentioned earlier, the names table distributed with the UW Tools package gives names and default formats in English. This table has the external name ".D_ENG" and the alternate name "_D_ENG". If you want to create and use a different table, simply define the table and pass it as an argument to .TMFMT. You can also use the .DLANG function to make your table the default table for the duration of the program.

Defaults:

The default settings in the .D_ENG names table are:

%A: Sunday, Monday, Tuesday, ...
%a: Sun, Mon, Tue, ...
%B: January, February, March, ...
%b: Jan, Feb, Mar, ...
%p: AM, PM
%c: %x %X
%C: %A, %B %e, %Y
%X: %H:%M:%S
%x: %m/%d/%y