This chapter provides reference material for those APIs used to store and manipulate date and time values. It is organized as follows:
DateTime Structures and Types
DateTime Constants
DateTime Functions and Macros
The header file DateTime.h
declares the API that this chapter describes. For more information on using the DateTime APIs, see Chapter 11, "Time."
DateTime Structures and Types
DateFormatType Typedef
Purpose
Contains a DateFormatTag
value, which specifies a display format for date values.
Declared In
DateTime.h
Prototype
typedef Enum8 DateFormatType
DateTimeType Struct
Purpose
Represents a date and time value.
Declared In
DateTime.h
Prototype
typedef struct { int16_t second; int16_t minute; int16_t hour; int16_t day; int16_t month; int16_t year; int16_t weekDay; } DateTimeType
typedef DateTimeType *DateTimePtr
Fields
-
second
- The number of seconds. This is a value between 0 and 59.
-
minute
- The number of minutes. This is a value between 0 and 59.
-
hour
- The number of hours. This is a value between 0 and 23.
-
day
- The day number. This is a value between 1 and 31.
-
month
- The month number. This is a value between 1 and 12.
-
year
- The year number.
-
weekDay
- The day number. This represents the number of days since Sunday and is thus a value between 0 and 6.
DateType Struct
Purpose
Declared In
DateTime.h
Prototype
typedef struct { uint16_t day :5; uint16_t month :4; uint16_t year :7; } DateType
typedef DateType *DatePtr
Fields
-
day
- The day number. This is a value between 1 and 31.
-
month
- The month number. This is a value between 1 and 12.
-
year
- The number of years since 1904.
DaylightSavingsTypes Typedef
Purpose
Contains one of the forms of daylight savings times defined by the DaylightSavingsTag
enum.
Declared In
DateTime.h
Prototype
typedef Enum8 DaylightSavingsTypes
DayOfMonthType
Purpose
Creates an alias for the DayOfWeekType
typedef.
Declared In
DateTime.h
Prototype
DayOfWeekType Typedef
Purpose
Contains one of the day-of-the-week numeric values returned by the DayOfMonth()
function and enumerated in DayOfWeekTag
.
Declared In
DateTime.h
Prototype
typedef Enum8 DayOfWeekType
TimeFormatType Typedef
Purpose
Contains one of the different display formats for time values enumerated in TimeFormatTag
.
Declared In
DateTime.h
Prototype
typedef Enum8 TimeFormatType
TimeType Struct
Purpose
Declared In
DateTime.h
Prototype
typedef struct { uint16_t hours : 8; uint16_t minutes : 8; } TimeType
typedef TimeType *TimePtr
Fields
-
hours
- The number of hours. This is a value between 0 and 23.
-
minutes
- The number of minutes. This is value between 0 and 59.
DateTime Constants
String Lengths
Purpose
These constants represent the maximum lengths of strings returned by the date and time formatting routines DateToAscii()
, DateToDOWDMFormat()
, and TimeToAscii()
.
Declared In
DateTime.h
Constants
-
#define dateStringLength 15
- Maximum length of the string returned by
DateToAscii()
for short date formats. -
#define dowDateStringLength 31
- Maximum length of the string returned by
DateToDOWDMFormat()
for short date formats. -
#define dowLongDateStrLength 47
- Maximum length of the string returned by
DateToDOWDMFormat()
for both medium and long date formats. -
#define longDateStrLength 31
- Maximum length of the string returned by
DateToAscii()
for medium and long date formats. -
#define timeStringLength 15
- Maximum length of the string returned by
TimeToAscii()
. -
#define timeZoneStringLength 50
- Maximum length of a descriptive string for a time zone as returned by
TimeZoneToAscii()
orTimeZoneToAsciiV50()
.
Months
Purpose
Constants that represent the months of the year.
Declared In
DateTime.h
Constants
-
#define april 4
-
#define august 8
-
#define december 12
-
#define february 2
-
#define january 1
-
#define july 7
-
#define june 6
-
#define march 3
-
#define may 5
-
#define november 11
-
#define october 10
-
#define september 9
Days
Purpose
Constants that represent the days of the week.
Declared In
DateTime.h
Constants
-
#define friday 5
-
#define monday 1
-
#define saturday 6
-
#define sunday 0
-
#define thursday 4
-
#define tuesday 2
-
#define wednesday 3
Conversions
Purpose
Constants that define various intervals in terms of a smaller unit.
Declared In
DateTime.h
Constants
-
#define daysInFourYears (daysInLeapYear + 3 * daysInYear)
- The number of days in four years.
-
#define daysInLeapYear 366
- The number of days in a leap year.
-
#define daysInSeconds (0x15180)
- The number of seconds in a day.
-
#define daysInWeek 7
- The number of days in a week.
-
#define daysInYear 365
- The number of days in a non-leap year.
-
#define hoursInMinutes 60
- The number of minutes in an hour.
-
#define hoursInSeconds (hoursInMinutes * minutesInSeconds)
- The number of seconds in an hour.
-
#define hoursPerDay 24
- The number of hours in a day.
-
#define minutesInSeconds 60
- The number of seconds in a minute.
-
#define monthsInYear 12
- The number of months in a year.
-
#define secondsInSeconds 1
- The number of seconds in a second.
Template Formatting Characters
Purpose
Characters that are used in conjunction with single-digit value types (declared in the Template Value Types enum) to construct formatting substrings for use with DateTemplateToAscii()
. See that function for a complete description of how you specify date formatting in template strings.
Declared In
DateTime.h
Constants
-
#define dateTemplateChar chrCircumflexAccent
- Character that marks the beginning of a formatting substring.
-
#define dateTemplateLeadZeroModifier 'z'
- Modifier that adds a leading zero to the formatted numeric value.
-
#define dateTemplateLongModifier 'l'
- Modifier that formats the value in long form,
-
#define dateTemplateRegularModifier 'r'
- Modifier that formats the value in regular form.
-
#define dateTemplateShortModifier 's'
- Modifier that formats the value in short form.
Miscellaneous DateTime Constants
Purpose
The DateTime.h
file also declares these constants.
Declared In
DateTime.h
Constants
-
#define firstYear 1904
- The year upon which the year values in
DateType
structures are based. -
#define lastYear (firstYear + numberOfYears - 1)
- The greatest year that can be represented by a
DateType
structure. -
#define maxDays ((uint32_t) numberOfYears / 4 * daysInFourYears - 1)
- The number of days in
numberOfYears
. -
#define maxSeconds ((uint32_t) (maxDays + 1) * daysInSeconds - 1)
- The number of seconds in
numberOfYears
. -
#define noTime -1
- A time value that represents "no time." This value is used, for instance, when you create an appointment in the Date Book application and specify "No Time" for the time of the appointment.
-
#define numberOfYears 128
- The
DateType
structure uses 7 bits to represent the year (as an offset fromfirstYear
); this constant is the largest value that can be represented by those 7 bits.
DateFormatTag Enum
Purpose
Specify the different display formats for date values. These values are typically contained within DateFormatType
variables.
Declared In
DateTime.h
Constants
-
dfMDYWithSlashes
- The month, day, and year numbers separated by slashes. For example:
12/31/95
. This is considered a short format. -
dfDMYWithSlashes
- The day, month, and year numbers separated by slashes. For example:
31/12/95
. This is considered a short format. -
dfDMYWithDots
- The day, month, and year numbers separated by dots. For example,
31.12.95
. This is considered a short format. -
dfDMYWithDashes
- The day, month, and year numbers separated by dashes. For example,
31-12-95
. This is considered a short format. -
dfYMDWithSlashes
- The year, month, and day numbers separated by slashes. For example,
95/12/31
. This is considered a short format. -
dfYMDWithDots
- The year, month, and day numbers separated by dots. For example,
95.12.31
. This is considered a short format. -
dfYMDWithDashes
- The year, month, and day numbers separated by dashes. For example,
95-12-31
. This is considered a short format. -
dfMDYLongWithComma
- The month, day, and year in long format, with a comma. For example,
Dec 31, 1995
. This is considered a long format. -
dfDMYLong
- The month, day, and year in long format. For example,
31 Dec 1995
. This is considered a long format. -
dfDMYLongWithDot
- The month, day, and year in long format, with a dot. For example,
31. Dec 1995
. This is considered a long format. -
dfDMYLongNoDay
- The month and year in long format. For example,
Dec 1995
. This is considered a long format. -
dfDMYLongWithComma
- The day, month, and year in long format, with a comma. For example,
31 Dec, 1995
. This is considered a long format. -
dfYMDLongWithDot
- The year, month, and day in long format with dot separators. For example,
1995.12.31
. This is considered a long format. -
dfYMDLongWithSpace
- The year, month, and day in long format with space separators. For example,
1995 Dec 31
. This is considered a long format. -
dfMYMed
- The month in long format with the two-digit year, preceded by an apostrophe. For example,
Dec '95
. This is considered a medium format. -
dfMYMedNoPost
- The month in long format with the two-digit year. For example,
Dec 95
. This is considered a medium format. -
dfMDYWithDashes
- The month, day, and year numbers separated by dashes. For example,
12-31-95
. This is considered a short format.
Compatibility
These values are provided for compatibility purposes only. ARM-native application developers shouldn't specify the format of dates directly (and thus shouldn't use these enum values). Instead, use the preference selected by the user (such as prefDateFormat
; see SystemPreferencesChoice
). If you need to use a format appropriate for a specific locale, ask the Locale Manager for that format. If you need more control than that, format the date youself in such a way as to allow it to be localized.
Template Value Types Enum
Purpose
Values that specify portions of a date, used along with Template Formatting Characters to construct formatting substrings for use with DateTemplateToAscii()
. See that function for a complete description of how you specify date formatting in template strings.
Declared In
DateTime.h
Constants
-
dateTemplateDayNum = '0'
- The day number. For example, "1", "01", "23", or "31".
-
dateTemplateDOWName
- The day name. For example "Tue" or "Tuesday".
-
dateTemplateMonthName
- The month name. For example, "May", "Aug", or "August".
-
dateTemplateMonthNum
- The number of the month. For example, "4", "04", or "11".
-
dateTemplateYearNum
- The year. For example, "97" or "1997".
DaylightSavingsTag Enum
Purpose
The DaylightSavingsTypes
enum specifies the different forms of daylight savings times that you can specify for date and time values. Use DaylightSavingsTypes
variables to contain daylight savings types values.
Declared In
DateTime.h
Constants
-
dsNone
- No DST (daylight savings time)
-
dsUSA
- U.S.A. DST
-
dsAustralia
- Australian DST
-
dsWesternEuropean
- Western European DST
-
dsMiddleEuropean
- Middle European DST
-
dsEasternEuropean
- Eastern European DST
-
dsGreatBritain
- Great Britain and Eire DST
-
dsRumania
- Rumanian DST
-
dsTurkey
- Turkish DST
-
dsAustraliaShifted
- Australian DST, with the 1986 shift
Comments
Palm OS represents daylight savings time as an integer value that gives the number of minutes to add to the current time for daylight savings time.
DayOfWeekTag Enum
Purpose
Specifies the different day-of-the-week numeric values that are returned by the DayOfMonth()
function. These values are used to represent repeating appointments that occur on specific days of the month; for example, the first Friday or the third Tuesday of each month. Variables that contain these values should be declared as DayOfWeekType
.
Declared In
DateTime.h
Constants
-
dom1stSun
- The first Sunday of the month.
-
dom1stMon
- The first Monday of the month.
-
dom1stTue
- The first Tuesday of the month.
-
dom1stWen
- The first Wednesday of the month.
-
dom1stThu
- The first Thursday of the month.
-
dom1stFri
- The first Friday of the month.
-
dom1stSat
- The first Saturday of the month.
-
dom2ndSun
- The second Sunday of the month.
-
dom2ndMon
- The second Monday of the month.
-
dom2ndTue
- The second Tuesday of the month.
-
dom2ndWen
- The second Wednesday of the month.
-
dom2ndThu
- The second Thursday of the month.
-
dom2ndFri
- The second Friday of the month.
-
dom2ndSat
- The second Saturday of the month.
-
dom3rdSun
- The third Sunday of the month.
-
dom3rdMon
- The third Monday of the month.
-
dom3rdTue
- The third Tuesday of the month.
-
dom3rdWen
- The third Wednesday of the month.
-
dom3rdThu
- The third Thursday of the month.
-
dom3rdFri
- The third Friday of the month.
-
dom3rdSat
- The third Saturday of the month.
-
dom4thSun
- The fourth Sunday of the month.
-
dom4thMon
- The fourth Monday of the month.
-
dom4thTue
- The fourth Tuesday of the month.
-
dom4thWen
- The fourth Wednesday of the month.
-
dom4thThu
- The fourth Thursday of the month.
-
dom4thFri
- The fourth Friday of the month.
-
dom4thSat
- The fourth Saturday of the month.
-
domLastSun
- The last Sunday of the month.
-
domLastMon
- The last Monday of the month.
-
domLastTue
- The last Tuesday of the month.
-
domLastWen
- The last Wednesday of the month.
-
domLastThu
- The last Thursday of the month.
-
domLastFri
- The last Friday of the month.
-
domLastSat
- The last Saturday of the month.
TimeFormatTag Enum
Purpose
Specifies the different display formats for time values. Variables that contain these values should be declared as TimeFormatType
.
Declared In
DateTime.h
Constants
-
tfColon
- The hour and minutes separated by a colon character. For example,
1:00
. -
tfColonAMPM
- The hour and minutes separated by a colon and followed by an AM/PM indication. For example,
1:00 pm
. -
tfColon24h
- The 24-hour time with the hour and minutes separated by a colon character. For example,
13:00
. -
tfDot
- The hour and minutes separated by a dot character. For example,
1.00
. -
tfDotAMPM
- The hour and minutes separated by a period and followed by an AM/PM indication. For example,
1.00 pm
. -
tfDot24h
- The 24-hour time with the hour and minutes separated by a dot character. For example,
13.00
. -
tfHoursAMPM
- The hour value followed by an AM/PM indication. For example,
1 pm
. -
tfHours24h
- The 24-hour value. For example,
13
. -
tfComma24h
- The 24-hour time with the hour and minutes separated by a comma character. For example,
13,00
.
Compatibility
These values are provided for compatibility purposes only. ARM-native application developers shouldn't specify the format of times directly (and thus shouldn't use these enum values). Instead, use the preference selected by the user (such as prefTimeFormat
; see SystemPreferencesChoice
). If you need to use a format appropriate for a specific locale, ask the Locale Manager for that format. If you need more control than that, format the time youself in such a way as to allow it to be localized.
DateTime Functions and Macros
DateAdjust Function
Purpose
Add or subtract a specified number of days from a given date.
Declared In
DateTime.h
Prototype
void DateAdjust ( DatePtrdateP
, int32_tadjustment
)
Parameters
-
↔ dateP
- A pointer to a
DateType
structure with the date to be adjusted. -
→ adjustment
- The number of days by which to adjust the date.
Returns
Returns nothing. Upon return, dateP
contains the adjusted date.
Comments
This function adjusts the date by the specified number of days and manages month and year wrapping conditions.
See Also
DateDaysToDate Function
Purpose
Converts a date specified as the number of days since January 1, 1904 to a DateType
structure.
Declared In
DateTime.h
Prototype
void DateDaysToDate ( uint32_tdays
, DatePtrdate
)
Parameters
-
→ days
- The number of days since 1/1/1904.
-
← date
- A pointer to a
DateType
structure that receives the computed date values.
Returns
Returns nothing. Upon return, the date information is returned in the structure referenced by date
.
See Also
DateSecondsToDate()
, DateToDays()
DateSecondsToDate Function
Purpose
Converts a date specified as the number of seconds since January 1, 1904 to a DateType
structure.
Declared In
DateTime.h
Prototype
void DateSecondsToDate ( uint32_tseconds
, DatePtrdate
)
Parameters
-
→ seconds
- The number of seconds since 1/1/1904.
-
← date
- A pointer to a
DateType
structure that receives the computed date values.
Returns
Returns nothing. Upon return, the date information is returned in the structure referenced by date
.
See Also
DateDaysToDate()
, DateToDays()
DateTemplateToAscii Function
Purpose
Convert the specified date values into a string that is formatted according to a formatting template specification.
Declared In
DateTime.h
Prototype
uint16_t DateTemplateToAscii ( const char*templateP
, uint8_tmonths
, uint8_tdays
, uint16_tyears
, char*stringP
, int16_tstringLen
)
Parameters
-
→ templateP
- A pointer to the template string used to format the date. See the Comments section below for details on how to specify date formatting in this template string.
-
→ months
- The month number, which must be a value between
1
and12
. -
→ days
- The day number, which must be a value between
1
and31
. -
→ years
- The four-digit year number. For example,
1995
. -
← stringP
- A pointer to a string that is updated with the result. If
stringP
isNULL
, this function does not write an output string; however, it does return the length required for the output string. IfstringP
is notNULL
, this function writes up tostringLen
bytes intostringP
. -
→ stringLen
- The size of the
stringP
buffer.
Returns
The length of the formatted string (whether or not stringP
is NULL
), up to but not including the null terminator.
Comments
This function is intended as a replacement for the DateToAscii()
and DateToDOWDMFormat()
functions.
This function uses the formatting template referenced by templateP
to create a formatted string from the date values that you pass in.
You specify a series of formatting substrings in templateP
. Each substring has the form:
^<valueType><formatModifier>
Each substring has three components:
- The
^
character begins a substring. - The
<valueType>
component is a single-digit value that specifies the value type. The Template Value Types enum declares constants that represent these values. - The
<formatModifier>
component is a single-letter value that specifies how you want that value formatted. See "Template Formatting Characters" for a set of constants that correspond to these formatting characters.
The following is an example of a template specification with three substrings:
^0z ^2l ^4r Table 20.1 shows the values you can specify for the <valueType
> component. Note that the formatted result depends on the <modifier
> value.
Table 20.1 Template value types for the DateTemplateToAscii function
Table 20.2 shows the values you can specify for the <modifier> component of each template substring.
Table 20.2 Template modifier types for the DateTemplateToAscii function
Finally, Table 20.3 shows examples of each value type formatted with each modifier type.
Table 20.3 Examples of formatted values
Example
Calling DateTemplateToAscii
as follows:
DateTemplateToAscii("^0z ^2l ^4r", 2, 7, 2000, myStr, 20)
Produces the following formatted string:
07 February 2000See Also
DateToAscii()
, DateToDOWDMFormat()
DateToAscii Function
Purpose
Convert the passed date to a string using the format specified by the dateFormat
parameter.
Declared In
DateTime.h
Prototype
void DateToAscii ( uint8_tmonths
, uint8_tdays
, uint16_tyears
, DateFormatTypedateFormat
, char*pString
)
Parameters
-
→ months
- The month number, which must be a value between
1
and12
. -
→ days
- The day number, which must be a value between
1
and31
. -
→ years
- The four-digit year number. For example,
1995
. -
→ dateFormat
- Any
DateFormatType
format. -
→ pString
- A pointer to string that is updated with the result. This string must be of length
dateStringLength
for short formats orlongDateStrLength
for medium or long formats. Note that these lengths include the terminating null byte. For more information about required string lengths, see "DateTime Constants."
Returns
Returns nothing. The string reference by pString
is updated with the formatted string.
Comments
If you are using a debug ROM, the string buffer is filled with either dateStringLength
or longStrLength
debugging bytes, depending on the value of the dateFormat
parameter.
It is important to allocate enough space for your string buffer. Finding buffer overflow errors can be difficult when using a debug ROM. One common situation is when you pass a buffer that is too small from a form, for an element such as a label or title. Then, the buffer overflow can clobber objects that follow the form in memory. When a form element's location information is corrupted, it disappears from the display.
See Also
TimeToAscii()
, DateToDOWDMFormat()
, DateTemplateToAscii()
DateToDays Function
Purpose
Convert the DateType
structure to the number of days elapsed from January 1, 1904.
Declared In
DateTime.h
Prototype
uint32_t DateToDays (
DateType date
)
Parameters
-
→ date
- A
DateType
structure.
Returns
Returns the number of days elapsed from January 1, 1904 to the specified date
.
See Also
DateToDOWDMFormat Function
Purpose
Convert a date to a formatted string using a specified format. The resultant string includes the name of the day of the week.
Declared In
DateTime.h
Prototype
void DateToDOWDMFormat ( uint8_tmonths
, uint8_tdays
, uint16_tyears
, DateFormatTypedateFormat
, char*pString
)
Parameters
-
→ months
- The month number, which must be a value between
1
and12
. -
→ days
- The day number, which must be a value between
1
and31
. -
→ years
- The four-digit year number. For example,
1995
. -
→ dateFormat
- Any
DateFormatType
format. -
← pString
- A pointer to a string that is updated with the result. The string must be of length
dowDateStringLength
for short formats ordowLongDateStrLength
for medium or long date formats.
Returns
Returns nothing. The string referenced by pString
is updated with the formatted string.
Comments
The values of some of the DateTime Constants that specify the required string buffer lengths do change from time to time. You should always use the constants or verify the required lengths by checking the DateTime.h
file.
It is important to allocate enough space for your string buffer. Finding buffer overflow errors can be difficult when using a debug ROM. One common situation is when you pass a buffer that is too small from a form, for an element such as a label or title. Then, the buffer overflow can clobber objects that follow the form in memory. When a form element's location information is corrupted, it disappears from the display.
See Also
DateToAscii()
,
DateTemplateToAscii()
DateToInt Macro
Purpose
Convert a date in a DateType
structure to an unsigned integer.
Declared In
DateTime.h
Prototype
#define DateToInt (
date
)
Parameters
-
→ date
- A
DateType
structure containing the date value to be converted.
Returns
The date as an unsigned 16-bit integer of type uint16_t
.
See Also
DayOfMonth Function
Purpose
Determine the day of a month on which the specified date occurs. The value returned by this function represents a quantity such as "First Monday" or "Third Friday" as is used for repeating appointments in the Datebook.
Declared In
DateTime.h
Prototype
int16_t DayOfMonth ( int16_tmonth
, int16_tday
, int16_tyear
)
Parameters
-
→ month
- The month number, which must be a value between
1
and12
. -
→ day
- The day number, which must be a value between
1
and31
. -
→ year
- The four-digit year number. For example,
1995
.
Returns
Returns one of the DayOfWeekType
values that represents the day of the month.
Comments
The returns value can be used to specify on which day of the month an appointment repeats.
DayOfWeek Function
Purpose
Determine the day of the week value for a specified date.
Declared In
DateTime.h
Prototype
int16_t DayOfWeek ( int16_tmonth
, int16_tday
, int16_tyear
)
Parameters
-
→ month
- The month number, which must be a value between
1
and12
. -
→ day
- The day number, which must be a value between
1
and31
. -
→ year
- The four-digit year number. For example,
1995
.
Returns
Returns one of the values listed under "Days."
DaysInMonth Function
Purpose
Return the number of days in the month.
Declared In
DateTime.h
Prototype
int16_t DaysInMonth ( int16_tmonth
, int16_tyear
)
Parameters
-
→ month
- The month number, which must be a value between
1
and12
. -
→ year
- The four-digit year number. For example,
1995
.
Returns
Returns the number of days in the month for the specified year.
TimAdjust Function
Purpose
Add or subtract a specified number of seconds from a given time and date.
Declared In
DateTime.h
Prototype
void TimAdjust ( DateTimePtrdateTimeP
, int32_tadjustment
)
Parameters
-
↔ dateTimeP
- A pointer to a
DateType
structure containing the time and date to be adjusted. -
→ adjustment
- The number of seconds by which to adjust the time.
Returns
Returns nothing. The structure referenced by dateTimeP
is modified to contain the updated date and time.
Comments
This function advances the time by the specified number of seconds and takes care of any wraparound conditions.
See Also
TimDateTimeToSeconds Function
Purpose
Determine the number of seconds elapsed from 12:00 A.M. on January 1, 1904 to the specified date and time.
Declared In
DateTime.h
Prototype
uint32_t TimDateTimeToSeconds (
DateTimePtr dateTimeP
)
Parameters
-
→ dateTimeP
- A pointer to a
DateTimeType
structure containing a date and time.
Returns
The number of seconds elapsed from 12:00 A.M. on January 1, 1904 to the date referenced by dateTimeP
.
See Also
TimeGetFormatSeparator Function
Purpose
Get the time format separator (such as ':') used by a specified time format.
Declared In
DateTime.h
Prototype
wchar32_t TimeGetFormatSeparator (
TimeFormatType timeFormat
)
Parameters
Returns
Returns the separator character that the specified time format uses.
Comments
If the time format uses a multi-character time separator, this function returns only the first character of the separator.
See Also
TimeGetFormatSuffix()
, TimeIs24HourFormat()
TimeGetFormatSuffix Function
Purpose
Obtain the time format suffix (such as "am" or "pm) that's appropriate given a time format and a time.
Declared In
DateTime.h
Prototype
Boolean TimeGetFormatSuffix ( TimeFormatTypetimeFormat
, uint8_thours
, char*suffixStr
)
Parameters
-
→ timeFormat
- The time format.
-
→ hours
- The time, in hours.
-
← suffixStr
- Pointer to a character buffer into which the time format suffix is written. If the specified time format doesn't have a suffix, a single null-terminator character is written.
Returns
Returns true
if a valid suffix string is returned (that is, one that is not simply a null-terminator). Otherwise, this function returns false
.
See Also
TimeGetFormatSeparator()
, TimeIs24HourFormat()
TimeIs24HourFormat Function
Purpose
Returns whether the specified time format is a 24-hour format, as opposed to a 12-hour, AM/PM format.
Declared In
DateTime.h
Prototype
Boolean TimeIs24HourFormat (
TimeFormatType timeFormat
)
Parameters
Returns
Returns true
if the specified time format is a 24-hour format, false
otherwise.
See Also
TimeToAscii Function
Purpose
Convert the time to a string that is formatted according to the specified time format.
Declared In
DateTime.h
Prototype
void TimeToAscii ( uint8_thours
, uint8_tminutes
, TimeFormatTypetimeFormat
, char*pString
)
Parameters
-
→ hours
- The number of hours. This must be a value between
0
and23
. -
→ minutes
- The number of minutes. This must be a value between
0
and59
. -
→ timeFormat
- The time format for the resultant string. This must be one of the
TimeFormatType
values. -
→ pString
- A pointer to a string that is updated with the resultant string. This string must be of length
timeStringLength
. See "DateTime Constants" for information on string buffer lengths.
Returns
Returns nothing. The string referenced by pString
is updated with the formatted string.
Comments
It is important to allocate enough space for your string buffer. Finding buffer overflow errors can be difficult when using a debug ROM. One common situation is when you pass a buffer that is too small from a form, for an element such as a label or title. Then, the buffer overflow can clobber objects that follow the form in memory. When a form element's location information is corrupted, it disappears from the display.
See Also
TimeToInt Macro
Purpose
Convert a time in a TimeType
structure to a signed integer.
Declared In
DateTime.h
Prototype
#define TimeToInt (
time
)
Parameters
-
→ time
- A
TimeType
structure containing the time value to be converted.
Returns
The time as a signed 16-bit integer of type int16_t
.
See Also
TimeZoneToAscii Function
Purpose
Convert a time zone ID to an ASCII string.
Declared In
DateTime.h
Prototype
void TimeZoneToAscii ( const char*timeZoneID
, char*string
)
Parameters
-
→ timeZoneID
- Time zone ID. This is one of the time zone ID strings found in the UI Library's
TimeZoneSet.xrd
file. For instance, "Asia/Kabul". -
← string
- A pointer to a string in which to return the result. This string must be of length
timeZoneStringLength
.
Returns
Comments
This function returns a descriptive string for the specified time zone. This string identifies the time zone first by its country, such as "USA (Mountain)" or "Canada (Eastern)." If the function cannot find a time zone that matches the specified GMT offset and country, it returns a string containing the time zone as a numeric offset from the GMT (for example, "GMT+9:00").
TimeZoneToAsciiV50 Function
Purpose
Convert a time zone to a string.
Declared In
DateTime.h
Prototype
void TimeZoneToAsciiV50 ( int16_ttimeZone
, const LmLocaleType*localeP
, char*string
)
Parameters
-
→ timeZone
- The time zone, given as minutes east of Greenwich Mean Time (GMT).
-
→ localeP
- A pointer to a locale (see
LmLocaleType
) that identifies the time zone country. You can use the constantlmAnyLanguage
as the value for the language field of the structure pointed to by this parameter. -
← string
- A pointer to a string in which to return the result. This string must be of length
timeZoneStringLength
.
Returns
Comments
This function returns a descriptive string for the specified time zone. This string identifies the time zone first by its country, such as "USA (Mountain)" or "Canada (Eastern)." If the function cannot find a time zone that matches the specified GMT offset and country, it returns a string containing the time zone as a numeric offset from the GMT (for example, "GMT+9:00").
Compatibility
This function is provided for compatibility purposes only; applications should use TimeZoneToAscii()
instead.
TimSecondsToDateTime Function
Purpose
Converts a date specified as the number of seconds since January 1, 1904 to a DateTimeType
structure.
Declared In
DateTime.h
Prototype
void TimSecondsToDateTime ( uint32_tseconds
, DateTimePtrdateTimeP
)
Parameters
-
→ seconds
- A date specified as the number of seconds elapsed from 12:00 A.M. on January 1, 1904 to the date
-
← dateTimeP
- A pointer to a
DateTimeType
structure that is updated with the date and time values.
Returns
Returns nothing. The structure referenced by dateTimeP
is updated with the date and time computed for the number of seconds since 12:00 A.M. on January 1, 1904.
See Also
TimTimeZoneToUTC Function
Purpose
Converts a date and time from a given time zone to Universal Coordinated Time (UTC). UTC is also known as Greenwich Mean Time (GMT).
Declared In
DateTime.h
Prototype
uint32_t TimTimeZoneToUTC ( uint32_tseconds
, int16_ttimeZone
, int16_tdaylightSavingAdjustment
)
Parameters
-
→ seconds
- The number of seconds since 12:00 A.M. on January 1, 1904.
-
→ timeZone
- The time zone, given as the number of minutes east of UTC. For time zones west of UTC but before the international dateline, this is a negative number.
-
→ daylightSavingAdjustment
- The number of minutes to add to the current time for daylight savings time in this time zone.
Returns
Returns the same time as seconds
but in the Universal Coordinated Time. The value is still given as the number of seconds since 12:00 A.M. on January 1, 1904.
Comments
The returned value is not necessarily the time in Greenwich because Greenwich may be observing daylight saving time.
Example
You can use this function to convert the local time to UTC. The time zone and the daylight savings adjustment are system preferences that can be retrieved using PrefGetPreference()
. For example, the following code converts the current local time to UTC:
See Also
TimUTCToTimeZone Function
Purpose
Converts a date and time from Universal Coordinated Time (UTC) to the specified time zone. UTC is also known as Greenwich Mean Time (GMT).
Declared In
DateTime.h
Prototype
uint32_t TimUTCToTimeZone ( uint32_tseconds
, int16_ttimeZone
, int16_tdaylightSavingAdjustment
)
Parameters
-
→ seconds
- The number of seconds since 12:00 A.M. on January 1, 1904 in UTC.
-
→ timeZone
- The time zone, given as the number of minutes east of UTC. For time zones west of UTC before the international dateline, this is a negative number.
-
→ daylightSavingAdjustment
- The number of minutes to add to the current time for daylight savings time in this time zone.
Returns
Returns the same time as seconds
but in the specified time zone. The value is still given as the number of seconds since 12:00 A.M. on January 1, 1904.
Comments
The seconds
value is not necessarily the time in Greenwich because Greenwich may be observing daylight saving time.