DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (d38398e5144e)

VCS Links

BasicTimeZone

Macros

Line Code
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
// Copyright (C) 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
*******************************************************************************
* Copyright (C) 2007-2013, International Business Machines Corporation and
* others. All Rights Reserved.
*******************************************************************************
*/
#ifndef BASICTZ_H
#define BASICTZ_H

/**
 * \file 
 * \brief C++ API: ICU TimeZone base class
 */

#include "unicode/utypes.h"

#if !UCONFIG_NO_FORMATTING

#include "unicode/timezone.h"
#include "unicode/tzrule.h"
#include "unicode/tztrans.h"

U_NAMESPACE_BEGIN

// forward declarations
class UVector;

/**
 * <code>BasicTimeZone</code> is an abstract class extending <code>TimeZone</code>.
 * This class provides some additional methods to access time zone transitions and rules.
 * All ICU <code>TimeZone</code> concrete subclasses extend this class.
 * @stable ICU 3.8
 */
class U_I18N_API BasicTimeZone: public TimeZone {
public:
    /**
     * Destructor.
     * @stable ICU 3.8
     */
    virtual ~BasicTimeZone();

    /**
     * Gets the first time zone transition after the base time.
     * @param base      The base time.
     * @param inclusive Whether the base time is inclusive or not.
     * @param result    Receives the first transition after the base time.
     * @return  TRUE if the transition is found.
     * @stable ICU 3.8
     */
    virtual UBool getNextTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const = 0;

    /**
     * Gets the most recent time zone transition before the base time.
     * @param base      The base time.
     * @param inclusive Whether the base time is inclusive or not.
     * @param result    Receives the most recent transition before the base time.
     * @return  TRUE if the transition is found.
     * @stable ICU 3.8
     */
    virtual UBool getPreviousTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const = 0;

    /**
     * Checks if the time zone has equivalent transitions in the time range.
     * This method returns true when all of transition times, from/to standard
     * offsets and DST savings used by this time zone match the other in the
     * time range.
     * @param tz    The <code>BasicTimeZone</code> object to be compared with.
     * @param start The start time of the evaluated time range (inclusive)
     * @param end   The end time of the evaluated time range (inclusive)
     * @param ignoreDstAmount
     *              When true, any transitions with only daylight saving amount
     *              changes will be ignored, except either of them is zero.
     *              For example, a transition from rawoffset 3:00/dstsavings 1:00
     *              to rawoffset 2:00/dstsavings 2:00 is excluded from the comparison,
     *              but a transtion from rawoffset 2:00/dstsavings 1:00 to
     *              rawoffset 3:00/dstsavings 0:00 is included.
     * @param ec    Output param to filled in with a success or an error.
     * @return      true if the other time zone has the equivalent transitions in the
     *              time range.
     * @stable ICU 3.8
     */
    virtual UBool hasEquivalentTransitions(const BasicTimeZone& tz, UDate start, UDate end,
        UBool ignoreDstAmount, UErrorCode& ec) const;

    /**
     * Returns the number of <code>TimeZoneRule</code>s which represents time transitions,
     * for this time zone, that is, all <code>TimeZoneRule</code>s for this time zone except
     * <code>InitialTimeZoneRule</code>.  The return value range is 0 or any positive value.
     * @param status    Receives error status code.
     * @return The number of <code>TimeZoneRule</code>s representing time transitions.
     * @stable ICU 3.8
     */
    virtual int32_t countTransitionRules(UErrorCode& status) const = 0;

    /**
     * Gets the <code>InitialTimeZoneRule</code> and the set of <code>TimeZoneRule</code>
     * which represent time transitions for this time zone.  On successful return,
     * the argument initial points to non-NULL <code>InitialTimeZoneRule</code> and
     * the array trsrules is filled with 0 or multiple <code>TimeZoneRule</code>
     * instances up to the size specified by trscount.  The results are referencing the
     * rule instance held by this time zone instance.  Therefore, after this time zone
     * is destructed, they are no longer available.
     * @param initial       Receives the initial timezone rule
     * @param trsrules      Receives the timezone transition rules
     * @param trscount      On input, specify the size of the array 'transitions' receiving
     *                      the timezone transition rules.  On output, actual number of
     *                      rules filled in the array will be set.
     * @param status        Receives error status code.
     * @stable ICU 3.8
     */
    virtual void getTimeZoneRules(const InitialTimeZoneRule*& initial,
        const TimeZoneRule* trsrules[], int32_t& trscount, UErrorCode& status) const = 0;

    /**
     * Gets the set of time zone rules valid at the specified time.  Some known external time zone
     * implementations are not capable to handle historic time zone rule changes.  Also some
     * implementations can only handle certain type of rule definitions.
     * If this time zone does not use any daylight saving time within about 1 year from the specified
     * time, only the <code>InitialTimeZone</code> is returned.  Otherwise, the rule for standard
     * time and daylight saving time transitions are returned in addition to the
     * <code>InitialTimeZoneRule</code>.  The standard and daylight saving time transition rules are
     * represented by <code>AnnualTimeZoneRule</code> with <code>DateTimeRule::DOW</code> for its date
     * rule and <code>DateTimeRule::WALL_TIME</code> for its time rule.  Because daylight saving time
     * rule is changing time to time in many time zones and also mapping a transition time rule to
     * different type is lossy transformation, the set of rules returned by this method may be valid
     * for short period of time.
     * The time zone rule objects returned by this method is owned by the caller, so the caller is
     * responsible for deleting them after use.
     * @param date      The date used for extracting time zone rules.
     * @param initial   Receives the <code>InitialTimeZone</code>, always not NULL.
     * @param std       Receives the <code>AnnualTimeZoneRule</code> for standard time transitions.
     *                  When this time time zone does not observe daylight saving times around the
     *                  specified date, NULL is set.
     * @param dst       Receives the <code>AnnualTimeZoneRule</code> for daylight saving time
     *                  transitions.  When this time zone does not observer daylight saving times
     *                  around the specified date, NULL is set.
     * @param status    Receives error status code.
     * @stable ICU 3.8
     */
    virtual void getSimpleRulesNear(UDate date, InitialTimeZoneRule*& initial,
        AnnualTimeZoneRule*& std, AnnualTimeZoneRule*& dst, UErrorCode& status) const;


#ifndef U_HIDE_INTERNAL_API
    /**
     * The time type option bit flags used by getOffsetFromLocal
     * @internal
     */
    enum {
        kStandard = 0x01,
        kDaylight = 0x03,
        kFormer = 0x04,
        kLatter = 0x0C
    };
#endif  /* U_HIDE_INTERNAL_API */

    /**
     * Get time zone offsets from local wall time.
     * @internal
     */
    virtual void getOffsetFromLocal(UDate date, int32_t nonExistingTimeOpt, int32_t duplicatedTimeOpt,
        int32_t& rawOffset, int32_t& dstOffset, UErrorCode& status) const;

protected:

#ifndef U_HIDE_INTERNAL_API
    /**
     * The time type option bit masks used by getOffsetFromLocal
     * @internal
     */
    enum {
        kStdDstMask = kDaylight,
        kFormerLatterMask = kLatter
    };
#endif  /* U_HIDE_INTERNAL_API */

    /**
     * Default constructor.
     * @stable ICU 3.8
     */
    BasicTimeZone();

    /**
     * Construct a timezone with a given ID.
     * @param id a system time zone ID
     * @stable ICU 3.8
     */
    BasicTimeZone(const UnicodeString &id);

    /**
     * Copy constructor.
     * @param source the object to be copied.
     * @stable ICU 3.8
     */
    BasicTimeZone(const BasicTimeZone& source);

    /**
     * Gets the set of TimeZoneRule instances applicable to the specified time and after.
     * @param start     The start date used for extracting time zone rules
     * @param initial   Receives the InitialTimeZone, always not NULL
     * @param transitionRules   Receives the transition rules, could be NULL
     * @param status    Receives error status code
     */
    void getTimeZoneRulesAfter(UDate start, InitialTimeZoneRule*& initial, UVector*& transitionRules,
        UErrorCode& status) const;
};

U_NAMESPACE_END

#endif /* #if !UCONFIG_NO_FORMATTING */

#endif // BASICTZ_H

//eof