Converting Date and Time Strings Into Numeric Representations

Mac OS X header:	CoreServices/CoreServices.h
Mac OS 9 header:	DateTimeUtils.h

Converting Date and Time Strings Into Numeric Representations Functions
InitDateCache	Initializes the date cache structure, which is used to store data for use by the StringToDate and StringToTime functions.
StringToDate	Parses a string for a date and converts the date information into values in a date-time structure.
StringToTime	Parses a string for a time specification and converts the date information into values in a date-time structure.

Initializes the date cache structure, which is used to store data for use by the StringToDate and StringToTime functions.

OSErr InitDateCache (
    DateCachePtr theCache
);

Parameter descriptions

theCache

A pointer to adate cache structure. This parameter can be a local variable, a pointer, or a locked handle.

function result

A result code.

Discussion

You must call InitDateCache to initialize the date cache structure before using either the StringToDate or StringToTime functions. You must pass a pointer to a date cache structure. You have to declare the structure as a variable or allocate it in the heap.

If you are writing an application that allows the use of global variables, you can make your date cache structure a global variable and initialize it once, when you perform other global initialization.

InitDateCache calls the GetResource and LoadResource functions and it can also return the error codes they produce.

Availability

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

Special Considerations

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

Parses a string for a date and converts the date information into values in a date-time structure.

StringToDateStatus StringToDate (
    Ptr textPtr, 
    SInt32 textLen, 
    DateCachePtr theCache, 
    SInt32 *lengthUsed, 
    LongDateRec *dateTime
);

Parameter descriptions

textPtr

A pointer to the text string to be parsed. StringToDate expects a date specification, in a format defined by the current script, at the beginning of the string.

textLen

The number of bytes in the text string.

theCache

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

lengthUsed

On output, contains a pointer to the number of bytes of the string that were parsed for the date. Use this value to compute the starting location of the text that you can pass to StringToTime. Alternatively, you can use them in reverse order.

dateTime

On output, a pointer to the LongDateRec structure, which contains the year, month, day, and day of the week parsed for the date.

function result

A set of bit values that indicate confidence levels, with higher numbers indicating low confidence in how closely the input string matched what the function expected. For example, specifying a date with nonstandard separators may work, but it returns a message indicating that the separator was not standard.

Discussion

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.

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 functions sequentially to fill in all of the values in a LongDateRec structure.

When one of the date components is missing, such as the year, the current date value is used as a default.

Availability

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

Special Considerations

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

Parses a string for a time specification and converts the date information into values in a date-time structure.

StringToDateStatus StringToTime (
    Ptr textPtr, 
    SInt32 textLen, 
    DateCachePtr theCache, 
    SInt32 *lengthUsed, 
    LongDateRec *dateTime
);

Parameter descriptions

textPtr

A pointer to the text string to be parsed. At the beginning of the string, StringToTime expects a time specification in a format defined by the current script.

textLen

The number of bytes in the text string.

theCache

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

lengthUsed

On output, contains a pointer to the length, in bytes, of the string that was parsed for the time.

dateTime

On output, a pointer to the LongDateRec structure, which contains the hour, minute, and second values that were parsed for the time.

function result

StringToTime returns a status value that indicates the confidence level for the success of the conversion. This is the same status value indicator type as does StringToDate: a set of bit values that indicate confidence levels, with higher numbers indicating low confidence in how closely the input string matched what the function expected.

Discussion

StringToTime parses the string until it has finished finding all time information or until it has examined the number of bytes specified by textLen.

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

Availability

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

Special Considerations

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

© 2001 Apple Computer, Inc. (Last Updated July 17, 2001)