ICU API proposal: Deprecate C create/getMilligramPerDeciliter, J MILLIGRAM_PER_DECILITER

20 views
Skip to first unread message

Peter Edberg

unread,
Jun 26, 2025, 1:10:25 PMJun 26
to icu-d...@unicode.org

Dear ICU team & users,


I would like to propose the following API change for: ICU 78

Please provide feedback by: next Wednesday, 2025-07-03

Designated API reviewer: Rich G

Ticket: ICU-23150


Background:
    • CLDR 29 added the measurement unit milligram-per-deciliter, and the corresponding ICU 57 added ICU4C createMilligramPerDeciliter and ICU4J MILLIGRAM_PER_DECILITER; these are now @stable.
    • ICU 64 added ICU4C getMilligramPerDeciliter (along with getXxxx methods for other units); this is also now @stable.
    • CLDR 39 deprecated milligram-per-deciliter and replaced it with milligram-ofglucose-per-deciliter; the corresponding ICU 69 added createMilligramOfglucosePerDeciliter/getMilligramOfglucosePerDeciliter and MILLIGRAM_OFGLUCOSE_PER_DECILITER, which are now @stable.
    • However, the older ICU createMilligramPerDeciliter/ getMilligramPerDeciliter and MILLIGRAM_PER_DECILITER have not been deprecated (though there is a note in the interfaces about the renaming); they should be.
    • This is very similar to what was done per ICU-22142 for C createMetricTon/getMetricTon, J METRIC_TON

    Specific proposal:

    C  API change, measunit.h (remove, add):

    +#ifndef U_HIDE_DEPRECATED_API
         /**
          * Returns by pointer, unit of concentr: milligram-per-deciliter.
          * (renamed to milligram-ofglucose-per-deciliter in CLDR 39 / ICU 69).
          * Caller owns returned value and must free it.
          * Also see {@link #createMilligramOfglucosePerDeciliter()}.
          * Also see {@link #getMilligramPerDeciliter()}.
          * @param status ICU error code.
    -     * @stable ICU 57
    +     * @deprecated ICU 78 use createMilligramOfglucosePerDeciliter(UErrorCode &status)
          */
         static MeasureUnit *createMilligramPerDeciliter(UErrorCode &status);

         /**
          * Returns by value, unit of concentr: milligram-per-deciliter.
          * (renamed to milligram-ofglucose-per-deciliter in CLDR 39 / ICU 69).
          * Also see {@link #getMilligramOfglucosePerDeciliter()}.
          * Also see {@link #createMilligramPerDeciliter()}.
    -     * @stable ICU 64
    +     * @deprecated ICU 78 use getMilligramOfglucosePerDeciliter()
          */
         static MeasureUnit getMilligramPerDeciliter();
    +#endif  /* U_HIDE_DEPRECATED_API */

    J API change, MeasureUnit.java (remove, add):

         /**
          * Constant for unit of concentr: milligram-per-deciliter
          * (renamed to milligram-ofglucose-per-deciliter in CLDR 39 / ICU 69).
    -     * @stable ICU 57
    +     * @internal
    +     * @deprecated This API is ICU internal only.
          */
    +    @Deprecated
         public static final MeasureUnit MILLIGRAM_PER_DECILITER = MeasureUnit.internalGetInstance("concentr", "milligram-ofglucose-per-deciliter");

    Peter Edberg

    unread,
    Jun 27, 2025, 10:39:37 AMJun 27
    to Shane Carr, icu-d...@unicode.org
    The ICU MeasureUnit methods are supposed to correspond to tags that exist explicitly in CLDR data; milligram-per-deciliter does not exist in CLDR data. The only exception is a transition period after a tag is renamed (as in this case) in which methods using the old tag name exist alongside methods using the new name until the latter are stable; but the methods using the old tag name actually use the new tag to access the CLDR data in ICU, so they produce the same results as the methods using the new tag name.
    -Peter

    On Jun 26, 2025, at 4:47 PM, Shane Carr <sf...@google.com> wrote:

    I don't get it; milligramPerDeciliter is still a valid unit. Shouldn't we just return it?

    --
    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/E6A4FEEE-59EE-49EC-A4F7-6E8A33AAFAB1%40unicode.org.
    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/E6A4FEEE-59EE-49EC-A4F7-6E8A33AAFAB1%40unicode.org.

    Shane Carr

    unread,
    Jun 27, 2025, 2:36:25 PMJun 27
    to Peter Edberg, icu-d...@unicode.org
    I don't get it; milligramPerDeciliter is still a valid unit. Shouldn't we just return it?

    On Thu, Jun 26, 2025 at 12:10 PM Peter Edberg <ped...@unicode.org> wrote:

    Markus Scherer

    unread,
    Jul 9, 2025, 5:24:58 PMJul 9
    to Peter Edberg, icu-d...@unicode.org
    On Thu, Jun 26, 2025 at 10:10 AM Peter Edberg <ped...@unicode.org> wrote:
    J API change, MeasureUnit.java (remove, add):

         /**
          * Constant for unit of concentr: milligram-per-deciliter
          * (renamed to milligram-ofglucose-per-deciliter in CLDR 39 / ICU 69).
    -     * @stable ICU 57
    +     * @internal
    +     * @deprecated This API is ICU internal only.
          */
    +    @Deprecated
         public static final MeasureUnit MILLIGRAM_PER_DECILITER

    This should not be @internal.
    It should be
    @deprecated ICU 78 use MILLIGRAM_OFGLUCOSE_PER_DECILITER
    analogous to C++

    otherwise lgtm tnx
    markus
    Reply all
    Reply to author
    Forward
    0 new messages