1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 *******************************************************************************
5 * Copyright (C) 2009-2016, International Business Machines Corporation and
6 * others. All Rights Reserved.
7 *******************************************************************************
8 */
9 #ifndef __ZRULE_H
10 #define __ZRULE_H
11 
12 /**
13  * \file
14  * \brief C API: Time zone rule classes
15  */
16 
17 #include "unicode/utypes.h"
18 
19 #if !UCONFIG_NO_FORMATTING
20 
21 #include "unicode/uobject.h"
22 
23 #ifndef UCNV_H
24 
25 /**
26  * A TimeZoneRule.  Use the zrule_* API to manipulate.  Create with
27  * zrule_open*, and destroy with zrule_close.
28  */
29 struct ZRule;
30 typedef struct ZRule ZRule;
31 
32 /**
33  * An InitialTimeZoneRule.  Use the izrule_* API to manipulate.  Create with
34  * izrule_open*, and destroy with izrule_close.
35  */
36 struct IZRule;
37 typedef struct IZRule IZRule;
38 
39 /**
40  * An AnnualTimeZoneRule.  Use the azrule_* API to manipulate.  Create with
41  * azrule_open*, and destroy with azrule_close.
42  */
43 struct AZRule;
44 typedef struct AZRule AZRule;
45 
46 #endif
47 
48 /*********************************************************************
49  * ZRule API
50  *********************************************************************/
51 
52 /**
53  * Disposes of the storage used by a ZRule object.  This function should
54  * be called exactly once for objects returned by zrule_open*.
55  * @param set the object to dispose of
56  */
57 U_CAPI void U_EXPORT2
58 zrule_close(ZRule* rule);
59 
60 /**
61  * Returns true if rule1 is identical to rule2
62  * and vis versa.
63  * @param rule1 to be checked for containment
64  * @param rule2 to be checked for containment
65  * @return true if the test condition is met
66  */
67 U_CAPI UBool U_EXPORT2
68 zrule_equals(const ZRule* rule1, const ZRule* rule2);
69 
70 /**
71  * Fills in "name" with the name of this time zone.
72  * @param rule, the Zrule to use
73  * @param name  Receives the name of this time zone.
74  * @param nameLength, length of the returned name
75  */
76 U_CAPI void U_EXPORT2
77 zrule_getName(ZRule* rule, UChar* name, int32_t nameLength);
78 
79 /**
80  * Gets the standard time offset.
81  * @param rule, the Zrule to use
82  * @return  The standard time offset from UTC in milliseconds.
83  */
84 U_CAPI int32_t U_EXPORT2
85 zrule_getRawOffset(ZRule* rule);
86 
87 /**
88  * Gets the amount of daylight saving delta time from the standard time.
89  * @param rule, the Zrule to use
90  * @return  The amount of daylight saving offset used by this rule
91  *          in milliseconds.
92  */
93 U_CAPI int32_t U_EXPORT2
94 zrule_getDSTSavings(ZRule* rule);
95 
96 /**
97  * Returns if this rule represents the same rule and offsets as another.
98  * When two ZRule objects differ only its names, this method
99  * returns true.
100  * @param rule1 to be checked for containment
101  * @param rule2 to be checked for containment
102  * @return  true if the other <code>TimeZoneRule</code> is the same as this one.
103  */
104 U_CAPI UBool U_EXPORT2
105 zrule_isEquivalentTo(ZRule* rule1,  ZRule* rule2);
106 
107 /*********************************************************************
108  * IZRule API
109  *********************************************************************/
110 
111 /**
112  * Constructs an IZRule with the name, the GMT offset of its
113  * standard time and the amount of daylight saving offset adjustment.
114  * @param name          The time zone name.
115  * @param nameLength    The length of the time zone name.
116  * @param rawOffset     The UTC offset of its standard time in milliseconds.
117  * @param dstSavings    The amount of daylight saving offset adjustment in milliseconds.
118  *                      If this ia a rule for standard time, the value of this argument is 0.
119  */
120 U_CAPI IZRule* U_EXPORT2
121 izrule_open(const UChar* name, int32_t nameLength, int32_t rawOffset, int32_t dstSavings);
122 
123 /**
124  * Disposes of the storage used by a IZRule object.  This function should
125  * be called exactly once for objects returned by izrule_open*.
126  * @param set the object to dispose of
127  */
128 U_CAPI void U_EXPORT2
129 izrule_close(IZRule* rule);
130 
131 /**
132  * Returns a copy of this object.
133  * @param rule the original IZRule
134  * @return the newly allocated copy of the IZRule
135  */
136 U_CAPI IZRule* U_EXPORT2
137 izrule_clone(IZRule *rule);
138 
139 /**
140  * Returns true if rule1 is identical to rule2
141  * and vis versa.
142  * @param rule1 to be checked for containment
143  * @param rule2 to be checked for containment
144  * @return true if the test condition is met
145  */
146 U_CAPI UBool U_EXPORT2
147 izrule_equals(const IZRule* rule1, const IZRule* rule2);
148 
149 /**
150  * Fills in "name" with the name of this time zone.
151  * @param rule, the IZrule to use
152  * @param name  Receives the name of this time zone.
153  * @param nameLength, length of the returned name
154  */
155 U_CAPI void U_EXPORT2
156 izrule_getName(IZRule* rule, UChar* & name, int32_t & nameLength);
157 
158 /**
159  * Gets the standard time offset.
160  * @param rule, the IZrule to use
161  * @return  The standard time offset from UTC in milliseconds.
162  */
163 U_CAPI int32_t U_EXPORT2
164 izrule_getRawOffset(IZRule* rule);
165 
166 /**
167  * Gets the amount of daylight saving delta time from the standard time.
168  * @param rule, the IZrule to use
169  * @return  The amount of daylight saving offset used by this rule
170  *          in milliseconds.
171  */
172 U_CAPI int32_t U_EXPORT2
173 izrule_getDSTSavings(IZRule* rule);
174 
175 /**
176  * Returns if this rule represents the same rule and offsets as another.
177  * When two IZRule objects differ only its names, this method
178  * returns true.
179  * @param rule1 to be checked for containment
180  * @param rule2 to be checked for containment
181  * @return  true if the other <code>TimeZoneRule</code> is the same as this one.
182  */
183 U_CAPI UBool U_EXPORT2
184 izrule_isEquivalentTo(IZRule* rule1,  IZRule* rule2);
185 
186 /**
187  * Gets the very first time when this rule takes effect.
188  * @param rule              The IZrule to use
189  * @param prevRawOffset     The standard time offset from UTC before this rule
190  *                          takes effect in milliseconds.
191  * @param prevDSTSavings    The amount of daylight saving offset from the
192  *                          standard time.
193  * @param result            Receives the very first time when this rule takes effect.
194  * @return  true if the start time is available.  When false is returned, output parameter
195  *          "result" is unchanged.
196  */
197 U_CAPI UBool U_EXPORT2
198 izrule_getFirstStart(IZRule* rule, int32_t prevRawOffset, int32_t prevDSTSavings,
199                     UDate& result);
200 
201 /**
202  * Gets the final time when this rule takes effect.
203  * @param rule              The IZrule to use
204  * @param prevRawOffset     The standard time offset from UTC before this rule
205  *                          takes effect in milliseconds.
206  * @param prevDSTSavings    The amount of daylight saving offset from the
207  *                          standard time.
208  * @param result            Receives the final time when this rule takes effect.
209  * @return  true if the start time is available.  When false is returned, output parameter
210  *          "result" is unchanged.
211  */
212 U_CAPI UBool U_EXPORT2
213 izrule_getFinalStart(IZRule* rule, int32_t prevRawOffset, int32_t prevDSTSavings,
214                     UDate& result);
215 
216 /**
217  * Gets the first time when this rule takes effect after the specified time.
218  * @param rule              The IZrule to use
219  * @param base              The first start time after this base time will be returned.
220  * @param prevRawOffset     The standard time offset from UTC before this rule
221  *                          takes effect in milliseconds.
222  * @param prevDSTSavings    The amount of daylight saving offset from the
223  *                          standard time.
224  * @param inclusive         Whether the base time is inclusive or not.
225  * @param result            Receives The first time when this rule takes effect after
226  *                          the specified base time.
227  * @return  true if the start time is available.  When false is returned, output parameter
228  *          "result" is unchanged.
229  */
230 U_CAPI UBool U_EXPORT2
231 izrule_getNextStart(IZRule* rule, UDate base, int32_t prevRawOffset,
232                    int32_t prevDSTSavings, UBool inclusive, UDate& result);
233 
234 /**
235  * Gets the most recent time when this rule takes effect before the specified time.
236  * @param rule              The IZrule to use
237  * @param base              The most recent time before this base time will be returned.
238  * @param prevRawOffset     The standard time offset from UTC before this rule
239  *                          takes effect in milliseconds.
240  * @param prevDSTSavings    The amount of daylight saving offset from the
241  *                          standard time.
242  * @param inclusive         Whether the base time is inclusive or not.
243  * @param result            Receives The most recent time when this rule takes effect before
244  *                          the specified base time.
245  * @return  true if the start time is available.  When false is returned, output parameter
246  *          "result" is unchanged.
247  */
248 U_CAPI UBool U_EXPORT2
249 izrule_getPreviousStart(IZRule* rule, UDate base, int32_t prevRawOffset,
250                        int32_t prevDSTSavings, UBool inclusive, UDate& result);
251 
252 
253 /**
254  * Return the class ID for this class. This is useful only for comparing to
255  * a return value from getDynamicClassID(). For example:
256  * <pre>
257  * .   Base* polymorphic_pointer = createPolymorphicObject();
258  * .   if (polymorphic_pointer->getDynamicClassID() ==
259  * .       erived::getStaticClassID()) ...
260  * </pre>
261  * @param rule              The IZrule to use
262  * @return          The class ID for all objects of this class.
263  */
264 U_CAPI UClassID U_EXPORT2
265 izrule_getStaticClassID(IZRule* rule);
266 
267 /**
268  * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
269  * method is to implement a simple version of RTTI, since not all C++
270  * compilers support genuine RTTI. Polymorphic operator==() and clone()
271  * methods call this method.
272  *
273  * @param rule              The IZrule to use
274  * @return          The class ID for this object. All objects of a
275  *                  given class have the same class ID.  Objects of
276  *                  other classes have different class IDs.
277  */
278 U_CAPI UClassID U_EXPORT2
279 izrule_getDynamicClassID(IZRule* rule);
280 
281 #endif
282 
283 #endif
284