Compaq C Run-Time Library Utilities Reference Manual

Document revision date: 30 March 2001

Compaq C Run-Time Library Utilities Reference Manual

Contents

Index

2.6 LC_NUMERIC Category

The LC_NUMERIC category defines rules and symbols for formatting nonmonetary numeric information. This category begins with the LC_NUMERIC and ends with the END LC_NUMERIC trailer.

All operands for the LC_NUMERIC category keywords are defined as string or integer values. String values are bounded by double quotation marks ("). All values are separated from the keyword they define by one or more blank characters (spaces or tabs). Two adjacent double quotation characters ("") indicate an undefined string value. A negative one (-1) indicates an undefined integer value.

Table 2-6 lists the statement keywords recognized in the LC_NUMERIC category.

Table 2-6 LC_NUMERIC Category Keywords
Keyword Description

copy Specifies the name of an existing locale to be used as the definition of this category.
If you specify a copy statement, you cannot specify any other keyword.

decimal_point Specifies the decimal delimiter string used to format nonmonetary numeric quantities.
This keyword cannot be omitted and cannot be set to the undefined string value.

thousands_sep Specifies the string separator used for grouping digits to the left of the decimal delimiter in formatted nonmonetary numeric quantities.

grouping Defines the size of each group of digits in formatted monetary quantities.
The operand for the grouping keyword consists of a sequence of integers separated by semicolons. Each integer specifies the number of digits in a group. The first integer defines the size of the group immediately to the left of the decimal delimiter. Subsequent integers define succeeding groups to the left of the previous group. Grouping is performed for each integer specified for the grouping keyword. If the last integer is not -1, it is used repeatedly to group any remaining digits. If the last integer is -1, no more grouping is performed.
A sample interpretation of the grouping statement follows. Assuming a value of 123456789 to be formatted and a thousands_sep operand of ' (single quotation mark), the following results occur:

mon_grouping Formatted Value

3;-1 123456'789

3 123'456'789

3;2;-1 1234'56'789

3;2 12'34'56'789

The following is a sample LC_NUMERIC category specified in a locale definition source file:

LC_NUMERIC # decimal_point "<period>" thousands_sep "<comma>" grouping <3> # END LC_NUMERIC

2.7 LC_TIME Category

The LC_TIME category defines rules and symbols for formatting time and date information. This category begins with the LC_TIME category header and ends with the END LC_TIME trailer.

All operands for the LC_TIME category keywords are defined as string or integer values. String values are bounded by double quotation marks ("). All values are separated from the keyword they define by one or more blank characters (spaces or tabs). Two adjacent double quotation characters ("") indicate an undefined string value. Field descriptors, described later in this section, are used by commands and subroutines that query the LC_TIME category to represent elements of time and date formats.

2.7.1 Keywords

Table 2-7 lists the statement keywords recognized in the LC_TIME category.

Table 2-7 LC_TIME Category Keywords
Keyword Description

copy Specifies the name of an existing locale to be used as the definition of this category.
If you specify a copy statement, you cannot specify any other keyword.

abday Defines the abbreviated weekday names corresponding to the %a field descriptor.
Recognized values consist of seven strings separated by semicolons. The first string corresponds to the abbreviated name for the first day of the week (Sun), the second to the abbreviated name for the second day of the week, and so on.

day Defines the full spelling of the weekday names corresponding to the %A field descriptor.
Recognized values consist of seven strings separated by semicolons. The first string corresponds to the full spelling of the name of the first day of the week (Sunday), the second to the name of the second day of the week, and so on.

abmon Defines the abbreviated month names corresponding to the %b field descriptor.
Recognized values consist of 12 strings separated by semicolons. The first string corresponds to the abbreviated name for the first month of the year (Jan), the second to the abbreviated name for the second month of the year, and so on.

mon Defines the full spelling of the month names corresponding to the %B field descriptor.
Recognized values consist of 12 strings separated by semicolons. The first string corresponds to the full spelling of the name for the first month of the year (January), the second to the full spelling of the name for the second month of the year, and so on.

d_t_fmt Defines the string used for the standard date-and-time format corresponding to the %c field descriptor. The string can contain any combination of characters and field descriptors.

d_fmt Defines the string used for the standard date format corresponding to the %x field descriptor. The string can contain any combination of characters and field descriptors.

t_fmt Defines the string used for the standard time format corresponding to the %X field descriptor. The string can contain any combination of characters and field descriptors.

am_pm Defines the strings used to represent a.m. (before noon) and p.m. (afternoon) corresponding to the %p field descriptor.
Recognized values consist of two strings separated by semicolons. The first string corresponds to the a.m. designation, the second string corresponds to the p.m. designation.

t_fmt_ampm Defines the string used for the standard 12-hour time format that includes an am_pm value (%p field descriptor).
This statement corresponds to the %r field descriptor. The string can contain any combination of characters and field descriptors. If the string is empty, the 12-hour format is not supported by the locale.

era Defines how the years are counted and displayed for each era in a locale, corresponding to the %E field descriptor modifier.
For each era, there must be one string in the following format:
direction: offset: start_date: end_date: name: format
The variables for the era string format are defined as follows:

direction --- Specifies a minus (-) or a plus (+) character.
The minus character (-) indicates that years count in the negative direction when moving from the start date to the end date. The plus character (+) indicates that years count in the positive direction when moving from the start date to the end date.
offset --- Specifies a number representing the first year of the era corresponding to the %Ey field descriptor.
start_date --- Specifies the starting date of the era in yyyy/mm/dd format, where yyyy, mm, and dd are the year, month, and day, respectively, on the Gregorian calendar.
Years prior to the year A.D. 1 are represented as negative numbers. For example, an era beginning March 5 in the year 100 B.C. would be represented as -100/03/05.
end_date --- Specifies the ending date of the era in the same form used for the start_date variable or one of the two special values -* or +*.
A -* value indicates that the ending date of the era extends backward to the beginning of time. A +* value indicates that the ending date of the era extends forward to the end of time. Therefore, the ending date can be chronologically before or after the starting date of the era. For example, the strings for the Christian eras A.D. and B.C. would be entered, respectively, in the following way:
+:0:0000/01/01:+*:AD:%Ey %EC
+:1:-0001/12/31:-*:BC:%Ey %EC

name --- Specifies a string representing the name of the era that is substituted for the %EC field descriptor.
format --- Specifies a strftime , strptime , and wcsftime format string to use when formatting the %EY field descriptor.
This string can contain any strftime , strptime , and wcsftime format control characters (except %EY) and locale-dependent multibyte characters.

An era value consists of one string (enclosed in quotation marks) for each era. If more than one era is specified, each era string is separated by a semicolon (;).

era_d_fmt Defines the string used to represent the date in alternate-era format corresponding to the %Ex field descriptor. The string can contain any combination of characters and field descriptors.

era_t_fmt Defines the locale's alternative time format as represented by the %EX field descriptor for strftime , strptime , and wcsftime .

era_d_t_fmt Defines the locale's alternative date-and-time format as represented by the %Ec field descriptor for strftime , strptime , and wcsftime .

alt_digits Defines alternate strings for digits corresponding to the %O field descriptor.
Recognized values consist of a group of strings separated by semicolons. The first string represents the alternate string for 0 (zero), the second string represents the alternate string for 1, and so on. You can specify a maximum of 100 alternate strings.

**Table 2-7 LC_TIME Category Keywords**
Keyword	Description
`copy`	Specifies the name of an existing locale to be used as the definition of this category. If you specify a `copy` statement, you cannot specify any other keyword.
`abday`	Defines the abbreviated weekday names corresponding to the %a field descriptor. Recognized values consist of seven strings separated by semicolons. The first string corresponds to the abbreviated name for the first day of the week (Sun), the second to the abbreviated name for the second day of the week, and so on.
`day`	Defines the full spelling of the weekday names corresponding to the %A field descriptor. Recognized values consist of seven strings separated by semicolons. The first string corresponds to the full spelling of the name of the first day of the week (Sunday), the second to the name of the second day of the week, and so on.
`abmon`	Defines the abbreviated month names corresponding to the %b field descriptor. Recognized values consist of 12 strings separated by semicolons. The first string corresponds to the abbreviated name for the first month of the year (Jan), the second to the abbreviated name for the second month of the year, and so on.
`mon`	Defines the full spelling of the month names corresponding to the %B field descriptor. Recognized values consist of 12 strings separated by semicolons. The first string corresponds to the full spelling of the name for the first month of the year (January), the second to the full spelling of the name for the second month of the year, and so on.
`d_t_fmt`	Defines the string used for the standard date-and-time format corresponding to the %c field descriptor. The string can contain any combination of characters and field descriptors.
`d_fmt`	Defines the string used for the standard date format corresponding to the %x field descriptor. The string can contain any combination of characters and field descriptors.
`t_fmt`	Defines the string used for the standard time format corresponding to the %X field descriptor. The string can contain any combination of characters and field descriptors.
`am_pm`	Defines the strings used to represent a.m. (before noon) and p.m. (afternoon) corresponding to the %p field descriptor. Recognized values consist of two strings separated by semicolons. The first string corresponds to the a.m. designation, the second string corresponds to the p.m. designation.
`t_fmt_ampm`	Defines the string used for the standard 12-hour time format that includes an `am_pm` value (%p field descriptor). This statement corresponds to the %r field descriptor. The string can contain any combination of characters and field descriptors. If the string is empty, the 12-hour format is not supported by the locale.
`era`	Defines how the years are counted and displayed for each era in a locale, corresponding to the %E field descriptor modifier. For each era, there must be one string in the following format: direction: offset: start_date: end_date: name: format The variables for the era string format are defined as follows: direction --- Specifies a minus (-) or a plus (+) character. The minus character (-) indicates that years count in the negative direction when moving from the start date to the end date. The plus character (+) indicates that years count in the positive direction when moving from the start date to the end date. offset --- Specifies a number representing the first year of the era corresponding to the %Ey field descriptor. start_date --- Specifies the starting date of the era in yyyy/mm/dd format, where yyyy, mm, and dd are the year, month, and day, respectively, on the Gregorian calendar. Years prior to the year A.D. 1 are represented as negative numbers. For example, an era beginning March 5 in the year 100 B.C. would be represented as -100/03/05. end_date --- Specifies the ending date of the era in the same form used for the `start_date` variable or one of the two special values -* or +. A - value indicates that the ending date of the era extends backward to the beginning of time. A +* value indicates that the ending date of the era extends forward to the end of time. Therefore, the ending date can be chronologically before or after the starting date of the era. For example, the strings for the Christian eras A.D. and B.C. would be entered, respectively, in the following way: +:0:0000/01/01:+:AD:%Ey %EC +:1:-0001/12/31:-:BC:%Ey %EC name --- Specifies a string representing the name of the era that is substituted for the %EC field descriptor. format --- Specifies a `strftime` , `strptime` , and `wcsftime` format string to use when formatting the %EY field descriptor. This string can contain any `strftime` , `strptime` , and `wcsftime` format control characters (except %EY) and locale-dependent multibyte characters. An era value consists of one string (enclosed in quotation marks) for each era. If more than one era is specified, each era string is separated by a semicolon (;).
`era_d_fmt`	Defines the string used to represent the date in alternate-era format corresponding to the %Ex field descriptor. The string can contain any combination of characters and field descriptors.
`era_t_fmt`	Defines the locale's alternative time format as represented by the %EX field descriptor for `strftime` , `strptime` , and `wcsftime` .
`era_d_t_fmt`	Defines the locale's alternative date-and-time format as represented by the %Ec field descriptor for `strftime` , `strptime` , and `wcsftime` .
`alt_digits`	Defines alternate strings for digits corresponding to the %O field descriptor. Recognized values consist of a group of strings separated by semicolons. The first string represents the alternate string for 0 (zero), the second string represents the alternate string for 1, and so on. You can specify a maximum of 100 alternate strings.

2.7.2 Field Descriptors

The LC_TIME locale definition source file uses field descriptors to represent elements of time and date formats. You can combine these field descriptors to create other field descriptors or to create time and date format strings. When used in format strings that contain field descriptors and other characters, field descriptors are replaced by their current values. All other characters are copied without change. Table 2-8 lists the field descriptors used by commands and subroutines that query the LC_TIME category for time formatting.

Table 2-8 LC_TIME Locale Field Descriptors
Field Descriptor Meaning

%a Represents the abbreviated weekday name (for example, Sun) defined by the abday statement.

%A Represents the full weekday name (for example, Sunday) defined by the day statement.

%b Represents the abbreviated month name (for example, Jan) defined by the abmon statement.

%B Represents the full month name (for example, January) defined by the mon statement.

%c Represents the date-and-time format defined by the d_t_fmt statement.

%C Represents the century as a decimal number (00 to 99).

%d Represents the day of the month as a decimal number (01 to 31).

%D Represents the date in %m/%d/%y format (for example, 01/31/91).

%e Represents the day of the month as a decimal number (1 to 31).
If the day of the month is not a 2-digit number, the leading digit is filled with a space character.

%Ec Specifies the alternate date-and-time representation for the locale.

%EC Specifies the name of the base year (period) in the locale's alternate representation.

%Ex Specifies the alternate date representation for the locale.

%Ey Specifies the offset from %EC (year only) in the locale's alternate representation.

%EY Specifies the full alternate year representation.

%h Represents the abbreviated month name (for example, Jan) defined by the abmon statement. This field descriptor is a synonym for the %b field descriptor.

%H Represents the 24-hour clock hour as a decimal number (00 to 23).

%I Represents the 12-hour clock hour as a decimal number (01 to 12).

%j Represents the day of the year as a decimal number (001 to 366).

%m Represents the month of the year as a decimal number (01 to 12).

%M Represents the minutes of the hour as a decimal number (00 to 59).

%n Specifies a new-line character.

%Od Specifies the day of the month by using the locale's alternate numeric symbols.

%Oe Specifies the day of the month by using the locale's alternate numeric symbols.

%OH Specifies the hour (24-hour clock) by using the locale's alternate numeric symbols.

%OI Specifies the hour (12-hour clock) by using the locale's alternate numeric symbols.

%Om Specifies the month by using the locale's alternate numeric symbols.

%OM Specifies the minutes by using the locale's alternate numeric symbols.

%OS Specifies the seconds by using the locale's alternate numeric symbols.

%OU Specifies the week number of the year (with Sunday as the first day of the week) by using the locale's alternate numeric symbols.

%Ow Specifies the weekday as a number in the locale's alternate representation (Sunday = 0).

%OW Specifies the week number of the year (with Monday as the first day of the week) by using the locale's alternate numeric symbols.

%Oy Specifies the year (offset from %C) using the locale's alternate numeric symbols.

%p Represents the a.m. or p.m. string defined by the am_pm statement.

%r Represents the 12-hour clock time with a.m./p.m. notation as defined by the t_fmt_ampm statement.

%S Represents the seconds of the minute as a decimal number (00 to 59).

%t Specifies a tab character.

%T Represents 24-hour clock time in the format %H:%M:%S (for example, 16:55:15).

%U Represents the week of the year as a decimal number (00 to 53).
Sunday, or its equivalent as defined by the day statement, is considered the first day of the week for calculating the value of this field descriptor.

%w Represents the day of the week as a decimal number (0 to 6).
Sunday, or its equivalent as defined by the day statement, is considered to be 0 (zero) for calculating the value of this field descriptor.

%W Represents the week of the year as a decimal number (00 to 53).
Monday, or its equivalent as defined by the day statement, is considered the first day of the week for calculating the value of this field descriptor.

%x Represents the date format defined by the d_fmt statement.

%X Represents the time format defined by the t_fmt statement.

%y Represents the year of the century (00 to 99).

%Y Represents the year as a decimal number (for example, 1989).

%% Specifies a % (percent sign) character.

**Table 2-8 LC_TIME Locale Field Descriptors**
Field Descriptor	Meaning
%a	Represents the abbreviated weekday name (for example, Sun) defined by the `abday` statement.
%A	Represents the full weekday name (for example, Sunday) defined by the `day` statement.
%b	Represents the abbreviated month name (for example, Jan) defined by the `abmon` statement.
%B	Represents the full month name (for example, January) defined by the `mon` statement.
%c	Represents the date-and-time format defined by the `d_t_fmt` statement.
%C	Represents the century as a decimal number (00 to 99).
%d	Represents the day of the month as a decimal number (01 to 31).
%D	Represents the date in %m/%d/%y format (for example, 01/31/91).
%e	Represents the day of the month as a decimal number (1 to 31). If the day of the month is not a 2-digit number, the leading digit is filled with a space character.
%Ec	Specifies the alternate date-and-time representation for the locale.
%EC	Specifies the name of the base year (period) in the locale's alternate representation.
%Ex	Specifies the alternate date representation for the locale.
%Ey	Specifies the offset from %EC (year only) in the locale's alternate representation.
%EY	Specifies the full alternate year representation.
%h	Represents the abbreviated month name (for example, Jan) defined by the `abmon` statement. This field descriptor is a synonym for the %b field descriptor.
%H	Represents the 24-hour clock hour as a decimal number (00 to 23).
%I	Represents the 12-hour clock hour as a decimal number (01 to 12).
%j	Represents the day of the year as a decimal number (001 to 366).
%m	Represents the month of the year as a decimal number (01 to 12).
%M	Represents the minutes of the hour as a decimal number (00 to 59).
%n	Specifies a new-line character.
%Od	Specifies the day of the month by using the locale's alternate numeric symbols.
%Oe	Specifies the day of the month by using the locale's alternate numeric symbols.
%OH	Specifies the hour (24-hour clock) by using the locale's alternate numeric symbols.
%OI	Specifies the hour (12-hour clock) by using the locale's alternate numeric symbols.
%Om	Specifies the month by using the locale's alternate numeric symbols.
%OM	Specifies the minutes by using the locale's alternate numeric symbols.
%OS	Specifies the seconds by using the locale's alternate numeric symbols.
%OU	Specifies the week number of the year (with Sunday as the first day of the week) by using the locale's alternate numeric symbols.
%Ow	Specifies the weekday as a number in the locale's alternate representation (Sunday = 0).
%OW	Specifies the week number of the year (with Monday as the first day of the week) by using the locale's alternate numeric symbols.
%Oy	Specifies the year (offset from %C) using the locale's alternate numeric symbols.
%p	Represents the a.m. or p.m. string defined by the `am_pm` statement.
%r	Represents the 12-hour clock time with a.m./p.m. notation as defined by the `t_fmt_ampm` statement.
%S	Represents the seconds of the minute as a decimal number (00 to 59).
%t	Specifies a tab character.
%T	Represents 24-hour clock time in the format %H:%M:%S (for example, 16:55:15).
%U	Represents the week of the year as a decimal number (00 to 53). Sunday, or its equivalent as defined by the `day` statement, is considered the first day of the week for calculating the value of this field descriptor.
%w	Represents the day of the week as a decimal number (0 to 6). Sunday, or its equivalent as defined by the `day` statement, is considered to be 0 (zero) for calculating the value of this field descriptor.
%W	Represents the week of the year as a decimal number (00 to 53). Monday, or its equivalent as defined by the `day` statement, is considered the first day of the week for calculating the value of this field descriptor.
%x	Represents the date format defined by the `d_fmt` statement.
%X	Represents the time format defined by the `t_fmt` statement.
%y	Represents the year of the century (00 to 99).
%Y	Represents the year as a decimal number (for example, 1989).
%%	Specifies a % (percent sign) character.

2.7.3 Sample Locale Definition

The following is a sample LC_TIME category specified in a locale definition source file:

LC_TIME # #Abbreviated weekday names (%a) abday "<S><n>";"<M><o><n>";"<T><e>";"<W><e><d>";\ "<T><h>";"<F><r>";"<S><a><t>" #Full weekday names (%A) day "<S><n><d><a><y>";"<M><o><n><d><a><y>";\ "<T><e><s><d><a><y>";"<W><e><d><n><e><s><d><a><y>";\ <T><h><r><s><d><a><y>";"<F><r><d><a><y>";\ <S><a><t><r><d><a><y>" #Abbreviated month names (%b) abmon "<J><a><n>";"<F><e>";"<M><a><r>";"<A><r>";\ "<M><a><y>";"<J><n>";"<J><l>";"<A><g>";\ <S><e>";"<O><c><t>";"<N><o><v>";"<D><e><c>" #Full month names (%B) mon "<J><a><n><a><r><y>";"<F><e><r><a><r><y>";\ "<M><a><r><c><h>";"<A><r><l>";"<M><a><y>";\ <J><n><e>";"<J><l><y>";"<A><g><s><t>";\ "<S><e><t><e><m><e><r>";"<O><c><t><o><e><r>";\ <N><o><v><e><m><e><r>";"<D><e><c><e><m><e><r>" #Date-and-time format (%c) #Note that for improved readability, this section uses actual #characters, rather than symbolic names, and is inconsistent with #the other sections in this example. This is bad form. #In practice, symbolic names should be used. d_t_fmt "%a %b %d %H:%M:%S %Y" # #Date format (%x) d_fmt "%m/%d/%y" # #Time format (%X) t_fmt "%H:%M:%S" # #Equivalent of AM/PM (%p) am_pm "<A><M>";"<M>" # #12-hour time format (%r) #Note that for improved readability, this section uses actual #characters, rather than symbolic names, and is inconsistent with #the other sections in this example. This is bad form. #In practice, symbolic names should be used. t_fmt_ampm "%I:%M:%S %p" # era "+:0:0000/01/01:+*:AD:%Ey %EC";\ "+:1:-0001/12/31:-*:BC:%Ey %EC" era_d_fmt "" alt_digits "<0><t><h>";"<1><s><t>";"<2><n><d>";"<3><r><d>";\ "<4><t><h>";"<5><t><h>";"<6><t><h>";"<7><t><h>";\ "<8><t><h>";"<9><t><h>";"<1><0><t><h>" # END LC_TIME

Contents

Index

privacy and legal statement

6494PRO_003.HTML