ifx_gl_convert_date - Convert a date string to an internal representation.
SYNOPSIS
#include <ifxgls.h>
int ifx_gl_convert_date(mi_date *date, char *datestr, char *format)
DESCRIPTION
This function converts the date string stored in datestr into
an internal representation. The internal representation is stored in
the mi_date structure pointed to by date in the format specified
by format.
If format is NULL, then the format is
determined from the environment as follows:
- If the DBDATE environment variable is set, then the date is scanned
according to the order of the format elements in DBDATE.
- If the GL_DATE environment variable is set then the format is scanned according to the specification
of GL_DATE.
- Otherwise the d_fmt setting of the current GLS locale is used.
If format is not NULL, then it must point to a string which
follows the rules described in the FORMAT section below.
FORMAT
The format is composed of zero or more directives. Each directive is
composed of one of the following:
- -
-
one or more white-space characters (as specified by the ifx_gl_ismspace()
function)
- -
-
an ordinary character (neither % or a white-space character)
- -
-
a conversion specification. Each conversion specification is composed
of a % character followed by a conversion character which specifies
the replacement required. There must be white-space or other
non-alphanumeric characters between any two conversion
specifications.
The following conversion specifications are supported:
- %a
-
is the day of the week, using the locale's weekday names; either the
abbreviated or full name may be specified (see the 'abday' and 'day'
sub-categories of the locale's LC_TIME category).
- %A
-
is the same as %a.
- %b
-
is the month, using the locale's month names; either the
abbreviated or full name may be specified (see the 'abmon' and 'mon'
sub-categories of the locale's LC_TIME category).
- %B
-
is the same as %b.
- %C
-
is the century number [0,99]; leading zeros are permitted, but
not required.
- %d
-
is the day of the month as a decimal number [01,31]; leading
zeros are permitted, but not required.
- %e
-
is the same as %d.
- %h
-
same as %b.
- %j
-
is the day of the year as a decimal number [001,366].
Leading zeros are permitted, but not required.
- %m
-
is the month as a decimal number [01,12].
Leading zeros are permitted, but not required.
- %n
-
is any white space as defined by ifx_gl_ismspace().
- %t
-
is any white space as defined by ifx_gl_ismspace().
- %u
-
is the weekday as a decimal number [1,7], with 0
representing Sunday. Leading zeros are permitted, but not required.
- %w
-
is the weekday as a decimal number [0,6], with 0
representing Sunday. Leading zeros are permitted, but not required.
- %x
-
the value of the 'd_fmt' sub-category of the locale's LC_TIME category
is temporarily used as the format string.
- %y
-
is year within century as a decimal number [00,99].
Leading zeros are permitted, but not required. The century associated
with this year is determined from the DBCENTURY setting.
- %iy
-
Is an Informix backward compatibility modifier which scans like the
Informix DBDATE format Y2. Both "96" and "1996" would be interpreted as
1996 (or whatever is appropriate according to DBCENTURY).
- %Y
-
is year including the century as a decimal number [0000,9999].
- %iY
-
Is an Informix backward compatibility modifier which scans like the
Informix DBDATE format Y4. Both "96" and "1996" would be interpreted as
1996 (or whatever is appropriate according to DBCENTURY).
- %%
-
is replaced by %.
If a conversion specification does not correspond to any of the above,
the behaviour is undefined.
Modified Directives
Some directives specifiers can be modified by the E or O modifier
characters to indicate that an alternative format or specification
should be used rather than the one normally used by the unmodified
directive. If the alternative format or specification does
not exist for the current locale, the behavior will be as if unmodified
conversion specifications were used.
- %EC
-
is the name of the base year (period) in the locale's alternative
representation. Either the abbreviated or full name may be specified.
(see the 'era' sub-category of the locale's LC_TIME category).
- %Eg
-
is the same as %EC.
- %Ex
-
the value of the 'era_d_fmt' sub-category of the locale's LC_TIME category
is temporarily used as the format string.
- %Ey
-
is the offset from %EC (year only) in the
locale's alternative representation
(see the 'era' sub-category of the locale's LC_TIME category).
- %EY
-
is the full alternative year representation
(see the 'era' sub-category of the locale's LC_TIME category).
- %Od
-
is the day of the month using the locale's alternative numeric digits.
Leading zeros are permitted, but not required.
- %Oe
-
is the same as %Od.
- %Om
-
is the month using the locale's alternative numeric
digits
- %Ow
-
is the weekday as a number using the locale's alternative
numeric digits (Sunday=0).
- %Oy
-
is the value of %Ey using the locale's alternative numeric digits.
A directive that is an ordinary character is executed by scanning the next
character from the buffer. If the character scanned from the buffer differs
from the one comprising the directive, the directive fails, and the differing
and subsequent characters remain unscanned.
A series of directives composed of %n, %t, white-space characters or any
combination is executed by scanning up to the first character that is not
white space (which remains unscanned), or until no more characters can
be scanned.
Any other conversion specification is executed by scanning characters
until one or more characters matching the next directive is scanned,
or until no more characters can be scanned. These characters, except
the one matching the next directive, are then compared to the current locale
values associated with the conversion specifier. If a match is found,
then date is updated appropriately. Case is ignored when
matching items in s such as month or weekday names. If no match if
found, no more characters are scanned and failure is returned.
Field Description Specification
An optional field description specification may immediately follow
the initial % of a directive for any format specifications which
read numeric values. This field description has the following format:
[-|0][<max-width>][.<min-width>]
If the first character of the field description is a minus (-), then
the field is assumed to be left justified. In this case the value
being read must start with a digit and may be trailed with spaces.
If the first character of the field description is not a minus, then
the field is assumed to be right justified. The field may be preceeded
with leading spaces unless the first character is a zero (0).
If the first character of field description is a zero, then the
field is assumed to be right justifed. Any left had padding must
use zeros.
After the optional justification and padding information, an optional
maximum field width may be specified. This maximum field width is
a decimal number.
Finally, an optional minimum field width may be specified. This minimum
field width is defined by a decimal point followed by a decimal number.
Any field description specification will be ignored for non-numeric
or compound formats.
DEFAULTS
In order to determine the year using era information, the era base,
era offset, day and month are needed. A default era offset of 1 will
be used if era base, day and month but not era offset are specified.
AMBIGUOUS FORMATS
This section describes how ambiguous formats are handled.
If format contains redundant format specifiers then specifiers that
are closer to the the end of the format string will take precedence
over ones closer the beginning of the format string.
If %y is used without %C and the month and day of month are part of the
input string, then the century is determined from DBCENTURY.
If %C is used without %y then it is ignored.
In order to determine the year from era information, the day, month,
and era name must be included in the format. If the era offset is not
specified, then an offset of 1 is assumed.
RETURN VALUES
On success, this function returns 0.
On failure, this function returns -1.
ERRORS
If an error has occurred, this function returns -1 and
ifx_gl_lc_errno() returns,
- [IFX_GL_EBADF]
- The format specifier is invalid
- [IFX_GL_INVALIDFMT]
- Invalid formatted argument string
- [IFX_GL_EDAYRANGE]
- Day number out of bounds
- [IFX_GL_EWKDAYRANGE]
- Week Day number out of bounds
- [IFX_GL_EYDAYRANGE]
- Year Day number out of bounds
- [IFX_GL_EMONTHRANGE]
- Month number out of bounds
- [IFX_GL_EYEARRANGE]
- Year number out of bounds
- [IFX_GL_EERAOFFRANGE]
- Era Offset out of bounds
- [IFX_GL_BADDAY]
- Month Day could not be scanned
- [IFX_GL_BADWKDAY]
- Week Day could not be scanned
- [IFX_GL_BADYDAY]
- Year Day could not be scanned
- [IFX_GL_BADMONTH]
- Month could not be scanned
- [IFX_GL_BADYEAR]
- Year could not be scanned
- [IFX_GL_BADERANAME]
- Invalid Era name
- [IFX_GL_BADERAOFFSET]
- Invalid Era offset
- [IFX_GL_BADFMTMOD]
- Invalid Format modifer
- [IFX_GL_BADFMTWP]
- Invalid width/precision
- [IFX_GL_BADINPUT]
- Input string doesn't match format
- [IFX_GL_NOPOINT]
- Missing decimal point in input
- [IFX_GL_BADMONTHSTR]
- Month string could not be scanned
- [IFX_GL_BADFMTMOD]
- Invalid Format modifer
- [IFX_GL_BADFMTWP]
- Invalid width/precision
- [IFX_GL_BADINPUT]
- Input string doesn't match format
- [IFX_GL_BADMONTHSTR]
- Month string could not be scanned
- [IFX_GL_BADERASPEC]
- Couldn't load era from locale
SEE ALSO
ifx_gl_format_date(),
ACKNOWLEDGEMENT
Portions of this description were derived from the X/Open CAE
Specification: "System Interfaces and Headers, Issue 4"; X/Open
Document Number: C202; ISBN: 1-872630-47-2; Published by X/Open Company
Ltd., U.K.