ICU-20144 Adding better documentation and behavior testing on NumberingSystem.

icu4c/source/i18n/unicode/numsys.h

@@ -106,9 +106,9 @@ public:
 
     /**
      * Return a StringEnumeration over all the names of numbering systems known to ICU.
+     * The numbering system names will be in alphabetical (invariant) order.
      * @stable ICU 4.2
      */
-
      static StringEnumeration * U_EXPORT2 getAvailableNames(UErrorCode& status);
 
     /**
@@ -119,8 +119,10 @@ public:
      * default, native, traditional, finance - do not identify specific numbering systems,
      * but rather key values that may only be used as part of a locale, which in turn
      * defines how they are mapped to a specific numbering system such as "latn" or "hant".
+     *
      * @param name   The name of the numbering system.
-     * @param status ICU status
+     * @param status ICU status; set to U_UNSUPPORTED_ERROR if numbering system not found.
+     * @return The NumberingSystem instance, or nullptr if not found.
      * @stable ICU 4.2
      */
     static NumberingSystem* U_EXPORT2 createInstanceByName(const char* name, UErrorCode& status);

icu4c/source/i18n/unicode/unumsys.h

@@ -105,6 +105,7 @@ U_NAMESPACE_END
 /**
  * Returns an enumeration over the names of all of the predefined numbering systems known
  * to ICU.
+ * The numbering system names will be in alphabetical (invariant) order.
  * @param status    A pointer to a UErrorCode to receive any errors.
  * @return          A pointer to a UEnumeration that must be closed with uenum_close(),
  *                  or NULL if an error occurred.

icu4c/source/test/intltest/numfmtst.cpp

@@ -6954,7 +6954,7 @@ void NumberFormatTest::TestExplicitParents() {
  * Test available numbering systems API.
  */
 void NumberFormatTest::TestAvailableNumberingSystems() {
-    UErrorCode status = U_ZERO_ERROR;
+    IcuTestErrorCode status(*this, "TestAvailableNumberingSystems");
     StringEnumeration *availableNumberingSystems = NumberingSystem::getAvailableNames(status);
     CHECK_DATA(status, "NumberingSystem::getAvailableNames()")
 
@@ -6969,6 +6969,7 @@ void NumberFormatTest::TestAvailableNumberingSystems() {
     /* one that we initially thought.                                                      */
 
     int32_t len;
+    const char* prevName = nullptr;
     for ( int32_t i = 0 ; i < nsCount ; i++ ) {
         const char *nsname = availableNumberingSystems->next(&len,status);
         NumberingSystem* ns = NumberingSystem::createInstanceByName(nsname,status);
@@ -6976,10 +6977,23 @@ void NumberFormatTest::TestAvailableNumberingSystems() {
         if ( uprv_strcmp(nsname,ns->getName()) ) {
             errln("FAIL: Numbering system name didn't match for name = %s\n",nsname);
         }
+        if (prevName != nullptr) {
+            int comp = uprv_strcmp(prevName, nsname);
+            assertTrue(
+                UnicodeString(u"NS names should be in alphabetical order: ")
+                    + prevName + u" vs " + nsname,
+                // TODO: Why are there duplicates? This doesn't work if comp < 0
+                comp <= 0);
+        }
+        prevName = nsname;
 
         delete ns;
     }
 
+    LocalPointer<NumberingSystem> dummy(NumberingSystem::createInstanceByName("dummy", status), status);
+    status.expectErrorAndReset(U_UNSUPPORTED_ERROR);
+    assertTrue("Non-existent numbering system should return null", dummy.isNull());
+
     delete availableNumberingSystems;
 }
 

icu4j/main/classes/core/src/com/ibm/icu/text/NumberingSystem.java

@@ -223,6 +223,7 @@ public class NumberingSystem {
      * @param name The name of the desired numbering system.  Numbering system
      * names often correspond with the name of the script they are associated
      * with.  For example, "thai" for Thai digits, "hebr" for Hebrew numerals.
+     * @return The NumberingSystem instance, or null if not available.
      * @stable ICU 4.2
      */
     public static NumberingSystem getInstanceByName(String name) {
@@ -257,6 +258,8 @@ public class NumberingSystem {
     /**
      * Returns a string array containing a list of the names of numbering systems
      * currently known to ICU.
+     *
+     * @return An array of strings in alphabetical (invariant) order.
      * @stable ICU 4.2
      */
     public static String [] getAvailableNames() {
@@ -266,7 +269,7 @@ public class NumberingSystem {
             UResourceBundle temp;
 
             String nsName;
-            ArrayList<String> output = new ArrayList<String>();
+            ArrayList<String> output = new ArrayList<>();
             UResourceBundleIterator it = nsCurrent.getIterator();
             while (it.hasNext()) {
                 temp = it.next();

icu4j/main/tests/core/src/com/ibm/icu/dev/test/format/NumberFormatTest.java

@@ -1912,8 +1912,16 @@ public class NumberFormatTest extends TestFmwk {
         if (availableNames == null || availableNames.length <= 0) {
             errln("ERROR: NumberingSystem.getAvailableNames() returned a null or empty array.");
         } else {
+            // Check for alphabetical order
+            for (int i=0; i<availableNames.length-1; i++) {
+                assertTrue("Names should be in alphabetical order",
+                        availableNames[i].compareTo(availableNames[i+1]) < 0);
+            }
+
             boolean latnFound = false;
             for (String name : availableNames){
+                assertNotEquals("should not throw and should not be null",
+                        null, NumberingSystem.getInstanceByName(name));
                 if ("latn".equals(name)) {
                     latnFound = true;
                     break;
@@ -1925,6 +1933,9 @@ public class NumberFormatTest extends TestFmwk {
             }
         }
 
+        assertEquals("Non-existing numbering system should return null",
+                null, NumberingSystem.getInstanceByName("dummy"));
+
         // Test NumberingSystem.getInstance()
         NumberingSystem ns1 = NumberingSystem.getInstance();
         if (ns1 == null || ns1.isAlgorithmic()) {