Legacy Document

Inside Macintosh: Text /

Chapter 5 - Text Utilities / Using the Text Utilities

Working With Date and Time Strings

Applications that address international audiences must work with how the numeric-format ('itl0') resource and long-date-format ('itl1') resource handle the differences in date and time formats used in different countries and regions of the world.

The numeric-format resource contains general conventions for formatting numeric strings. It provides several different definitions, including separators for decimals, thousands, and lists; currency information; time values; and short date formats. Some of the variations in date and time formats are shown in Table 5-3.

Table 5-3 Variations in time and short date formats

Morning	Afternoon	Short date	System software
1:02 AM	1:02 PM	2/1/90	United States
1:02	13:02	02/01/90	Canadian French
1:02 AM	1:02 PM	90.01.02	Chinese
1:02	13:02	02-01-1990	Dutch
1:02 Uhr	13:02 Uhr	2.1.1990	German
1:02	13:02	2-01-1990	Italian
01.02	13.02	90-02-01	Swedish

For time and date values, the numeric-format resource includes values that specify this information:

• the order of the month, day, and year values in short date formats
• which separator to use in the short date format (for example, : or / or -)
• the trailing string to display for morning (for example, A.M.)
• the trailing string to display for evening (for example, P.M.)
• up to 4 trailing bytes to display for 24-hour times before noon, and another 4 bytes
  to display for 24-hour times at noon and after. For example, the German string Uhr
  is used for both purposes.
• whether or not to indicate leading zeros in each of the time elements (hours,
  minutes, and seconds)

The long-date-format resource includes conventions for long date formats, abbreviated date formats, and the regional version of the script the resource is associated with. Some of the variations in long and abbreviated date formats are shown in Table 5-4.

Table 5-4 Variations in long and abbreviated date formats (Continued)

Long date	Abbreviated date	System software
Tuesday, January 2, 1990	Tue, Jan 2, 1990	United States
Tuesday, 2 January 1990	Tue, 2 Jan 1990	Australian
Mardi 02 janvier 1990	Mard 02 janv 1990	Canadian French
tirsdag 2. januar 1990	tir 2. jan 1990	Danish
Mardi 2 Janvier 1990	Mar 2 Jan 1990	French

The long-date-format resource includes values that specify this information:

• the names of the days
• the names of the months
• which punctuation to use for abbreviated day names and month names

You can optionally add an extension to a long-date-format resource that adds a number of other specification capabilities, including the following:

• a calendar code for the specification of calendars other than the standard Gregorian calendar, such as the Arabic calendar
• a list of extra day names for calendars with more than seven days
• a list of extra month names for calendars with more than twelve months
• a list of abbreviated day names
• a list of abbreviated month names
• a list of additional date separators

Many of the Apple-supplied long-date-format resources already include such extensions.

The Text Utilities routines that work with dates and times use the information in the long-date-format and numeric-format resources to create different string representations of date and time values. The Macintosh Operating System provides routines that return the current date and time to you in numeric format; you can then use the Text Utilities routines to convert those values into strings that can be presented in different international formats.

The Text Utilities also include routines that can parse date and time strings as entered by users and fill in the fields of a record with the components of the date and time, including the month, day, year, hours, minutes, and seconds.

For more details on the numeric-format ('itl0') and long-date-format ('itl1') resources, see the appendix "International Resources" in this book. For information on obtaining the current date and time values from the Macintosh Operating System, see Inside Macintosh: Operating System Utilities.

Converting Formatted Date and Time Strings
Into Internal Numeric Representations

When your application works with date and time values, it must convert string versions of dates and times into internal numeric representations that it can manipulate. You might, for example, need to convert a date typed by the user into a numeric representation so that you can compute another date some number of days ahead. You can then format the new value for display as a formatted date string.

The Text Utilities contains two routines that you can use to parse formatted date and time values from input strings and create an internal numeric representation of the
date and time. The StringToDate function parses an input string for a date, and
the StringToTime function parses an input string (possibly the same input string) for time information.

Both of these functions pass a date cache record as one of the parameters. A date cache record is a data structure of type DateCacheRec that you must declare in your application. Because you must pass this record as a parameter, you must initialize it by calling the InitDateCache function before calling StringToDate or StringToTime. You need to call InitDateCache only once--typically in your main program initialization code. For more information about the date cache record and the InitDateCache function, see the section "InitDateCache" on page 5-83.

Both the StringToDate and the StringToTime functions fill in fields in a long date-time record, which is defined by a LongDateRec data structure. This data type is described in the book Inside Macintosh: Operating System Utilities.

You usually use StringToDate and StringToTime sequentially to parse the date and time values from an input string and fill in these fields. Listing 5-5 shows how to first call StringToDate to parse the date, then offset the starting address of the string, and finally, call StringToTime to parse the time.

Listing 5-5 Using StringToDate and StringToTime

str := "March 27, 1992 08:14 p.m.";

strPtr := ptr(ord(@str) + 1); {Pointer to 1st char of str}
strLen := length(str);
status := StringToDate(strPtr, strLen, myDateCache,
                                       numBytes, lDateRec);
strPtr := ptr(ord(@str)+numBytes+1);
strLen := strLen - numBytes;
status := StringToTime(strPtr, strLen, myDateCache, 
                                       numBytes, lDateRec);

StringToDate parses the text string until it has finished finding all date information or until it has examined the number of bytes specified by textLen. It returns a status value that indicates the confidence level for the success of the conversion. StringToDate recognizes date strings in many formats, including "September 1, 1987," "1 Sept 1987," "1/9/1987," and "1 1987 sEpT."

Note that StringToDate fills in only the year, month, day, and day of the week; StringToTime fills in the hour, minute, and second. You can use these two routines sequentially to fill in all of the values in a LongDateRec record.

StringToDate assigns to its lengthUsed parameter the number of bytes that it uses to parse the date; use this value to compute the starting location of the text that you can pass to StringToTime.

StringToDate interprets the date and StringToTime interprets the time based on values that are defined in the long-date-format ('itl1') resource. These values, which include the tokens used for separators and the month and day names, are described in the appendix "International Resources" in this book.

StringToDate uses the IntlTokenize function, as described in the chapter "Script Manager" in this book, to separate the components of the strings. It assumes that the names of the months and days, as specified in the international long-date-format resource, are single alphanumeric tokens.

When one of the date components is missing, such as the year, the current date value is used as a default. If the value of the input year is less than 100, StringToDate determines the year as follows.

1. If (current year) MOD 100 is greater than or equal to 90 and the input year is less than or equal to 10, the input year is assumed to be in the next century.
2. If (current year) MOD 100 is less than or equal to 10 and the input year is greater than or equal to 90, the input year is assumed to be in the previous century.
3. Otherwise, the input year is assumed to be in the current century.

If the value of the input year is between 100 and 1000, then 1000 is added to it. Thus the dates 1/9/87, 1/9/987, and 1/9/1987 are equivalent.

Both StringToDate and StringToTime return a value of type StringToDateStatus, which is a set of bit values that indicate confidence levels, with higher numbers indicating low confidence in how closely the input string matched what the routine expected. Each StringToDateStatus value can contain a number of the possible bit values that have been OR'ed together. For example, specifying a date with nonstandard separators may work, but it returns a message indicating that the separator was not standard.

The possible values of this type are described in Table 5-5.

StringToDateStatus values and their meanings (Continued)

StringToDateStatus value	Result of the conversion
fatalDateTime	A fatal error occurred during the parse.
tokenErr	The token processing software could not find a token.
cantReadUtilities	The resources needed to parse the date or time value could not be read.
dateTimeNotFound	A valid date or time value could not be found in the string.
dateTimeInvalid	The start of a valid date or time value was found, but a valid date or time value could not be parsed from the string.
longDateFound	A valid long date was found. This bit is not set when a short date or time was found.
leftOverChars	A valid date or time value was found, and there were characters remaining in the input string.
sepNotIntlSep	A valid date or time value was found; however, one or more of the separator characters in the string was not an expected separator character for the script system in use.
fieldOrderNotIntl	A valid date or time value was found; however, the order of the fields did not match the expected order for the script system in use.
extraneousStrings	A valid date or time value was found; however, one or more unparsable strings was encountered and skipped while parsing the string.
tooManySeps	A valid date or time value was found; however, one or more extra separator characters was encountered and skipped while parsing the string.
sepNotConsistent	A valid date or time value was found; however, the separator characters did not consistently match the expected separators for the script system in use.

For example, if StringToDate and StringToTime successfully parse date and
time values from the input string and more characters remain in the string, then the function result will be the constant leftOverChars. If StringToDate discovers two separators in sequence, the parse will be successful and the return value will be the constant tooManySeps. If StringToDate finds a perfectly valid short date, it
returns the value noErr; if StringToDate finds a perfectly valid long date, it returns the value longDateFound.

Date and Time Value Representations

The Macintosh Operating System provides several different representations of date and time values. One representation is the standard date-time value that is returned by the Macintosh Operating system routine GetDateTime. This is a 32-bit integer that represents the number of seconds between midnight, January 1, 1904 and the current time. Another is the date-time record, which includes integer fields for each date and time component value.

The Macintosh Operating System also provides two data types that allow for longer spans of time than do the standard date-time value and date-time record: the long date-time value and the long-date record. The long date-time value, of data type LongDateTime, is a 64-bit, signed representation of the number of seconds since Jan. 1, 1904, which allows for coverage of a much longer span of time (approximately 30,000 years) than does the standard date-time representation. The long date-time record, of data type LongDateRec, is similar to the date-time record, except that it adds several additional fields, including integer values for the era, the day of the year, and the week of the year.

The Macintosh Operating System provides four routines for converting among the different date and time data types:

• DateToSeconds, which converts a date-time record into a standard date-time value
• SecondsToDate, which converts a standard date-time value into a date-time record
• LongDateToSeconds, which converts a long-date record into a long date-time value
• LongSecondsToDate, which converts a long date-time value into a long-date record

The standard date-time value, the long date-time value, and each of the data structures and routines mentioned in this section are described in the book Inside Macintosh: Operating System Utilities.

Converting Standard Date and Time Values Into Strings

When you want to present a date or time value as a string, you need to convert from one of the numeric date-time representations into a formatted string. The Text Utilities include the DateString and TimeString procedures for converting standard date-time values into formatted strings, and the LongDateString and LongTimeString procedures for converting long date-time values into formatted strings. Each of these routines uses information from a long-date-format or numeric-format resource that you specify as a parameter.

When you use the DateString and LongDateString procedures, you can request an output format for the resulting date string. The output format can be one of the three values of the DateForm enumerated data type:

DateForm = (shortDate,longDate,abbrevDate);

Here are examples of the date strings that these specifications produce.

Value	Date string produced
shortDate	1/31/92
abbrevDate	Fri, Jan 31, 1992
longDate	Friday, January 31, 1992

When you request a long or abbreviated date format, the formatting information in a long-date-format resource is used. For short date formats, the information is found in a numeric-format resource. The DateString and LongDateString procedures use the long-date-format or numeric-format resource that you specify. If you request a long or abbreviated date format, you must include the handle to a long-date-format resource, and if you request a short date format, you must include the handle to a numeric-format resource. If you specify NIL for the value of the resource handle parameter, both routines uses the appropriate resource from the current script.

When you use the TimeString and LongTimeString procedures to produce a formatted time string, you can request an output format for the resulting string. You specify whether or not you want the time string to include the seconds by passing a Boolean parameter to these procedures.

Value	Time string produced
FALSE	03:24 P.M.
TRUE	03:24:17 P.M.

The TimeString and LongTimeString procedures use the time formatting information in the numeric-format resource that you specify. This information defines which separator to use between the elements of the time string, which suffix strings to use, and whether or not to add leading zeros in each of the time elements. If you specify NIL in place of a resource handle, these procedures use the numeric-format resource from the current script.