Re: [icu-design] API Proposal: C wrappers for for VTimeZone, TimeZoneTransition and TimeZoneRule

[<yos...@us...>]

My comments below -

Jason J Spieth <sp...@us...> wrote on 04/29/2010 05:58:23 PM:

> 
> Dear ICU team & users, 
> 
> I would like to propose adding C wrappers for the VTimeZone, 
> TimeZoneTransition and TimeZoneRule CPP classes. 
> 
> For details see http://www.icu-project.org/trac/ticket/7524 
> 
> Please provide feedback by  Wednesday 2010-May-12 
> I would like to designate Steven Loomis as reviewer 
> 
> Thank you. 
> 
> ------ 
> The wrapper for VTimeZone will be VZone and will have methods as 
follows: 
> ------ 
> 
> struct VZone; 
> /** 
>  * A UnicodeSet.  Use the vzone_* API to manipulate.  Create with 
>  * vzone_open*, and destroy with vzone_close. 
>  * @draft ICU 4.6 
>  */ 
> typedef struct VZone VZone; 

Why "A UnicodeSet"?
Also, I think we should use our naming convention - Uxxx.
So it would be UVTimeZone or something.

> 
> /** 
>  * Creates a vzone from the given time zone ID. 
>  * @param ID The time zone ID, such as America/New_York 
>  * @param idLength, length of the ID parameter 
>  * @return A vzone object initialized by the time zone ID, 
>  * or NULL when the ID is unknown. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT VZone* U_EXPORT2 
> vzone_openID(const UChar* ID, int32_t idLength); 
> 

The prefix should also follow our convention.  For example, uvtz_*

> /** 
>  * Create a vzone instance by RFC2445 VTIMEZONE data 
>  * @param vtzdata The string including VTIMEZONE data block 
>  * @param vtzdataLength, length of the vtzdata 
>  * @param status Output param to filled in with a success or an error. 
>  * @return A vzone initialized by the VTIMEZONE data or 
>  * NULL if failed to load the rule from the VTIMEZONE data. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT VZone* U_EXPORT2 
> vzone_openData(const UChar* vtzdata, int32_t vtzdataLength, 
> UErrorCode& status); 
> 
> /** 
>  * Disposes of the storage used by a VZone object.  This function should 

>  * be called exactly once for objects returned by vzone_open*. 
>  * @param set the object to dispose of 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void U_EXPORT2 
> vzone_close(VZone* zone); 
> 
> /** 
>  * Returns a copy of this object. 
>  * @param zone the original vzone 
>  * @return the newly allocated copy of the vzone 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT VZone* U_EXPORT2 
> vzone_clone(const VZone *zone); 
> 
> /** 
>  * Returns true if zone1 is identical to zone2 
>  * and vis versa. 
>  * @param zone1 to be checked for containment 
>  * @param zone2 to be checked for containment 
>  * @return true if the test condition is met 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UBool U_EXPORT2 
> vzone_equals(const VZone* zone1, const VZone* zone2); 
> 
> /** 
>  * Gets the RFC2445 TZURL property value.  When a vzone instance was 
>  * created from VTIMEZONE data, the initial value is set by the TZURL 
>  * property value in the data.  Otherwise, the initial value is not set. 

>  * 
>  * If the URL receiver variable is null, urlLength will contain the 
number 
>  * of bytes necessary to hold the URL and the receiver variable will not 

>  * be set. 
>  * 
>  * @param zone, the vzone to use 
>  * @param url Receives the RFC2445 TZURL property value. 
>  * @param urlLength, length of the url 
>  * @return TRUE if TZURL attribute is available and value is set. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UBool U_EXPORT2 
> vzone_getTZURL(VZone* zone, UChar* & url, int32_t & urlLength); 

Isn't this a C API?
If this API copies the value to url, then you should add UErrorCode*.
If this API returns the pointer, then url should be const UChar **url?

> 
> /** 
>  * Sets the RFC2445 TZURL property value. 
>  * @param zone, the vzone to use 
>  * @param url The TZURL property value. 
>  * @param urlLength, length of the url 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void U_EXPORT2 
> vzone_setTZURL(VZone* zone, UChar* url, int32_t urlLength); 

const UChar* url?

> 
> /** 
>  * Gets the RFC2445 LAST-MODIFIED property value.  When a vzone instance 

>  * was created from VTIMEZONE data, the initial value is set by the 
>  * LAST-MODIFIED property value in the data.  Otherwise, the initial 
value 
>  * is not set. 
>  * @param zone, the vzone to use 
>  * @param lastModified Receives the last modified date. 
>  * @return TRUE if lastModified attribute is available and value is set. 

>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UBool U_EXPORT2 
> vzone_getLastModified(VZone* zone, UDate& lastModified); 

UDate*?

> 
> /** 
>  * Sets the RFC2445 LAST-MODIFIED property value. 
>  * @param zone, the vzone to use 
>  * @param lastModified The LAST-MODIFIED date. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void U_EXPORT2 
> vzone_setLastModified(VZone* zone, UDate lastModified); 
> 
> /** 
>  * Writes RFC2445 VTIMEZONE data for this time zone 
>  * 
>  * If the receiver variable is null, the returned length will 
> contain the number 
>  * of bytes necessary to hold the data and the receiver variable will 
not 
>  * be set. 
>  * 
>  * @param zone, the vzone to use 
>  * @param result Output param to filled in with the VTIMEZONE data. 
>  * @param resultLength, length of the result output 
>  * @param status Output param to filled in with a success or an error. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void U_EXPORT2 
> vzone_write(VZone* zone, UChar* & result, int32_t & resultLength, 
> UErrorCode& status); 

UChar* result and int32_t* resultLength (in/out) and also, the function 
may
return the result length

> 
> /** 
>  * Writes RFC2445 VTIMEZONE data for this time zone applicalbe 
>  * for dates after the specified start time. 
>  * 
>  * If the receiver variable is null, the returned length will 
> contain the number 
>  * of bytes necessary to hold the data and the receiver variable will 
not 
>  * be set. 
>  * 
>  * @param zone, the vzone to use 
>  * @param start The start date. 
>  * @param result Output param to filled in with the VTIMEZONE data. 
>  * @param resultLength, length of the result output 
>  * @param status Output param to filled in with a success or an error. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void U_EXPORT2 
> vzone_writeFromStart(VZone* zone, UDate start, UChar* & result, 
> int32_t & resultLength, UErrorCode& status); 

Same as above.

> 
> /** 
>  * Writes RFC2445 VTIMEZONE data applicalbe for the specified date. 
>  * Some common iCalendar implementations can only handle a single time 
>  * zone property or a pair of standard and daylight time properties 
using 
>  * BYDAY rule with day of week (such as BYDAY=1SUN).  This method 
produce 
>  * the VTIMEZONE data which can be handled these implementations.  The 
rules 
>  * produced by this method can be used only for calculating time zone 
offset 
>  * around the specified date. 
>  * 
>  * If the receiver variable is null, the returned length will 
> contain the number 
>  * of bytes necessary to hold the data and the receiver variable will 
not 
>  * be set. 
>  * 
>  * @param zone, the vzone to use 
>  * @param time The date used for rule extraction. 
>  * @param result Output param to filled in with the VTIMEZONE data. 
>  * @param status Output param to filled in with a success or an error. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void U_EXPORT2 
> vzone_writeSimple(VZone* zone, UDate time, UChar* & result, int32_t 
> & resultLength, UErrorCode& status); 
> 

Same as above.

> /** 
>  * Returns the time zone raw and GMT offset for the given moment 
>  * in time.  Upon return, local-millis = GMT-millis + rawOffset + 
>  * dstOffset.  All computations are performed in the proleptic 
>  * Gregorian calendar.  The default implementation in the TimeZone 
>  * class delegates to the 8-argument getOffset(). 
>  * 
>  * @param zone, the vzone to use 
>  * @param date moment in time for which to return offsets, in 
>  * units of milliseconds from January 1, 1970 0:00 GMT, either GMT 
>  * time or local wall time, depending on `local'. 
>  * @param local if true, `date' is local wall time; otherwise it 
>  * is in GMT time. 
>  * @param rawOffset output parameter to receive the raw offset, that 
>  * is, the offset not including DST adjustments 
>  * @param dstOffset output parameter to receive the DST offset, 
>  * that is, the offset to be added to `rawOffset' to obtain the 
>  * total offset between local and GMT time. If DST is not in 
>  * effect, this value is zero; otherwise it is a positive value, 
>  * typically one hour. 
>  * @param ec input-output error code 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void U_EXPORT2 
> vzone_getOffset(VZone* zone, UDate date, UBool local, int32_t& 
rawOffset, 
>                 int32_t& dstOffset, UErrorCode& ec); 
> 
> /** 
>  * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds 
to add
>  * to GMT to get local time, before taking daylight savings time 
> into account). 
>  * 
>  * @param zone, the vzone to use 
>  * @param offsetMillis  The new raw GMT offset for this time zone. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void U_EXPORT2 
> vzone_setRawOffset(VZone* zone, int32_t offsetMillis); 
> 
> /** 
>  * Returns the TimeZone's raw GMT offset (i.e., the number of 
> milliseconds to add 
>  * to GMT to get local time, before taking daylight savings time 
> into account). 
>  * 
>  * @param zone, the vzone to use 
>  * @return   The TimeZone's raw GMT offset. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT int32_t U_EXPORT2 
> vzone_getRawOffset(VZone* zone); 
> 
> /** 
>  * Queries if this time zone uses daylight savings time. 
>  * @param zone, the vzone to use 
>  * @return true if this time zone uses daylight savings time, 
>  * false, otherwise. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UBool U_EXPORT2 
> vzone_useDaylightTime(VZone* zone); 
> 
> /** 
>  * Returns true if this zone has the same rule and offset as another 
zone. 
>  * That is, if this zone differs only in ID, if at all. 
>  * @param zone, the vzone to use 
>  * @param other the <code>TimeZone</code> object to be compared with 
>  * @return true if the given zone is the same as this one, 
>  * with the possible exception of the ID 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UBool U_EXPORT2 
> vzone_hasSameRules(VZone* zone, const VZone* other); 
> 
> /** 
>  * Gets the first time zone transition after the base time. 
>  * @param zone, the vzone to use 
>  * @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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UBool U_EXPORT2 
> vzone_getNextTransition(VZone* zone, UDate base, UBool inclusive, 
> ZTrans* result); 
> 
> /** 
>  * Gets the most recent time zone transition before the base time. 
>  * @param zone, the vzone to use 
>  * @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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UBool U_EXPORT2 
> vzone_getPreviousTransition(VZone* zone, UDate base, UBool 
> inclusive, ZTrans* result); 
> 
> /** 
>  * 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 zone, the vzone to use 
>  * @param status    Receives error status code. 
>  * @return The number of <code>TimeZoneRule</code>s representing 
> time transitions. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT int32_t U_EXPORT2 
> vzone_countTransitionRules(VZone* zone, UErrorCode& status); 
> 

Not sure we need these TimeZone APIs.  Do we have C API for accessing 
timezone directly?


> /** 
>  * 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 zone, the vzone to use 
>  * @return          The class ID for all objects of this class. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UClassID U_EXPORT2 
> vzone_getStaticClassID(VZone* zone); 
> 
> /** 
>  * 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 zone, the vzone 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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UClassID U_EXPORT2 
> vzone_getDynamicClassID(VZone* zone); 
> 
> ------ 
> The wrapper for TimeZoneTransition will be ZTrans and will have 
> methods as follows: 
> ------ 
> 
> /** 
>  * A TimeZoneTransition.  Use the ztrans_* API to manipulate.  Create 
with 
>  * ztrans_open*, and destroy with ztrans_close. 
>  * @draft ICU 4.6 
>  */ 
> struct ZTrans; 
> typedef struct ZTrans ZTrans; 
> 
> 
> /** 
>  * Constructs a time zone transition with the time and the rules 
before/after
>  * the transition. 
>  * 
>  * @param time  The time of transition in milliseconds since the base 
time. 
>  * @param from  The time zone rule used before the transition. 
>  * @param to    The time zone rule used after the transition. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT ZTrans* U_EXPORT2 
> ztrans_open(UDate time, const void* from, const void* to); 
> 
> /** 
>  * Constructs an empty <code>TimeZoneTransition</code> 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT ZTrans* U_EXPORT2 
> ztrans_openEmpty(); 
> 
> /** 
>  * Disposes of the storage used by a ZTrans object.  This function 
should 
>  * be called exactly once for objects returned by ztrans_open*. 
>  * @param trans the object to dispose of 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void U_EXPORT2 
> ztrans_close(ZTrans *trans); 
> 
> /** 
>  * Returns a copy of this object. 
>  * @param rule the original ZRule 
>  * @return the newly allocated copy of the ZRule 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT ZTrans* U_EXPORT2 
> ztrans_clone(ZTrans *trans); 
> 
> /** 
>  * Returns true if trans1 is identical to trans2 
>  * and vis versa. 
>  * @param trans1 to be checked for containment 
>  * @param trans2 to be checked for containment 
>  * @return true if the test condition is met 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UBool U_EXPORT2 
> ztrans_equals(const ZTrans* trans1, const ZTrans* trans2); 
> 
> /** 
>  * Returns the time of transition in milliseconds. 
>  * param trans, the transition to use 
>  * @return the time of the transition in milliseconds since the 1970
> Jan 1 epoch time. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UDate U_EXPORT2 
> ztrans_getTime(ZTrans* trans); 
> 
> /** 
>  * Sets the time of transition in milliseconds. 
>  * param trans, the transition to use 
>  * @param time the time of the transition in milliseconds since the 
> 1970 Jan 1 epoch time. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void U_EXPORT2 
> ztrans_setTime(ZTrans* trans, UDate time); 
> 
> /** 
>  * Returns the rule used before the transition. 
>  * @param trans, the transition to use 
>  * @return the time zone rule used after the transition. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void* U_EXPORT2 
> ztrans_getFrom(ZTrans* & trans); 
> 
> /** 
>  * Sets the rule used before the transition.  The caller remains 
>  * responsible for deleting the TimeZoneRule object. 
>  * @param trans, the transition to use 
>  * @param from the time zone rule used before the transition. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void U_EXPORT2 
> ztrans_setFrom(ZTrans* trans, const void* from); 
> 
> /** 
>  * Adopts the rule used before the transition.  The caller must 
>  * not delete the TimeZoneRule object passed in. 
>  * @param trans, the transition to use 
>  * @param from the time zone rule used before the transition. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void U_EXPORT2 
> ztrans_adoptFrom(ZTrans* trans, void* from); 
> 
> /** 
>  * Returns the rule used after the transition. 
>  * @param trans, the transition to use 
>  * @return the time zone rule used after the transition. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void* U_EXPORT2 
> ztrans_getTo(ZTrans* trans); 
> 
> /** 
>  * Sets the rule used after the transition.  The caller remains 
>  * responsible for deleting the TimeZoneRule object. 
>  * @param trans, the transition to use 
>  * @param to the time zone rule used after the transition. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void U_EXPORT2 
> ztrans_setTo(ZTrans* trans, const void* to); 
> 
> /** 
>  * Adopts the rule used after the transition.  The caller must 
>  * not delete the TimeZoneRule object passed in. 
>  * @param trans, the transition to use 
>  * @param to the time zone rule used after the transition. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT void U_EXPORT2 
> ztrans_adoptTo(ZTrans* trans, void* to); 
> 
> /** 
>  * 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 trans, the transition to use 
>  * @return the class ID for all objects of this class. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UClassID U_EXPORT2 
> ztrans_getStaticClassID(ZTrans* trans); 
> 
> /** 
>  * 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 trans, the transition 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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UClassID U_EXPORT2 
> ztrans_getDynamicClassID(ZTrans* trans); 
> 

We probably define these as ucal_*


> ------ 
> The wrapper for TimeZoneRule will be ZRule and will have methods as 
follows: 
> ------ 
> 
> /** 
>  * A TimeZoneRule.  Use the zrule_* API to manipulate.  Create with 
>  * zrule_open*, and destroy with zrule_close. 
>  * @draft ICU 4.6 
>  */ 
> struct ZRule; 
> typedef struct ZRule ZRule; 
> 
> /** 
>  * An InitialTimeZoneRule.  Use the izrule_* API to manipulate.  Create 
with 
>  * izrule_open*, and destroy with izrule_close. 
>  * @draft ICU 4.6 
>  */ 
> struct IZRule; 
> typedef struct IZRule IZRule; 
> 
> 
> /********************************************************************* 
>  * 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 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UBool U_EXPORT2 
> zrule_equals(const ZRule* rule1, const ZRule* rule2); 
> 
> /** 
>  * Fills in "name" with the name of this time zone. 
>  * 
>  * If the receiver variable is null, the returned length will 
> contain the number 
>  * of bytes necessary to hold the data and the receiver variable will 
not 
>  * be set. 
>  * 
>  * @param rule, the Zrule to use 
>  * @param name  Receives the name of this time zone. 
>  * @param nameLength, length of the returned name 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UBool U_EXPORT2 
> izrule_equals(const IZRule* rule1, const IZRule* rule2); 
> 
> /** 
>  * Fills in "name" with the name of this time zone. 
>  * 
>  * If the receiver variable is null, the returned length will 
> contain the number 
>  * of bytes necessary to hold the data and the receiver variable will 
not 
>  * be set. 
>  * 
>  * @param rule, the IZrule to use 
>  * @param name  Receives the name of this time zone. 
>  * @param nameLength, length of the returned name 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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 beforethis 
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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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 beforethis 
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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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 beforethis 
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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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 beforethis 
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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT 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. 
>  * @draft ICU 4.6 
>  */ 
> U_DRAFT UClassID U_EXPORT2 
> izrule_getDynamicClassID(IZRule* rule); 

Same as above.