Legacy Document

Inside Macintosh: Text /

Chapter 5 - Text Utilities / Text Utilities Reference

Routines / Converting Date and Time Strings Into Numeric Representations

StringToDate

The StringToDate function parses a string for a date and converts the date information into values in a date-time record. It expects a date specification, in a format defined by the current script, at the beginning of the string. It returns a status value that indicates the confidence level for the success of the conversion.

FUNCTION StringToDate(textPtr: Ptr; textLen: LongInt; 
                  theCache: DateCachePtr; VAR lengthUsed: LongInt;
                  VAR dateTime: LongDateRec): StringToDateStatus;

textPtr

A pointer to the text string to be parsed.

textLen

The number of bytes in the text string.

theCache

A pointer to the date cache record initialized by the InitDateCache function with data that is used during the conversion process.

lengthUsed

On output, contains the number of bytes of the string that were parsed for the date.

dateTime

On output, this LongDateRec record contains the year, month, day, and day of the week parsed for the date.

DESCRIPTION

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. For an overview of how this function operates, see the section "Converting Formatted Date and Time Strings Into Internal Numeric Representations" beginning on page 5-31.

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 (or you can use them in reverse order).

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 described on page 5-32.

StringToDate returns 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. 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 on page 5-33.

SPECIAL CONSIDERATIONS

StringToDate may move memory; your application should not call this function at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the StringToDate function are

Trap macro	Selector
_ScriptUtil	$8214 FFF6