int64 support - additional API proposed

Additional API changes for jitterbug 813 (int64_t support).
Please comment by Nov. 14.

I had neglected to include the C APIs in unum.h, the two new APIs are
listed below.  Thanks Deborah!

There is still debate about supporting unsigned as well as signed
support.  I agree that support for uint64 would be useful, but tend to
side with George that we should probably wait another release when
issues with stdio and uint64 on our supported platforms are
cleared up.  Please speak up now, though, if you differ!

There are additional API additions to Formattable I'd like to propose
following a discussion Monday.

Looking at Formattable and at the usage model in the tests, it seemed
cleaner to provide a means directy in Formattable for coercing the
numeric value into the requested type, as compared to requiring that
the user always test the formattable's type directly.  It also seemed
that in general it was not an error to request an int32 or an int64 if
the value would fit into the limits of these representations.  Nor is
it usually an error to request an integer type for a double even if
the fractional part of the double would be dropped.

So, I propose overloads of all the getXXX() methods that take
a status code.  Numbers interconvert where possible without error.
If the magnitude of the internal value is outside the range of the 
requested value type, an error status is set and the returned value
is pinned to it's maximum/minimum representable value.  If the type
is incorrect (modulo the interconversion mentioned above) the
status code is set to an error.

Fully 'lightweight' getters are maintained, including getInt64(void)
for those (common) cases where the type is known or explicitly tested
for.

Doug

--- unum.h ---

/**
* Format an int64 using a UNumberFormat.
* The int64 will be formatted according to the UNumberFormat's locale.
* @param fmt The formatter to use.
* @param number The number to format.
* @param result A pointer to a buffer to receive the formatted number.
* @param resultLength The maximum size of result.
* @param pos    A pointer to a UFieldPosition.  On input, position->field
* is read.  On output, position->beginIndex and position->endIndex indicate
* the beginning and ending indices of field number position->field, if such
* a field exists.  This parameter may be NULL, in which case no field
* @param status A pointer to an UErrorCode to receive any errors
* @return The total buffer size needed; if greater than resultLength, the
output was truncated.
* @see unum_format
* @see unum_formatDouble
* @see unum_parse
* @see unum_parseInt64
* @see unum_parseDouble
* @see UFieldPosition
* @stable ICU 2.0
*/
U_CAPI int32_t U_EXPORT2 
unum_formatInt64(const UNumberFormat *fmt,
        int64_t         number,
        UChar*          result,
        int32_t         resultLength,
        UFieldPosition *pos,
        UErrorCode*     status);

/**
* Parse a string into an int64 using a UNumberFormat.
* The string will be parsed according to the UNumberFormat's locale.
* @param fmt The formatter to use.
* @param text The text to parse.
* @param textLength The length of text, or -1 if null-terminated.
* @param parsePos If not 0, on input a pointer to an integer specifying the
offset at which
* to begin parsing.  If not 0, on output the offset at which parsing ended.
* @param status A pointer to an UErrorCode to receive any errors
* @return The value of the parsed integer
* @see unum_parse
* @see unum_parseDouble
* @see unum_format
* @see unum_formatInt64
* @see unum_formatDouble
* @draft ICU 2.8
*/
U_CAPI int64_t U_EXPORT2 
unum_parseInt64(const UNumberFormat*  fmt,
        const UChar*  text,
        int32_t       textLength,
        int32_t       *parsePos /* 0 = start */,
        UErrorCode    *status);

--- fmtable.h ---

    /**
     * Gets the double value of this object.  This converts from long or
     * int64 values as required (conversion from int64 can lose precision).
     * If the type is not a numeric type, 0 is returned and the status
     * is set to U_INVALID_FORMAT_ERROR.
     * @param status the error code
     * @return    the double value of this object.
     * @draft ICU 2.8
     */ 
    double          getDouble(UErrorCode* status) const;

    /**
     * Gets the long value of this object.  This converts from double or
     * int64 values as required.  If the magnitude is too large to fit in a
long,
     * the maximum or minimum long value, as appropriate, is returned and
     * the status is set to U_INVALID_FORMAT_ERROR.
     * If the type is not a numeric type, 0 is returned and the status 
     * is set to U_INVALID_FORMAT_ERROR.
     * @param status the error code
     * @return    the long value of this object.
     * @stable ICU 2.0
     */ 
    int32_t         getLong(UErrorCode* status) const;

    /**
     * Gets the int64 value of this object.  This converts from double or
     * int64 values as required.  If the value value won't fit in an int64,
     * the maximum or minimum in64 value, as appropriate, is returned and
     * the status is set to U_INVALID_FORMAT_ERROR.
     * If the type is not a numeric type, 0 is returned and the status 
     * is set to U_INVALID_FORMAT_ERROR.
     * @param status the error code
     * @return    the int64 value of this object.
     * @draft ICU 2.8
     */ 
    int64_t         getInt64(UErrorCode* status) const;

    /**
     * Gets the int64 value of this object.  This converts from double or
     * int64 values as required.  If the value value won't fit in an int64,
     * the maximum or minimum in64 value, as appropriate, is returned and
     * the status is set to U_INVALID_FORMAT_ERROR.
     * If the type is not a numeric type, 0 is returned and the status 
     * is set to U_INVALID_FORMAT_ERROR.
     * @param status the error code
     * @return    the int64 value of this object.
     * @draft ICU 2.8
     */ 
    int64_t         getInt64(UErrorCode* status) const;

    /**
     * Gets the Date value of this object.
     * @param status the error code.  If the type is not a date, status
     * is set to U_INVALID_FORMAT_ERROR and the return value is undefined.
     * @return    the Date value of this object.
     * @draft ICU 2.8
     */ 
    inline UDate    getDate(UErrorCode* status) const;

    /**
     * Gets the string value of this object.
     * @param result    Output param to receive the Date value of this object.
     * @param status    the error code.  If the type is not a string, status
     * is set to U_INVALID_FORMAT_ERROR and the result is unchanged.
     * @return          A reference to 'result'.
     * @draft ICU 2.8
     */ 
    UnicodeString&  getString(UnicodeString& result, UErrorCode* status) const;

    /**
     * Gets a const reference to the string value of this object.
     * @param status    the error code.  If the type is not a string, status
     * is set to U_INVALID_FORMAT_ERROR and the result is undefined.
     * @return   a const reference to the string value of this object.
     * @draft ICU 2.8
     */
    inline const UnicodeString& getString(UErrorCode* status) const;

    /**
     * Gets a reference to the string value of this object.
     * @param status    the error code.  If the type is not a string, status
     * is set to U_INVALID_FORMAT_ERROR and the result is undefined.
     * @return   a reference to the string value of this object.
     * @draft ICU 2.8
     */
    inline UnicodeString& getString(UErrorCode* status);

    /**
     * Gets the array value and count of this object.
     * @param count    fill-in with the count of this object.
     * @param status the error code.  If the type is not an array, status
     * is set to U_INVALID_FORMAT_ERROR, count is set to 0, and the result is
NULL.
     * @return         the array value of this object.
     * @draft ICU 2.8
     */ 

--- end ---

__________________________________
Do you Yahoo!?
Protect your identity with Yahoo! Mail AddressGuard
http://antispam.yahoo.com/whatsnewfree