src/third_party/icu/source/i18n/unicode/basictz.h

   1 /*
   2 *******************************************************************************
   3 * Copyright (C) 2007-2013, International Business Machines Corporation and
   4 * others. All Rights Reserved.
   5 *******************************************************************************
   6 */
   7 #ifndef BASICTZ_H
   8 #define BASICTZ_H
   9
  10 /**
  11  * \file
  12  * \brief C++ API: ICU TimeZone base class
  13  */
  14
  15 #include "unicode/utypes.h"
  16
  17 #if !UCONFIG_NO_FORMATTING
  18
  19 #include "unicode/timezone.h"
  20 #include "unicode/tzrule.h"
  21 #include "unicode/tztrans.h"
  22
  23 U_NAMESPACE_BEGIN
  24
  25 // forward declarations
  26 class UVector;
  27
  28 /**
  29  * <code>BasicTimeZone</code> is an abstract class extending <code>TimeZone</code>.
  30  * This class provides some additional methods to access time zone transitions and rules.
  31  * All ICU <code>TimeZone</code> concrete subclasses extend this class.
  32  * @stable ICU 3.8
  33  */
  34 class U_I18N_API BasicTimeZone: public TimeZone {
  35 public:
  36     /**
  37      * Destructor.
  38      * @stable ICU 3.8
  39      */
  40     virtual ~BasicTimeZone();
  41
  42     /**
  43      * Gets the first time zone transition after the base time.
  44      * @param base      The base time.
  45      * @param inclusive Whether the base time is inclusive or not.
  46      * @param result    Receives the first transition after the base time.
  47      * @return  TRUE if the transition is found.
  48      * @stable ICU 3.8
  49      */
  50     virtual UBool getNextTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const = 0;
  51
  52     /**
  53      * Gets the most recent time zone transition before the base time.
  54      * @param base      The base time.
  55      * @param inclusive Whether the base time is inclusive or not.
  56      * @param result    Receives the most recent transition before the base time.
  57      * @return  TRUE if the transition is found.
  58      * @stable ICU 3.8
  59      */
  60     virtual UBool getPreviousTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const = 0;
  61
  62     /**
  63      * Checks if the time zone has equivalent transitions in the time range.
  64      * This method returns true when all of transition times, from/to standard
  65      * offsets and DST savings used by this time zone match the other in the
  66      * time range.
  67      * @param tz    The <code>BasicTimeZone</code> object to be compared with.
  68      * @param start The start time of the evaluated time range (inclusive)
  69      * @param end   The end time of the evaluated time range (inclusive)
  70      * @param ignoreDstAmount
  71      *              When true, any transitions with only daylight saving amount
  72      *              changes will be ignored, except either of them is zero.
  73      *              For example, a transition from rawoffset 3:00/dstsavings 1:00
  74      *              to rawoffset 2:00/dstsavings 2:00 is excluded from the comparison,
  75      *              but a transtion from rawoffset 2:00/dstsavings 1:00 to
  76      *              rawoffset 3:00/dstsavings 0:00 is included.
  77      * @param ec    Output param to filled in with a success or an error.
  78      * @return      true if the other time zone has the equivalent transitions in the
  79      *              time range.
  80      * @stable ICU 3.8
  81      */
  82     virtual UBool hasEquivalentTransitions(const BasicTimeZone& tz, UDate start, UDate end,
  83         UBool ignoreDstAmount, UErrorCode& ec) const;
  84
  85     /**
  86      * Returns the number of <code>TimeZoneRule</code>s which represents time transitions,
  87      * for this time zone, that is, all <code>TimeZoneRule</code>s for this time zone except
  88      * <code>InitialTimeZoneRule</code>.  The return value range is 0 or any positive value.
  89      * @param status    Receives error status code.
  90      * @return The number of <code>TimeZoneRule</code>s representing time transitions.
  91      * @stable ICU 3.8
  92      */
  93     virtual int32_t countTransitionRules(UErrorCode& status) const = 0;
  94
  95     /**
  96      * Gets the <code>InitialTimeZoneRule</code> and the set of <code>TimeZoneRule</code>
  97      * which represent time transitions for this time zone.  On successful return,
  98      * the argument initial points to non-NULL <code>InitialTimeZoneRule</code> and
  99      * the array trsrules is filled with 0 or multiple <code>TimeZoneRule</code>
 100      * instances up to the size specified by trscount.  The results are referencing the
 101      * rule instance held by this time zone instance.  Therefore, after this time zone
 102      * is destructed, they are no longer available.
 103      * @param initial       Receives the initial timezone rule
 104      * @param trsrules      Receives the timezone transition rules
 105      * @param trscount      On input, specify the size of the array 'transitions' receiving
 106      *                      the timezone transition rules.  On output, actual number of
 107      *                      rules filled in the array will be set.
 108      * @param status        Receives error status code.
 109      * @stable ICU 3.8
 110      */
 111     virtual void getTimeZoneRules(const InitialTimeZoneRule*& initial,
 112         const TimeZoneRule* trsrules[], int32_t& trscount, UErrorCode& status) const = 0;
 113
 114     /**
 115      * Gets the set of time zone rules valid at the specified time.  Some known external time zone
 116      * implementations are not capable to handle historic time zone rule changes.  Also some
 117      * implementations can only handle certain type of rule definitions.
 118      * If this time zone does not use any daylight saving time within about 1 year from the specified
 119      * time, only the <code>InitialTimeZone</code> is returned.  Otherwise, the rule for standard
 120      * time and daylight saving time transitions are returned in addition to the
 121      * <code>InitialTimeZoneRule</code>.  The standard and daylight saving time transition rules are
 122      * represented by <code>AnnualTimeZoneRule</code> with <code>DateTimeRule::DOW</code> for its date
 123      * rule and <code>DateTimeRule::WALL_TIME</code> for its time rule.  Because daylight saving time
 124      * rule is changing time to time in many time zones and also mapping a transition time rule to
 125      * different type is lossy transformation, the set of rules returned by this method may be valid
 126      * for short period of time.
 127      * The time zone rule objects returned by this method is owned by the caller, so the caller is
 128      * responsible for deleting them after use.
 129      * @param date      The date used for extracting time zone rules.
 130      * @param initial   Receives the <code>InitialTimeZone</code>, always not NULL.
 131      * @param std       Receives the <code>AnnualTimeZoneRule</code> for standard time transitions.
 132      *                  When this time time zone does not observe daylight saving times around the
 133      *                  specified date, NULL is set.
 134      * @param dst       Receives the <code>AnnualTimeZoneRule</code> for daylight saving time
 135      *                  transitions.  When this time zone does not observer daylight saving times
 136      *                  around the specified date, NULL is set.
 137      * @param status    Receives error status code.
 138      * @stable ICU 3.8
 139      */
 140     virtual void getSimpleRulesNear(UDate date, InitialTimeZoneRule*& initial,
 141         AnnualTimeZoneRule*& std, AnnualTimeZoneRule*& dst, UErrorCode& status) const;
 142
 143
 144 #ifndef U_HIDE_INTERNAL_API
 145     /**
 146      * The time type option bit flags used by getOffsetFromLocal
 147      * @internal
 148      */
 149     enum {
 150         kStandard = 0x01,
 151         kDaylight = 0x03,
 152         kFormer = 0x04,
 153         kLatter = 0x0C
 154     };
 155 #endif  /* U_HIDE_INTERNAL_API */
 156
 157     /**
 158      * Get time zone offsets from local wall time.
 159      * @internal
 160      */
 161     virtual void getOffsetFromLocal(UDate date, int32_t nonExistingTimeOpt, int32_t duplicatedTimeOpt,
 162         int32_t& rawOffset, int32_t& dstOffset, UErrorCode& status) const;
 163
 164 protected:
 165
 166 #ifndef U_HIDE_INTERNAL_API
 167     /**
 168      * The time type option bit masks used by getOffsetFromLocal
 169      * @internal
 170      */
 171     enum {
 172         kStdDstMask = kDaylight,
 173         kFormerLatterMask = kLatter
 174     };
 175 #endif  /* U_HIDE_INTERNAL_API */
 176
 177     /**
 178      * Default constructor.
 179      * @stable ICU 3.8
 180      */
 181     BasicTimeZone();
 182
 183     /**
 184      * Construct a timezone with a given ID.
 185      * @param id a system time zone ID
 186      * @stable ICU 3.8
 187      */
 188     BasicTimeZone(const UnicodeString &id);
 189
 190     /**
 191      * Copy constructor.
 192      * @param source the object to be copied.
 193      * @stable ICU 3.8
 194      */
 195     BasicTimeZone(const BasicTimeZone& source);
 196
 197     /**
 198      * Gets the set of TimeZoneRule instances applicable to the specified time and after.
 199      * @param start     The start date used for extracting time zone rules
 200      * @param initial   Receives the InitialTimeZone, always not NULL
 201      * @param transitionRules   Receives the transition rules, could be NULL
 202      * @param status    Receives error status code
 203      */
 204     void getTimeZoneRulesAfter(UDate start, InitialTimeZoneRule*& initial, UVector*& transitionRules,
 205         UErrorCode& status) const;
 206 };
 207
 208 U_NAMESPACE_END
 209
 210 #endif /* #if !UCONFIG_NO_FORMATTING */
 211
 212 #endif // BASICTZ_H
 213
 214 //eof