Explains how to use various functions related to Time.
This function is used to assign a date and
time string contained in a descriptor to this TTime. The
code below gives examples of invalid input strings, causing an error to be
returned. When there is an error, the date/time remains unchanged. Note that
when specifying the month and day in the input string, both values start at
zero, so that 19940102 indicates 3rd February 1994.
_LIT(KDateCorrect1,"19940102:");
TBuf <24> theDate=KDateCorrect1; // theDate = 3rd February 1994 00:00:00 am
TInt err=time.Set(theDate); // No error
_LIT(KDateCorrect2,"19940102:.000001");
theDate=KDateCorrect2; // theDate = 3rd February 1994 00:00:00.000001
err=time.Set(theDate); // No error
_LIT(KDateWrongColonPos,"1994012:100000.000001");
theDate=KDateWrongColonPos;
err=time.Set(theDate); // KErrGeneral error - time is unchanged
// Error — colon in wrong position (position 7). If present, must
// be either at position zero or position eight
_LIT(KDateWrongDotPos,"19940102.000001");
theDate=KDateWrongDotPos;
err=time.Set(theDate); // KErrGeneral error - time is unchanged
// Error — dot in wrong position. If no colon present, dot must be
// at position zero (indicating that both YYYYMMDD and HHMMSS
// omitted), or position six (indicating that YYYYMMDD omitted)
_LIT(KDateNoDotOrColon,"19940102");
theDate=KDateNoDotOrColon;
err=time.Set(theDate); // Error — either or both dot and colon must be present This function is used to calculate the number of months between two date/times. The result may be positive or negative. A positive value means that this time is later than the time contained in the argument and a negative value means that this time is earlier than the time in the argument.
The following code shows how intervals are
calculated between dates in months which have different numbers of days. This TTime (time)
is initialized to 10:00:00 AM on the 31st October. The code demonstrates that
counting forwards, one month elapses when the same time on the 30th November
is reached. When counting backwards, one month elapses when the last microsecond
in the previous month (30/09/1997 23:59:59:999999) is reached.
_LIT(KMiddleDateTime,"19970930:100000.000000");
TTime time(KMiddleDateTime);
// time=31/10/1997 10:00:00:000000
_LIT(KEarlierDateTime,"19970829:235959.999999");
TTime earlierTime(KEarlierDateTime);
// earlierTime=30/09/1997 23:59:59:999999
_LIT(KLaterDateTime,"19971029:100000.000000");
TTime laterTime(KLaterDateTime);
// laterTime=30/11/1997 10:00:00:000000
TTimeIntervalMonths result=time.MonthsFrom(earlierTime);
// result == +1
result=time.MonthsFrom(laterTime); // result == -1
TTimeIntervalMicroSeconds interval(1);
earlierTime+=interval; // earlierTime=01/10/1997 00:00:00:000000
laterTime-=interval; // laterTime=30/11/1997 09:59:59:999999
result=time.MonthsFrom(earlierTime); // result == zero
result=time.MonthsFrom(laterTime); // result == zero This function is used to calculate
the number of years between two date/times. The result may be positive or
negative. In the following piece of code, this TTime (leapYear)
is set to the 29th February 1996. It demonstrates that from 10:00:00 29th
February 1996 to 10:00:00 28th February 1997 is an interval of one year.
TTimeIntervalYears result; TDateTime dateTime(1996,EFebruary,28,10,00,00,000000); TTime leapYear(dateTime); // leapYear==29/02/1996 10:00:00:000000 TTime nextYear(dateTime); TTimeIntervalYears intervalInYears(1); nextYear+=intervalInYears; // nextYear==28/02/1997 10:00:00:000000 result=leapYear.YearsFrom(nextYear); // as expected, result==–1
These functions are used to find the number of the current week in the year. Variants are provided to allow the user to specify the date which is to be considered as the start of the year and to set the rule governing which week is the first week in the year.
Assuming
that the first day in the week is Monday, the first day in the year is January
1st and the current date is Monday 6th January 1997 and time is
an instance of TTime:
time.WeekNoInYear()==2 because
Monday 6th is the first day in week 2.
time.WeekNoInYear(EFirstFullWeek)==1 because
Monday 6th is the first day in the first week entirely in 1997.
time.WeekNoInYear(EFirstWeek)==2 because
the first week in the year was the week containing the 1st January (Wednesday
1st to Sunday 5th).
time.WeekNoInYear(EFirstFourDayWeek)==2 because
the first four days of the year, representing the first week in the year,
were Wednesday 1st to Saturday 4th.
The examples below demonstrate how to format a descriptor which holds a date/time string, locale-dependently and independently.
The following code fragment is locale-dependent. It
assumes the current date and time (TTime time)
is 2nd January 1997 23:59:59.999999, and uses the system default date and
time settings for a UK locale, including the default date and time separators,
a 12 hour clock, trailing am/pm text and assumes a point for the decimal separator;
TBuf<30> dateString; _LIT(KDateString1,"%E%D%X%N%Y %1 %2 %3"); time.FormatL(dateString,KDateString1); // dateString contains "Thursday 02nd January 1997" - no abbreviation _LIT(KDateString2,"%*E%*D%X%*N%*Y %1 %2 '%3"); time.FormatL(dateString,KDateString2); // dateString contains "Thu 2nd Jan '97" - everything abbreviated _LIT(KDateString3,"%D%M%Y%/0%1%/1%2%/2%3%/3"); time.FormatL(dateString,KDateString3); // dateString contains "02/01/1997" - no abbreviation; first and third // date separators are both '\0' _LIT(KDateString4,"%-B%:0%J%:1%T%:2%S%.%*C4%:3%+B"); time.FormatL(dateString,KDateString4); // dateString contains "11:59:59.9999 pm" - first and third time // separators are both '\0'; locale dependent decimal separator // separates seconds and microseconds _LIT(KDateString5,"%-B%:0%J%:1%T%:2%S%:3%+B"); time.FormatL(dateString,KDateString5); // dateString contains "11:59:59 pm - as above, but no microseconds
The following code demonstrates formatting two component dates and times.
_LIT(KDateString6,"%-B%:0%J%:1%T%:3%+B"); time.FormatL(dateString,KDateString6); // dateString contains "11:59 pm" - Two component time (hour:minute). // Third time delimiter omitted as it separates minutes and seconds _LIT(KDateString7,"%M%Y%/0%4%/1%5%/3"); time.FormatL(dateString,KDateString7); // dateString contains "02/01" - Two component date (day/month). // Third date delimiter omitted
The following code demonstrates
that the ordering of the %D %M %Y is
irrelevant when using locale-dependent formatting. The ordering of the date
components is determined by the order of the %1, %2,
and %3 formatting commands.
_LIT(KDateString8,"%M%Y%D%/0%1%/1%2%/2%3%/3");
time.FormatL(dateString,KDateString8);
// dateString contains 02/01/1997
_LIT(KDateString9,"%Y%D%M%/0%1%/1%2%/2%3%/3");
time.FormatL(dateString,KDateString9);
// dateString contains 02/01/1997
_LIT(KDateString10,"%D%M%Y%/0%3%/1%1%/2%2%/3");
time.FormatL(dateString,KDateString10);
// dateString contains 1997/02/01 However, when using locale-independent
formatting, the %1, %2 and %3 are
not required. The ordering of the date components is determined by the ordering
of the %D, %M and %Y.
_LIT(KDateString11,"%F%/0%M%/1%Y%/2%D%/3"); time.FormatL(dateString,KDateString11); // dateString contains 01/1997/02
This function is used to parse a descriptor
containing either or both a date and time, setting this TTime to
the value of the parsed descriptor.
The following example code demonstrates
setting the time alone. The following four calls to TTime::Parse() give
the same result; 23:34.56. Because no date is specified, the date is set to
January 1st year zero, and all return a value of EParseTimePresent.
Different time separators may be used in the same string
TTime time; _LIT(KTimeString1,"23:34.56"); TInt returnvalue=time.Parse(KTimeString1); // 11 pm _LIT(KTimeString2,"0023:0034.056"); returnvalue=time.Parse(KTimeString2); // Leading zeros ignored _LIT(KTimeString3,"23:34.56am"); returnvalue=time.Parse(KTimeString3); // "am" ignored _LIT(KTimeString4,"11:34.56p"); returnvalue=time.Parse(KTimeString4); // 11 pm
The following example code demonstrates setting the date alone.
Because no time is specified, the time is set to midnight (00:00:00), and
all except the final call return a value of EParseDatePresent.
Different date separators may be used in the same string, and the month may
be specified as text or numbers.
_LIT(KDateString1, "5-6-1996"); // 5 June 1996
returnvalue=time.Parse(KDateString1); // 5 June 1996
_LIT(KDateString2,"5 jun, 00");
returnvalue=time.Parse(KDateString2,00); // 5 June 2000
_LIT(KDateString3, "5/june/00");
returnvalue=time.Parse(KDateString3,00); // 5 June 2000
_LIT(KDateString4, "june 5");
returnvalue=time.Parse(KDateString4);
// error - two component dates not supported The following
example code demonstrates setting both the time and date. Either date or time
component may occur first in the descriptor. Both return a value of EParseDatePresent and EParseTimePresent.
_LIT(KDateTimeString1, "20-feb/00 12:40.01am");
returnvalue=time.Parse(KDateTimeString1);
// 20 Feb 2000 00:40:01
_LIT(KDateTimeString2, "12:40.01pm 20 FEBRUARY 00");
returnvalue=time.Parse(KDateTimeString2);
// 12:40:01 20 Feb 2000 The following code sets two of
the locale settings which are honoured by TTime::Parse():
the date and time separator characters. The first call to TTime::Parse() returns
a date/time of midnight 20th April 2018 because the hyphen is interpreted
as a date separator character. The second call returns a date/time of January
1st year zero, at 20:04.18 because the dot is interpreted as a time separator
character.
TLocale locale;
locale.SetDateSeparator('-',1); // set first date separator
locale.SetDateSeparator('-',2); // set second date separator
locale.SetTimeSeparator('.',1); // set first time separator
locale.SetTimeSeparator('.',2); // set second time separator
locale.Set(); // transfer the new locale settings to the system
_LIT(KParseLocaleString1,"20-04-18"); // DD/MM/YYYY
returnvalue=time.Parse(KParseLocaleString1); // 20th April 2018 00:00:00.0000
_LIT(KParseLocaleString2,"20.04.18");
returnvalue=time.Parse(KParseLocaleString2); // 01 Jan 0000 20:04.18