<?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 &lt;24&gt; 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>
</conbody></concept>