|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-4DC2D055-E522-51C4-8BF9-1361089F0E4A" xml:lang="en"><title>Using |
|
13 TTime</title><shortdesc>Explains how to use various functions related to Time.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-BB4B8F39-12EE-438F-A214-A40FBC59AB02"><title>Set()</title> <p>This function is used to assign a date and |
|
15 time string contained in a descriptor to this <codeph>TTime</codeph>. The |
|
16 code below gives examples of invalid input strings, causing an error to be |
|
17 returned. When there is an error, the date/time remains unchanged. Note that |
|
18 when specifying the month and day in the input string, both values start at |
|
19 zero, so that 19940102 indicates 3rd February 1994.</p> <codeblock id="GUID-473FDD90-2EE4-5949-94DB-E7AB836D68B5" xml:space="preserve"> |
|
20 _LIT(KDateCorrect1,"19940102:"); |
|
21 TBuf <24> theDate=KDateCorrect1; // theDate = 3rd February 1994 00:00:00 am |
|
22 TInt err=time.Set(theDate); // No error |
|
23 _LIT(KDateCorrect2,"19940102:.000001"); |
|
24 theDate=KDateCorrect2; // theDate = 3rd February 1994 00:00:00.000001 |
|
25 err=time.Set(theDate); // No error |
|
26 _LIT(KDateWrongColonPos,"1994012:100000.000001"); |
|
27 theDate=KDateWrongColonPos; |
|
28 err=time.Set(theDate); // KErrGeneral error - time is unchanged |
|
29 // Error — colon in wrong position (position 7). If present, must |
|
30 // be either at position zero or position eight |
|
31 _LIT(KDateWrongDotPos,"19940102.000001"); |
|
32 theDate=KDateWrongDotPos; |
|
33 err=time.Set(theDate); // KErrGeneral error - time is unchanged |
|
34 // Error — dot in wrong position. If no colon present, dot must be |
|
35 // at position zero (indicating that both YYYYMMDD and HHMMSS |
|
36 // omitted), or position six (indicating that YYYYMMDD omitted) |
|
37 _LIT(KDateNoDotOrColon,"19940102"); |
|
38 theDate=KDateNoDotOrColon; |
|
39 err=time.Set(theDate); // Error — either or both dot and colon must be present</codeblock> </section> |
|
40 <section id="GUID-69327BF0-82B1-496E-96E6-018EA1FB75C8"><title>MonthsFrom()</title> <p>This function is used to calculate |
|
41 the number of months between two date/times. The result may be positive or |
|
42 negative. A positive value means that this time is later than the time contained |
|
43 in the argument and a negative value means that this time is earlier than |
|
44 the time in the argument.</p> <p>The following code shows how intervals are |
|
45 calculated between dates in months which have different numbers of days. This <codeph>TTime</codeph> (<codeph>time</codeph>) |
|
46 is initialized to 10:00:00 AM on the 31st October. The code demonstrates that |
|
47 counting forwards, one month elapses when the same time on the 30th November |
|
48 is reached. When counting backwards, one month elapses when the last microsecond |
|
49 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"> |
|
50 _LIT(KMiddleDateTime,"19970930:100000.000000"); |
|
51 TTime time(KMiddleDateTime); |
|
52 // time=31/10/1997 10:00:00:000000 |
|
53 _LIT(KEarlierDateTime,"19970829:235959.999999"); |
|
54 TTime earlierTime(KEarlierDateTime); |
|
55 // earlierTime=30/09/1997 23:59:59:999999 |
|
56 _LIT(KLaterDateTime,"19971029:100000.000000"); |
|
57 TTime laterTime(KLaterDateTime); |
|
58 // laterTime=30/11/1997 10:00:00:000000 |
|
59 TTimeIntervalMonths result=time.MonthsFrom(earlierTime); |
|
60 // result == +1 |
|
61 result=time.MonthsFrom(laterTime); // result == -1 |
|
62 TTimeIntervalMicroSeconds interval(1); |
|
63 earlierTime+=interval; // earlierTime=01/10/1997 00:00:00:000000 |
|
64 laterTime-=interval; // laterTime=30/11/1997 09:59:59:999999 |
|
65 result=time.MonthsFrom(earlierTime); // result == zero |
|
66 result=time.MonthsFrom(laterTime); // result == zero</codeblock> </section> |
|
67 <section id="GUID-9F678981-840F-4779-8510-2A5883E2A4C0"><title>YearsFrom()</title> <p>This function is used to calculate |
|
68 the number of years between two date/times. The result may be positive or |
|
69 negative. In the following piece of code, this <codeph>TTime</codeph> (<codeph>leapYear</codeph>) |
|
70 is set to the 29th February 1996. It demonstrates that from 10:00:00 29th |
|
71 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; |
|
72 TDateTime dateTime(1996,EFebruary,28,10,00,00,000000); |
|
73 TTime leapYear(dateTime); // leapYear==29/02/1996 10:00:00:000000 |
|
74 TTime nextYear(dateTime); |
|
75 TTimeIntervalYears intervalInYears(1); |
|
76 nextYear+=intervalInYears; // nextYear==28/02/1997 10:00:00:000000 |
|
77 result=leapYear.YearsFrom(nextYear); // as expected, result==–1</codeblock> </section> |
|
78 <section id="GUID-79EDFED3-7078-4CCB-AB58-B6FA04C956E5"><title>WeekNoInYear()</title> <p>These functions are used to find |
|
79 the number of the current week in the year. Variants are provided to allow |
|
80 the user to specify the date which is to be considered as the start of the |
|
81 year and to set the rule governing which week is the first week in the year.</p> <p>Assuming |
|
82 that the first day in the week is Monday, the first day in the year is January |
|
83 1st and the current date is Monday 6th January 1997 and <codeph>time</codeph> is |
|
84 an instance of <codeph>TTime</codeph>:</p> <ul> |
|
85 <li id="GUID-47AF61F9-B193-50C3-8007-26AE23808D4B"><p><codeph>time.WeekNoInYear()==2</codeph> because |
|
86 Monday 6th is the first day in week 2.</p> </li> |
|
87 <li id="GUID-4DA18438-1515-58BB-9FE9-E039023843DD"><p><codeph>time.WeekNoInYear(EFirstFullWeek)==1</codeph> because |
|
88 Monday 6th is the first day in the first week entirely in 1997.</p> </li> |
|
89 <li id="GUID-8403D336-70B3-5E1C-9DA9-4CA17E78A31E"><p><codeph>time.WeekNoInYear(EFirstWeek)==2</codeph> because |
|
90 the first week in the year was the week containing the 1st January (Wednesday |
|
91 1st to Sunday 5th).</p> </li> |
|
92 <li id="GUID-4EB8898D-151E-5D92-8D33-D7D6173FC444"><p><codeph>time.WeekNoInYear(EFirstFourDayWeek)==2</codeph> because |
|
93 the first four days of the year, representing the first week in the year, |
|
94 were Wednesday 1st to Saturday 4th.</p> </li> |
|
95 </ul> </section> |
|
96 <section id="GUID-528DC58D-B897-4B67-A0CF-4062195E9320"><title>FormatL()</title> <p>The examples below demonstrate how to |
|
97 format a descriptor which holds a date/time string, locale-dependently and |
|
98 independently.</p> <p>The following code fragment is locale-dependent. It |
|
99 assumes the current date and time (<codeph>TTime</codeph> <codeph>time</codeph>) |
|
100 is 2nd January 1997 23:59:59.999999, and uses the system default date and |
|
101 time settings for a UK locale, including the default date and time separators, |
|
102 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; |
|
103 _LIT(KDateString1,"%E%D%X%N%Y %1 %2 %3"); |
|
104 time.FormatL(dateString,KDateString1); |
|
105 // dateString contains "Thursday 02nd January 1997" - no abbreviation |
|
106 |
|
107 _LIT(KDateString2,"%*E%*D%X%*N%*Y %1 %2 '%3"); |
|
108 time.FormatL(dateString,KDateString2); |
|
109 // dateString contains "Thu 2nd Jan '97" - everything abbreviated |
|
110 |
|
111 _LIT(KDateString3,"%D%M%Y%/0%1%/1%2%/2%3%/3"); |
|
112 time.FormatL(dateString,KDateString3); |
|
113 // dateString contains "02/01/1997" - no abbreviation; first and third |
|
114 // date separators are both '\0' |
|
115 |
|
116 _LIT(KDateString4,"%-B%:0%J%:1%T%:2%S%.%*C4%:3%+B"); |
|
117 time.FormatL(dateString,KDateString4); |
|
118 // dateString contains "11:59:59.9999 pm" - first and third time |
|
119 // separators are both '\0'; locale dependent decimal separator |
|
120 // separates seconds and microseconds |
|
121 |
|
122 _LIT(KDateString5,"%-B%:0%J%:1%T%:2%S%:3%+B"); |
|
123 time.FormatL(dateString,KDateString5); |
|
124 // dateString contains "11:59:59 pm - as above, but no microseconds</codeblock> <p>The |
|
125 following code demonstrates formatting two component dates and times.</p> <codeblock id="GUID-821666B8-DC3D-5B1F-88C9-9D74FABA978B" xml:space="preserve"> |
|
126 _LIT(KDateString6,"%-B%:0%J%:1%T%:3%+B"); |
|
127 time.FormatL(dateString,KDateString6); |
|
128 // dateString contains "11:59 pm" - Two component time (hour:minute). |
|
129 // Third time delimiter omitted as it separates minutes and seconds |
|
130 |
|
131 _LIT(KDateString7,"%M%Y%/0%4%/1%5%/3"); |
|
132 time.FormatL(dateString,KDateString7); |
|
133 // dateString contains "02/01" - Two component date (day/month). |
|
134 // Third date delimiter omitted</codeblock> <p>The following code demonstrates |
|
135 that the ordering of the <codeph>%D</codeph> <codeph>%M</codeph> <codeph>%Y</codeph> is |
|
136 irrelevant when using locale-dependent formatting. The ordering of the date |
|
137 components is determined by the order of the <codeph>%1</codeph>, <codeph>%2</codeph>, |
|
138 and <codeph>%3</codeph> formatting commands.</p> <codeblock id="GUID-6D0B0117-37AC-5D68-A1F1-A514DCCC359C" xml:space="preserve"> |
|
139 _LIT(KDateString8,"%M%Y%D%/0%1%/1%2%/2%3%/3"); |
|
140 time.FormatL(dateString,KDateString8); |
|
141 // dateString contains 02/01/1997 |
|
142 |
|
143 _LIT(KDateString9,"%Y%D%M%/0%1%/1%2%/2%3%/3"); |
|
144 time.FormatL(dateString,KDateString9); |
|
145 // dateString contains 02/01/1997 |
|
146 |
|
147 _LIT(KDateString10,"%D%M%Y%/0%3%/1%1%/2%2%/3"); |
|
148 time.FormatL(dateString,KDateString10); |
|
149 // dateString contains 1997/02/01</codeblock> <p>However, when using locale-independent |
|
150 formatting, the <codeph>%1</codeph>, <codeph>%2</codeph> and <codeph>%3</codeph> are |
|
151 not required. The ordering of the date components is determined by the ordering |
|
152 of the <codeph>%D</codeph>, <codeph>%M</codeph> and <codeph>%Y</codeph>.</p> <codeblock id="GUID-F9E88ECC-D3AC-531E-8498-52B7085F587C" xml:space="preserve"> |
|
153 _LIT(KDateString11,"%F%/0%M%/1%Y%/2%D%/3"); |
|
154 time.FormatL(dateString,KDateString11); |
|
155 // dateString contains 01/1997/02</codeblock> </section> |
|
156 <section id="GUID-B4810AFC-D97B-4868-AF1C-F42C6D4DFB43"><title>Parse()</title> <p>This function is used to parse a descriptor |
|
157 containing either or both a date and time, setting this <codeph>TTime</codeph> to |
|
158 the value of the parsed descriptor.</p> <p>The following example code demonstrates |
|
159 setting the time alone. The following four calls to <codeph>TTime::Parse()</codeph> give |
|
160 the same result; 23:34.56. Because no date is specified, the date is set to |
|
161 January 1st year zero, and all return a value of <codeph>EParseTimePresent</codeph>. |
|
162 Different time separators may be used in the same string</p> <codeblock id="GUID-8854867B-6DE0-5EF3-8405-BDBAECC1E881" xml:space="preserve">TTime time; |
|
163 _LIT(KTimeString1,"23:34.56"); |
|
164 TInt returnvalue=time.Parse(KTimeString1); // 11 pm |
|
165 _LIT(KTimeString2,"0023:0034.056"); |
|
166 returnvalue=time.Parse(KTimeString2); // Leading zeros ignored |
|
167 _LIT(KTimeString3,"23:34.56am"); |
|
168 returnvalue=time.Parse(KTimeString3); // "am" ignored |
|
169 _LIT(KTimeString4,"11:34.56p"); |
|
170 returnvalue=time.Parse(KTimeString4); // 11 pm |
|
171 </codeblock> <p>The following example code demonstrates setting the date alone. |
|
172 Because no time is specified, the time is set to midnight (00:00:00), and |
|
173 all except the final call return a value of <codeph>EParseDatePresent</codeph>. |
|
174 Different date separators may be used in the same string, and the month may |
|
175 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 |
|
176 returnvalue=time.Parse(KDateString1); // 5 June 1996 |
|
177 _LIT(KDateString2,"5 jun, 00"); |
|
178 returnvalue=time.Parse(KDateString2,00); // 5 June 2000 |
|
179 _LIT(KDateString3, "5/june/00"); |
|
180 returnvalue=time.Parse(KDateString3,00); // 5 June 2000 |
|
181 _LIT(KDateString4, "june 5"); |
|
182 returnvalue=time.Parse(KDateString4); |
|
183 // error - two component dates not supported</codeblock> <p>The following |
|
184 example code demonstrates setting both the time and date. Either date or time |
|
185 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"); |
|
186 returnvalue=time.Parse(KDateTimeString1); |
|
187 // 20 Feb 2000 00:40:01 |
|
188 _LIT(KDateTimeString2, "12:40.01pm 20 FEBRUARY 00"); |
|
189 returnvalue=time.Parse(KDateTimeString2); |
|
190 // 12:40:01 20 Feb 2000</codeblock> <p>The following code sets two of |
|
191 the locale settings which are honoured by <codeph>TTime::Parse()</codeph>: |
|
192 the date and time separator characters. The first call to <codeph>TTime::Parse()</codeph> returns |
|
193 a date/time of midnight 20th April 2018 because the hyphen is interpreted |
|
194 as a date separator character. The second call returns a date/time of January |
|
195 1st year zero, at 20:04.18 because the dot is interpreted as a time separator |
|
196 character.</p> <codeblock id="GUID-E1C8019E-6074-5875-8826-A84EC0A3C8D0" xml:space="preserve">TLocale locale; |
|
197 locale.SetDateSeparator('-',1); // set first date separator |
|
198 locale.SetDateSeparator('-',2); // set second date separator |
|
199 locale.SetTimeSeparator('.',1); // set first time separator |
|
200 locale.SetTimeSeparator('.',2); // set second time separator |
|
201 locale.Set(); // transfer the new locale settings to the system |
|
202 _LIT(KParseLocaleString1,"20-04-18"); // DD/MM/YYYY |
|
203 returnvalue=time.Parse(KParseLocaleString1); // 20th April 2018 00:00:00.0000 |
|
204 _LIT(KParseLocaleString2,"20.04.18"); |
|
205 returnvalue=time.Parse(KParseLocaleString2); // 01 Jan 0000 20:04.18 |
|
206 </codeblock> </section> |
|
207 </conbody></concept> |