.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
See Also:
- expl b lib .tfmt
- for a similar function that takes a time number instead
of a time structure.
- expl b lib .tm
- for the creation and the format of time structures.
- expl b lib .dlang
- for making a new names table the default.
- expl c lib strftime
- for a similar function.
Copyright © 1996, Thinkage Ltd.