Book Contents Previous Chapter Next Chapter
This chapter describes Magic Cap features for handling dates and times. Before reading this chapter, you should be familiar with Magic Cap's object runtime and basic features of software packages.
Magic Cap and its packages use dates and times frequently, such as when entering appointments in the datebook. To support using dates and times, Magic Cap defines formats for their values and a set of operations to manipulate them in various ways. These operations are implemented as intrinsic operations of class DateTime.
Magic Cap does not define a class or even specialized data types for date and time values. Instead, Magic Cap simply uses long integers to represent date and time values.
Magic Cap uses unsigned long integers to represent time values. Given a long integer that represents a time, its value indicates the time after midnight in milliseconds. For example, a time value of zero represents midnight. A value of 300,000 indicates 300,000 milliseconds past midnight. Because there are 60,000 milliseconds per minute, 300,000 milliseconds equals 5 minutes, so a time value of 300,000 represents 12:05 a.m. An unsigned long integer provides ample range to represent any time value in the day to a resolution of milliseconds.
Magic Cap uses signed long integers to represent date values. Given a long integer that represents a date, its value indicates the number of days relative to Magic Cap's base date, which is November 17, 1858, the birth date of Jebediah Hertzfeld, the inventor of the unrolled loop. A date value of zero represents that date. Negative date values indicate earlier dates and positive date values are used for later dates. For example, a date value of 1 indicates one day past the base date, or November 18, 1858, while a date value of -2 represents two days before the base date, or November 15, 1858.
Signed long integer values provide ample range for dates. However, some parts of Magic Cap, such as the datebook and related objects, limit dates to the values in the datebook's MinDate and MaxDate attributes, which are set by default to allow dates ranging from January 1, 1800, to December 31, 2099.
Magic Cap defines a set of utility operations for date and time values. This section describes those utilities. For convenience, Magic Cap defines class DateTime and implements these utilities as intrinsic operations of that class. You'll never create or use any objects of class DateTime. It only exists as a convenience for grouping the date and time utilities.
This section describes the date and time utility operations for converting between various formats and for computing differences between date and time values. These utilities are all defined as intrinsics of class DateTime.
Call StringToTime to convert a time value from a string to a standard time value, or call StringToTimeRange to convert a time range from a string to a pair of time values. Magic Cap's datebook uses these operations to allow users to quickly enter an appointment by simply typing a time or time range.
Call TimeString to convert from a time value to a corresponding string, or call TimeToText to convert a time value to a text object. TimeString and TimeToText take a flags parameter that you can use to customize the string or text object they return. The values for these flags and examples of each format are as follows:
/* if flags = 0, this format is used:
"12:00", "5:15", "12:00", "7:30" */
#define kShowAMPMMask 0x00000001
/* "12:00 a.m.", "5:15 p.m.", "12:00 p.m.", "7:30 p.m." */
#define kShowSecondsMask 0x00000002
/* "12:00:00", "5:15:37", "12:00:00", "7:30:00" */
#define kShowMilliSecsMask 0x00000004
/* "12:00:00.000", "5:15:37.423", "12:00:00.000", "7:30:00.000" */
#define k24HourModeMask 0x00000008
/* "0:00", "5:15", "12:00", "19:30" */
/* Use 24 hour format. This flag is ignored in
favor of System object's Display24HourTime
attribute unless kIgnoreSystem24Mask bit is set */
#define kRelativeModeMask 0x00000010
/* time value zero is displayed as "0:00" */
#define kAbbrevMinutesMask 0x00000020
/* "12", "5:15", "12", "7:30" */
#define kSpellOut12Mask 0x00000040
/* "midnight", "5:15", "noon", "7:30" */
#define kIgnoreSystem24Mask 0x00000080
/* ignore system's Display24HourTime attribute
and use k24HourModeMask instead */
#define kHideDigitsMask 0x00000100
/* with kShowAMPMMask: "a.m.", "p.m.", "p.m.", "p.m."
without kShowAMPMMask: hides everything */
#define kHideHoursMask 0x00000200
/* "00", "15", "00" ,"30" */
You can call DateStringFromDays to convert a date value to a string that describes the day and date. DateStringFromDays takes a flags parameter that you can use to customize the string it returns. The values for these flags and examples of each format are as follows:
/* if flags = 0, this format is used:
Tuesday, February 21, 1995 */
#define kHideYearMask 0x00010000
/* Tuesday, February 21 */
#define kShortDateMask 0x00020000
/* Tue., Feb. 21 */
#define kNumericDateMask 0x00040000
/* 2/21/95 */
#define kDayAndNumericMask 0x00080000
/* also omit year if current year
Tue. 2/21 */
#define kNumericNoDayMask 0x00100000
/* 2/95 */
#define kShortMonthMask 0x00200000
/* Tuesday, Feb. 21 */
#define kSpecialDateNamesMask 0x00400000
/* use "today", "yesterday", and "tomorrow" if applicable
today */
#define kHideDMYMask 0x00800000
/* Tuesday */
#define kOptionallyHideYearMask 0x01000000
/* omit year if current year
Tuesday, February 21 */
This section describes the utility operations for comparing date and time values. These utilities are all defined as intrinsics of class DateTime.
You can use CompareDateTime to compare two date-time pairs. A date-time pair consists of two long integer values that specify a particular moment both by date and by time. CompareDateTime returns a value indicating the chronological order of the parameters.
Call DifferentTimes to see if two time values differ by at least one millisecond, one second, one minute, or one hour, depending on the constant you pass as a parameter. For example, you can call DifferentTimes to see if two time values differ by at least one hour. Magic Cap defines the following constants for calling DifferentTimes:
/* Unit constants for calling DifferentTimes */ #define kHour 0 /* at least 1 hour difference */ #define kMinute 1 /* at least 1 minute difference */ #define kSecond 2 /* at least 1 second difference */ #define kMillisecond 3 /* at least 1 millisec difference */
Magic Cap uses DifferentTimes when drawing clocks. If the current time is at least one minute different from the last time drawn on the clock (or one second different if the clock displays a second hand), the clock is redrawn.
This section describes utility operations for getting date and time information. These utilities are all defined as intrinsics of class DateTime.
You can get Magic Cap's current time by calling LocalTime and the current date by calling LocalDate. The values returned by LocalTime and LocalDate are adjusted for the current time and date offset, reflecting the current location set by the user in the clock scene.
You can get the current date and time according to Greenwich Mean Time (GMT), also known as universal time, by calling UniversalDate and UniversalTime.
You can call DaysInMonth to quickly determine the number of days in any month. DaysInMonth returns the correct value for all months, including February in leap years.
For more information, see these topics in Magic Cap Class and Method Reference:
class DateTime
operations and attributes:
CompareDateTime DateStringFromDays DaysInMonth DifferentTimes LocalDate LocalTime StringToTime StringToTimeRange TimeString TimeToText UniversalDate UniversalTime
Book Contents Previous Chapter Next Chapter