![[Index]](../../../stock/btn_index.gif){kind=small}
![[Glossary]](../../../stock/btn_glossary.gif){kind=small}
![[Previous]](../../../stock/btn_prev.gif){kind=small}
![[Next]](../../../stock/btn_next.gif){kind=small}
| |
|
| |
Location:
e32std.h
Link against: euser.lib
TTime
Supported from 5.0
Stores and manipulates the date and time. It represents a date and
time as a number of microseconds since midnight, January 1st, 0 AD nominal
Gregorian. BC dates are represented by negative TTime values. A
TTime object may be constructed from a TInt64, a
TDateTime a string literal, or by default, which initialises the
time to an arbitrary value. To access human-readable time information, the
TTime may be converted from a TInt64 into a
TDateTime, which represents the date and time as seven numeric
fields and provides functions to extract these fields. Alternatively, to
display the time as text, the time may be formatted and placed into a
descriptor using a variety of formatting commands and which may or may not
honour the system's locale settings. The conversion between time and text may
be performed the other way around, so that a descriptor can be parsed and
converted into a TTime value.
In addition to setting and getting the date and time and converting
between text and time, TTime provides functions to get intervals
between times and standard comparison and arithmetic operators which enable
time intervals to be added or subtracted to or from the
time.
Defined in TTime:
DateTime(), DayNoInMonth(), DayNoInWeek(), DayNoInYear(), DaysFrom(), DaysInMonth(), FormatL(), HomeTime(), HoursFrom(), Int64(), MicroSecondsFrom(), MinutesFrom(), MonthsFrom(), Parse(), RoundUpToNextMinute(), SecondsFrom(), Set(), TTime(), UniversalTime(), WeekNoInYear(), YearsFrom(), operator!=(), operator+(), operator+=(), operator-(), operator-=(), operator<(), operator<=(), operator=(), operator==(), operator>(), operator>=()
TTime(const TInt64& aTime);
Constructs a TTime object from a 64-bit
microsecond value.
|
TTime(const TDesC& aString);
Constructs a TTime object with a text string. The
string consists of up to three components, any or all of which may be
omitted: —
year, month and day, followed by a colon
hour, minute and second, followed by a dot
microsecond
When all three components are present, the string should take the form:
YYYYMMDD:HHMMSS.MMMMMM
The conversion from text to time is carried out in the same
manner as that used in TTime::Set(). For a more complete
description of how the string may be composed, see the description of
TTime::Set().
Note:
A panic will occur if the string is syntactically
incorrect, for example if neither a colon nor a dot is present, or if any
component of the date or time is assigned an invalid value. For a list of the
range of valid values for date and time components, see
TDateTime::Set().
|
TTime(const TDateTime& aDateTime);
Constructs a TTime object with the seven fields
which comprise a date and time.
|
|
TTime& operator=(const TInt64& aTime);
Assigns a value contained in a 64-bit integer to this
TTime.
|
|
TTime& operator=(const TDateTime& aDateTime);
Assigns a TDateTime object to this
TTime.
|
|
|
TInt Set(const TDesC& aString);
Assigns a date and time contained in a descriptor to this
TTime. The string consists of up to three components, any or all
of which may be omitted: —
year, month and day, followed by a colon
hour, minute and second, followed by a dot
microsecond
When all three components are present, the string should take the form:
YYYYMMDD:HHMMSS.MMMMMM
If omitted, the first component is set to January 1st 0 AD nominal Gregorian. If either the second or third components are omitted, they are set to zero.
Notes:
The month and day values are offset from zero.
The only situations in which either the colon or dot may be omitted are as follows: —
If the microsecond component is omitted, the preceding dot may also be omitted.
The colon can be omitted only if a dot is located at string position zero (indicating that the first two components are missing) or at string position six (indicating that the first component only is missing).
|
|
|
TDateTime DateTime() const;
Converts a TTime object into a
TDateTime object. This conversion should be carried out before the
seven fields which comprise a date and time can be
accessed.
|
|
TTimeIntervalMicroSeconds MicroSecondsFrom(TTime aTime) const;
Calculates the number of microseconds difference between a
TTime object and this TTime.
|
|
TInt SecondsFrom(TTime aTime,TTimeIntervalSeconds& aInterval) const;
Calculates the number of seconds difference between a
TTime object and this TTime. The difference may be
positive or negative.
|
|
TInt MinutesFrom(TTime aTime,TTimeIntervalMinutes& aInterval) const;
Calculates the number of minutes difference between a
TTime object and this TTime. The difference may be
positive or negative.
|
|
TInt HoursFrom(TTime aTime,TTimeIntervalHours& aInterval) const;
Calculates the number of hours difference between a
TTime object and this TTime. The difference may be
positive or negative.
|
|
TTimeIntervalDays DaysFrom(TTime aTime) const;
Calculates the number of days difference between a
TTime object and this TTime. The difference may be
positive or negative.
|
|
TTimeIntervalMonths MonthsFrom(TTime aTime) const;
Calculates the number of months between a TTime
and this TTime. The result may be positive or negative.
Notes:
The interval in months between two TTimes is
calculated by incrementing it by one each time the same day number and time in
the previous or following month has been reached. Exceptions to this rule occur
when this TTime is on the last day of the month. In this case, the
following rules apply: —
When comparing this TTime with a later
time,
if the following month is shorter, one month is deemed to separate the times when the same time on the last day of the following month is reached. In this case, the two day numbers are not the same.
When comparing this TTime with an earlier
time,
if the previous month is shorter, one month is deemed to separate the times when the last microsecond of the previous month is reached (23:59:59.999999 on the last day of the month).
if the previous month is longer, one month is deemed to separate the times when the same time on the last day of previous month is reached. In this case, the two day numbers are not the same.
|
|
TTimeIntervalYears YearsFrom(TTime aTime) const;
Calculates the number of years between a TTime and
this TTime. The result may be positive or negative.
Notes:
The interval in years between two TTimes is
calculated by incrementing it by one each time the same day number and time in
the previous or following year has been reached. The exception to this rule
occurs when this TTime is the last day in February in a leap year.
In this case, one year is deemed to have passed when the same time of day on
the last day in the preceding or following February has been reached.
|
|
|
TInt WeekNoInYear() const;
TInt WeekNoInYear(TTime aStartDate) const;
TInt WeekNoInYear(TFirstWeekRule aRule) const;
TInt WeekNoInYear(TTime aStartDate,TFirstWeekRule aRule) const;
Finds the number of the current week in the year. Variants are provided which allow the user to specify the date which is to be considered as the start of the year and to determine the rule governing which week is the first week in the year.
|
|
TInt DayNoInYear() const;
TInt DayNoInYear(TTime aStartDate) const;
Gets the day number in the year. A variant exists allowing the user to set the date which is to be considered as the start of the year. If no start date is specified, the default is January 1st.
|
|
TInt DayNoInMonth() const;
Gets the day number in the month.
|
TDay DayNoInWeek() const;
Gets the day number within the current week, from zero to six,
honouring the setting specified in TLocale::SetStartOfWeek(). By
default the first day in the week is Monday.
|
TInt DaysInMonth() const;
Gets the number of days in the current month.
|
|
void FormatL(TDes& aDes,const TDesC& aFormat) const;
Puts this TTime into a descriptor and formats it
according to the format string specified in the second argument. Many of the
formatting commands use the system's locale settings for the date and time, for
instance the characters used to separate components of the date and time and
the ordering of day, month and year. The list of formatting commands below is
divided into two sections, the first of which lists the commands which operate
without reference to the locale's date and time settings (see class
TLocale) and the second table lists the commands which do use
these settings.
The following formatting commands do not honour the locale-specific system settings:
%% : Include a single '%'
character in the string
%* : Abbreviate following item (the following
item should not be preceded by a '%' character).
%C : Interpret the argument as the six digit
microsecond component of the time. In its abbreviated form,
('%*C') this should be followed by an integer between zero and
six — the integer indicates the number of digits to
display.
%D : Interpret the argument as the two digit
day number in the month. Abbreviation suppresses leading zero.
%E : Interpret the argument as the day name.
Abbreviation is language-specific (e.g. English uses the first three
letters).
%F : Use this command for locale-independent
ordering of date components. This orders the following day/month/year
component(s) (%D, %M, %Y for example)
according to the order in which they are specified in the string. This removes
the need to use %1 to %5 (described below).
%H : Interpret the argument as the one or two
digit hour component of the time in 24 hour time format. Abbreviation
suppresses leading zero. For locale-dependent hour formatting, use
%J.
%I : Interpret the argument as the one or two
digit hour component of the time in 12 hour time format. The leading zero is
automatically suppressed so that abbreviation has no effect. For
locale-dependent hour formatting, use %J.
%M : Interpret the argument as the one or two
digit month number. Abbreviation suppresses leading zero.
%N : Interpret the argument as the month name.
Abbreviation is language specific, e.g. English uses the first three
letters only. When using locale-dependent formatting, (that is, %F
has not previously been specified), specifying %N causes any
subsequent occurrence of a month specifier in the string to insert the month as
text rather than in numeric form. When using locale-independent formatting,
specifying %N causes the month to be inserted as text at that
position, but any subsequent occurrence of %M will cause the month
to be inserted in numeric form.
%S : Interpret the argument as the one or two
digit seconds component of the time. Abbreviation suppresses leading
zero.
%T : Interpret the argument as the one or two
digit minutes component of the time. Abbreviation suppresses leading
zero.
%W : Interpret the argument as the one or two
digit week number in year. Abbreviation suppresses leading zero.
%X : Interpret the argument as the date
suffix. Cannot be abbreviated. When using locale-dependent formatting (that is,
%F has not previously been specified), %X causes all
further occurrences of the day number to be displayed with the date suffix.
When using locale-independent formatting, a date suffix will be inserted only
after the occurrence of the day number which %X follows in the
format string. Any further occurrence of %D without a following
%X will insert the day number without a suffix.
%Y : Interpret the argument as the four digit
year number. Abbreviation suppresses the first two digits.
%Z : Interpret the argument as the one, two or
three digit day number in the year. Abbreviation suppresses leading
zeros.
The following formatting commands do honour the locale-specific system settings:
%. : Interpret the argument as the decimal
separator character (as set by TLocale::SetDecimalSeparator()).
The decimal separator is used to separate seconds and microseconds, if
present.
%: : Interpret the argument as one of the four
time separator characters (as set by TLocale::SetTimeSeparator()).
Must be followed by an integer between zero and three inclusive to indicate
which time separator character is being referred to.
%/ : Interpret the argument as one of the four
date separator characters (as set by TLocale::SetDateSeparator()).
Must be followed by an integer between zero and three inclusive to indicate
which date separator character is being referred to.
%1 : Interpret the argument as the first
component of a three component date (i.e. day, month or year) where the order
has been set by TLocale::SetDateFormat(). When the date format is
EDateEuropean, this is the day, when EDateAmerican,
the month, and when EDateJapanese, the year. For more information
on this and the following four formatting commands, see the Notes section
immediately below.
%2 : Interpret the argument as the second
component of a three component date where the order has been set by
TLocale::SetDateFormat(). When the date format is
EDateEuropean, this is the month, when EDateAmerican,
the day and when EDateJapanese, the month.
%3 : Interpret the argument as the third
component of a three component date where the order has been set by
TLocale::SetDateFormat(). When the date format is
EDateEuropean, or EDateAmerican this is the year and
when EDateJapanese, the day.
%4 : Interpret the argument as the first
component of a two component date (day and month) where the order has been set
by TLocale::SetDateFormat(). When the date format is
EDateEuropean this is the day, and when EDateAmerican
or EDateJapanese, the month.
%5 : Interpret the argument as the second
component of a two component date (day and month) where the order has been set
by TLocale::SetDateFormat(). When the date format is
EDateEuropean this is the month, and when
EDateAmerican or EDateJapanese, the day.
%A : Interpret the argument as "am" or "pm"
text according to the current language and time of day. Unlike the
%B formatting command (described below), %A
disregards the locale's 12 or 24 hour clock setting, so that when used without
an inserted + or – sign, am/pm text will always
be displayed. Whether a space is inserted between the am/pm text and the time
depends on the locale-specific settings. However, if abbreviated
(%*A), no space is inserted, regardless of the locale's settings.
The am/pm text appears before or after the time, according to the position of
the %A, regardless of the locale-specific settings. For example,
the following ordering of formatting commands causes am/pm text to be printed
after the time: %H
%T
%S
%A. Optionally, a minus or plus sign may be inserted between the
"%" and the "A". This operates as
follows: —
%-A causes am/pm text to be inserted into the
descriptor only if the am/pm symbol position has been set in the locale to
ELocaleBefore. Cannot be abbreviated using asterisk.
%+A causes am/pm text to be inserted into the
descriptor only if the am/pm symbol position has been set in the locale to
ELocaleAfter. Cannot be abbreviated using asterisk. For example,
the following formatting commands will cause am/pm text to be displayed after
the time if the am/pm position has been set in the locale to
ELocaleAfter or before the time if ELocaleBefore:
%–A
%H
%T
%S
%+A.
%B Interpret the argument as am or pm text
according to the current language and time of day. Unlike the %A
command, when using %B, am/pm text is displayed only if the clock
setting in the locale is 12-hour. Whether a space is inserted between the am/pm
text and the time depends on the locale-specific settings. However, if
abbreviated (%*B), no space is inserted, regardless of the
locale's settings. The am/pm text appears before or after the time, according
to the location of the "%B", regardless of the locale-specific
settings. For example, the following formatting commands cause am/pm text to be
printed after the time: %H
%T
%S
%B. Optionally, a minus or plus sign may be inserted between the
"%" and the "B". This operates as
follows: —
%-B causes am/pm text to be inserted into the
descriptor only if using a 12 hour clock and the am/pm symbol position has been
set in the locale to ELocaleBefore. Cannot be abbreviated using
asterisk.
%+B causes am/pm text to be inserted into the
descriptor only if using a 12 hour clock and the am/pm symbol position has been
set in the locale to ELocaleAfter. Cannot be abbreviated using
asterisk. For example, the following formatting commands cause am/pm text to be
printed after the time if the am/pm position has been set in the locale to
ELocaleAfter or before the time if ELocaleBefore:
%–B
%H
%T
%S
%+B.
%J Interpret the argument as the hour
component of the time in either 12 or 24 hour clock format depending on the
locale's clock format setting. When the clock format has been set to 12 hour,
leading zeros are automatically suppressed so that abbreviation has no effect.
Abbreviation suppresses leading zero only when using a 24 hour clock.
Notes:
The %1, %2, %3,
%4 and %5 formatting commands are used in conjunction
with %D, %M and %Y to format the date
locale-dependently. When formatting the date locale-dependently, the order of
the day, month and year components within the string is determined by the order
of the %1 to %5 formatting commands, not that of
%D, %M, %Y.
When formatting the date locale-independently (that is,
%F has been specified in the format string), the %1
to %5 formatting commands are not required, and should be omitted.
In this case, the order of the date components is determined by the order of
the %D, %M, %Y format commands within
aFormat.
Up to four date separators and up to four time separators can be used to separate the components of a date or time. When formatting a numerical date consisting of the day, month and year or a time containing hours, minutes and seconds, all four separators should always be specified in the format command string. Usually, the leading and trailing separators should not be displayed. In this case, the first and fourth separators should still be specified, but should be represented by a null character.
The date format follows the pattern: —
DateSeparator[0] DateComponent1 DateSeparator[1] DateComponent2 DateSeparator[2] DateComponent3 DateSeparator[3]
where the ordering of date components is determined by the locale's date format setting.
The time format follows the pattern: —
TimeSeparator[0] Hours TimeSeparator[1] Minutes TimeSeparator[2] Seconds TimeSeparator[3]
If the time includes a microseconds component, the third separator should occur after the microseconds, and the seconds and microseconds should be separated by the decimal separator. When formatting a two component time, the following rules apply:
if the time consists of hours and minutes, the third time delimiter should be omitted
if the time consists of minutes and seconds, the second time delimiter should be omitted
A set of examples demonstrating how to format the date locale-dependently and independently, is given in the “Using” document for this class.
|
|
|
void RoundUpToNextMinute();
Rounds this TTime up to the next minute. Both the
seconds and microseconds components are set to zero.
|
TInt Parse(const TDesC& aDes,TInt aCenturyOffset=0);
Parses a descriptor containing either or both a date and time,
setting this TTime to the value of the parsed descriptor.
The descriptor may contain the date only, the time only, the date followed by the time, or the time followed by the date. When both the date and time are specified in the descriptor, they should be separated using one or more space characters.
Leading zeros and spaces preceding any time or date components are discarded.
Dates may be specified either with all three components (day, month and year), or with just two components; for example month and day. The date suffix ("st" "nd" "rd" or "th") may not be included in the descriptor.
The date and its components may take different forms: —
The month may be represented by text or by numbers.
European (DD/MM/YYYY), American (MM/DD/YYYY) and Japanese (YYYY/MM/DD) date formats are supported. An exception to this ordering of date components occurs when European or American formatting is used and the month is represented by text. In this case, the month may be positioned in either the first or second field. When using Japanese date format, the month, whether text or numbers, must always be the second field.
The year may be two or four digits. When the year is a two
digit number, (e.g. 97 rather than 1997), to resolve any confusion as to which
century the year falls in, the second argument determines the century. For
example, if the current year is 1997, a value for aCenturyOffset
of 20 means that any two digit year will resolve to a year in the range 1920 to
2019. In this case, two digit years between 00 and 19 inclusive refer to the
years between 2000 and 2019 and two digit years between 20 and 99 inclusive
refer to the years between 1920 and 1999. By default, two digit years are in
the current century (aCenturyOffset = 0).
Any of the following characters may be used as the date
separator: /(slash) – (dash)
, (comma), spaces, or either of the date separator characters
specified in TLocale::SetDateSeparator() (at index 1 or 2). Other
characters are illegal.
If a colon or a dot has been specified in TLocale
as the date separator character, neither may be used as date separators in this
function.
If specified, the time must include the hour, but both minutes and seconds, or seconds alone may be omitted.
The time and its components may take different forms: —
An am/pm time suffix may be appended to the time. If 24 hour clock format is in use, this text will be ignored.
The am/pm suffix may be abbreviated to "a" or "p".
Any of the following characters may be used as the time
separator: :(colon) .(dot) or either of the
time separator characters specified in TLocale::SetDateSeparator()
(at index 1 or 2). Other characters are illegal.
When a character can be interpreted as either a date or time separator character, this function will interpret it as a date separator.
Look out for cases in which wrongly interpreting the contents
of a descriptor, based on the interpretation of separator characters, causes an
error. For example, trying to interpret the following descriptor
_L("5.6.1996") as a time is invalid and will return an error of
–2 because 1,996 seconds is out of range.
Notes:
The entire content of the descriptor must be valid and syntactically correct, or an error will be returned and the parse will fail. So, excepting whitespace, which is discarded, any trailing characters within the descriptor which do not form part of the date or time are illegal.
If no time is specified in the descriptor, the hours,
minutes and seconds of this TTime are all set to zero,
corresponding to midnight at the start of the day specified in the date. If no
date is specified, each of this TTime's date components are set to
zero.
|
|
|
TTime operator+(TTimeIntervalYears aYear) const;
TTime operator+(TTimeIntervalMonths aMonth) const;
TTime operator+(TTimeIntervalDays aDay) const;
TTime operator+(TTimeIntervalHours aHour) const;
TTime operator+(TTimeIntervalMinutes aMinute) const;
TTime operator+(TTimeIntervalSeconds aSecond) const;
TTime operator+(TTimeIntervalMicroSeconds aMicroSecond) const;
TTime operator+(TTimeIntervalMicroSeconds32 aMicroSecond) const;
Adds a time interval in any time units to a TTime,
returning the result as a TTime.
Notes:
When adding one month to the last day in the month, if the following month is shorter, the result is the last day in the following month. For example, when adding one month to 31st August, the result is the 30th September.
In a leap year, when adding one year to the 29th February, the result is 28th February in the following year.
All the above arguments except
TTimeIntervalMicroSeconds are stored as a 32 bit signed integer.
The maximum value which they can represent is 2147483647. An attempt to add
more than this amount will produce incorrect results.
|
TTime& operator+=(TTimeIntervalYears aYear);
TTime& operator+=(TTimeIntervalMonths aMonth);
TTime& operator+=(TTimeIntervalDays aDay);
TTime& operator+=(TTimeIntervalHours aHour);
TTime& operator+=(TTimeIntervalMinutes aMinute);
TTime& operator+=(TTimeIntervalSeconds aSecond);
TTime& operator+=(TTimeIntervalMicroSeconds aMicroSecond);
TTime& operator+=(TTimeIntervalMicroSeconds32 aMicroSecond);
Adds an interval of time in any time units to a
TTime, assigning the result to the
TTime.
|
TTime operator-(TTimeIntervalYears aYear) const;
TTime operator-(TTimeIntervalMonths aMonth) const;
TTime operator-(TTimeIntervalDays aDay) const;
TTime operator-(TTimeIntervalHours aHour) const;
TTime operator-(TTimeIntervalMinutes aMinute) const;
TTime operator-(TTimeIntervalSeconds aSecond) const;
TTime operator-(TTimeIntervalMicroSeconds aMicroSecond) const;
TTime operator-(TTimeIntervalMicroSeconds32 aMicroSecond) const;
Subtracts an interval of time in any units from a
TTime, returning the result as a TTime.
Notes:
All the above arguments except
TTimeIntervalMicroSeconds are stored as a 32 bit signed integer.
The maximum value which they can represent is 2147483647. An attempt to
subtract more than this amount will produce incorrect results.
When subtracting one month from the last day in the month, if the preceding month is shorter, the result is the last day in the preceding month. For example, when subtracting 1 month from 31st October, the result will be the 30th September.
In a leap year, when subtracting one year from the 29th February, the result is 28th February in the preceding year.
|
TTime& operator-=(TTimeIntervalYears aYear);
TTime& operator-=(TTimeIntervalMonths aMonth);
TTime& operator-=(TTimeIntervalDays aDay);
TTime& operator-=(TTimeIntervalHours aHour);
TTime& operator-=(TTimeIntervalMinutes aMinute);
TTime& operator-=(TTimeIntervalSeconds aSecond);
TTime& operator-=(TTimeIntervalMicroSeconds aMicroSecond);
TTime& operator-=(TTimeIntervalMicroSeconds32 aMicroSecond);
Subtracts an interval of time in any units from a
TTime, assigning the result to the
TTime.
|
|
TBool operator==(TTime aTime) const;
Tests whether two date/times are equal.
|
|
TBool operator!=(TTime aTime) const;
Tests whether two date/times are not equal.
|
|
TBool operator>=(TTime aTime) const;
Tests whether a date/time is after or is the same as another.
|
|
TBool operator<=(TTime aTime) const;
Tests whether a date/time precedes or is the same as another.
|
|
TBool operator>(TTime aTime) const;
Tests whether a date/time is after another.
|
|
TBool operator<(TTime aTime) const;
Tests whether a date/time precedes another.
|
|
|
const TInt64& Int64() const;
Gets the 64 bit integer representation of a
TTime.
|
Copyright ©2002 Symbian Ltd. 6.1-00174 |
|
![[Top]](../../../stock/arrow_up_2.gif){kind=icon}
![[Top]](../../../stock/arrow_up.gif){kind=icon}