Legacy Document

Inside Macintosh: Operating System Utilities /

Chapter 4 - Date, Time, and Measurement Utilities / Date, Time, and Measurement Utilities Reference

Data Structures

The Long Date-Time Record

In addition to the date-time record, system software provides the long date-time record, which extends the date-time record format by adding several more fields. This format lets you use dates and times with a much longer span (30,000 B.C. to 30,000 A.D.). In addition, the long date-time record allows conversions to different calendar systems, such as a lunar calendar.

The LongDateRec data type defines the format of the long date-time record.

TYPE LongDateRec =
RECORD
   CASE Integer OF
   0:
      (era:          Integer;    {era}
       year:         Integer;    {year, from 30,081 B.C. }
                                 { to 29,940 A.D.}
       month:        Integer;    {month}
       day:          Integer;    {day of the month}
       hour:         Integer;    {hour, from 0 to 23}
       minute:       Integer;    {minute, from 0 to 59}
       second:       Integer;    {second, from 0 to 59}
       dayOfWeek:    Integer;    {day of the week}
       dayOfYear:    Integer;    {day of the year}
       weekOfYear:   Integer;    {week of the year}
       pm:           Integer;    {morning/evening}
       res1:         Integer;    {reserved}
       res2:         Integer;    {reserved}
       res3:         Integer);   {reserved}
   1:
                                 {index by LongDateField}
      (list:         ARRAY[0..13] OF Integer);
   2:
      (eraAlt:       Integer;       {era}
      oldDate:       DateTimeRec);  {date-time record}
END;

Field Description

era

The era, where 0 represents A.D., and -1 represents B.C.

year

The year, ranging from 30,081 B.C. to 29,940 A.D. Values outside this range produce unpredictable results in all fields of the record. Note that to indicate the year 1984, this field would store the integer 1984, not just 84. This field accepts input of 0 or negative values, but these values return the positive result of the value plus one for the year. For example, a year value of 0 returns 1, and a year value of -1993 returns 1994. Other fields are unaffected.

month

The month of the year, where 1 represents January, and 12 represents December. When you use the LongSecondsToDate and LongDateToSeconds procedures, month values greater than 12 cause a wraparound to a future year and month. A value of 0 in this field returns the 12th month of the previous year. For example, a month value of 0 and a year value of 1993 return 12 and 1992, respectively. A negative value in this field has the effect of subtracting that number from the first month of the given year. For example, a month value of -2 and a year value of 1993 return 10 and 1992, respectively.

day

The day of the month, ranging from 1 to 31. When using the LongSecondsToDate and LongDateToSeconds procedures, day values greater than the number of days in a given month cause a wraparound to a future month and day. This feature is useful for working with leap years. For example, the 366th day of January in 1992 (1992 was a leap year) evaluates as December 31, 1992, and the 367th day of that year evaluates as January 1, 1993. A value of 0 in this field produces unpredictable results in the month and day fields. A negative value in this field has the effect of subtracting that number from the first day of the given month. For example, a day value of -10 and a month value of 10 return 9 and 20, respectively.

hour

The hour of the day, ranging from 0 to 23, where 0 represents midnight and 23 represents 11:00 P.M. When you use the LongSecondsToDate and LongDateToSeconds procedures, hour values greater than 23 cause a wraparound to a future day and hour. A negative value in this field produces unpredictable results. Note that this field is always maintained in 24-hour time. The pm field, if used, is redundant.

minute

The minute of the hour, ranging from 0 to 59. When you use the LongSecondsToDate and LongDateToSeconds procedures, minute values greater than 59 cause a wraparound to a future hour and minute. A negative value in this field has the effect of subtracting that number from the first minute of the given hour. For example, an hour value of 10 and a minute value of -10 return 9 and 50, respectively. However, if the negative value causes the hour value to become less than 0, for example hour = 0 and minute = -61, unpredictable results occur.

second

The second of the minute, ranging from 0 to 59. When you use the LongSecondsToDate and LongDateToSeconds procedures, second values greater than 59 cause a wraparound to a future minute and second. A negative value in this field has the effect of subtracting that number from the first second of the given minute. For example, an minute value of 10 and a second value of -10 return 9 and 50, respectively. However, if the negative value causes the hour value to become less than 0, for example hour = 0, minute = 0, and second = -61, unpredictable results occur.

dayOfWeek

The day number of the week, where 1 indicates Sunday and 7 indicates Saturday. This field accepts 0, negative values, or values greater than 7. When you use the LongSecondsToDate and LongDateToSeconds procedures, you get correct values because this field is automatically calculated from the values in the year, month, and day fields. For calendars that have more than 7 day names and 12 month names (for example, the Jewish calendar sometimes has 13 months), you use the 'itl1' resource, defined by the Itl1ExtRec data type. To get more information on the format of the 'itl1' resource, see the appendix "International Resources" in Inside Macintosh: Text.

dayOfYear

The day number of the year, ranging from 1 to 366. Values greater than the number of days in a given year cause a wraparound to a future year and day. This feature is useful for working with leap years. For example, in a Gregorian calendar the 366th day of January in 1992 (1992 was a leap year) evaluates as December 31, 1992, and the 367th day of that year evaluates as January 1, 1993.

weekOfYear

The week number of the year, ranging from 1 to 52. Note that out-of-range values (such as 0, negative numbers, or numbers greater than 52) can be set for this field. However, you can use the LongSecondsToDate procedure to convert these out-of-range values to appropriate values.

pm

The morning or evening half of the 24-hour day cycle, where 0 represents the morning (for example, A.M.), and 1 represents the evening (for example, P.M.). Note that out-of-range values can be set for this field. However, you can use the LongSecondsToDate procedure to convert these out-of-range values to appropriate values.

res1

Reserved. Set this field to 0.

res2

Reserved. Set this field to 0.

res3

Reserved. Set this field to 0.

list

An array of LongDateField values. The field parameter of the ToggleDate function uses the enumerated data type LongDateField to indicate the LongDateRec fields that the ValidDate function should check. The following values are available:
TYPE LongDateField =
(eraField, yearField, monthField, dayField,
hourField, minuteField, secondField,
dayOfWeekField, dayOfYearField,
weekOfYearField, pmField, res1Field,
res2Field, res3Field);

eraAlt

The era, where 0 represents A.D., and -1 represents B.C. Use this field and the oldDate field to convert from a date-time record.

oldDate

The date-time record to convert. Use this field and the eraAlt field to convert from a date-time record.