-
Notifications
You must be signed in to change notification settings - Fork 74
Expand file tree
/
Copy pathcalendar.h
More file actions
2258 lines (2054 loc) · 91.5 KB
/
calendar.h
File metadata and controls
2258 lines (2054 loc) · 91.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
********************************************************************************
* Copyright (C) 1997-2011, International Business Machines
* Corporation and others. All Rights Reserved.
********************************************************************************
*
* File CALENDAR.H
*
* Modification History:
*
* Date Name Description
* 04/22/97 aliu Expanded and corrected comments and other header
* contents.
* 05/01/97 aliu Made equals(), before(), after() arguments const.
* 05/20/97 aliu Replaced fAreFieldsSet with fAreFieldsInSync and
* fAreAllFieldsSet.
* 07/27/98 stephen Sync up with JDK 1.2
* 11/15/99 weiv added YEAR_WOY and DOW_LOCAL
* to EDateFields
* 8/19/2002 srl Removed Javaisms
* 11/07/2003 srl Update, clean up documentation.
********************************************************************************
*/
#ifndef CALENDAR_H
#define CALENDAR_H
#include "unicode/utypes.h"
/**
* \file
* \brief C++ API: Calendar object
*/
#if !UCONFIG_NO_FORMATTING
#include "unicode/uobject.h"
#include "unicode/locid.h"
#include "unicode/timezone.h"
#include "unicode/ucal.h"
#include "unicode/umisc.h"
U_NAMESPACE_BEGIN
class ICUServiceFactory;
/**
* @internal
*/
typedef int32_t UFieldResolutionTable[12][8];
/**
* <code>Calendar</code> is an abstract base class for converting between
* a <code>UDate</code> object and a set of integer fields such as
* <code>YEAR</code>, <code>MONTH</code>, <code>DAY</code>, <code>HOUR</code>,
* and so on. (A <code>UDate</code> object represents a specific instant in
* time with millisecond precision. See UDate
* for information about the <code>UDate</code> class.)
*
* <p>
* Subclasses of <code>Calendar</code> interpret a <code>UDate</code>
* according to the rules of a specific calendar system.
* The most commonly used subclass of <code>Calendar</code> is
* <code>GregorianCalendar</code>. Other subclasses could represent
* the various types of lunar calendars in use in many parts of the world.
*
* <p>
* <b>NOTE</b>: (ICU 2.6) The subclass interface should be considered unstable
* - it WILL change.
*
* <p>
* Like other locale-sensitive classes, <code>Calendar</code> provides a
* static method, <code>createInstance</code>, for getting a generally useful
* object of this type. <code>Calendar</code>'s <code>createInstance</code> method
* returns the appropriate <code>Calendar</code> subclass whose
* time fields have been initialized with the current date and time:
* \htmlonly<blockquote>\endhtmlonly
* <pre>
* Calendar *rightNow = Calendar::createInstance(errCode);
* </pre>
* \htmlonly</blockquote>\endhtmlonly
*
* <p>
* A <code>Calendar</code> object can produce all the time field values
* needed to implement the date-time formatting for a particular language
* and calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
*
* <p>
* When computing a <code>UDate</code> from time fields, two special circumstances
* may arise: there may be insufficient information to compute the
* <code>UDate</code> (such as only year and month but no day in the month),
* or there may be inconsistent information (such as "Tuesday, July 15, 1996"
* -- July 15, 1996 is actually a Monday).
*
* <p>
* <strong>Insufficient information.</strong> The calendar will use default
* information to specify the missing fields. This may vary by calendar; for
* the Gregorian calendar, the default for a field is the same as that of the
* start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc.
*
* <p>
* <strong>Inconsistent information.</strong> If fields conflict, the calendar
* will give preference to fields set more recently. For example, when
* determining the day, the calendar will look for one of the following
* combinations of fields. The most recent combination, as determined by the
* most recently set single field, will be used.
*
* \htmlonly<blockquote>\endhtmlonly
* <pre>
* MONTH + DAY_OF_MONTH
* MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
* MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
* DAY_OF_YEAR
* DAY_OF_WEEK + WEEK_OF_YEAR
* </pre>
* \htmlonly</blockquote>\endhtmlonly
*
* For the time of day:
*
* \htmlonly<blockquote>\endhtmlonly
* <pre>
* HOUR_OF_DAY
* AM_PM + HOUR
* </pre>
* \htmlonly</blockquote>\endhtmlonly
*
* <p>
* <strong>Note:</strong> for some non-Gregorian calendars, different
* fields may be necessary for complete disambiguation. For example, a full
* specification of the historial Arabic astronomical calendar requires year,
* month, day-of-month <em>and</em> day-of-week in some cases.
*
* <p>
* <strong>Note:</strong> There are certain possible ambiguities in
* interpretation of certain singular times, which are resolved in the
* following ways:
* <ol>
* <li> 24:00:00 "belongs" to the following day. That is,
* 23:59 on Dec 31, 1969 < 24:00 on Jan 1, 1970 < 24:01:00 on Jan 1, 1970
*
* <li> Although historically not precise, midnight also belongs to "am",
* and noon belongs to "pm", so on the same day,
* 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm
* </ol>
*
* <p>
* The date or time format strings are not part of the definition of a
* calendar, as those must be modifiable or overridable by the user at
* runtime. Use {@link DateFormat}
* to format dates.
*
* <p>
* <code>Calendar</code> provides an API for field "rolling", where fields
* can be incremented or decremented, but wrap around. For example, rolling the
* month up in the date <code>December 12, <b>1996</b></code> results in
* <code>January 12, <b>1996</b></code>.
*
* <p>
* <code>Calendar</code> also provides a date arithmetic function for
* adding the specified (signed) amount of time to a particular time field.
* For example, subtracting 5 days from the date <code>September 12, 1996</code>
* results in <code>September 7, 1996</code>.
*
* @stable ICU 2.0
*/
class U_I18N_API Calendar : public UObject {
public:
/**
* Field IDs for date and time. Used to specify date/time fields. ERA is calendar
* specific. Example ranges given are for illustration only; see specific Calendar
* subclasses for actual ranges.
* @deprecated ICU 2.6. Use C enum UCalendarDateFields defined in ucal.h
*/
enum EDateFields {
#ifndef U_HIDE_DEPRECATED_API
/*
* ERA may be defined on other platforms. To avoid any potential problems undefined it here.
*/
#ifdef ERA
#undef ERA
#endif
ERA, // Example: 0..1
YEAR, // Example: 1..big number
MONTH, // Example: 0..11
WEEK_OF_YEAR, // Example: 1..53
WEEK_OF_MONTH, // Example: 1..4
DATE, // Example: 1..31
DAY_OF_YEAR, // Example: 1..365
DAY_OF_WEEK, // Example: 1..7
DAY_OF_WEEK_IN_MONTH, // Example: 1..4, may be specified as -1
AM_PM, // Example: 0..1
HOUR, // Example: 0..11
HOUR_OF_DAY, // Example: 0..23
MINUTE, // Example: 0..59
SECOND, // Example: 0..59
MILLISECOND, // Example: 0..999
ZONE_OFFSET, // Example: -12*U_MILLIS_PER_HOUR..12*U_MILLIS_PER_HOUR
DST_OFFSET, // Example: 0 or U_MILLIS_PER_HOUR
YEAR_WOY, // 'Y' Example: 1..big number - Year of Week of Year
DOW_LOCAL, // 'e' Example: 1..7 - Day of Week / Localized
EXTENDED_YEAR,
JULIAN_DAY,
MILLISECONDS_IN_DAY,
IS_LEAP_MONTH,
FIELD_COUNT = UCAL_FIELD_COUNT // See ucal.h for other fields.
#endif /* U_HIDE_DEPRECATED_API */
};
/**
* Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients
* who create locale resources for the field of first-day-of-week should be aware of
* this. For instance, in US locale, first-day-of-week is set to 1, i.e., SUNDAY.
* @deprecated ICU 2.6. Use C enum UCalendarDaysOfWeek defined in ucal.h
*/
enum EDaysOfWeek {
#ifndef U_HIDE_DEPRECATED_API
SUNDAY = 1,
MONDAY,
TUESDAY,
WEDNESDAY,
THURSDAY,
FRIDAY,
SATURDAY
#endif /* U_HIDE_DEPRECATED_API */
};
/**
* Useful constants for month. Note: Calendar month is 0-based.
* @deprecated ICU 2.6. Use C enum UCalendarMonths defined in ucal.h
*/
enum EMonths {
#ifndef U_HIDE_DEPRECATED_API
JANUARY,
FEBRUARY,
MARCH,
APRIL,
MAY,
JUNE,
JULY,
AUGUST,
SEPTEMBER,
OCTOBER,
NOVEMBER,
DECEMBER,
UNDECIMBER
#endif /* U_HIDE_DEPRECATED_API */
};
/**
* Useful constants for hour in 12-hour clock. Used in GregorianCalendar.
* @deprecated ICU 2.6. Use C enum UCalendarAMPMs defined in ucal.h
*/
enum EAmpm {
#ifndef U_HIDE_DEPRECATED_API
AM,
PM
#endif /* U_HIDE_DEPRECATED_API */
};
/**
* destructor
* @stable ICU 2.0
*/
virtual ~Calendar();
/**
* Create and return a polymorphic copy of this calendar.
*
* @return a polymorphic copy of this calendar.
* @stable ICU 2.0
*/
virtual Calendar* clone(void) const = 0;
/**
* Creates a Calendar using the default timezone and locale. Clients are responsible
* for deleting the object returned.
*
* @param success Indicates the success/failure of Calendar creation. Filled in
* with U_ZERO_ERROR if created successfully, set to a failure result
* otherwise. U_MISSING_RESOURCE_ERROR will be returned if the resource data
* requests a calendar type which has not been installed.
* @return A Calendar if created successfully. NULL otherwise.
* @stable ICU 2.0
*/
static Calendar* U_EXPORT2 createInstance(UErrorCode& success);
/**
* Creates a Calendar using the given timezone and the default locale.
* The Calendar takes ownership of zoneToAdopt; the
* client must not delete it.
*
* @param zoneToAdopt The given timezone to be adopted.
* @param success Indicates the success/failure of Calendar creation. Filled in
* with U_ZERO_ERROR if created successfully, set to a failure result
* otherwise.
* @return A Calendar if created successfully. NULL otherwise.
* @stable ICU 2.0
*/
static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, UErrorCode& success);
/**
* Creates a Calendar using the given timezone and the default locale. The TimeZone
* is _not_ adopted; the client is still responsible for deleting it.
*
* @param zone The timezone.
* @param success Indicates the success/failure of Calendar creation. Filled in
* with U_ZERO_ERROR if created successfully, set to a failure result
* otherwise.
* @return A Calendar if created successfully. NULL otherwise.
* @stable ICU 2.0
*/
static Calendar* U_EXPORT2 createInstance(const TimeZone& zone, UErrorCode& success);
/**
* Creates a Calendar using the default timezone and the given locale.
*
* @param aLocale The given locale.
* @param success Indicates the success/failure of Calendar creation. Filled in
* with U_ZERO_ERROR if created successfully, set to a failure result
* otherwise.
* @return A Calendar if created successfully. NULL otherwise.
* @stable ICU 2.0
*/
static Calendar* U_EXPORT2 createInstance(const Locale& aLocale, UErrorCode& success);
/**
* Creates a Calendar using the given timezone and given locale.
* The Calendar takes ownership of zoneToAdopt; the
* client must not delete it.
*
* @param zoneToAdopt The given timezone to be adopted.
* @param aLocale The given locale.
* @param success Indicates the success/failure of Calendar creation. Filled in
* with U_ZERO_ERROR if created successfully, set to a failure result
* otherwise.
* @return A Calendar if created successfully. NULL otherwise.
* @stable ICU 2.0
*/
static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, const Locale& aLocale, UErrorCode& success);
/**
* Gets a Calendar using the given timezone and given locale. The TimeZone
* is _not_ adopted; the client is still responsible for deleting it.
*
* @param zoneToAdopt The given timezone to be adopted.
* @param aLocale The given locale.
* @param success Indicates the success/failure of Calendar creation. Filled in
* with U_ZERO_ERROR if created successfully, set to a failure result
* otherwise.
* @return A Calendar if created successfully. NULL otherwise.
* @stable ICU 2.0
*/
static Calendar* U_EXPORT2 createInstance(const TimeZone& zoneToAdopt, const Locale& aLocale, UErrorCode& success);
/**
* Returns a list of the locales for which Calendars are installed.
*
* @param count Number of locales returned.
* @return An array of Locale objects representing the set of locales for which
* Calendars are installed. The system retains ownership of this list;
* the caller must NOT delete it. Does not include user-registered Calendars.
* @stable ICU 2.0
*/
static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
/**
* Given a key and a locale, returns an array of string values in a preferred
* order that would make a difference. These are all and only those values where
* the open (creation) of the service with the locale formed from the input locale
* plus input keyword and that value has different behavior than creation with the
* input locale alone.
* @param key one of the keys supported by this service. For now, only
* "calendar" is supported.
* @param locale the locale
* @param commonlyUsed if set to true it will return only commonly used values
* with the given locale in preferred order. Otherwise,
* it will return all the available values for the locale.
* @param status ICU Error Code
* @return a string enumeration over keyword values for the given key and the locale.
* @stable ICU 4.2
*/
static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* key,
const Locale& locale, UBool commonlyUsed, UErrorCode& status);
/**
* Returns the current UTC (GMT) time measured in milliseconds since 0:00:00 on 1/1/70
* (derived from the system time).
*
* @return The current UTC time in milliseconds.
* @stable ICU 2.0
*/
static UDate U_EXPORT2 getNow(void);
/**
* Gets this Calendar's time as milliseconds. May involve recalculation of time due
* to previous calls to set time field values. The time specified is non-local UTC
* (GMT) time. Although this method is const, this object may actually be changed
* (semantically const).
*
* @param status Output param set to success/failure code on exit. If any value
* previously set in the time field is invalid or restricted by
* leniency, this will be set to an error status.
* @return The current time in UTC (GMT) time, or zero if the operation
* failed.
* @stable ICU 2.0
*/
inline UDate getTime(UErrorCode& status) const { return getTimeInMillis(status); }
/**
* Sets this Calendar's current time with the given UDate. The time specified should
* be in non-local UTC (GMT) time.
*
* @param date The given UDate in UTC (GMT) time.
* @param status Output param set to success/failure code on exit. If any value
* set in the time field is invalid or restricted by
* leniency, this will be set to an error status.
* @stable ICU 2.0
*/
inline void setTime(UDate date, UErrorCode& status) { setTimeInMillis(date, status); }
/**
* Compares the equality of two Calendar objects. Objects of different subclasses
* are considered unequal. This comparison is very exacting; two Calendar objects
* must be in exactly the same state to be considered equal. To compare based on the
* represented time, use equals() instead.
*
* @param that The Calendar object to be compared with.
* @return True if the given Calendar is the same as this Calendar; false
* otherwise.
* @stable ICU 2.0
*/
virtual UBool operator==(const Calendar& that) const;
/**
* Compares the inequality of two Calendar objects.
*
* @param that The Calendar object to be compared with.
* @return True if the given Calendar is not the same as this Calendar; false
* otherwise.
* @stable ICU 2.0
*/
UBool operator!=(const Calendar& that) const {return !operator==(that);}
/**
* Returns TRUE if the given Calendar object is equivalent to this
* one. An equivalent Calendar will behave exactly as this one
* does, but it may be set to a different time. By contrast, for
* the operator==() method to return TRUE, the other Calendar must
* be set to the same time.
*
* @param other the Calendar to be compared with this Calendar
* @stable ICU 2.4
*/
virtual UBool isEquivalentTo(const Calendar& other) const;
/**
* Compares the Calendar time, whereas Calendar::operator== compares the equality of
* Calendar objects.
*
* @param when The Calendar to be compared with this Calendar. Although this is a
* const parameter, the object may be modified physically
* (semantically const).
* @param status Output param set to success/failure code on exit. If any value
* previously set in the time field is invalid or restricted by
* leniency, this will be set to an error status.
* @return True if the current time of this Calendar is equal to the time of
* Calendar when; false otherwise.
* @stable ICU 2.0
*/
UBool equals(const Calendar& when, UErrorCode& status) const;
/**
* Returns true if this Calendar's current time is before "when"'s current time.
*
* @param when The Calendar to be compared with this Calendar. Although this is a
* const parameter, the object may be modified physically
* (semantically const).
* @param status Output param set to success/failure code on exit. If any value
* previously set in the time field is invalid or restricted by
* leniency, this will be set to an error status.
* @return True if the current time of this Calendar is before the time of
* Calendar when; false otherwise.
* @stable ICU 2.0
*/
UBool before(const Calendar& when, UErrorCode& status) const;
/**
* Returns true if this Calendar's current time is after "when"'s current time.
*
* @param when The Calendar to be compared with this Calendar. Although this is a
* const parameter, the object may be modified physically
* (semantically const).
* @param status Output param set to success/failure code on exit. If any value
* previously set in the time field is invalid or restricted by
* leniency, this will be set to an error status.
* @return True if the current time of this Calendar is after the time of
* Calendar when; false otherwise.
* @stable ICU 2.0
*/
UBool after(const Calendar& when, UErrorCode& status) const;
/**
* UDate Arithmetic function. Adds the specified (signed) amount of time to the given
* time field, based on the calendar's rules. For example, to subtract 5 days from
* the current time of the calendar, call add(Calendar::DATE, -5). When adding on
* the month or Calendar::MONTH field, other fields like date might conflict and
* need to be changed. For instance, adding 1 month on the date 01/31/96 will result
* in 02/29/96.
*
* @param field Specifies which date field to modify.
* @param amount The amount of time to be added to the field, in the natural unit
* for that field (e.g., days for the day fields, hours for the hour
* field.)
* @param status Output param set to success/failure code on exit. If any value
* previously set in the time field is invalid or restricted by
* leniency, this will be set to an error status.
* @deprecated ICU 2.6. use add(UCalendarDateFields field, int32_t amount, UErrorCode& status) instead.
*/
virtual void add(EDateFields field, int32_t amount, UErrorCode& status);
/**
* UDate Arithmetic function. Adds the specified (signed) amount of time to the given
* time field, based on the calendar's rules. For example, to subtract 5 days from
* the current time of the calendar, call add(Calendar::DATE, -5). When adding on
* the month or Calendar::MONTH field, other fields like date might conflict and
* need to be changed. For instance, adding 1 month on the date 01/31/96 will result
* in 02/29/96.
*
* @param field Specifies which date field to modify.
* @param amount The amount of time to be added to the field, in the natural unit
* for that field (e.g., days for the day fields, hours for the hour
* field.)
* @param status Output param set to success/failure code on exit. If any value
* previously set in the time field is invalid or restricted by
* leniency, this will be set to an error status.
* @stable ICU 2.6.
*/
virtual void add(UCalendarDateFields field, int32_t amount, UErrorCode& status);
/**
* Time Field Rolling function. Rolls (up/down) a single unit of time on the given
* time field. For example, to roll the current date up by one day, call
* roll(Calendar::DATE, true). When rolling on the year or Calendar::YEAR field, it
* will roll the year value in the range between getMinimum(Calendar::YEAR) and the
* value returned by getMaximum(Calendar::YEAR). When rolling on the month or
* Calendar::MONTH field, other fields like date might conflict and, need to be
* changed. For instance, rolling the month up on the date 01/31/96 will result in
* 02/29/96. Rolling up always means rolling forward in time; e.g., rolling the year
* up on "100 BC" will result in "99 BC", for Gregorian calendar. When rolling on the
* hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the hour value in the range
* between 0 and 23, which is zero-based.
* <P>
* NOTE: Do not use this method -- use roll(EDateFields, int, UErrorCode&) instead.
*
* @param field The time field.
* @param up Indicates if the value of the specified time field is to be rolled
* up or rolled down. Use true if rolling up, false otherwise.
* @param status Output param set to success/failure code on exit. If any value
* previously set in the time field is invalid or restricted by
* leniency, this will be set to an error status.
* @deprecated ICU 2.6. Use roll(UCalendarDateFields field, UBool up, UErrorCode& status) instead.
*/
inline void roll(EDateFields field, UBool up, UErrorCode& status);
/**
* Time Field Rolling function. Rolls (up/down) a single unit of time on the given
* time field. For example, to roll the current date up by one day, call
* roll(Calendar::DATE, true). When rolling on the year or Calendar::YEAR field, it
* will roll the year value in the range between getMinimum(Calendar::YEAR) and the
* value returned by getMaximum(Calendar::YEAR). When rolling on the month or
* Calendar::MONTH field, other fields like date might conflict and, need to be
* changed. For instance, rolling the month up on the date 01/31/96 will result in
* 02/29/96. Rolling up always means rolling forward in time; e.g., rolling the year
* up on "100 BC" will result in "99 BC", for Gregorian calendar. When rolling on the
* hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the hour value in the range
* between 0 and 23, which is zero-based.
* <P>
* NOTE: Do not use this method -- use roll(UCalendarDateFields, int, UErrorCode&) instead.
*
* @param field The time field.
* @param up Indicates if the value of the specified time field is to be rolled
* up or rolled down. Use true if rolling up, false otherwise.
* @param status Output param set to success/failure code on exit. If any value
* previously set in the time field is invalid or restricted by
* leniency, this will be set to an error status.
* @stable ICU 2.6.
*/
inline void roll(UCalendarDateFields field, UBool up, UErrorCode& status);
/**
* Time Field Rolling function. Rolls by the given amount on the given
* time field. For example, to roll the current date up by one day, call
* roll(Calendar::DATE, +1, status). When rolling on the month or
* Calendar::MONTH field, other fields like date might conflict and, need to be
* changed. For instance, rolling the month up on the date 01/31/96 will result in
* 02/29/96. Rolling by a positive value always means rolling forward in time;
* e.g., rolling the year by +1 on "100 BC" will result in "99 BC", for Gregorian
* calendar. When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will
* roll the hour value in the range between 0 and 23, which is zero-based.
* <P>
* The only difference between roll() and add() is that roll() does not change
* the value of more significant fields when it reaches the minimum or maximum
* of its range, whereas add() does.
*
* @param field The time field.
* @param amount Indicates amount to roll.
* @param status Output param set to success/failure code on exit. If any value
* previously set in the time field is invalid, this will be set to
* an error status.
* @deprecated ICU 2.6. Use roll(UCalendarDateFields field, int32_t amount, UErrorCode& status) instead.
*/
virtual void roll(EDateFields field, int32_t amount, UErrorCode& status);
/**
* Time Field Rolling function. Rolls by the given amount on the given
* time field. For example, to roll the current date up by one day, call
* roll(Calendar::DATE, +1, status). When rolling on the month or
* Calendar::MONTH field, other fields like date might conflict and, need to be
* changed. For instance, rolling the month up on the date 01/31/96 will result in
* 02/29/96. Rolling by a positive value always means rolling forward in time;
* e.g., rolling the year by +1 on "100 BC" will result in "99 BC", for Gregorian
* calendar. When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will
* roll the hour value in the range between 0 and 23, which is zero-based.
* <P>
* The only difference between roll() and add() is that roll() does not change
* the value of more significant fields when it reaches the minimum or maximum
* of its range, whereas add() does.
*
* @param field The time field.
* @param amount Indicates amount to roll.
* @param status Output param set to success/failure code on exit. If any value
* previously set in the time field is invalid, this will be set to
* an error status.
* @stable ICU 2.6.
*/
virtual void roll(UCalendarDateFields field, int32_t amount, UErrorCode& status);
/**
* Return the difference between the given time and the time this
* calendar object is set to. If this calendar is set
* <em>before</em> the given time, the returned value will be
* positive. If this calendar is set <em>after</em> the given
* time, the returned value will be negative. The
* <code>field</code> parameter specifies the units of the return
* value. For example, if <code>fieldDifference(when,
* Calendar::MONTH)</code> returns 3, then this calendar is set to
* 3 months before <code>when</code>, and possibly some addition
* time less than one month.
*
* <p>As a side effect of this call, this calendar is advanced
* toward <code>when</code> by the given amount. That is, calling
* this method has the side effect of calling <code>add(field,
* n)</code>, where <code>n</code> is the return value.
*
* <p>Usage: To use this method, call it first with the largest
* field of interest, then with progressively smaller fields. For
* example:
*
* <pre>
* int y = cal->fieldDifference(when, Calendar::YEAR, err);
* int m = cal->fieldDifference(when, Calendar::MONTH, err);
* int d = cal->fieldDifference(when, Calendar::DATE, err);</pre>
*
* computes the difference between <code>cal</code> and
* <code>when</code> in years, months, and days.
*
* <p>Note: <code>fieldDifference()</code> is
* <em>asymmetrical</em>. That is, in the following code:
*
* <pre>
* cal->setTime(date1, err);
* int m1 = cal->fieldDifference(date2, Calendar::MONTH, err);
* int d1 = cal->fieldDifference(date2, Calendar::DATE, err);
* cal->setTime(date2, err);
* int m2 = cal->fieldDifference(date1, Calendar::MONTH, err);
* int d2 = cal->fieldDifference(date1, Calendar::DATE, err);</pre>
*
* one might expect that <code>m1 == -m2 && d1 == -d2</code>.
* However, this is not generally the case, because of
* irregularities in the underlying calendar system (e.g., the
* Gregorian calendar has a varying number of days per month).
*
* @param when the date to compare this calendar's time to
* @param field the field in which to compute the result
* @param status Output param set to success/failure code on exit. If any value
* previously set in the time field is invalid, this will be set to
* an error status.
* @return the difference, either positive or negative, between
* this calendar's time and <code>when</code>, in terms of
* <code>field</code>.
* @deprecated ICU 2.6. Use fieldDifference(UDate when, UCalendarDateFields field, UErrorCode& status).
*/
virtual int32_t fieldDifference(UDate when, EDateFields field, UErrorCode& status);
/**
* Return the difference between the given time and the time this
* calendar object is set to. If this calendar is set
* <em>before</em> the given time, the returned value will be
* positive. If this calendar is set <em>after</em> the given
* time, the returned value will be negative. The
* <code>field</code> parameter specifies the units of the return
* value. For example, if <code>fieldDifference(when,
* Calendar::MONTH)</code> returns 3, then this calendar is set to
* 3 months before <code>when</code>, and possibly some addition
* time less than one month.
*
* <p>As a side effect of this call, this calendar is advanced
* toward <code>when</code> by the given amount. That is, calling
* this method has the side effect of calling <code>add(field,
* n)</code>, where <code>n</code> is the return value.
*
* <p>Usage: To use this method, call it first with the largest
* field of interest, then with progressively smaller fields. For
* example:
*
* <pre>
* int y = cal->fieldDifference(when, Calendar::YEAR, err);
* int m = cal->fieldDifference(when, Calendar::MONTH, err);
* int d = cal->fieldDifference(when, Calendar::DATE, err);</pre>
*
* computes the difference between <code>cal</code> and
* <code>when</code> in years, months, and days.
*
* <p>Note: <code>fieldDifference()</code> is
* <em>asymmetrical</em>. That is, in the following code:
*
* <pre>
* cal->setTime(date1, err);
* int m1 = cal->fieldDifference(date2, Calendar::MONTH, err);
* int d1 = cal->fieldDifference(date2, Calendar::DATE, err);
* cal->setTime(date2, err);
* int m2 = cal->fieldDifference(date1, Calendar::MONTH, err);
* int d2 = cal->fieldDifference(date1, Calendar::DATE, err);</pre>
*
* one might expect that <code>m1 == -m2 && d1 == -d2</code>.
* However, this is not generally the case, because of
* irregularities in the underlying calendar system (e.g., the
* Gregorian calendar has a varying number of days per month).
*
* @param when the date to compare this calendar's time to
* @param field the field in which to compute the result
* @param status Output param set to success/failure code on exit. If any value
* previously set in the time field is invalid, this will be set to
* an error status.
* @return the difference, either positive or negative, between
* this calendar's time and <code>when</code>, in terms of
* <code>field</code>.
* @stable ICU 2.6.
*/
virtual int32_t fieldDifference(UDate when, UCalendarDateFields field, UErrorCode& status);
/**
* Sets the calendar's time zone to be the one passed in. The Calendar takes ownership
* of the TimeZone; the caller is no longer responsible for deleting it. If the
* given time zone is NULL, this function has no effect.
*
* @param value The given time zone.
* @stable ICU 2.0
*/
void adoptTimeZone(TimeZone* value);
/**
* Sets the calendar's time zone to be the same as the one passed in. The TimeZone
* passed in is _not_ adopted; the client is still responsible for deleting it.
*
* @param zone The given time zone.
* @stable ICU 2.0
*/
void setTimeZone(const TimeZone& zone);
/**
* Returns a reference to the time zone owned by this calendar. The returned reference
* is only valid until clients make another call to adoptTimeZone or setTimeZone,
* or this Calendar is destroyed.
*
* @return The time zone object associated with this calendar.
* @stable ICU 2.0
*/
const TimeZone& getTimeZone(void) const;
/**
* Returns the time zone owned by this calendar. The caller owns the returned object
* and must delete it when done. After this call, the new time zone associated
* with this Calendar is the default TimeZone as returned by TimeZone::createDefault().
*
* @return The time zone object which was associated with this calendar.
* @stable ICU 2.0
*/
TimeZone* orphanTimeZone(void);
/**
* Queries if the current date for this Calendar is in Daylight Savings Time.
*
* @param status Fill-in parameter which receives the status of this operation.
* @return True if the current date for this Calendar is in Daylight Savings Time,
* false, otherwise.
* @stable ICU 2.0
*/
virtual UBool inDaylightTime(UErrorCode& status) const = 0;
/**
* Specifies whether or not date/time interpretation is to be lenient. With lenient
* interpretation, a date such as "February 942, 1996" will be treated as being
* equivalent to the 941st day after February 1, 1996. With strict interpretation,
* such dates will cause an error when computing time from the time field values
* representing the dates.
*
* @param lenient True specifies date/time interpretation to be lenient.
*
* @see DateFormat#setLenient
* @stable ICU 2.0
*/
void setLenient(UBool lenient);
/**
* Tells whether date/time interpretation is to be lenient.
*
* @return True tells that date/time interpretation is to be lenient.
* @stable ICU 2.0
*/
UBool isLenient(void) const;
/**
* Sets what the first day of the week is; e.g., Sunday in US, Monday in France.
*
* @param value The given first day of the week.
* @deprecated ICU 2.6. Use setFirstDayOfWeek(UCalendarDaysOfWeek value) instead.
*/
void setFirstDayOfWeek(EDaysOfWeek value);
/**
* Sets what the first day of the week is; e.g., Sunday in US, Monday in France.
*
* @param value The given first day of the week.
* @stable ICU 2.6.
*/
void setFirstDayOfWeek(UCalendarDaysOfWeek value);
/**
* Gets what the first day of the week is; e.g., Sunday in US, Monday in France.
*
* @return The first day of the week.
* @deprecated ICU 2.6 use the overload with error code
*/
EDaysOfWeek getFirstDayOfWeek(void) const;
/**
* Gets what the first day of the week is; e.g., Sunday in US, Monday in France.
*
* @param status error code
* @return The first day of the week.
* @stable ICU 2.6
*/
UCalendarDaysOfWeek getFirstDayOfWeek(UErrorCode &status) const;
/**
* Sets what the minimal days required in the first week of the year are; For
* example, if the first week is defined as one that contains the first day of the
* first month of a year, call the method with value 1. If it must be a full week,
* use value 7.
*
* @param value The given minimal days required in the first week of the year.
* @stable ICU 2.0
*/
void setMinimalDaysInFirstWeek(uint8_t value);
/**
* Gets what the minimal days required in the first week of the year are; e.g., if
* the first week is defined as one that contains the first day of the first month
* of a year, getMinimalDaysInFirstWeek returns 1. If the minimal days required must
* be a full week, getMinimalDaysInFirstWeek returns 7.
*
* @return The minimal days required in the first week of the year.
* @stable ICU 2.0
*/
uint8_t getMinimalDaysInFirstWeek(void) const;
/**
* Gets the minimum value for the given time field. e.g., for Gregorian
* DAY_OF_MONTH, 1.
*
* @param field The given time field.
* @return The minimum value for the given time field.
* @deprecated ICU 2.6. Use getMinimum(UCalendarDateFields field) instead.
*/
virtual int32_t getMinimum(EDateFields field) const;
/**
* Gets the minimum value for the given time field. e.g., for Gregorian
* DAY_OF_MONTH, 1.
*
* @param field The given time field.
* @return The minimum value for the given time field.
* @stable ICU 2.6.
*/
virtual int32_t getMinimum(UCalendarDateFields field) const;
/**
* Gets the maximum value for the given time field. e.g. for Gregorian DAY_OF_MONTH,
* 31.
*
* @param field The given time field.
* @return The maximum value for the given time field.
* @deprecated ICU 2.6. Use getMaximum(UCalendarDateFields field) instead.
*/
virtual int32_t getMaximum(EDateFields field) const;
/**
* Gets the maximum value for the given time field. e.g. for Gregorian DAY_OF_MONTH,
* 31.
*
* @param field The given time field.
* @return The maximum value for the given time field.
* @stable ICU 2.6.
*/
virtual int32_t getMaximum(UCalendarDateFields field) const;
/**
* Gets the highest minimum value for the given field if varies. Otherwise same as
* getMinimum(). For Gregorian, no difference.
*
* @param field The given time field.
* @return The highest minimum value for the given time field.
* @deprecated ICU 2.6. Use getGreatestMinimum(UCalendarDateFields field) instead.
*/
virtual int32_t getGreatestMinimum(EDateFields field) const;
/**
* Gets the highest minimum value for the given field if varies. Otherwise same as
* getMinimum(). For Gregorian, no difference.
*
* @param field The given time field.
* @return The highest minimum value for the given time field.
* @stable ICU 2.6.
*/
virtual int32_t getGreatestMinimum(UCalendarDateFields field) const;
/**
* Gets the lowest maximum value for the given field if varies. Otherwise same as
* getMaximum(). e.g., for Gregorian DAY_OF_MONTH, 28.
*
* @param field The given time field.
* @return The lowest maximum value for the given time field.
* @deprecated ICU 2.6. Use getLeastMaximum(UCalendarDateFields field) instead.
*/
virtual int32_t getLeastMaximum(EDateFields field) const;
/**
* Gets the lowest maximum value for the given field if varies. Otherwise same as
* getMaximum(). e.g., for Gregorian DAY_OF_MONTH, 28.
*
* @param field The given time field.
* @return The lowest maximum value for the given time field.
* @stable ICU 2.6.
*/
virtual int32_t getLeastMaximum(UCalendarDateFields field) const;
/**
* Return the minimum value that this field could have, given the current date.
* For the Gregorian calendar, this is the same as getMinimum() and getGreatestMinimum().
*
* The version of this function on Calendar uses an iterative algorithm to determine the
* actual minimum value for the field. There is almost always a more efficient way to
* accomplish this (in most cases, you can simply return getMinimum()). GregorianCalendar
* overrides this function with a more efficient implementation.
*
* @param field the field to determine the minimum of
* @param status Fill-in parameter which receives the status of this operation.
* @return the minimum of the given field for the current date of this Calendar
* @deprecated ICU 2.6. Use getActualMinimum(UCalendarDateFields field, UErrorCode& status) instead.
*/
int32_t getActualMinimum(EDateFields field, UErrorCode& status) const;
/**
* Return the minimum value that this field could have, given the current date.
* For the Gregorian calendar, this is the same as getMinimum() and getGreatestMinimum().
*
* The version of this function on Calendar uses an iterative algorithm to determine the
* actual minimum value for the field. There is almost always a more efficient way to
* accomplish this (in most cases, you can simply return getMinimum()). GregorianCalendar
* overrides this function with a more efficient implementation.
*
* @param field the field to determine the minimum of
* @param status Fill-in parameter which receives the status of this operation.
* @return the minimum of the given field for the current date of this Calendar
* @stable ICU 2.6.
*/
virtual int32_t getActualMinimum(UCalendarDateFields field, UErrorCode& status) const;
/**
* Return the maximum value that this field could have, given the current date.
* For example, with the date "Feb 3, 1997" and the DAY_OF_MONTH field, the actual
* maximum would be 28; for "Feb 3, 1996" it s 29. Similarly for a Hebrew calendar,
* for some years the actual maximum for MONTH is 12, and for others 13.
*
* The version of this function on Calendar uses an iterative algorithm to determine the
* actual maximum value for the field. There is almost always a more efficient way to