--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-4DC2D055-E522-51C4-8BF9-1361089F0E4A.dita Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,207 @@
+<?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<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</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>
\ No newline at end of file