Using TTime

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