Using +TTime

Set()

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

MonthsFrom()

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

YearsFrom()

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

WeekNoInYear()

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.

FormatL()

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

Parse()

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 +