public/i18n/unicode/calendar.h - Issue 19417002: Move ICU header part 2

Side by Side Diff: public/i18n/unicode/calendar.h

Issue 19417002: Move ICU header part 2 (Closed) Base URL: svn://chrome-svn/chrome/trunk/deps/third_party/icu46/

Patch Set: Created 7 years, 5 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View unified diff | Download patch | Annotate | Revision Log

OLD	NEW
	(Empty)
1 /*

2 ********************************************************************************

3 * Copyright (C) 1997-2010, International Business Machines

4 * Corporation and others. All Rights Reserved.

5 ********************************************************************************

6 *

7 * File CALENDAR.H

8 *

9 * Modification History:

10 *

11 * Date Name Description

12 * 04/22/97 aliu Expanded and corrected comments and other header

13 * contents.

14 * 05/01/97 aliu Made equals(), before(), after() arguments const.

15 * 05/20/97 aliu Replaced fAreFieldsSet with fAreFieldsInSync and

16 * fAreAllFieldsSet.

17 * 07/27/98 stephen Sync up with JDK 1.2

18 * 11/15/99 weiv added YEAR_WOY and DOW_LOCAL

19 * to EDateFields

20 * 8/19/2002 srl Removed Javaisms

21 * 11/07/2003 srl Update, clean up documentation.

22 ********************************************************************************

23 */

24

25 #ifndef CALENDAR_H

26 #define CALENDAR_H

27

28 #include "unicode/utypes.h"

29

30 /**

31 * \file

32 * \brief C++ API: Calendar object

33 */

34 #if !UCONFIG_NO_FORMATTING

35

36 #include "unicode/uobject.h"

37 #include "unicode/locid.h"

38 #include "unicode/timezone.h"

39 #include "unicode/ucal.h"

40 #include "unicode/umisc.h"

41

42 U_NAMESPACE_BEGIN

43

44 class ICUServiceFactory;

45

46 /**

47 * @internal

48 */

49 typedef int32_t UFieldResolutionTable[12][8];

50

51 /**

52 * <code>Calendar</code> is an abstract base class for converting between

53 * a <code>UDate</code> object and a set of integer fields such as

54 * <code>YEAR</code>, <code>MONTH</code>, <code>DAY</code>, <code>HOUR</code>,

55 * and so on. (A <code>UDate</code> object represents a specific instant in

56 * time with millisecond precision. See UDate

57 * for information about the <code>UDate</code> class.)

58 *

59 * <p>

60 * Subclasses of <code>Calendar</code> interpret a <code>UDate</code>

61 * according to the rules of a specific calendar system.

62 * The most commonly used subclass of <code>Calendar</code> is

63 * <code>GregorianCalendar</code>. Other subclasses could represent

64 * the various types of lunar calendars in use in many parts of the world.

65 *

66 * <p>

67 * <b>NOTE</b>: (ICU 2.6) The subclass interface should be considered unstable

68 * - it WILL change.

69 *

70 * <p>

71 * Like other locale-sensitive classes, <code>Calendar</code> provides a

72 * static method, <code>createInstance</code>, for getting a generally useful

73 * object of this type. <code>Calendar</code>'s <code>createInstance</code> meth od

74 * returns the appropriate <code>Calendar</code> subclass whose

75 * time fields have been initialized with the current date and time:

76 * \htmlonly<blockquote>\endhtmlonly

77 * <pre>

78 * Calendar *rightNow = Calendar::createInstance(errCode);

79 * </pre>

80 * \htmlonly</blockquote>\endhtmlonly

81 *

82 * <p>

83 * A <code>Calendar</code> object can produce all the time field values

84 * needed to implement the date-time formatting for a particular language

85 * and calendar style (for example, Japanese-Gregorian, Japanese-Traditional).

86 *

87 * <p>

88 * When computing a <code>UDate</code> from time fields, two special circumstanc es

89 * may arise: there may be insufficient information to compute the

90 * <code>UDate</code> (such as only year and month but no day in the month),

91 * or there may be inconsistent information (such as "Tuesday, July 15, 1996"

92 * -- July 15, 1996 is actually a Monday).

93 *

94 * <p>

95 * <strong>Insufficient information.</strong> The calendar will use default

96 * information to specify the missing fields. This may vary by calendar; for

97 * the Gregorian calendar, the default for a field is the same as that of the

98 * start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc.

99 *

100 * <p>

101 * <strong>Inconsistent information.</strong> If fields conflict, the calendar

102 * will give preference to fields set more recently. For example, when

103 * determining the day, the calendar will look for one of the following

104 * combinations of fields. The most recent combination, as determined by the

105 * most recently set single field, will be used.

106 *

107 * \htmlonly<blockquote>\endhtmlonly

108 * <pre>

109 * MONTH + DAY_OF_MONTH

110 * MONTH + WEEK_OF_MONTH + DAY_OF_WEEK

111 * MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK

112 * DAY_OF_YEAR

113 * DAY_OF_WEEK + WEEK_OF_YEAR

114 * </pre>

115 * \htmlonly</blockquote>\endhtmlonly

116 *

117 * For the time of day:

118 *

119 * \htmlonly<blockquote>\endhtmlonly

120 * <pre>

121 * HOUR_OF_DAY

122 * AM_PM + HOUR

123 * </pre>

124 * \htmlonly</blockquote>\endhtmlonly

125 *

126 * <p>

127 * <strong>Note:</strong> for some non-Gregorian calendars, different

128 * fields may be necessary for complete disambiguation. For example, a full

129 * specification of the historial Arabic astronomical calendar requires year,

130 * month, day-of-month <em>and</em> day-of-week in some cases.

131 *

132 * <p>

133 * <strong>Note:</strong> There are certain possible ambiguities in

134 * interpretation of certain singular times, which are resolved in the

135 * following ways:

136 * <ol>

137 * <li> 24:00:00 "belongs" to the following day. That is,

138 * 23:59 on Dec 31, 1969 < 24:00 on Jan 1, 1970 < 24:01:00 on Jan 1, 1970

139 *

140 * <li> Although historically not precise, midnight also belongs to "am",

141 * and noon belongs to "pm", so on the same day,

142 * 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm

143 * </ol>

144 *

145 * <p>

146 * The date or time format strings are not part of the definition of a

147 * calendar, as those must be modifiable or overridable by the user at

148 * runtime. Use {@link DateFormat}

149 * to format dates.

150 *

151 * <p>

152 * <code>Calendar</code> provides an API for field "rolling", where fields

153 * can be incremented or decremented, but wrap around. For example, rolling the

154 * month up in the date <code>December 12, <b>1996</b></code> results in

155 * <code>January 12, <b>1996</b></code>.

156 *

157 * <p>

158 * <code>Calendar</code> also provides a date arithmetic function for

159 * adding the specified (signed) amount of time to a particular time field.

160 * For example, subtracting 5 days from the date <code>September 12, 1996</code>

161 * results in <code>September 7, 1996</code>.

162 *

163 * @stable ICU 2.0

164 */

165 class U_I18N_API Calendar : public UObject {

166 public:

167

168 /**

169 * Field IDs for date and time. Used to specify date/time fields. ERA is cal endar

170 * specific. Example ranges given are for illustration only; see specific Ca lendar

171 * subclasses for actual ranges.

172 * @deprecated ICU 2.6. Use C enum UCalendarDateFields defined in ucal.h

173 */

174 enum EDateFields {

175 #ifndef U_HIDE_DEPRECATED_API

176 /*

177 * ERA may be defined on other platforms. To avoid any potential problems undefi ned it here.

178 */

179 #ifdef ERA

180 #undef ERA

181 #endif

182 ERA, // Example: 0..1

183 YEAR, // Example: 1..big number

184 MONTH, // Example: 0..11

185 WEEK_OF_YEAR, // Example: 1..53

186 WEEK_OF_MONTH, // Example: 1..4

187 DATE, // Example: 1..31

188 DAY_OF_YEAR, // Example: 1..365

189 DAY_OF_WEEK, // Example: 1..7

190 DAY_OF_WEEK_IN_MONTH, // Example: 1..4, may be specified as -1

191 AM_PM, // Example: 0..1

192 HOUR, // Example: 0..11

193 HOUR_OF_DAY, // Example: 0..23

194 MINUTE, // Example: 0..59

195 SECOND, // Example: 0..59

196 MILLISECOND, // Example: 0..999

197 ZONE_OFFSET, // Example: -12U_MILLIS_PER_HOUR..12U_MILLIS_PER _HOUR

198 DST_OFFSET, // Example: 0 or U_MILLIS_PER_HOUR

199 YEAR_WOY, // 'Y' Example: 1..big number - Year of Week of Ye ar

200 DOW_LOCAL, // 'e' Example: 1..7 - Day of Week / Localized

201

202 EXTENDED_YEAR,

203 JULIAN_DAY,

204 MILLISECONDS_IN_DAY,

205 IS_LEAP_MONTH,

206

207 FIELD_COUNT = UCAL_FIELD_COUNT // See ucal.h for other fields.

208 #endif /* U_HIDE_DEPRECATED_API */

209 };

210

211 /**

212 * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients

213 * who create locale resources for the field of first-day-of-week should be aware of

214 * this. For instance, in US locale, first-day-of-week is set to 1, i.e., SU NDAY.

215 * @deprecated ICU 2.6. Use C enum UCalendarDaysOfWeek defined in ucal.h

216 */

217 enum EDaysOfWeek {

218 #ifndef U_HIDE_DEPRECATED_API

219 SUNDAY = 1,

220 MONDAY,

221 TUESDAY,

222 WEDNESDAY,

223 THURSDAY,

224 FRIDAY,

225 SATURDAY

226 #endif /* U_HIDE_DEPRECATED_API */

227 };

228

229 /**

230 * Useful constants for month. Note: Calendar month is 0-based.

231 * @deprecated ICU 2.6. Use C enum UCalendarMonths defined in ucal.h

232 */

233 enum EMonths {

234 #ifndef U_HIDE_DEPRECATED_API

235 JANUARY,

236 FEBRUARY,

237 MARCH,

238 APRIL,

239 MAY,

240 JUNE,

241 JULY,

242 AUGUST,

243 SEPTEMBER,

244 OCTOBER,

245 NOVEMBER,

246 DECEMBER,

247 UNDECIMBER

248 #endif /* U_HIDE_DEPRECATED_API */

249 };

250

251 /**

252 * Useful constants for hour in 12-hour clock. Used in GregorianCalendar.

253 * @deprecated ICU 2.6. Use C enum UCalendarAMPMs defined in ucal.h

254 */

255 enum EAmpm {

256 #ifndef U_HIDE_DEPRECATED_API

257 AM,

258 PM

259 #endif /* U_HIDE_DEPRECATED_API */

260 };

261

262 /**

263 * destructor

264 * @stable ICU 2.0

265 */

266 virtual ~Calendar();

267

268 /**

269 * Create and return a polymorphic copy of this calendar.

270 *

271 * @return a polymorphic copy of this calendar.

272 * @stable ICU 2.0

273 */

274 virtual Calendar* clone(void) const = 0;

275

276 /**

277 * Creates a Calendar using the default timezone and locale. Clients are res ponsible

278 * for deleting the object returned.

279 *

280 * @param success Indicates the success/failure of Calendar creation. Fille d in

281 * with U_ZERO_ERROR if created successfully, set to a failu re result

282 * otherwise. U_MISSING_RESOURCE_ERROR will be returned if t he resource data

283 * requests a calendar type which has not been installed.

284 * @return A Calendar if created successfully. NULL otherwise.

285 * @stable ICU 2.0

286 */

287 static Calendar* U_EXPORT2 createInstance(UErrorCode& success);

288

289 /**

290 * Creates a Calendar using the given timezone and the default locale.

291 * The Calendar takes ownership of zoneToAdopt; the

292 * client must not delete it.

293 *

294 * @param zoneToAdopt The given timezone to be adopted.

295 * @param success Indicates the success/failure of Calendar creation. F illed in

296 * with U_ZERO_ERROR if created successfully, set to a f ailure result

297 * otherwise.

298 * @return A Calendar if created successfully. NULL otherwise.

299 * @stable ICU 2.0

300 */

301 static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, UErrorCode& success);

302

303 /**

304 * Creates a Calendar using the given timezone and the default locale. The TimeZone

305 * is _not_ adopted; the client is still responsible for deleting it.

306 *

307 * @param zone The timezone.

308 * @param success Indicates the success/failure of Calendar creation. F illed in

309 * with U_ZERO_ERROR if created successfully, set to a f ailure result

310 * otherwise.

311 * @return A Calendar if created successfully. NULL otherwise.

312 * @stable ICU 2.0

313 */

314 static Calendar* U_EXPORT2 createInstance(const TimeZone& zone, UErrorCode& success);

315

316 /**

317 * Creates a Calendar using the default timezone and the given locale.

318 *

319 * @param aLocale The given locale.

320 * @param success Indicates the success/failure of Calendar creation. Fille d in

321 * with U_ZERO_ERROR if created successfully, set to a failu re result

322 * otherwise.

323 * @return A Calendar if created successfully. NULL otherwise.

324 * @stable ICU 2.0

325 */

326 static Calendar* U_EXPORT2 createInstance(const Locale& aLocale, UErrorCode& success);

327

328 /**

329 * Creates a Calendar using the given timezone and given locale.

330 * The Calendar takes ownership of zoneToAdopt; the

331 * client must not delete it.

332 *

333 * @param zoneToAdopt The given timezone to be adopted.

334 * @param aLocale The given locale.

335 * @param success Indicates the success/failure of Calendar creation. F illed in

336 * with U_ZERO_ERROR if created successfully, set to a f ailure result

337 * otherwise.

338 * @return A Calendar if created successfully. NULL otherwise.

339 * @stable ICU 2.0

340 */

341 static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, const Local e& aLocale, UErrorCode& success);

342

343 /**

344 * Gets a Calendar using the given timezone and given locale. The TimeZone

345 * is _not_ adopted; the client is still responsible for deleting it.

346 *

347 * @param zoneToAdopt The given timezone to be adopted.

348 * @param aLocale The given locale.

349 * @param success Indicates the success/failure of Calendar creation. F illed in

350 * with U_ZERO_ERROR if created successfully, set to a f ailure result

351 * otherwise.

352 * @return A Calendar if created successfully. NULL otherwise.

353 * @stable ICU 2.0

354 */

355 static Calendar* U_EXPORT2 createInstance(const TimeZone& zoneToAdopt, const Locale& aLocale, UErrorCode& success);

356

357 /**

358 * Returns a list of the locales for which Calendars are installed.

359 *

360 * @param count Number of locales returned.

361 * @return An array of Locale objects representing the set of locales for which

362 * Calendars are installed. The system retains ownership of t his list;

363 * the caller must NOT delete it. Does not include user-regist ered Calendars.

364 * @stable ICU 2.0

365 */

366 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);

367

368

369 /**

370 * Given a key and a locale, returns an array of string values in a preferre d

371 * order that would make a difference. These are all and only those values w here

372 * the open (creation) of the service with the locale formed from the input locale

373 * plus input keyword and that value has different behavior than creation wi th the

374 * input locale alone.

375 * @param key one of the keys supported by this service. For now, only

376 * "calendar" is supported.

377 * @param locale the locale

378 * @param commonlyUsed if set to true it will return only commonly used val ues

379 * with the given locale in preferred order. Otherwise ,

380 * it will return all the available values for the loca le.

381 * @param status ICU Error Code

382 * @return a string enumeration over keyword values for the given key and th e locale.

383 * @stable ICU 4.2

384 */

385 static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* ke y,

386 const Locale& locale, UBool commonlyUsed, UErrorCode& status );

387

388 /**

389 * Returns the current UTC (GMT) time measured in milliseconds since 0:00:00 on 1/1/70

390 * (derived from the system time).

391 *

392 * @return The current UTC time in milliseconds.

393 * @stable ICU 2.0

394 */

395 static UDate U_EXPORT2 getNow(void);

396

397 /**

398 * Gets this Calendar's time as milliseconds. May involve recalculation of t ime due

399 * to previous calls to set time field values. The time specified is non-loc al UTC

400 * (GMT) time. Although this method is const, this object may actually be ch anged

401 * (semantically const).

402 *

403 * @param status Output param set to success/failure code on exit. If any v alue

404 * previously set in the time field is invalid or restricted by

405 * leniency, this will be set to an error status.

406 * @return The current time in UTC (GMT) time, or zero if the operati on

407 * failed.

408 * @stable ICU 2.0

409 */

410 inline UDate getTime(UErrorCode& status) const { return getTimeInMillis(stat us); }

411

412 /**

413 * Sets this Calendar's current time with the given UDate. The time specifie d should

414 * be in non-local UTC (GMT) time.

415 *

416 * @param date The given UDate in UTC (GMT) time.

417 * @param status Output param set to success/failure code on exit. If any v alue

418 * set in the time field is invalid or restricted by

419 * leniency, this will be set to an error status.

420 * @stable ICU 2.0

421 */

422 inline void setTime(UDate date, UErrorCode& status) { setTimeInMillis(date, status); }

423

424 /**

425 * Compares the equality of two Calendar objects. Objects of different subcl asses

426 * are considered unequal. This comparison is very exacting; two Calendar ob jects

427 * must be in exactly the same state to be considered equal. To compare base d on the

428 * represented time, use equals() instead.

429 *

430 * @param that The Calendar object to be compared with.

431 * @return True if the given Calendar is the same as this Calendar; fal se

432 * otherwise.

433 * @stable ICU 2.0

434 */

435 virtual UBool operator==(const Calendar& that) const;

436

437 /**

438 * Compares the inequality of two Calendar objects.

439 *

440 * @param that The Calendar object to be compared with.

441 * @return True if the given Calendar is not the same as this Calendar; false

442 * otherwise.

443 * @stable ICU 2.0

444 */

445 UBool operator!=(const Calendar& that) const {return !operator==(that);}

446

447 /**

448 * Returns TRUE if the given Calendar object is equivalent to this

449 * one. An equivalent Calendar will behave exactly as this one

450 * does, but it may be set to a different time. By contrast, for

451 * the operator==() method to return TRUE, the other Calendar must

452 * be set to the same time.

453 *

454 * @param other the Calendar to be compared with this Calendar

455 * @stable ICU 2.4

456 */

457 virtual UBool isEquivalentTo(const Calendar& other) const;

458

459 /**

460 * Compares the Calendar time, whereas Calendar::operator== compares the equ ality of

461 * Calendar objects.

462 *

463 * @param when The Calendar to be compared with this Calendar. Although t his is a

464 * const parameter, the object may be modified physically

465 * (semantically const).

466 * @param status Output param set to success/failure code on exit. If any v alue

467 * previously set in the time field is invalid or restricted by

468 * leniency, this will be set to an error status.

469 * @return True if the current time of this Calendar is equal to the time of

470 * Calendar when; false otherwise.

471 * @stable ICU 2.0

472 */

473 UBool equals(const Calendar& when, UErrorCode& status) const;

474

475 /**

476 * Returns true if this Calendar's current time is before "when"'s current t ime.

477 *

478 * @param when The Calendar to be compared with this Calendar. Although t his is a

479 * const parameter, the object may be modified physically

480 * (semantically const).

481 * @param status Output param set to success/failure code on exit. If any v alue

482 * previously set in the time field is invalid or restricted by

483 * leniency, this will be set to an error status.

484 * @return True if the current time of this Calendar is before the ti me of

485 * Calendar when; false otherwise.

486 * @stable ICU 2.0

487 */

488 UBool before(const Calendar& when, UErrorCode& status) const;

489

490 /**

491 * Returns true if this Calendar's current time is after "when"'s current ti me.

492 *

493 * @param when The Calendar to be compared with this Calendar. Although t his is a

494 * const parameter, the object may be modified physically

495 * (semantically const).

496 * @param status Output param set to success/failure code on exit. If any v alue

497 * previously set in the time field is invalid or restricted by

498 * leniency, this will be set to an error status.

499 * @return True if the current time of this Calendar is after the tim e of

500 * Calendar when; false otherwise.

501 * @stable ICU 2.0

502 */

503 UBool after(const Calendar& when, UErrorCode& status) const;

504

505 /**

506 * UDate Arithmetic function. Adds the specified (signed) amount of time to the given

507 * time field, based on the calendar's rules. For example, to subtract 5 day s from

508 * the current time of the calendar, call add(Calendar::DATE, -5). When addi ng on

509 * the month or Calendar::MONTH field, other fields like date might conflict and

510 * need to be changed. For instance, adding 1 month on the date 01/31/96 wil l result

511 * in 02/29/96.

512 *

513 * @param field Specifies which date field to modify.

514 * @param amount The amount of time to be added to the field, in the natura l unit

515 * for that field (e.g., days for the day fields, hours for t he hour

516 * field.)

517 * @param status Output param set to success/failure code on exit. If any v alue

518 * previously set in the time field is invalid or restricted by

519 * leniency, this will be set to an error status.

520 * @deprecated ICU 2.6. use add(UCalendarDateFields field, int32_t amount, U ErrorCode& status) instead.

521 */

522 virtual void add(EDateFields field, int32_t amount, UErrorCode& status);

523

524 /**

525 * UDate Arithmetic function. Adds the specified (signed) amount of time to the given

526 * time field, based on the calendar's rules. For example, to subtract 5 day s from

527 * the current time of the calendar, call add(Calendar::DATE, -5). When addi ng on

528 * the month or Calendar::MONTH field, other fields like date might conflict and

529 * need to be changed. For instance, adding 1 month on the date 01/31/96 wil l result

530 * in 02/29/96.

531 *

532 * @param field Specifies which date field to modify.

533 * @param amount The amount of time to be added to the field, in the natura l unit

534 * for that field (e.g., days for the day fields, hours for t he hour

535 * field.)

536 * @param status Output param set to success/failure code on exit. If any v alue

537 * previously set in the time field is invalid or restricted by

538 * leniency, this will be set to an error status.

539 * @stable ICU 2.6.

540 */

541 virtual void add(UCalendarDateFields field, int32_t amount, UErrorCode& stat us);

542

543 /**

544 * Time Field Rolling function. Rolls (up/down) a single unit of time on the given

545 * time field. For example, to roll the current date up by one day, call

546 * roll(Calendar::DATE, true). When rolling on the year or Calendar::YEAR fi eld, it

547 * will roll the year value in the range between getMinimum(Calendar::YEAR) and the

548 * value returned by getMaximum(Calendar::YEAR). When rolling on the month o r

549 * Calendar::MONTH field, other fields like date might conflict and, need to be

550 * changed. For instance, rolling the month up on the date 01/31/96 will res ult in

551 * 02/29/96. Rolling up always means rolling forward in time; e.g., rolling the year

552 * up on "100 BC" will result in "99 BC", for Gregorian calendar. When rolli ng on the

553 * hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the hour value i n the range

554 * between 0 and 23, which is zero-based.

555 * <P>

556 * NOTE: Do not use this method -- use roll(EDateFields, int, UErrorCode&) i nstead.

557 *

558 * @param field The time field.

559 * @param up Indicates if the value of the specified time field is to b e rolled

560 * up or rolled down. Use true if rolling up, false otherwise .

561 * @param status Output param set to success/failure code on exit. If any v alue

562 * previously set in the time field is invalid or restricted by

563 * leniency, this will be set to an error status.

564 * @deprecated ICU 2.6. Use roll(UCalendarDateFields field, UBool up, UError Code& status) instead.

565 */

566 inline void roll(EDateFields field, UBool up, UErrorCode& status);

567

568 /**

569 * Time Field Rolling function. Rolls (up/down) a single unit of time on the given

570 * time field. For example, to roll the current date up by one day, call

571 * roll(Calendar::DATE, true). When rolling on the year or Calendar::YEAR fi eld, it

572 * will roll the year value in the range between getMinimum(Calendar::YEAR) and the

573 * value returned by getMaximum(Calendar::YEAR). When rolling on the month o r

574 * Calendar::MONTH field, other fields like date might conflict and, need to be

575 * changed. For instance, rolling the month up on the date 01/31/96 will res ult in

576 * 02/29/96. Rolling up always means rolling forward in time; e.g., rolling the year

577 * up on "100 BC" will result in "99 BC", for Gregorian calendar. When rolli ng on the

578 * hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the hour value i n the range

579 * between 0 and 23, which is zero-based.

580 * <P>

581 * NOTE: Do not use this method -- use roll(UCalendarDateFields, int, UError Code&) instead.

582 *

583 * @param field The time field.

584 * @param up Indicates if the value of the specified time field is to b e rolled

585 * up or rolled down. Use true if rolling up, false otherwise .

586 * @param status Output param set to success/failure code on exit. If any v alue

587 * previously set in the time field is invalid or restricted by

588 * leniency, this will be set to an error status.

589 * @stable ICU 2.6.

590 */

591 inline void roll(UCalendarDateFields field, UBool up, UErrorCode& status);

592

593 /**

594 * Time Field Rolling function. Rolls by the given amount on the given

595 * time field. For example, to roll the current date up by one day, call

596 * roll(Calendar::DATE, +1, status). When rolling on the month or

597 * Calendar::MONTH field, other fields like date might conflict and, need to be

598 * changed. For instance, rolling the month up on the date 01/31/96 will res ult in

599 * 02/29/96. Rolling by a positive value always means rolling forward in ti me;

600 * e.g., rolling the year by +1 on "100 BC" will result in "99 BC", for Greg orian

601 * calendar. When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will

602 * roll the hour value in the range between 0 and 23, which is zero-based.

603 * <P>

604 * The only difference between roll() and add() is that roll() does not chan ge

605 * the value of more significant fields when it reaches the minimum or maxim um

606 * of its range, whereas add() does.

607 *

608 * @param field The time field.

609 * @param amount Indicates amount to roll.

610 * @param status Output param set to success/failure code on exit. If any v alue

611 * previously set in the time field is invalid, this will be set to

612 * an error status.

613 * @deprecated ICU 2.6. Use roll(UCalendarDateFields field, int32_t amount, UErrorCode& status) instead.

614 */

615 virtual void roll(EDateFields field, int32_t amount, UErrorCode& status);

616

617 /**

618 * Time Field Rolling function. Rolls by the given amount on the given

619 * time field. For example, to roll the current date up by one day, call

620 * roll(Calendar::DATE, +1, status). When rolling on the month or

621 * Calendar::MONTH field, other fields like date might conflict and, need to be

622 * changed. For instance, rolling the month up on the date 01/31/96 will res ult in

623 * 02/29/96. Rolling by a positive value always means rolling forward in ti me;

624 * e.g., rolling the year by +1 on "100 BC" will result in "99 BC", for Greg orian

625 * calendar. When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will

626 * roll the hour value in the range between 0 and 23, which is zero-based.

627 * <P>

628 * The only difference between roll() and add() is that roll() does not chan ge

629 * the value of more significant fields when it reaches the minimum or maxim um

630 * of its range, whereas add() does.

631 *

632 * @param field The time field.

633 * @param amount Indicates amount to roll.

634 * @param status Output param set to success/failure code on exit. If any v alue

635 * previously set in the time field is invalid, this will be set to

636 * an error status.

637 * @stable ICU 2.6.

638 */

639 virtual void roll(UCalendarDateFields field, int32_t amount, UErrorCode& sta tus);

640

641 /**

642 * Return the difference between the given time and the time this

643 * calendar object is set to. If this calendar is set

644 * <em>before</em> the given time, the returned value will be

645 * positive. If this calendar is set <em>after</em> the given

646 * time, the returned value will be negative. The

647 * <code>field</code> parameter specifies the units of the return

648 * value. For example, if <code>fieldDifference(when,

649 * Calendar::MONTH)</code> returns 3, then this calendar is set to

650 * 3 months before <code>when</code>, and possibly some addition

651 * time less than one month.

652 *

653 * <p>As a side effect of this call, this calendar is advanced

654 * toward <code>when</code> by the given amount. That is, calling

655 * this method has the side effect of calling <code>add(field,

656 * n)</code>, where <code>n</code> is the return value.

657 *

658 * <p>Usage: To use this method, call it first with the largest

659 * field of interest, then with progressively smaller fields. For

660 * example:

661 *

662 * <pre>

663 * int y = cal->fieldDifference(when, Calendar::YEAR, err);

664 * int m = cal->fieldDifference(when, Calendar::MONTH, err);

665 * int d = cal->fieldDifference(when, Calendar::DATE, err);</pre>

666 *

667 * computes the difference between <code>cal</code> and

668 * <code>when</code> in years, months, and days.

669 *

670 * <p>Note: <code>fieldDifference()</code> is

671 * <em>asymmetrical</em>. That is, in the following code:

672 *

673 * <pre>

674 * cal->setTime(date1, err);

675 * int m1 = cal->fieldDifference(date2, Calendar::MONTH, err);

676 * int d1 = cal->fieldDifference(date2, Calendar::DATE, err);

677 * cal->setTime(date2, err);

678 * int m2 = cal->fieldDifference(date1, Calendar::MONTH, err);

679 * int d2 = cal->fieldDifference(date1, Calendar::DATE, err);</pre>

680 *

681 * one might expect that <code>m1 == -m2 && d1 == -d2</code>.

682 * However, this is not generally the case, because of

683 * irregularities in the underlying calendar system (e.g., the

684 * Gregorian calendar has a varying number of days per month).

685 *

686 * @param when the date to compare this calendar's time to

687 * @param field the field in which to compute the result

688 * @param status Output param set to success/failure code on exit. If any v alue

689 * previously set in the time field is invalid, this will be set to

690 * an error status.

691 * @return the difference, either positive or negative, between

692 * this calendar's time and <code>when</code>, in terms of

693 * <code>field</code>.

694 * @deprecated ICU 2.6. Use fieldDifference(UDate when, UCalendarDateFields field, UErrorCode& status).

695 */

696 virtual int32_t fieldDifference(UDate when, EDateFields field, UErrorCode& s tatus);

697

698 /**

699 * Return the difference between the given time and the time this

700 * calendar object is set to. If this calendar is set

701 * <em>before</em> the given time, the returned value will be

702 * positive. If this calendar is set <em>after</em> the given

703 * time, the returned value will be negative. The

704 * <code>field</code> parameter specifies the units of the return

705 * value. For example, if <code>fieldDifference(when,

706 * Calendar::MONTH)</code> returns 3, then this calendar is set to

707 * 3 months before <code>when</code>, and possibly some addition

708 * time less than one month.

709 *

710 * <p>As a side effect of this call, this calendar is advanced

711 * toward <code>when</code> by the given amount. That is, calling

712 * this method has the side effect of calling <code>add(field,

713 * n)</code>, where <code>n</code> is the return value.

714 *

715 * <p>Usage: To use this method, call it first with the largest

716 * field of interest, then with progressively smaller fields. For

717 * example:

718 *

719 * <pre>

720 * int y = cal->fieldDifference(when, Calendar::YEAR, err);

721 * int m = cal->fieldDifference(when, Calendar::MONTH, err);

722 * int d = cal->fieldDifference(when, Calendar::DATE, err);</pre>

723 *

724 * computes the difference between <code>cal</code> and

725 * <code>when</code> in years, months, and days.

726 *

727 * <p>Note: <code>fieldDifference()</code> is

728 * <em>asymmetrical</em>. That is, in the following code:

729 *

730 * <pre>

731 * cal->setTime(date1, err);

732 * int m1 = cal->fieldDifference(date2, Calendar::MONTH, err);

733 * int d1 = cal->fieldDifference(date2, Calendar::DATE, err);

734 * cal->setTime(date2, err);

735 * int m2 = cal->fieldDifference(date1, Calendar::MONTH, err);

736 * int d2 = cal->fieldDifference(date1, Calendar::DATE, err);</pre>

737 *

738 * one might expect that <code>m1 == -m2 && d1 == -d2</code>.

739 * However, this is not generally the case, because of

740 * irregularities in the underlying calendar system (e.g., the

741 * Gregorian calendar has a varying number of days per month).

742 *

743 * @param when the date to compare this calendar's time to

744 * @param field the field in which to compute the result

745 * @param status Output param set to success/failure code on exit. If any v alue

746 * previously set in the time field is invalid, this will be set to

747 * an error status.

748 * @return the difference, either positive or negative, between

749 * this calendar's time and <code>when</code>, in terms of

750 * <code>field</code>.

751 * @stable ICU 2.6.

752 */

753 virtual int32_t fieldDifference(UDate when, UCalendarDateFields field, UErro rCode& status);

754

755 /**

756 * Sets the calendar's time zone to be the one passed in. The Calendar takes ownership

757 * of the TimeZone; the caller is no longer responsible for deleting it. If the

758 * given time zone is NULL, this function has no effect.

759 *

760 * @param value The given time zone.

761 * @stable ICU 2.0

762 */

763 void adoptTimeZone(TimeZone* value);

764

765 /**

766 * Sets the calendar's time zone to be the same as the one passed in. The Ti meZone

767 * passed in is _not_ adopted; the client is still responsible for deleting it.

768 *

769 * @param zone The given time zone.

770 * @stable ICU 2.0

771 */

772 void setTimeZone(const TimeZone& zone);

773

774 /**

775 * Returns a reference to the time zone owned by this calendar. The returned reference

776 * is only valid until clients make another call to adoptTimeZone or setTime Zone,

777 * or this Calendar is destroyed.

778 *

779 * @return The time zone object associated with this calendar.

780 * @stable ICU 2.0

781 */

782 const TimeZone& getTimeZone(void) const;

783

784 /**

785 * Returns the time zone owned by this calendar. The caller owns the returne d object

786 * and must delete it when done. After this call, the new time zone associa ted

787 * with this Calendar is the default TimeZone as returned by TimeZone::creat eDefault().

788 *

789 * @return The time zone object which was associated with this calendar.

790 * @stable ICU 2.0

791 */

792 TimeZone* orphanTimeZone(void);

793

794 /**

795 * Queries if the current date for this Calendar is in Daylight Savings Time .

796 *

797 * @param status Fill-in parameter which receives the status of this operati on.

798 * @return True if the current date for this Calendar is in Daylight Savin gs Time,

799 * false, otherwise.

800 * @stable ICU 2.0

801 */

802 virtual UBool inDaylightTime(UErrorCode& status) const = 0;

803

804 /**

805 * Specifies whether or not date/time interpretation is to be lenient. With lenient

806 * interpretation, a date such as "February 942, 1996" will be treated as be ing

807 * equivalent to the 941st day after February 1, 1996. With strict interpret ation,

808 * such dates will cause an error when computing time from the time field va lues

809 * representing the dates.

810 *

811 * @param lenient True specifies date/time interpretation to be lenient.

812 *

813 * @see DateFormat#setLenient

814 * @stable ICU 2.0

815 */

816 void setLenient(UBool lenient);

817

818 /**

819 * Tells whether date/time interpretation is to be lenient.

820 *

821 * @return True tells that date/time interpretation is to be lenient.

822 * @stable ICU 2.0

823 */

824 UBool isLenient(void) const;

825

826 /**

827 * Sets what the first day of the week is; e.g., Sunday in US, Monday in Fra nce.

828 *

829 * @param value The given first day of the week.

830 * @deprecated ICU 2.6. Use setFirstDayOfWeek(UCalendarDaysOfWeek value) ins tead.

831 */

832 void setFirstDayOfWeek(EDaysOfWeek value);

833

834 /**

835 * Sets what the first day of the week is; e.g., Sunday in US, Monday in Fra nce.

836 *

837 * @param value The given first day of the week.

838 * @stable ICU 2.6.

839 */

840 void setFirstDayOfWeek(UCalendarDaysOfWeek value);

841

842 /**

843 * Gets what the first day of the week is; e.g., Sunday in US, Monday in Fra nce.

844 *

845 * @return The first day of the week.

846 * @deprecated ICU 2.6 use the overload with error code

847 */

848 EDaysOfWeek getFirstDayOfWeek(void) const;

849

850 /**

851 * Gets what the first day of the week is; e.g., Sunday in US, Monday in Fra nce.

852 *

853 * @param status error code

854 * @return The first day of the week.

855 * @stable ICU 2.6

856 */

857 UCalendarDaysOfWeek getFirstDayOfWeek(UErrorCode &status) const;

858

859 /**

860 * Sets what the minimal days required in the first week of the year are; Fo r

861 * example, if the first week is defined as one that contains the first day of the

862 * first month of a year, call the method with value 1. If it must be a full week,

863 * use value 7.

864 *

865 * @param value The given minimal days required in the first week of the ye ar.

866 * @stable ICU 2.0

867 */

868 void setMinimalDaysInFirstWeek(uint8_t value);

869

870 /**

871 * Gets what the minimal days required in the first week of the year are; e. g., if

872 * the first week is defined as one that contains the first day of the first month

873 * of a year, getMinimalDaysInFirstWeek returns 1. If the minimal days requi red must

874 * be a full week, getMinimalDaysInFirstWeek returns 7.

875 *

876 * @return The minimal days required in the first week of the year.

877 * @stable ICU 2.0

878 */

879 uint8_t getMinimalDaysInFirstWeek(void) const;

880

881 /**

882 * Gets the minimum value for the given time field. e.g., for Gregorian

883 * DAY_OF_MONTH, 1.

884 *

885 * @param field The given time field.

886 * @return The minimum value for the given time field.

887 * @deprecated ICU 2.6. Use getMinimum(UCalendarDateFields field) instead.

888 */

889 virtual int32_t getMinimum(EDateFields field) const;

890

891 /**

892 * Gets the minimum value for the given time field. e.g., for Gregorian

893 * DAY_OF_MONTH, 1.

894 *

895 * @param field The given time field.

896 * @return The minimum value for the given time field.

897 * @stable ICU 2.6.

898 */

899 virtual int32_t getMinimum(UCalendarDateFields field) const;

900

901 /**

902 * Gets the maximum value for the given time field. e.g. for Gregorian DAY_O F_MONTH,

903 * 31.

904 *

905 * @param field The given time field.

906 * @return The maximum value for the given time field.

907 * @deprecated ICU 2.6. Use getMaximum(UCalendarDateFields field) instead.

908 */

909 virtual int32_t getMaximum(EDateFields field) const;

910

911 /**

912 * Gets the maximum value for the given time field. e.g. for Gregorian DAY_O F_MONTH,

913 * 31.

914 *

915 * @param field The given time field.

916 * @return The maximum value for the given time field.

917 * @stable ICU 2.6.

918 */

919 virtual int32_t getMaximum(UCalendarDateFields field) const;

920

921 /**

922 * Gets the highest minimum value for the given field if varies. Otherwise s ame as

923 * getMinimum(). For Gregorian, no difference.

924 *

925 * @param field The given time field.

926 * @return The highest minimum value for the given time field.

927 * @deprecated ICU 2.6. Use getGreatestMinimum(UCalendarDateFields field) in stead.

928 */

929 virtual int32_t getGreatestMinimum(EDateFields field) const;

930

931 /**

932 * Gets the highest minimum value for the given field if varies. Otherwise s ame as

933 * getMinimum(). For Gregorian, no difference.

934 *

935 * @param field The given time field.

936 * @return The highest minimum value for the given time field.

937 * @stable ICU 2.6.

938 */

939 virtual int32_t getGreatestMinimum(UCalendarDateFields field) const;

940

941 /**

942 * Gets the lowest maximum value for the given field if varies. Otherwise sa me as

943 * getMaximum(). e.g., for Gregorian DAY_OF_MONTH, 28.

944 *

945 * @param field The given time field.

946 * @return The lowest maximum value for the given time field.

947 * @deprecated ICU 2.6. Use getLeastMaximum(UCalendarDateFields field) inste ad.

948 */

949 virtual int32_t getLeastMaximum(EDateFields field) const;

950

951 /**

952 * Gets the lowest maximum value for the given field if varies. Otherwise sa me as

953 * getMaximum(). e.g., for Gregorian DAY_OF_MONTH, 28.

954 *

955 * @param field The given time field.

956 * @return The lowest maximum value for the given time field.

957 * @stable ICU 2.6.

958 */

959 virtual int32_t getLeastMaximum(UCalendarDateFields field) const;

960

961 /**

962 * Return the minimum value that this field could have, given the current da te.

963 * For the Gregorian calendar, this is the same as getMinimum() and getGreat estMinimum().

964 *

965 * The version of this function on Calendar uses an iterative algorithm to d etermine the

966 * actual minimum value for the field. There is almost always a more effici ent way to

967 * accomplish this (in most cases, you can simply return getMinimum()). Gre gorianCalendar

968 * overrides this function with a more efficient implementation.

969 *

970 * @param field the field to determine the minimum of

971 * @param status Fill-in parameter which receives the status of this opera tion.

972 * @return the minimum of the given field for the current date of th is Calendar

973 * @deprecated ICU 2.6. Use getActualMinimum(UCalendarDateFields field, UErr orCode& status) instead.

974 */

975 int32_t getActualMinimum(EDateFields field, UErrorCode& status) const;

976

977 /**

978 * Return the minimum value that this field could have, given the current da te.

979 * For the Gregorian calendar, this is the same as getMinimum() and getGreat estMinimum().

980 *

981 * The version of this function on Calendar uses an iterative algorithm to d etermine the

982 * actual minimum value for the field. There is almost always a more effici ent way to

983 * accomplish this (in most cases, you can simply return getMinimum()). Gre gorianCalendar

984 * overrides this function with a more efficient implementation.

985 *

986 * @param field the field to determine the minimum of

987 * @param status Fill-in parameter which receives the status of this opera tion.

988 * @return the minimum of the given field for the current date of th is Calendar

989 * @stable ICU 2.6.

990 */

991 virtual int32_t getActualMinimum(UCalendarDateFields field, UErrorCode& stat us) const;

992

993 /**

994 * Return the maximum value that this field could have, given the current da te.

995 * For example, with the date "Feb 3, 1997" and the DAY_OF_MONTH field, the actual

996 * maximum would be 28; for "Feb 3, 1996" it s 29. Similarly for a Hebrew c alendar,

997 * for some years the actual maximum for MONTH is 12, and for others 13.

998 *

999 * The version of this function on Calendar uses an iterative algorithm to d etermine the

1000 * actual maximum value for the field. There is almost always a more effici ent way to

1001 * accomplish this (in most cases, you can simply return getMaximum()). Gre gorianCalendar

1002 * overrides this function with a more efficient implementation.

1003 *

1004 * @param field the field to determine the maximum of

1005 * @param status Fill-in parameter which receives the status of this opera tion.

1006 * @return the maximum of the given field for the current date of th is Calendar

1007 * @deprecated ICU 2.6. Use getActualMaximum(UCalendarDateFields field, UErr orCode& status) instead.

1008 */

1009 int32_t getActualMaximum(EDateFields field, UErrorCode& status) const;

1010

1011 /**

1012 * Return the maximum value that this field could have, given the current da te.

1013 * For example, with the date "Feb 3, 1997" and the DAY_OF_MONTH field, the actual

1014 * maximum would be 28; for "Feb 3, 1996" it s 29. Similarly for a Hebrew c alendar,

1015 * for some years the actual maximum for MONTH is 12, and for others 13.

1016 *

1017 * The version of this function on Calendar uses an iterative algorithm to d etermine the

1018 * actual maximum value for the field. There is almost always a more effici ent way to

1019 * accomplish this (in most cases, you can simply return getMaximum()). Gre gorianCalendar

1020 * overrides this function with a more efficient implementation.

1021 *

1022 * @param field the field to determine the maximum of

1023 * @param status Fill-in parameter which receives the status of this opera tion.

1024 * @return the maximum of the given field for the current date of th is Calendar

1025 * @stable ICU 2.6.

1026 */

1027 virtual int32_t getActualMaximum(UCalendarDateFields field, UErrorCode& stat us) const;

1028

1029 /**

1030 * Gets the value for a given time field. Recalculate the current time field values

1031 * if the time value has been changed by a call to setTime(). Return zero fo r unset

1032 * fields if any fields have been explicitly set by a call to set(). To forc e a

1033 * recomputation of all fields regardless of the previous state, call comple te().

1034 * This method is semantically const, but may alter the object in memory.

1035 *

1036 * @param field The given time field.

1037 * @param status Fill-in parameter which receives the status of the operatio n.

1038 * @return The value for the given time field, or zero if the field is unset,

1039 * and set() has been called for any other field.

1040 * @deprecated ICU 2.6. Use get(UCalendarDateFields field, UErrorCode& statu s) instead.

1041 */

1042 int32_t get(EDateFields field, UErrorCode& status) const;

1043

1044 /**

1045 * Gets the value for a given time field. Recalculate the current time field values

1046 * if the time value has been changed by a call to setTime(). Return zero fo r unset

1047 * fields if any fields have been explicitly set by a call to set(). To forc e a

1048 * recomputation of all fields regardless of the previous state, call comple te().

1049 * This method is semantically const, but may alter the object in memory.

1050 *

1051 * @param field The given time field.

1052 * @param status Fill-in parameter which receives the status of the operatio n.

1053 * @return The value for the given time field, or zero if the field is unset,

1054 * and set() has been called for any other field.

1055 * @stable ICU 2.6.

1056 */

1057 int32_t get(UCalendarDateFields field, UErrorCode& status) const;

1058

1059 /**

1060 * Determines if the given time field has a value set. This can affect in th e

1061 * resolving of time in Calendar. Unset fields have a value of zero, by defi nition.

1062 *

1063 * @param field The given time field.

1064 * @return True if the given time field has a value set; false otherwise.

1065 * @deprecated ICU 2.6. Use isSet(UCalendarDateFields field) instead.

1066 */

1067 UBool isSet(EDateFields field) const;

1068

1069 /**

1070 * Determines if the given time field has a value set. This can affect in th e

1071 * resolving of time in Calendar. Unset fields have a value of zero, by defi nition.

1072 *

1073 * @param field The given time field.

1074 * @return True if the given time field has a value set; false otherwise.

1075 * @stable ICU 2.6.

1076 */

1077 UBool isSet(UCalendarDateFields field) const;

1078

1079 /**

1080 * Sets the given time field with the given value.

1081 *

1082 * @param field The given time field.

1083 * @param value The value to be set for the given time field.

1084 * @deprecated ICU 2.6. Use set(UCalendarDateFields field, int32_t value) in stead.

1085 */

1086 void set(EDateFields field, int32_t value);

1087

1088 /**

1089 * Sets the given time field with the given value.

1090 *

1091 * @param field The given time field.

1092 * @param value The value to be set for the given time field.

1093 * @stable ICU 2.6.

1094 */

1095 void set(UCalendarDateFields field, int32_t value);

1096

1097 /**

1098 * Sets the values for the fields YEAR, MONTH, and DATE. Other field values are

1099 * retained; call clear() first if this is not desired.

1100 *

1101 * @param year The value used to set the YEAR time field.

1102 * @param month The value used to set the MONTH time field. Month value is 0-based.

1103 * e.g., 0 for January.

1104 * @param date The value used to set the DATE time field.

1105 * @stable ICU 2.0

1106 */

1107 void set(int32_t year, int32_t month, int32_t date);

1108

1109 /**

1110 * Sets the values for the fields YEAR, MONTH, DATE, HOUR_OF_DAY, and MINUTE . Other

1111 * field values are retained; call clear() first if this is not desired.

1112 *

1113 * @param year The value used to set the YEAR time field.

1114 * @param month The value used to set the MONTH time field. Month value is

1115 * 0-based. E.g., 0 for January.

1116 * @param date The value used to set the DATE time field.

1117 * @param hour The value used to set the HOUR_OF_DAY time field.

1118 * @param minute The value used to set the MINUTE time field.

1119 * @stable ICU 2.0

1120 */

1121 void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t mi nute);

1122

1123 /**

1124 * Sets the values for the fields YEAR, MONTH, DATE, HOUR_OF_DAY, MINUTE, an d SECOND.

1125 * Other field values are retained; call clear() first if this is not desire d.

1126 *

1127 * @param year The value used to set the YEAR time field.

1128 * @param month The value used to set the MONTH time field. Month value is

1129 * 0-based. E.g., 0 for January.

1130 * @param date The value used to set the DATE time field.

1131 * @param hour The value used to set the HOUR_OF_DAY time field.

1132 * @param minute The value used to set the MINUTE time field.

1133 * @param second The value used to set the SECOND time field.

1134 * @stable ICU 2.0

1135 */

1136 void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t mi nute, int32_t second);

1137

1138 /**

1139 * Clears the values of all the time fields, making them both unset and assi gning

1140 * them a value of zero. The field values will be determined during the next

1141 * resolving of time into time fields.

1142 * @stable ICU 2.0

1143 */

1144 void clear(void);

1145

1146 /**

1147 * Clears the value in the given time field, both making it unset and assign ing it a

1148 * value of zero. This field value will be determined during the next resolv ing of

1149 * time into time fields.

1150 *

1151 * @param field The time field to be cleared.

1152 * @deprecated ICU 2.6. Use clear(UCalendarDateFields field) instead.

1153 */

1154 void clear(EDateFields field);

1155

1156 /**

1157 * Clears the value in the given time field, both making it unset and assign ing it a

1158 * value of zero. This field value will be determined during the next resolv ing of

1159 * time into time fields.

1160 *

1161 * @param field The time field to be cleared.

1162 * @stable ICU 2.6.

1163 */

1164 void clear(UCalendarDateFields field);

1165

1166 /**

1167 * Returns a unique class ID POLYMORPHICALLY. Pure virtual method. This meth od is to

1168 * implement a simple version of RTTI, since not all C++ compilers support g enuine

1169 * RTTI. Polymorphic operator==() and clone() methods call this method.

1170 * <P>

1171 * Concrete subclasses of Calendar must implement getDynamicClassID() and al so a

1172 * static method and data member:

1173 *

1174 * static UClassID getStaticClassID() { return (UClassID)&fgClassID ; }

1175 * static char fgClassID;

1176 *

1177 * @return The class ID for this object. All objects of a given class have the

1178 * same class ID. Objects of other classes have different class ID s.

1179 * @stable ICU 2.0

1180 */

1181 virtual UClassID getDynamicClassID(void) const = 0;

1182

1183 /**

1184 * Returns the resource key string used for this calendar type.

1185 * For example, prepending "Eras_" to this string could return "Eras_japanes e"

1186 * or "Eras_gregorian".

1187 *

1188 * @returns static string, for example, "gregorian" or "japanese"

1189 * @internal

1190 */

1191 virtual const char * getType() const = 0;

1192

1193 /**

1194 * Returns whether the given day of the week is a weekday, a

1195 * weekend day, or a day that transitions from one to the other,

1196 * in this calendar system. If a transition occurs at midnight,

1197 * then the days before and after the transition will have the

1198 * type UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time

1199 * other than midnight, then the day of the transition will have

1200 * the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the

1201 * method getWeekendTransition() will return the point of

1202 * transition.

1203 * @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY.. UCAL_SATURDAY).

1204 * @param status The error code for the operation.

1205 * @return The UCalendarWeekdayType for the day of the week.

1206 * @stable ICU 4.4

1207 */

1208 virtual UCalendarWeekdayType getDayOfWeekType(UCalendarDaysOfWeek dayOfWeek, UErrorCode &status) const;

1209

1210 /**

1211 * Returns the time during the day at which the weekend begins or ends in

1212 * this calendar system. If getDayOfWeekType() rerturns UCAL_WEEKEND_ONSET

1213 * for the specified dayOfWeek, return the time at which the weekend begins.

1214 * If getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfW eek,

1215 * return the time at which the weekend ends. If getDayOfWeekType() returns

1216 * some other UCalendarWeekdayType for the specified dayOfWeek, is it an err or condition

1217 * (U_ILLEGAL_ARGUMENT_ERROR).

1218 * @param dayOfWeek The day of the week for which the weekend transition tim e is

1219 * desired (UCAL_SUNDAY..UCAL_SATURDAY).

1220 * @param status The error code for the operation.

1221 * @return The milliseconds after midnight at which the weekend begins or en ds.

1222 * @stable ICU 4.4

1223 */

1224 virtual int32_t getWeekendTransition(UCalendarDaysOfWeek dayOfWeek, UErrorCo de &status) const;

1225

1226 /**

1227 * Returns TRUE if the given UDate is in the weekend in

1228 * this calendar system.

1229 * @param date The UDate in question.

1230 * @param status The error code for the operation.

1231 * @return TRUE if the given UDate is in the weekend in

1232 * this calendar system, FALSE otherwise.

1233 * @stable ICU 4.4

1234 */

1235 virtual UBool isWeekend(UDate date, UErrorCode &status) const;

1236

1237 /**

1238 * Returns TRUE if this Calendar's current date-time is in the weekend in

1239 * this calendar system.

1240 * @return TRUE if this Calendar's current date-time is in the weekend in

1241 * this calendar system, FALSE otherwise.

1242 * @stable ICU 4.4

1243 */

1244 virtual UBool isWeekend(void) const;

1245

1246 protected:

1247

1248 /**

1249 * Constructs a Calendar with the default time zone as returned by

1250 * TimeZone::createInstance(), and the default locale.

1251 *

1252 * @param success Indicates the status of Calendar object construction. Re turns

1253 * U_ZERO_ERROR if constructed successfully.

1254 * @stable ICU 2.0

1255 */

1256 Calendar(UErrorCode& success);

1257

1258 /**

1259 * Copy constructor

1260 *

1261 * @param source Calendar object to be copied from

1262 * @stable ICU 2.0

1263 */

1264 Calendar(const Calendar& source);

1265

1266 /**

1267 * Default assignment operator

1268 *

1269 * @param right Calendar object to be copied

1270 * @stable ICU 2.0

1271 */

1272 Calendar& operator=(const Calendar& right);

1273

1274 /**

1275 * Constructs a Calendar with the given time zone and locale. Clients are no longer

1276 * responsible for deleting the given time zone object after it's adopted.

1277 *

1278 * @param zone The given time zone.

1279 * @param aLocale The given locale.

1280 * @param success Indicates the status of Calendar object construction. Ret urns

1281 * U_ZERO_ERROR if constructed successfully.

1282 * @stable ICU 2.0

1283 */

1284 Calendar(TimeZone* zone, const Locale& aLocale, UErrorCode& success);

1285

1286 /**

1287 * Constructs a Calendar with the given time zone and locale.

1288 *

1289 * @param zone The given time zone.

1290 * @param aLocale The given locale.

1291 * @param success Indicates the status of Calendar object construction. Ret urns

1292 * U_ZERO_ERROR if constructed successfully.

1293 * @stable ICU 2.0

1294 */

1295 Calendar(const TimeZone& zone, const Locale& aLocale, UErrorCode& success);

1296

1297 /**

1298 * Converts Calendar's time field values to GMT as milliseconds.

1299 *

1300 * @param status Output param set to success/failure code on exit. If any v alue

1301 * previously set in the time field is invalid or restricted by

1302 * leniency, this will be set to an error status.

1303 * @stable ICU 2.0

1304 */

1305 virtual void computeTime(UErrorCode& status);

1306

1307 /**

1308 * Converts GMT as milliseconds to time field values. This allows you to syn c up the

1309 * time field values with a new time that is set for the calendar. This met hod

1310 * does NOT recompute the time first; to recompute the time, then the fields , use

1311 * the method complete().

1312 *

1313 * @param status Output param set to success/failure code on exit. If any v alue

1314 * previously set in the time field is invalid or restricted by

1315 * leniency, this will be set to an error status.

1316 * @stable ICU 2.0

1317 */

1318 virtual void computeFields(UErrorCode& status);

1319

1320 /**

1321 * Gets this Calendar's current time as a long.

1322 *

1323 * @param status Output param set to success/failure code on exit. If any v alue

1324 * previously set in the time field is invalid or restricted by

1325 * leniency, this will be set to an error status.

1326 * @return the current time as UTC milliseconds from the epoch.

1327 * @stable ICU 2.0

1328 */

1329 double getTimeInMillis(UErrorCode& status) const;

1330

1331 /**

1332 * Sets this Calendar's current time from the given long value.

1333 * @param millis the new time in UTC milliseconds from the epoch.

1334 * @param status Output param set to success/failure code on exit. If any v alue

1335 * previously set in the time field is invalid or restricted by

1336 * leniency, this will be set to an error status.

1337 * @stable ICU 2.0

1338 */

1339 void setTimeInMillis( double millis, UErrorCode& status );

1340

1341 /**

1342 * Recomputes the current time from currently set fields, and then fills in any

1343 * unset fields in the time field list.

1344 *

1345 * @param status Output param set to success/failure code on exit. If any v alue

1346 * previously set in the time field is invalid or restricted by

1347 * leniency, this will be set to an error status.

1348 * @stable ICU 2.0

1349 */

1350 void complete(UErrorCode& status);

1351

1352 /**

1353 * Gets the value for a given time field. Subclasses can use this function t o get

1354 * field values without forcing recomputation of time.

1355 *

1356 * @param field The given time field.

1357 * @return The value for the given time field.

1358 * @deprecated ICU 2.6. Use internalGet(UCalendarDateFields field) instead.

1359 */

1360 inline int32_t internalGet(EDateFields field) const {return fFields[field];}

1361

1362 /**

1363 * Gets the value for a given time field. Subclasses can use this function t o get

1364 * field values without forcing recomputation of time. If the field's stamp is UNSET,

1365 * the defaultValue is used.

1366 *

1367 * @param field The given time field.

1368 * @param defaultValue a default value used if the field is unset.

1369 * @return The value for the given time field.

1370 * @internal

1371 */

1372 inline int32_t internalGet(UCalendarDateFields field, int32_t defaultValue) const {return fStamp[field]>kUnset ? fFields[field] : defaultValue;}

1373

1374 /**

1375 * Gets the value for a given time field. Subclasses can use this function t o get

1376 * field values without forcing recomputation of time.

1377 *

1378 * @param field The given time field.

1379 * @return The value for the given time field.

1380 * @internal

1381 */

1382 inline int32_t internalGet(UCalendarDateFields field) const {return fFields[ field];}

1383

1384 /**

1385 * Sets the value for a given time field. This is a fast internal method fo r

1386 * subclasses. It does not affect the areFieldsInSync, isTimeSet, or areAll FieldsSet

1387 * flags.

1388 *

1389 * @param field The given time field.

1390 * @param value The value for the given time field.

1391 * @deprecated ICU 2.6. Use internalSet(UCalendarDateFields field, int32_t v alue) instead.

1392 */

1393 void internalSet(EDateFields field, int32_t value);

1394

1395 /**

1396 * Sets the value for a given time field. This is a fast internal method fo r

1397 * subclasses. It does not affect the areFieldsInSync, isTimeSet, or areAll FieldsSet

1398 * flags.

1399 *

1400 * @param field The given time field.

1401 * @param value The value for the given time field.

1402 * @stable ICU 2.6.

1403 */

1404 inline void internalSet(UCalendarDateFields field, int32_t value);

1405

1406 /**

1407 * Prepare this calendar for computing the actual minimum or maximum.

1408 * This method modifies this calendar's fields; it is called on a

1409 * temporary calendar.

1410 * @internal

1411 */

1412 virtual void prepareGetActual(UCalendarDateFields field, UBool isMinimum, UE rrorCode &status);

1413

1414 /**

1415 * Limit enums. Not in sync with UCalendarLimitType (refers to internal fiel ds).

1416 * @internal

1417 */

1418 enum ELimitType {

1419 UCAL_LIMIT_MINIMUM = 0,

1420 UCAL_LIMIT_GREATEST_MINIMUM,

1421 UCAL_LIMIT_LEAST_MAXIMUM,

1422 UCAL_LIMIT_MAXIMUM,

1423 UCAL_LIMIT_COUNT

1424 };

1425

1426 /**

1427 * Subclass API for defining limits of different types.

1428 * Subclasses must implement this method to return limits for the

1429 * following fields:

1430 *

1431 * <pre>UCAL_ERA

1432 * UCAL_YEAR

1433 * UCAL_MONTH

1434 * UCAL_WEEK_OF_YEAR

1435 * UCAL_WEEK_OF_MONTH

1436 * UCAL_DATE (DAY_OF_MONTH on Java)

1437 * UCAL_DAY_OF_YEAR

1438 * UCAL_DAY_OF_WEEK_IN_MONTH

1439 * UCAL_YEAR_WOY

1440 * UCAL_EXTENDED_YEAR</pre>

1441 *

1442 * @param field one of the above field numbers

1443 * @param limitType one of <code>MINIMUM</code>, <code>GREATEST_MINIMUM</cod e>,

1444 * <code>LEAST_MAXIMUM</code>, or <code>MAXIMUM</code>

1445 * @internal

1446 */

1447 virtual int32_t handleGetLimit(UCalendarDateFields field, ELimitType limitTy pe) const = 0;

1448

1449 /**

1450 * Return a limit for a field.

1451 * @param field the field, from <code>0..UCAL_MAX_FIELD</code>

1452 * @param limitType the type specifier for the limit

1453 * @see #ELimitType

1454 * @internal

1455 */

1456 virtual int32_t getLimit(UCalendarDateFields field, ELimitType limitType) co nst;

1457

1458

1459 /**

1460 * Return the Julian day number of day before the first day of the

1461 * given month in the given extended year. Subclasses should override

1462 * this method to implement their calendar system.

1463 * @param eyear the extended year

1464 * @param month the zero-based month, or 0 if useMonth is false

1465 * @param useMonth if false, compute the day before the first day of

1466 * the given year, otherwise, compute the day before the first day of

1467 * the given month

1468 * @return the Julian day number of the day before the first

1469 * day of the given month and year

1470 * @internal

1471 */

1472 virtual int32_t handleComputeMonthStart(int32_t eyear, int32_t month,

1473 UBool useMonth) const = 0;

1474

1475 /**

1476 * Return the number of days in the given month of the given extended

1477 * year of this calendar system. Subclasses should override this

1478 * method if they can provide a more correct or more efficient

1479 * implementation than the default implementation in Calendar.

1480 * @internal

1481 */

1482 virtual int32_t handleGetMonthLength(int32_t extendedYear, int32_t month) co nst ;

1483

1484 /**

1485 * Return the number of days in the given extended year of this

1486 * calendar system. Subclasses should override this method if they can

1487 * provide a more correct or more efficient implementation than the

1488 * default implementation in Calendar.

1489 * @stable ICU 2.0

1490 */

1491 virtual int32_t handleGetYearLength(int32_t eyear) const;

1492

1493

1494 /**

1495 * Return the extended year defined by the current fields. This will

1496 * use the UCAL_EXTENDED_YEAR field or the UCAL_YEAR and supra-year fields ( such

1497 * as UCAL_ERA) specific to the calendar system, depending on which set of

1498 * fields is newer.

1499 * @return the extended year

1500 * @internal

1501 */

1502 virtual int32_t handleGetExtendedYear() = 0;

1503

1504 /**

1505 * Subclasses may override this. This method calls

1506 * handleGetMonthLength() to obtain the calendar-specific month

1507 * length.

1508 * @param bestField which field to use to calculate the date

1509 * @return julian day specified by calendar fields.

1510 * @internal

1511 */

1512 virtual int32_t handleComputeJulianDay(UCalendarDateFields bestField);

1513

1514 /**

1515 * Subclasses must override this to convert from week fields

1516 * (YEAR_WOY and WEEK_OF_YEAR) to an extended year in the case

1517 * where YEAR, EXTENDED_YEAR are not set.

1518 * The Calendar implementation assumes yearWoy is in extended gregorian form

1519 * @internal

1520 * @return the extended year, UCAL_EXTENDED_YEAR

1521 */

1522 virtual int32_t handleGetExtendedYearFromWeekFields(int32_t yearWoy, int32_t woy);

1523

1524 /**

1525 * Compute the Julian day from fields. Will determine whether to use

1526 * the JULIAN_DAY field directly, or other fields.

1527 * @return the julian day

1528 * @internal

1529 */

1530 int32_t computeJulianDay();

1531

1532 /**

1533 * Compute the milliseconds in the day from the fields. This is a

1534 * value from 0 to 23:59:59.999 inclusive, unless fields are out of

1535 * range, in which case it can be an arbitrary value. This value

1536 * reflects local zone wall time.

1537 * @internal

1538 */

1539 int32_t computeMillisInDay();

1540

1541 /**

1542 * This method can assume EXTENDED_YEAR has been set.

1543 * @param millis milliseconds of the date fields

1544 * @param millisInDay milliseconds of the time fields; may be out

1545 * or range.

1546 * @param ec Output param set to failure code on function return

1547 * when this function fails.

1548 * @internal

1549 */

1550 int32_t computeZoneOffset(double millis, int32_t millisInDay, UErrorCode &ec );

1551

1552

1553 /**

1554 * Determine the best stamp in a range.

1555 * @param start first enum to look at

1556 * @param end last enum to look at

1557 * @param bestSoFar stamp prior to function call

1558 * @return the stamp value of the best stamp

1559 * @internal

1560 */

1561 int32_t newestStamp(UCalendarDateFields start, UCalendarDateFields end, int3 2_t bestSoFar) const;

1562

1563 /**

1564 * Values for field resolution tables

1565 * @see #resolveFields

1566 * @internal

1567 */

1568 enum {

1569 /** Marker for end of resolve set (row or group). */

1570 kResolveSTOP = -1,

1571 /** Value to be bitwised "ORed" against resolve table field values for rem apping. Example: (UCAL_DATE \| kResolveRemap) in 1st column will cause 'UCAL_DAT E' to be returned, but will not examine the value of UCAL_DATE. */

1572 kResolveRemap = 32

1573 };

1574

1575 /**

1576 * Precedence table for Dates

1577 * @see #resolveFields

1578 * @internal

1579 */

1580 static const UFieldResolutionTable kDatePrecedence[];

1581

1582 /**

1583 * Precedence table for Year

1584 * @see #resolveFields

1585 * @internal

1586 */

1587 static const UFieldResolutionTable kYearPrecedence[];

1588

1589 /**

1590 * Precedence table for Day of Week

1591 * @see #resolveFields

1592 * @internal

1593 */

1594 static const UFieldResolutionTable kDOWPrecedence[];

1595

1596 /**

1597 * Given a precedence table, return the newest field combination in

1598 * the table, or UCAL_FIELD_COUNT if none is found.

1599 *

1600 * <p>The precedence table is a 3-dimensional array of integers. It

1601 * may be thought of as an array of groups. Each group is an array of

1602 * lines. Each line is an array of field numbers. Within a line, if

1603 * all fields are set, then the time stamp of the line is taken to be

1604 * the stamp of the most recently set field. If any field of a line is

1605 * unset, then the line fails to match. Within a group, the line with

1606 * the newest time stamp is selected. The first field of the line is

1607 * returned to indicate which line matched.

1608 *

1609 * <p>In some cases, it may be desirable to map a line to field that

1610 * whose stamp is NOT examined. For example, if the best field is

1611 * DAY_OF_WEEK then the DAY_OF_WEEK_IN_MONTH algorithm may be used. In

1612 * order to do this, insert the value <code>kResolveRemap \| F</code> at

1613 * the start of the line, where <code>F</code> is the desired return

1614 * field value. This field will NOT be examined; it only determines

1615 * the return value if the other fields in the line are the newest.

1616 *

1617 * <p>If all lines of a group contain at least one unset field, then no

1618 * line will match, and the group as a whole will fail to match. In

1619 * that case, the next group will be processed. If all groups fail to

1620 * match, then UCAL_FIELD_COUNT is returned.

1621 * @internal

1622 */

1623 UCalendarDateFields resolveFields(const UFieldResolutionTable *precedenceTab le);

1624

1625

1626 /**

1627 * @internal

1628 */

1629 virtual const UFieldResolutionTable* getFieldResolutionTable() const;

1630

1631 /**

1632 * Return the field that is newer, either defaultField, or

1633 * alternateField. If neither is newer or neither is set, return defaultFie ld.

1634 * @internal

1635 */

1636 UCalendarDateFields newerField(UCalendarDateFields defaultField, UCalendarDa teFields alternateField) const;

1637

1638

1639 private:

1640 /**

1641 * Helper function for calculating limits by trial and error

1642 * @param field The field being investigated

1643 * @param startValue starting (least max) value of field

1644 * @param endValue ending (greatest max) value of field

1645 * @param status return type

1646 * @internal

1647 */

1648 int32_t getActualHelper(UCalendarDateFields field, int32_t startValue, int32 _t endValue, UErrorCode &status) const;

1649

1650

1651 protected:

1652 /**

1653 * The flag which indicates if the current time is set in the calendar.

1654 * @stable ICU 2.0

1655 */

1656 UBool fIsTimeSet;

1657

1658 /**

1659 * True if the fields are in sync with the currently set time of this Calend ar.

1660 * If false, then the next attempt to get the value of a field will

1661 * force a recomputation of all fields from the current value of the time

1662 * field.

1663 * <P>

1664 * This should really be named areFieldsInSync, but the old name is retained

1665 * for backward compatibility.

1666 * @stable ICU 2.0

1667 */

1668 UBool fAreFieldsSet;

1669

1670 /**

1671 * True if all of the fields have been set. This is initially false, and se t to

1672 * true by computeFields().

1673 * @stable ICU 2.0

1674 */

1675 UBool fAreAllFieldsSet;

1676

1677 /**

1678 * True if all fields have been virtually set, but have not yet been

1679 * computed. This occurs only in setTimeInMillis(). A calendar set

1680 * to this state will compute all fields from the time if it becomes

1681 * necessary, but otherwise will delay such computation.

1682 * @stable ICU 3.0

1683 */

1684 UBool fAreFieldsVirtuallySet;

1685

1686 /**

1687 * Get the current time without recomputing.

1688 *

1689 * @return the current time without recomputing.

1690 * @stable ICU 2.0

1691 */

1692 UDate internalGetTime(void) const { return fTime; }

1693

1694 /**

1695 * Set the current time without affecting flags or fields.

1696 *

1697 * @param time The time to be set

1698 * @return the current time without recomputing.

1699 * @stable ICU 2.0

1700 */

1701 void internalSetTime(UDate time) { fTime = time; }

1702

1703 /**

1704 * The time fields containing values into which the millis is computed.

1705 * @stable ICU 2.0

1706 */

1707 int32_t fFields[UCAL_FIELD_COUNT];

1708

1709 /**

1710 * The flags which tell if a specified time field for the calendar is set.

1711 * @deprecated ICU 2.8 use (fStamp[n]!=kUnset)

1712 */

1713 UBool fIsSet[UCAL_FIELD_COUNT];

1714

1715 /** Special values of stamp[]

1716 * @stable ICU 2.0

1717 */

1718 enum {

1719 kUnset = 0,

1720 kInternallySet,

1721 kMinimumUserStamp

1722 };

1723

1724 /**

1725 * Pseudo-time-stamps which specify when each field was set. There

1726 * are two special values, UNSET and INTERNALLY_SET. Values from

1727 * MINIMUM_USER_SET to Integer.MAX_VALUE are legal user set values.

1728 * @stable ICU 2.0

1729 */

1730 int32_t fStamp[UCAL_FIELD_COUNT];

1731

1732 /**

1733 * Subclasses may override this method to compute several fields

1734 * specific to each calendar system. These are:

1735 *

1736 * <ul><li>ERA

1737 * <li>YEAR

1738 * <li>MONTH

1739 * <li>DAY_OF_MONTH

1740 * <li>DAY_OF_YEAR

1741 * <li>EXTENDED_YEAR</ul>

1742 *

1743 * Subclasses can refer to the DAY_OF_WEEK and DOW_LOCAL fields, which

1744 * will be set when this method is called. Subclasses can also call

1745 * the getGregorianXxx() methods to obtain Gregorian calendar

1746 * equivalents for the given Julian day.

1747 *

1748 * <p>In addition, subclasses should compute any subclass-specific

1749 * fields, that is, fields from BASE_FIELD_COUNT to

1750 * getFieldCount() - 1.

1751 *

1752 * <p>The default implementation in <code>Calendar</code> implements

1753 * a pure proleptic Gregorian calendar.

1754 * @internal

1755 */

1756 virtual void handleComputeFields(int32_t julianDay, UErrorCode &status);

1757

1758 /**

1759 * Return the extended year on the Gregorian calendar as computed by

1760 * <code>computeGregorianFields()</code>.

1761 * @internal

1762 */

1763 int32_t getGregorianYear() const {

1764 return fGregorianYear;

1765 }

1766

1767 /**

1768 * Return the month (0-based) on the Gregorian calendar as computed by

1769 * <code>computeGregorianFields()</code>.

1770 * @internal

1771 */

1772 int32_t getGregorianMonth() const {

1773 return fGregorianMonth;

1774 }

1775

1776 /**

1777 * Return the day of year (1-based) on the Gregorian calendar as

1778 * computed by <code>computeGregorianFields()</code>.

1779 * @internal

1780 */

1781 int32_t getGregorianDayOfYear() const {

1782 return fGregorianDayOfYear;

1783 }

1784

1785 /**

1786 * Return the day of month (1-based) on the Gregorian calendar as

1787 * computed by <code>computeGregorianFields()</code>.

1788 * @internal

1789 */

1790 int32_t getGregorianDayOfMonth() const {

1791 return fGregorianDayOfMonth;

1792 }

1793

1794 /**

1795 * Called by computeJulianDay. Returns the default month (0-based) for the year,

1796 * taking year and era into account. Defaults to 0 for Gregorian, which doe sn't care.

1797 * @param eyear The extended year

1798 * @internal

1799 */

1800 virtual int32_t getDefaultMonthInYear(int32_t eyear) ;

1801

1802

1803 /**

1804 * Called by computeJulianDay. Returns the default day (1-based) for the mo nth,

1805 * taking currently-set year and era into account. Defaults to 1 for Gregor ian.

1806 * @param eyear the extended year

1807 * @param month the month in the year

1808 * @internal

1809 */

1810 virtual int32_t getDefaultDayInMonth(int32_t eyear, int32_t month);

1811

1812 //-------------------------------------------------------------------------

1813 // Protected utility methods for use by subclasses. These are very handy

1814 // for implementing add, roll, and computeFields.

1815 //-------------------------------------------------------------------------

1816

1817 /**

1818 * Adjust the specified field so that it is within

1819 * the allowable range for the date to which this calendar is set.

1820 * For example, in a Gregorian calendar pinning the {@link #UCalendarDateFie lds DAY_OF_MONTH}

1821 * field for a calendar set to April 31 would cause it to be set

1822 * to April 30.

1823 * <p>

1824 * <b>Subclassing:</b>

1825 * <br>

1826 * This utility method is intended for use by subclasses that need to implem ent

1827 * their own overrides of {@link #roll roll} and {@link #add add}.

1828 * <p>

1829 * <b>Note:</b>

1830 * <code>pinField</code> is implemented in terms of

1831 * {@link #getActualMinimum getActualMinimum}

1832 * and {@link #getActualMaximum getActualMaximum}. If either of those metho ds uses

1833 * a slow, iterative algorithm for a particular field, it would be

1834 * unwise to attempt to call <code>pinField</code> for that field. If you

1835 * really do need to do so, you should override this method to do

1836 * something more efficient for that field.

1837 * <p>

1838 * @param field The calendar field whose value should be pinned.

1839 * @param status Output param set to failure code on function return

1840 * when this function fails.

1841 *

1842 * @see #getActualMinimum

1843 * @see #getActualMaximum

1844 * @stable ICU 2.0

1845 */

1846 virtual void pinField(UCalendarDateFields field, UErrorCode& status);

1847

1848 /**

1849 * Return the week number of a day, within a period. This may be the week nu mber in

1850 * a year or the week number in a month. Usually this will be a value >= 1, but if

1851 * some initial days of the period are excluded from week 1, because

1852 * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek} is > 1, then

1853 * the week number will be zero for those

1854 * initial days. This method requires the day number and day of week for som e

1855 * known date in the period in order to determine the day of week

1856 * on the desired day.

1857 * <p>

1858 * <b>Subclassing:</b>

1859 * <br>

1860 * This method is intended for use by subclasses in implementing their

1861 * {@link #computeTime computeTime} and/or {@link #computeFields computeFiel ds} methods.

1862 * It is often useful in {@link #getActualMinimum getActualMinimum} and

1863 * {@link #getActualMaximum getActualMaximum} as well.

1864 * <p>

1865 * This variant is handy for computing the week number of some other

1866 * day of a period (often the first or last day of the period) when its day

1867 * of the week is not known but the day number and day of week for some othe r

1868 * day in the period (e.g. the current date) <em>is</em> known.

1869 * <p>

1870 * @param desiredDay The {@link #UCalendarDateFields DAY_OF_YEAR} or

1871 * {@link #UCalendarDateFields DAY_OF_MONTH} whose week number is desired.

1872 * Should be 1 for the first day of the period.

1873 *

1874 * @param dayOfPeriod The {@link #UCalendarDateFields DAY_OF_YEAR}

1875 * or {@link #UCalendarDateFields DAY_OF_MONTH} for a day in th e period whose

1876 * {@link #UCalendarDateFields DAY_OF_WEEK} is specified by the

1877 * <code>knownDayOfWeek</code> parameter.

1878 * Should be 1 for first day of period.

1879 *

1880 * @param dayOfWeek The {@link #UCalendarDateFields DAY_OF_WEEK} for the da y

1881 * corresponding to the <code>knownDayOfPeriod</code> parameter .

1882 * 1-based with 1=Sunday.

1883 *

1884 * @return The week number (one-based), or zero if the day falls before

1885 * the first week because

1886 * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek}

1887 * is more than one.

1888 *

1889 * @stable ICU 2.8

1890 */

1891 int32_t weekNumber(int32_t desiredDay, int32_t dayOfPeriod, int32_t dayOfWee k);

1892

1893

1894 /**

1895 * Return the week number of a day, within a period. This may be the week nu mber in

1896 * a year, or the week number in a month. Usually this will be a value >= 1, but if

1897 * some initial days of the period are excluded from week 1, because

1898 * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek} is > 1,

1899 * then the week number will be zero for those

1900 * initial days. This method requires the day of week for the given date in order to

1901 * determine the result.

1902 * <p>

1903 * <b>Subclassing:</b>

1904 * <br>

1905 * This method is intended for use by subclasses in implementing their

1906 * {@link #computeTime computeTime} and/or {@link #computeFields computeFiel ds} methods.

1907 * It is often useful in {@link #getActualMinimum getActualMinimum} and

1908 * {@link #getActualMaximum getActualMaximum} as well.

1909 * <p>

1910 * @param dayOfPeriod The {@link #UCalendarDateFields DAY_OF_YEAR} or

1911 * {@link #UCalendarDateFields DAY_OF_MONTH} whose week number is desired.

1912 * Should be 1 for the first day of the period.

1913 *

1914 * @param dayOfWeek The {@link #UCalendarDateFields DAY_OF_WEEK} for the day

1915 * corresponding to the <code>dayOfPeriod</code> parame ter.

1916 * 1-based with 1=Sunday.

1917 *

1918 * @return The week number (one-based), or zero if the day falls before

1919 * the first week because

1920 * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek}

1921 * is more than one.

1922 * @internal

1923 */

1924 inline int32_t weekNumber(int32_t dayOfPeriod, int32_t dayOfWeek);

1925

1926 /**

1927 * returns the local DOW, valid range 0..6

1928 * @internal

1929 */

1930 int32_t getLocalDOW();

1931

1932 private:

1933

1934 /**

1935 * The next available value for fStamp[]

1936 */

1937 int32_t fNextStamp;// = MINIMUM_USER_STAMP;

1938

1939 /**

1940 * The current time set for the calendar.

1941 */

1942 UDate fTime;

1943

1944 /**

1945 * @see #setLenient

1946 */

1947 UBool fLenient;

1948

1949 /**

1950 * Time zone affects the time calculation done by Calendar. Calendar subclas ses use

1951 * the time zone data to produce the local time.

1952 */

1953 TimeZone* fZone;

1954

1955 /**

1956 * Both firstDayOfWeek and minimalDaysInFirstWeek are locale-dependent. They are

1957 * used to figure out the week count for a specific date for a given locale. These

1958 * must be set when a Calendar is constructed. For example, in US locale,

1959 * firstDayOfWeek is SUNDAY; minimalDaysInFirstWeek is 1. They are used to f igure

1960 * out the week count for a specific date for a given locale. These must be set when

1961 * a Calendar is constructed.

1962 */

1963 UCalendarDaysOfWeek fFirstDayOfWeek;

1964 uint8_t fMinimalDaysInFirstWeek;

1965 UCalendarDaysOfWeek fWeekendOnset;

1966 int32_t fWeekendOnsetMillis;

1967 UCalendarDaysOfWeek fWeekendCease;

1968 int32_t fWeekendCeaseMillis;

1969

1970 /**

1971 * Sets firstDayOfWeek and minimalDaysInFirstWeek. Called at Calendar constr uction

1972 * time.

1973 *

1974 * @param desiredLocale The given locale.

1975 * @param type The calendar type identifier, e.g: gregorian, buddh ist, etc.

1976 * @param success Indicates the status of setting the week count data from

1977 * the resource for the given locale. Returns U_ZERO_E RROR if

1978 * constructed successfully.

1979 */

1980 void setWeekData(const Locale& desiredLocale, const char *type, UErro rCode& success);

1981

1982 /**

1983 * Recompute the time and update the status fields isTimeSet

1984 * and areFieldsSet. Callers should check isTimeSet and only

1985 * call this method if isTimeSet is false.

1986 *

1987 * @param status Output param set to success/failure code on exit. If any v alue

1988 * previously set in the time field is invalid or restricted by

1989 * leniency, this will be set to an error status.

1990 */

1991 void updateTime(UErrorCode& status);

1992

1993 /**

1994 * The Gregorian year, as computed by computeGregorianFields() and

1995 * returned by getGregorianYear().

1996 * @see #computeGregorianFields

1997 */

1998 int32_t fGregorianYear;

1999

2000 /**

2001 * The Gregorian month, as computed by computeGregorianFields() and

2002 * returned by getGregorianMonth().

2003 * @see #computeGregorianFields

2004 */

2005 int32_t fGregorianMonth;

2006

2007 /**

2008 * The Gregorian day of the year, as computed by

2009 * computeGregorianFields() and returned by getGregorianDayOfYear().

2010 * @see #computeGregorianFields

2011 */

2012 int32_t fGregorianDayOfYear;

2013

2014 /**

2015 * The Gregorian day of the month, as computed by

2016 * computeGregorianFields() and returned by getGregorianDayOfMonth().

2017 * @see #computeGregorianFields

2018 */

2019 int32_t fGregorianDayOfMonth;

2020

2021 /* calculations */

2022

2023 /**

2024 * Compute the Gregorian calendar year, month, and day of month from

2025 * the given Julian day. These values are not stored in fields, but in

2026 * member variables gregorianXxx. Also compute the DAY_OF_WEEK and

2027 * DOW_LOCAL fields.

2028 */

2029 void computeGregorianAndDOWFields(int32_t julianDay, UErrorCode &ec);

2030

2031 protected:

2032

2033 /**

2034 * Compute the Gregorian calendar year, month, and day of month from the

2035 * Julian day. These values are not stored in fields, but in member

2036 * variables gregorianXxx. They are used for time zone computations and by

2037 * subclasses that are Gregorian derivatives. Subclasses may call this

2038 * method to perform a Gregorian calendar millis->fields computation.

2039 */

2040 void computeGregorianFields(int32_t julianDay, UErrorCode &ec);

2041

2042 private:

2043

2044 /**

2045 * Compute the fields WEEK_OF_YEAR, YEAR_WOY, WEEK_OF_MONTH,

2046 * DAY_OF_WEEK_IN_MONTH, and DOW_LOCAL from EXTENDED_YEAR, YEAR,

2047 * DAY_OF_WEEK, and DAY_OF_YEAR. The latter fields are computed by the

2048 * subclass based on the calendar system.

2049 *

2050 * <p>The YEAR_WOY field is computed simplistically. It is equal to YEAR

2051 * most of the time, but at the year boundary it may be adjusted to YEAR-1

2052 * or YEAR+1 to reflect the overlap of a week into an adjacent year. In

2053 * this case, a simple increment or decrement is performed on YEAR, even

2054 * though this may yield an invalid YEAR value. For instance, if the YEAR

2055 * is part of a calendar system with an N-year cycle field CYCLE, then

2056 * incrementing the YEAR may involve incrementing CYCLE and setting YEAR

2057 * back to 0 or 1. This is not handled by this code, and in fact cannot be

2058 * simply handled without having subclasses define an entire parallel set of

2059 * fields for fields larger than or equal to a year. This additional

2060 * complexity is not warranted, since the intention of the YEAR_WOY field is

2061 * to support ISO 8601 notation, so it will typically be used with a

2062 * proleptic Gregorian calendar, which has no field larger than a year.

2063 */

2064 void computeWeekFields(UErrorCode &ec);

2065

2066

2067 /**

2068 * Ensure that each field is within its valid range by calling {@link

2069 * #validateField(int, int&)} on each field that has been set. This method

2070 * should only be called if this calendar is not lenient.

2071 * @see #isLenient

2072 * @see #validateField(int, int&)

2073 * @internal

2074 */

2075 void validateFields(UErrorCode &status);

2076

2077 /**

2078 * Validate a single field of this calendar. Subclasses should

2079 * override this method to validate any calendar-specific fields.

2080 * Generic fields can be handled by

2081 * <code>Calendar.validateField()</code>.

2082 * @see #validateField(int, int, int, int&)

2083 * @internal

2084 */

2085 virtual void validateField(UCalendarDateFields field, UErrorCode &status);

2086

2087 /**

2088 * Validate a single field of this calendar given its minimum and

2089 * maximum allowed value. If the field is out of range,

2090 * <code>U_ILLEGAL_ARGUMENT_ERROR</code> will be set. Subclasses may

2091 * use this method in their implementation of {@link

2092 * #validateField(int, int&)}.

2093 * @internal

2094 */

2095 void validateField(UCalendarDateFields field, int32_t min, int32_t max, UErr orCode& status);

2096

2097 protected:

2098 /**

2099 * Convert a quasi Julian date to the day of the week. The Julian date used here is

2100 * not a true Julian date, since it is measured from midnight, not noon. Ret urn

2101 * value is one-based.

2102 *

2103 * @param julian The given Julian date number.

2104 * @return Day number from 1..7 (SUN..SAT).

2105 * @internal

2106 */

2107 static uint8_t julianDayToDayOfWeek(double julian);

2108

2109 private:

2110 char validLocale[ULOC_FULLNAME_CAPACITY];

2111 char actualLocale[ULOC_FULLNAME_CAPACITY];

2112

2113 public:

2114 #if !UCONFIG_NO_SERVICE

2115 /**

2116 * INTERNAL FOR 2.6 -- Registration.

2117 */

2118

2119 /**

2120 * Return a StringEnumeration over the locales available at the time of the call,

2121 * including registered locales.

2122 * @return a StringEnumeration over the locales available at the time of the call

2123 * @internal

2124 */

2125 static StringEnumeration* getAvailableLocales(void);

2126

2127 /**

2128 * Register a new Calendar factory. The factory will be adopted.

2129 * INTERNAL in 2.6

2130 * @param toAdopt the factory instance to be adopted

2131 * @param status the in/out status code, no special meanings are assigned

2132 * @return a registry key that can be used to unregister this factory

2133 * @internal

2134 */

2135 static URegistryKey registerFactory(ICUServiceFactory* toAdopt, UErrorCode& status);

2136

2137 /**

2138 * Unregister a previously-registered CalendarFactory using the key returned from the

2139 * register call. Key becomes invalid after a successful call and should no t be used again.

2140 * The CalendarFactory corresponding to the key will be deleted.

2141 * INTERNAL in 2.6

2142 * @param key the registry key returned by a previous call to registerFactor y

2143 * @param status the in/out status code, no special meanings are assigned

2144 * @return TRUE if the factory for the key was successfully unregistered

2145 * @internal

2146 */

2147 static UBool unregister(URegistryKey key, UErrorCode& status);

2148

2149 /**

2150 * Multiple Calendar Implementation

2151 * @internal

2152 */

2153 friend class CalendarFactory;

2154

2155 /**

2156 * Multiple Calendar Implementation

2157 * @internal

2158 */

2159 friend class CalendarService;

2160

2161 /**

2162 * Multiple Calendar Implementation

2163 * @internal

2164 */

2165 friend class DefaultCalendarFactory;

2166 #endif /* !UCONFIG_NO_SERVICE */

2167

2168 /**

2169 * @internal

2170 * @return TRUE if this calendar has a default century (i.e. 03 -> 2003)

2171 */

2172 virtual UBool haveDefaultCentury() const = 0;

2173

2174 /**

2175 * @internal

2176 * @return the start of the default century, as a UDate

2177 */

2178 virtual UDate defaultCenturyStart() const = 0;

2179 /**

2180 * @internal

2181 * @return the beginning year of the default century, as a year

2182 */

2183 virtual int32_t defaultCenturyStartYear() const = 0;

2184

2185 /** Get the locale for this calendar object. You can choose between valid an d actual locale.

2186 * @param type type of the locale we're looking for (valid or actual)

2187 * @param status error code for the operation

2188 * @return the locale

2189 * @stable ICU 2.8

2190 */

2191 Locale getLocale(ULocDataLocaleType type, UErrorCode &status) const;

2192

2193 /** Get the locale for this calendar object. You can choose between valid an d actual locale.

2194 * @param type type of the locale we're looking for (valid or actual)

2195 * @param status error code for the operation

2196 * @return the locale

2197 * @internal

2198 */

2199 const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const;

2200

2201 };

2202

2203 // -------------------------------------

2204

2205 inline Calendar*

2206 Calendar::createInstance(TimeZone* zone, UErrorCode& errorCode)

2207 {

2208 // since the Locale isn't specified, use the default locale

2209 return createInstance(zone, Locale::getDefault(), errorCode);

2210 }

2211

2212 // -------------------------------------

2213

2214 inline void

2215 Calendar::roll(UCalendarDateFields field, UBool up, UErrorCode& status)

2216 {

2217 roll(field, (int32_t)(up ? +1 : -1), status);

2218 }

2219

2220 inline void

2221 Calendar::roll(EDateFields field, UBool up, UErrorCode& status)

2222 {

2223 roll((UCalendarDateFields) field, up, status);

2224 }

2225

2226

2227 // -------------------------------------

2228

2229 /**

2230 * Fast method for subclasses. The caller must maintain fUserSetDSTOffset and

2231 * fUserSetZoneOffset, as well as the isSet[] array.

2232 */

2233

2234 inline void

2235 Calendar::internalSet(UCalendarDateFields field, int32_t value)

2236 {

2237 fFields[field] = value;

2238 fStamp[field] = kInternallySet;

2239 fIsSet[field] = TRUE; // Remove later

2240 }

2241

2242 inline int32_t Calendar::weekNumber(int32_t dayOfPeriod, int32_t dayOfWeek)

2243 {

2244 return weekNumber(dayOfPeriod, dayOfPeriod, dayOfWeek);

2245 }

2246

2247

2248 U_NAMESPACE_END

2249

2250 #endif /* #if !UCONFIG_NO_FORMATTING */

2251

2252 #endif // _CALENDAR

OLD	NEW

« no previous file with comments | « public/i18n/unicode/bmsearch.h ('k') | public/i18n/unicode/choicfmt.h » ('j') | no next file with comments »