Introduction of ICU 78 Units Converter API

[Younies Mahmoud]

Dear ICU Committee,

I am writing to introduce the ICU 78 Units Converter API, which includes new APIs for both Java and C++ MeasureUnit classes.

You can find the proposed APIs in the following document:

🔗 API Proposal – ICU 78 Units Converter

To demonstrate the implementation direction and provide an end-to-end overview, I have implemented a Draft Pull Request here:

🔗 GitHub PR #3512 – ICU Units Converter Implementation

For additional context, including the current status and previous discussions, please refer to the main project document:

🔗 Project Overview and Background

Thank you for your time and consideration. I look forward to discussing this proposal with you during our meeting this Thursday.

Sincerely,

Younies Mahmoud

[Shane Carr]

The proposed minimal API seems appropriate here, so long as it can be implemented efficiently.

--
You received this message because you are subscribed to the Google Groups "icu-design" group.
To unsubscribe from this group and stop receiving emails from it, send an email to icu-design+...@unicode.org.
To view this discussion visit https://groups.google.com/a/unicode.org/d/msgid/icu-design/CAA8Lwshx%2BPHw9yOafqSoY%3D%3DWygRxvo65OERwDuCNTX5jjZ29Jg%40mail.gmail.com.
For more options, visit https://groups.google.com/a/unicode.org/d/optout.

--
You received this message because you are subscribed to the Google Groups "ICU - Team" group.
To unsubscribe from this group and stop receiving emails from it, send an email to icu-team+u...@unicode.org.
To view this discussion visit https://groups.google.com/a/unicode.org/d/msgid/icu-team/CAA8Lwshx%2BPHw9yOafqSoY%3D%3DWygRxvo65OERwDuCNTX5jjZ29Jg%40mail.gmail.com.

[Younies Mahmoud]

Hello ICU Committee,

In the Units Converter API proposal, we have accepted it with the condition of adding the following changes in C++ and Java: •

• In Java: Extend IllegalArgumentException to a new UnitsIncompatibleException.

• In C++: Add a new error code U_UNITS_INCOMPATIBLE.

Could you please help me identify the appropriate places in the ICU codebase to define and integrate these errors?

Best regards,

Younies Mahmoud

[Fredrik Roubert]

On Wed, Jun 18, 2025 at 3:32 PM Younies Mahmoud <you...@unicode.org> wrote:

> In C++: Add a new error code U_UNITS_INCOMPATIBLE.
> Could you please help me identify the appropriate places in the ICU codebase to define and integrate these errors?

https://github.com/unicode-org/icu/blob/release-77-1/icu4c/source/common/unicode/utypes.h#L430

--
Fredrik Roubert
rou...@google.com

[Younies Mahmoud]

 Thanks, Fredrik.

Hello ICU Committee,

I am amending the UnitsConverter API design to include a new error type for unit incompatibility in both C++ and Java. I have also updated the API design document accordingly.

C++ Amendment

typedef enum UErrorCode {
    /**
     * Indicates that the units cannot be converted due to incompatibility.
     * Examples of unit compatibility:
     * - Converting `meter` to `mile` is linearly convertible → compatible.
     * - Converting `liter-per-100km` to `mile-per-gallon` is reciprocally convertible → compatible.
     * - Converting `meter` to `kilogram` is not convertible → incompatible.
     *
     * @draft ICU 78
     */
    U_UNITS_INCOMPATIBLE_ERROR = 32,
}

Java Amendment

/**
 * Exception thrown when there is an attempt to perform a conversion
 * between units that are incompatible with each other.
 *
 * @draft ICU 78
 */
public class UnitsIncompatibleException extends IllegalArgumentException {

    /**
     * Constructs a new UnitsIncompatibleException with no detail message.
     *
     * @draft ICU 78
     */
    public UnitsIncompatibleException() {
        super();
    }

    /**
     * Constructs a new UnitsIncompatibleException with the specified detail
     * message.
     *
     * @param message the detail message
     * @draft ICU 78
     */
    public UnitsIncompatibleException(String message) {
        super(message);
    }
}

Please let me know if you have any feedback or questions about these additions.

Best regards,

Younies Mahmoud

[Rich Gillam]

Looks okay to me.  Anybody else out there object or wait to discuss this next Thursday?

—Rich

--
You received this message because you are subscribed to the Google Groups "icu-design" group.
To unsubscribe from this group and stop receiving emails from it, send an email to icu-design+...@unicode.org.

To view this discussion visit https://groups.google.com/a/unicode.org/d/msgid/icu-design/CAA8LwsiYvymyHgk7zNi%3DAMEfuQ6ZV1iOXa1vhLwaiYYo1TE1Zw%40mail.gmail.com.

For more options, visit https://groups.google.com/a/unicode.org/d/optout.

--
You received this message because you are subscribed to the Google Groups "ICU - Team" group.
To unsubscribe from this group and stop receiving emails from it, send an email to icu-team+u...@unicode.org.

To view this discussion visit https://groups.google.com/a/unicode.org/d/msgid/icu-team/CAA8LwsiYvymyHgk7zNi%3DAMEfuQ6ZV1iOXa1vhLwaiYYo1TE1Zw%40mail.gmail.com.

[Markus Scherer]

UnitsIncompatibleException:

• I assume that this will live in com.ibm.icu.util like MeasureUnit and some of the other ICU exceptions.
• It is missing the two overloads that add a Throwable cause parameter.
• Not public API, but make sure that you include a serialVersionUID with a unique number.
• See com/ibm/icu/util/ICUCloneNotSupportedException.java for an example.

tnx

markus

[Younies Mahmoud]

Hi Markus,

Thanks for the notes.

I have added the package and also the two methods for a Throwable cause, Can you check my standing comment about serialVersionUID?

--

Younies

Software Engineer