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 */
29struct ZRule;
30typedef 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 */
36struct IZRule;
37typedef 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 */
43struct AZRule;
44typedef 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 */
57U_CAPI void U_EXPORT2
58zrule_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 */
67U_CAPI UBool U_EXPORT2
68zrule_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 */
76U_CAPI void U_EXPORT2
77zrule_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 */
84U_CAPI int32_t U_EXPORT2
85zrule_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 */
93U_CAPI int32_t U_EXPORT2
94zrule_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 */
104U_CAPI UBool U_EXPORT2
105zrule_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 */
120U_CAPI IZRule* U_EXPORT2
121izrule_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 */
128U_CAPI void U_EXPORT2
129izrule_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 */
136U_CAPI IZRule* U_EXPORT2
137izrule_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 */
146U_CAPI UBool U_EXPORT2
147izrule_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 */
155U_CAPI void U_EXPORT2
156izrule_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 */
163U_CAPI int32_t U_EXPORT2
164izrule_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 */
172U_CAPI int32_t U_EXPORT2
173izrule_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 */
183U_CAPI UBool U_EXPORT2
184izrule_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 */
197U_CAPI UBool U_EXPORT2
198izrule_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 */
212U_CAPI UBool U_EXPORT2
213izrule_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 */
230U_CAPI UBool U_EXPORT2
231izrule_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 */
248U_CAPI UBool U_EXPORT2
249izrule_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 */
264U_CAPI UClassID U_EXPORT2
265izrule_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 */
278U_CAPI UClassID U_EXPORT2
279izrule_getDynamicClassID(IZRule* rule);
280
281#endif
282
283#endif
284