<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-4DC2D055-E522-51C4-8BF9-1361089F0E4A" xml:lang="en"><title>Using

TTime</title><shortdesc>Explains how to use various functions related to Time.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-BB4B8F39-12EE-438F-A214-A40FBC59AB02"><title>Set()</title> <p>This function is used to assign a date and

time string contained in a descriptor to this <codeph>TTime</codeph>. 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.</p> <codeblock id="GUID-473FDD90-2EE4-5949-94DB-E7AB836D68B5" xml:space="preserve">

_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</codeblock> </section>

<section id="GUID-69327BF0-82B1-496E-96E6-018EA1FB75C8"><title>MonthsFrom()</title> <p>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.</p> <p>The following code shows how intervals are

calculated between dates in months which have different numbers of days. This <codeph>TTime</codeph> (<codeph>time</codeph>)

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.</p> <codeblock id="GUID-D5372028-DE73-55DC-B13F-8116C08D2CC6" xml:space="preserve">

_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</codeblock> </section>

<section id="GUID-9F678981-840F-4779-8510-2A5883E2A4C0"><title>YearsFrom()</title> <p>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 <codeph>TTime</codeph> (<codeph>leapYear</codeph>)

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.</p> <codeblock id="GUID-1D3AB4EE-AC45-58B3-88F9-4478B58481A6" xml:space="preserve">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</codeblock> </section>

<section id="GUID-79EDFED3-7078-4CCB-AB58-B6FA04C956E5"><title>WeekNoInYear()</title> <p>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.</p> <p>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 <codeph>time</codeph> is

an instance of <codeph>TTime</codeph>:</p> <ul>

<li id="GUID-47AF61F9-B193-50C3-8007-26AE23808D4B"><p><codeph>time.WeekNoInYear()==2</codeph> because

Monday 6th is the first day in week 2.</p> </li>

<li id="GUID-4DA18438-1515-58BB-9FE9-E039023843DD"><p><codeph>time.WeekNoInYear(EFirstFullWeek)==1</codeph> because

Monday 6th is the first day in the first week entirely in 1997.</p> </li>

<li id="GUID-8403D336-70B3-5E1C-9DA9-4CA17E78A31E"><p><codeph>time.WeekNoInYear(EFirstWeek)==2</codeph> because

the first week in the year was the week containing the 1st January (Wednesday

1st to Sunday 5th).</p> </li>

<li id="GUID-4EB8898D-151E-5D92-8D33-D7D6173FC444"><p><codeph>time.WeekNoInYear(EFirstFourDayWeek)==2</codeph> because

the first four days of the year, representing the first week in the year,

were Wednesday 1st to Saturday 4th.</p> </li>

</ul> </section>

<section id="GUID-528DC58D-B897-4B67-A0CF-4062195E9320"><title>FormatL()</title> <p>The examples below demonstrate how to

format a descriptor which holds a date/time string, locale-dependently and

independently.</p> <p>The following code fragment is locale-dependent. It

assumes the current date and time (<codeph>TTime</codeph>  <codeph>time</codeph>)

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;</p> <codeblock id="GUID-FFDF7E9C-EA94-59F3-BE24-B764B59D2EE6" xml:space="preserve">TBuf&lt;30&gt; 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</codeblock> <p>The

following code demonstrates formatting two component dates and times.</p> <codeblock id="GUID-821666B8-DC3D-5B1F-88C9-9D74FABA978B" xml:space="preserve">

_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</codeblock> <p>The following code demonstrates

that the ordering of the <codeph>%D</codeph>  <codeph>%M</codeph>  <codeph>%Y</codeph> is

irrelevant when using locale-dependent formatting. The ordering of the date

components is determined by the order of the <codeph>%1</codeph>, <codeph>%2</codeph>,

and <codeph>%3</codeph> formatting commands.</p> <codeblock id="GUID-6D0B0117-37AC-5D68-A1F1-A514DCCC359C" xml:space="preserve">

_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</codeblock> <p>However, when using locale-independent

formatting, the <codeph>%1</codeph>, <codeph>%2</codeph> and <codeph>%3</codeph> are

not required. The ordering of the date components is determined by the ordering

of the <codeph>%D</codeph>, <codeph>%M</codeph> and <codeph>%Y</codeph>.</p> <codeblock id="GUID-F9E88ECC-D3AC-531E-8498-52B7085F587C" xml:space="preserve">

_LIT(KDateString11,"%F%/0%M%/1%Y%/2%D%/3");

time.FormatL(dateString,KDateString11);

// dateString contains 01/1997/02</codeblock> </section>

<section id="GUID-B4810AFC-D97B-4868-AF1C-F42C6D4DFB43"><title>Parse()</title> <p>This function is used to parse a descriptor

containing either or both a date and time, setting this <codeph>TTime</codeph> to

the value of the parsed descriptor.</p> <p>The following example code demonstrates

setting the time alone. The following four calls to <codeph>TTime::Parse()</codeph> 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 <codeph>EParseTimePresent</codeph>.

Different time separators may be used in the same string</p> <codeblock id="GUID-8854867B-6DE0-5EF3-8405-BDBAECC1E881" xml:space="preserve">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

</codeblock> <p>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 <codeph>EParseDatePresent</codeph>.

Different date separators may be used in the same string, and the month may

be specified as text or numbers.</p> <codeblock id="GUID-73EE57A1-E907-59CF-96FA-320218FE2D08" xml:space="preserve">_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</codeblock> <p>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 <codeph>EParseDatePresent</codeph> and <codeph>EParseTimePresent</codeph>.</p> <codeblock id="GUID-D983FE29-E582-5A04-9885-C40223382FD0" xml:space="preserve">_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</codeblock> <p>The following code sets two of

the locale settings which are honoured by <codeph>TTime::Parse()</codeph>:

the date and time separator characters. The first call to <codeph>TTime::Parse()</codeph> 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.</p> <codeblock id="GUID-E1C8019E-6074-5875-8826-A84EC0A3C8D0" xml:space="preserve">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 

</codeblock> </section>