1---
2layout: default
3title: Updating MeasureUnit with new CLDR data
4parent: Release & Milestone Tasks
5grand_parent: Contributors
6nav_order: 120
7---
8
9<!--
10© 2020 and later: Unicode, Inc. and others.
11License & terms of use: http://www.unicode.org/copyright.html
12-->
13
14# Updating MeasureUnit with new CLDR data
15{: .no_toc }
16
17## Contents
18{: .no_toc .text-delta }
19
201. TOC
21{:toc}
22
23---
24
25This document explains how to update the C++ and Java version of the MeasureUnit
26class with new CLDR data.
27
28Code is generated by running MeasureUnitTest.java unit tests, which writes
29generated code to System.out. Two ways to access this:
30
311. Within **eclipse**:
32   - Open MeasureUnitTest.java, run it by clicking on the green play button on
33     menu bar.
34   - Copy the generated code from the eclipse console to the clipboard.
35
362. With **ant**:
37   - Run: `ant checkTest
38     -Dtestclass='com.ibm.icu.dev.test.format.MeasureUnitTest'`
39   - Open the checkTest output: `out/junit-results/checkTest/html/index.html`
40   - Navigate to "System.out" at the bottom of the MeasureUnitTest page to find
41     the generated code, and copy to the clipboard.
42
43After syncing CLDR data with ICU do the following. This documentation assumes
44that you are updating the MeasureUnit clases for ICU 68.
45
46* Check out
47  $GIT_ROOT/icu4j/main/tests/core/src/com/ibm/icu/dev/test/format/MeasureUnitTest.java
48* Open MeasureUnitTest.java.
49* Find the `testZZZ` test, its code should all be commented out. This test will
50  execute last and will run the desired code.
51
52    Make sure DRAFT_VERSIONS at top of MeasureUnitTest.java is set correctly.
53    These are the ICU versions that have draft methods.
54
55## Update MeasureUnit.java
56
57* Change `testZZZ` to run `generateConstants(“68”); // ICU 68.`
58* Run MeasureUnitTest.java, copy the generated code (see instructions above).
59* Open MeasureUnit.java:
60  $GIT_ROOT/icu4j/main/classes/core/src/com/ibm/icu/util/MeasureUnit.java
61* Look for line containing:
62
63  `// Start generated MeasureUnit constants`
64* Look for line containing:
65
66  `// End generated MeasureUnit constants`
67* Replace all the generated code in between with the contents of the clipboard
68* Run the MeasureUnitTest.java to ensure that the new code is backward
69  compatible. These compatibility tests are called something like
70  `TestCompatible65`, which tests backward compatibility with ICU 65.
71* Create a compatibility test for ICU 68. Change `testZZZ` to run
72  `generateBackwardCompatibilityTest(“68”)`
73* Run tests.
74* Copy generated test (see instructions above) into MeasureUnitTest.java
75* Run tests again to ensure that new code is backward compatible with itself
76
77## Update ICU4C
78
79* checkout ICU4C
80
81### Update measunit.h
82
83* Change testZZZ to run `generateCXXHConstants(“68”); // ICU 68`.
84* Run MeasureUnitTest.java, copy the generated code (see instructions above).
85* Open $GIT_ROOT/icu4c/source/i18n/unicode/measunit.h. Look for line containing:
86
87  `// Start generated createXXX methods`
88* Look for line:
89
90  `// End generated createXXX methods`
91* Replace all the generated code in between with the contents of the clipboard
92
93### Update measunit.cpp
94
95* Change testZZZ to run generateCXXConstants();
96* Run MeasureUnitTest.java, copy the generated code (see instructions above).
97* Open $GIT_ROOT/icu4c/source/i18n/measunit.cpp. Look for line containing:
98
99  `// Start generated code for measunit.cpp`
100* Look for lines
101
102  `// End generated code for measunit.cpp`
103* Replace all the generated code in between with the contents of the clipboard
104
105### Run C++ tests
106
107* Run `./intltest format/MeasureFormatTest` from `test/intltest` to ensure new
108  code is backward compatible.
109* Create a compatibility test for ICU 68. Change `testZZZ` in eclipse to run
110  `generateCXXBackwardCompatibilityTest(“68”)`
111* Run tests.
112* Copy generated test (see instructions above) into
113  $GIT_ROOT/icu4c/source/test/intltest/measfmttest.cpp. Make other necessary
114  changes to make test compile. You can find these changes by searching for
115  `TestCompatible65()`
116* Run tests again to ensure that new code is backward compatible with itself
117
118## Finishing changes
119
120These last changes are necessary to permanently record the ICU version number of
121any new measure units. Without these changes any new functions for this release
122will be considered new for the next release too.
123
124* Change `testZZZ` to run `updateJAVAVersions(“68”);`
125* Run MeasureUnitTest.java, copy the generated code (see instructions above).
126* Append the clipboard contents to the values of the JAVA_VERSIONS variable
127  near the top of MeasureUnitTest.java.
128
129  **Important:** what you are copying are just the new functions for the current
130  ICU version, in this case 68. Therefore append, do not replace.
131
132## Updating units.txt and unitConstants
133
134The standard ldml2icu process is used to update ICU's resource files (see
135[cldr-icu-readme.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/cldr-icu-readme.txt)).
136CLDR's units.xml defines conversion rates in terms of some constants defined in
137`unitConstants`.
138
139For efficiency and simplicity, ICU does not read `unitConstants` from the
140resource file. If any new constants are added, some code changes would be
141needed. This would be caught by `testUnitConstantFreshness` unit test in
142`units_test.cpp`.
143
144They are hard-coded:
145* Java: `UnitConverter.java` has the constant names in
146  `UnitConverter.Factor.addEntity()` and constant values in
147  `UnitConverter.Factor.getConversionRate()`.
148* C++: `units_converter.cpp` has the constant names in
149  `addSingleFactorConstant()`, with the constant values in `double
150  constantsValues[]` in the `units_converter.h` header file.
151