[apple/icu.git] / icuSources / i18n / zrule.h

// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
*******************************************************************************
* Copyright (C) 2009-2016, International Business Machines Corporation and
* others. All Rights Reserved.
*******************************************************************************
*/
#ifndef __ZRULE_H
#define __ZRULE_H

/**
 * \file 
 * \brief C API: Time zone rule classes
 */

#include "unicode/utypes.h"

#if !UCONFIG_NO_FORMATTING

#include "unicode/uobject.h"

#ifndef UCNV_H

/**
 * A TimeZoneRule.  Use the zrule_* API to manipulate.  Create with
 * zrule_open*, and destroy with zrule_close.
 */
struct ZRule;
typedef struct ZRule ZRule;

/**
 * An InitialTimeZoneRule.  Use the izrule_* API to manipulate.  Create with
 * izrule_open*, and destroy with izrule_close.
 */
struct IZRule;
typedef struct IZRule IZRule;

/**
 * An AnnualTimeZoneRule.  Use the azrule_* API to manipulate.  Create with
 * azrule_open*, and destroy with azrule_close.
 */
struct AZRule;
typedef struct AZRule AZRule;

#endif

/*********************************************************************
 * ZRule API
 *********************************************************************/

/**
 * Disposes of the storage used by a ZRule object.  This function should
 * be called exactly once for objects returned by zrule_open*.
 * @param set the object to dispose of
 */
U_CAPI void U_EXPORT2
zrule_close(ZRule* rule);

/**
 * Returns true if rule1 is identical to rule2
 * and vis versa.
 * @param rule1 to be checked for containment
 * @param rule2 to be checked for containment
 * @return true if the test condition is met
 */
U_CAPI UBool U_EXPORT2
zrule_equals(const ZRule* rule1, const ZRule* rule2);

/**
 * Fills in "name" with the name of this time zone.
 * @param rule, the Zrule to use
 * @param name  Receives the name of this time zone.
 * @param nameLength, length of the returned name
 */
U_CAPI void U_EXPORT2
zrule_getName(ZRule* rule, UChar* name, int32_t nameLength);

/**
 * Gets the standard time offset.
 * @param rule, the Zrule to use
 * @return  The standard time offset from UTC in milliseconds.
 */
U_CAPI int32_t U_EXPORT2
zrule_getRawOffset(ZRule* rule);

/**
 * Gets the amount of daylight saving delta time from the standard time.
 * @param rule, the Zrule to use
 * @return  The amount of daylight saving offset used by this rule
 *          in milliseconds.
 */
U_CAPI int32_t U_EXPORT2
zrule_getDSTSavings(ZRule* rule);

/**
 * Returns if this rule represents the same rule and offsets as another.
 * When two ZRule objects differ only its names, this method
 * returns true.
 * @param rule1 to be checked for containment
 * @param rule2 to be checked for containment
 * @return  true if the other <code>TimeZoneRule</code> is the same as this one.
 */
U_CAPI UBool U_EXPORT2
zrule_isEquivalentTo(ZRule* rule1,  ZRule* rule2);

/*********************************************************************
 * IZRule API
 *********************************************************************/

/**
 * Constructs an IZRule with the name, the GMT offset of its
 * standard time and the amount of daylight saving offset adjustment.
 * @param name          The time zone name.
 * @param nameLength    The length of the time zone name.
 * @param rawOffset     The UTC offset of its standard time in milliseconds.
 * @param dstSavings    The amount of daylight saving offset adjustment in milliseconds.
 *                      If this ia a rule for standard time, the value of this argument is 0.
 */
U_CAPI IZRule* U_EXPORT2
izrule_open(const UChar* name, int32_t nameLength, int32_t rawOffset, int32_t dstSavings);

/**
 * Disposes of the storage used by a IZRule object.  This function should
 * be called exactly once for objects returned by izrule_open*.
 * @param set the object to dispose of
 */
U_CAPI void U_EXPORT2
izrule_close(IZRule* rule);

/**
 * Returns a copy of this object.
 * @param rule the original IZRule
 * @return the newly allocated copy of the IZRule
 */
U_CAPI IZRule* U_EXPORT2
izrule_clone(IZRule *rule);

/**
 * Returns true if rule1 is identical to rule2
 * and vis versa.
 * @param rule1 to be checked for containment
 * @param rule2 to be checked for containment
 * @return true if the test condition is met
 */
U_CAPI UBool U_EXPORT2
izrule_equals(const IZRule* rule1, const IZRule* rule2);

/**
 * Fills in "name" with the name of this time zone.
 * @param rule, the IZrule to use
 * @param name  Receives the name of this time zone.
 * @param nameLength, length of the returned name
 */
U_CAPI void U_EXPORT2
izrule_getName(IZRule* rule, UChar* & name, int32_t & nameLength);

/**
 * Gets the standard time offset.
 * @param rule, the IZrule to use
 * @return  The standard time offset from UTC in milliseconds.
 */
U_CAPI int32_t U_EXPORT2
izrule_getRawOffset(IZRule* rule);

/**
 * Gets the amount of daylight saving delta time from the standard time.
 * @param rule, the IZrule to use
 * @return  The amount of daylight saving offset used by this rule
 *          in milliseconds.
 */
U_CAPI int32_t U_EXPORT2
izrule_getDSTSavings(IZRule* rule);

/**
 * Returns if this rule represents the same rule and offsets as another.
 * When two IZRule objects differ only its names, this method
 * returns true.
 * @param rule1 to be checked for containment
 * @param rule2 to be checked for containment
 * @return  true if the other <code>TimeZoneRule</code> is the same as this one.
 */
U_CAPI UBool U_EXPORT2
izrule_isEquivalentTo(IZRule* rule1,  IZRule* rule2);

/**
 * Gets the very first time when this rule takes effect.
 * @param rule              The IZrule to use
 * @param prevRawOffset     The standard time offset from UTC before this rule
 *                          takes effect in milliseconds.
 * @param prevDSTSavings    The amount of daylight saving offset from the
 *                          standard time.
 * @param result            Receives the very first time when this rule takes effect.
 * @return  true if the start time is available.  When false is returned, output parameter
 *          "result" is unchanged.
 */
U_CAPI UBool U_EXPORT2
izrule_getFirstStart(IZRule* rule, int32_t prevRawOffset, int32_t prevDSTSavings, 
                    UDate& result);

/**
 * Gets the final time when this rule takes effect.
 * @param rule              The IZrule to use     
 * @param prevRawOffset     The standard time offset from UTC before this rule
 *                          takes effect in milliseconds.
 * @param prevDSTSavings    The amount of daylight saving offset from the
 *                          standard time.
 * @param result            Receives the final time when this rule takes effect.
 * @return  true if the start time is available.  When false is returned, output parameter
 *          "result" is unchanged.
 */
U_CAPI UBool U_EXPORT2
izrule_getFinalStart(IZRule* rule, int32_t prevRawOffset, int32_t prevDSTSavings, 
                    UDate& result);

/**
 * Gets the first time when this rule takes effect after the specified time.
 * @param rule              The IZrule to use
 * @param base              The first start time after this base time will be returned.
 * @param prevRawOffset     The standard time offset from UTC before this rule
 *                          takes effect in milliseconds.
 * @param prevDSTSavings    The amount of daylight saving offset from the
 *                          standard time.
 * @param inclusive         Whether the base time is inclusive or not.
 * @param result            Receives The first time when this rule takes effect after
 *                          the specified base time.
 * @return  true if the start time is available.  When false is returned, output parameter
 *          "result" is unchanged.
 */
U_CAPI UBool U_EXPORT2
izrule_getNextStart(IZRule* rule, UDate base, int32_t prevRawOffset, 
                   int32_t prevDSTSavings, UBool inclusive, UDate& result);

/**
 * Gets the most recent time when this rule takes effect before the specified time.
 * @param rule              The IZrule to use
 * @param base              The most recent time before this base time will be returned.
 * @param prevRawOffset     The standard time offset from UTC before this rule
 *                          takes effect in milliseconds.
 * @param prevDSTSavings    The amount of daylight saving offset from the
 *                          standard time.
 * @param inclusive         Whether the base time is inclusive or not.
 * @param result            Receives The most recent time when this rule takes effect before
 *                          the specified base time.
 * @return  true if the start time is available.  When false is returned, output parameter
 *          "result" is unchanged.
 */
U_CAPI UBool U_EXPORT2
izrule_getPreviousStart(IZRule* rule, UDate base, int32_t prevRawOffset, 
                       int32_t prevDSTSavings, UBool inclusive, UDate& result);


/**
 * Return the class ID for this class. This is useful only for comparing to
 * a return value from getDynamicClassID(). For example:
 * <pre>
 * .   Base* polymorphic_pointer = createPolymorphicObject();
 * .   if (polymorphic_pointer->getDynamicClassID() ==
 * .       erived::getStaticClassID()) ...
 * </pre>
 * @param rule              The IZrule to use
 * @return          The class ID for all objects of this class.
 */
U_CAPI UClassID U_EXPORT2
izrule_getStaticClassID(IZRule* rule);

/**
 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
 * method is to implement a simple version of RTTI, since not all C++
 * compilers support genuine RTTI. Polymorphic operator==() and clone()
 * methods call this method.
 *
 * @param rule              The IZrule to use
 * @return          The class ID for this object. All objects of a
 *                  given class have the same class ID.  Objects of
 *                  other classes have different class IDs.
 */
U_CAPI UClassID U_EXPORT2
izrule_getDynamicClassID(IZRule* rule);

#endif

#endif
Commit	Line	Data
f3c0d7a5 A	1	// © 2016 and later: Unicode, Inc. and others.
f3c0d7a5 A	2	// License & terms of use: http://www.unicode.org/copyright.html
729e4ab9 A	3	/*
729e4ab9 A	4	*******************************************************************************
2ca993e8 A	5	* Copyright (C) 2009-2016, International Business Machines Corporation and
2ca993e8 A	6	* others. All Rights Reserved.
729e4ab9 A	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
2ca993e8 A	21	#include "unicode/uobject.h"
2ca993e8 A	22
729e4ab9 A	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.
729e4ab9 A	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.
729e4ab9 A	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.
729e4ab9 A	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
729e4ab9	56	*/
4388f060	57	U_CAPI void U_EXPORT2
729e4ab9 A	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
729e4ab9	66	*/
4388f060	67	U_CAPI UBool U_EXPORT2
729e4ab9 A	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
729e4ab9	75	*/
4388f060	76	U_CAPI void U_EXPORT2
729e4ab9 A	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.
729e4ab9	83	*/
4388f060	84	U_CAPI int32_t U_EXPORT2
729e4ab9 A	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.
729e4ab9	92	*/
4388f060	93	U_CAPI int32_t U_EXPORT2
729e4ab9 A	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.
729e4ab9	103	*/
4388f060	104	U_CAPI UBool U_EXPORT2
729e4ab9 A	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.
729e4ab9	119	*/
4388f060	120	U_CAPI IZRule* U_EXPORT2
729e4ab9 A	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
729e4ab9	127	*/
4388f060	128	U_CAPI void U_EXPORT2
729e4ab9 A	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
729e4ab9	135	*/
4388f060	136	U_CAPI IZRule* U_EXPORT2
729e4ab9 A	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
729e4ab9	145	*/
4388f060	146	U_CAPI UBool U_EXPORT2
729e4ab9 A	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
729e4ab9	154	*/
4388f060	155	U_CAPI void U_EXPORT2
729e4ab9 A	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.
729e4ab9	162	*/
4388f060	163	U_CAPI int32_t U_EXPORT2
729e4ab9 A	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.
729e4ab9	171	*/
4388f060	172	U_CAPI int32_t U_EXPORT2
729e4ab9 A	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.
729e4ab9	182	*/
4388f060	183	U_CAPI UBool U_EXPORT2
729e4ab9 A	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.
729e4ab9	196	*/
4388f060	197	U_CAPI UBool U_EXPORT2
729e4ab9 A	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.
729e4ab9	211	*/
4388f060	212	U_CAPI UBool U_EXPORT2
729e4ab9 A	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.
729e4ab9	229	*/
4388f060	230	U_CAPI UBool U_EXPORT2
729e4ab9 A	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.
729e4ab9	247	*/
4388f060	248	U_CAPI UBool U_EXPORT2
729e4ab9 A	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.
729e4ab9	263	*/
4388f060	264	U_CAPI UClassID U_EXPORT2
729e4ab9 A	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.
729e4ab9	277	*/
4388f060	278	U_CAPI UClassID U_EXPORT2
729e4ab9 A	279	izrule_getDynamicClassID(IZRule* rule);
	280
	281	#endif
	282
	283	#endif