ICU-10017 Add API specification for composition of time periods for ICU4J into code.

X-SVN-Rev: 33471

.gitattributes

@@ -248,6 +248,7 @@ icu4j/main/classes/core/.project -text
 icu4j/main/classes/core/.settings/org.eclipse.core.resources.prefs -text
 icu4j/main/classes/core/.settings/org.eclipse.jdt.core.prefs -text
 icu4j/main/classes/core/manifest.stub -text
+icu4j/main/classes/core/src/com/ibm/icu/util/TimePeriod.java -text
 icu4j/main/classes/currdata/.externalToolBuilders/copy-data-currdata.launch -text
 icu4j/main/classes/currdata/.settings/org.eclipse.core.resources.prefs -text
 icu4j/main/classes/currdata/.settings/org.eclipse.jdt.core.prefs -text

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

@@ -1,6 +1,6 @@
 /*
  **************************************************************************
- * Copyright (C) 2008-2012, Google, International Business Machines
+ * Copyright (C) 2008-2013, Google, International Business Machines
  * Corporation and others. All Rights Reserved.
  **************************************************************************
  */
@@ -17,6 +17,7 @@ import java.util.Set;
 import java.util.TreeMap;
 
 import com.ibm.icu.impl.ICUResourceBundle;
+import com.ibm.icu.util.TimePeriod;
 import com.ibm.icu.util.TimeUnit;
 import com.ibm.icu.util.TimeUnitAmount;
 import com.ibm.icu.util.ULocale;
@@ -70,7 +71,16 @@ public class TimeUnitFormat extends MeasureFormat {
      * @stable ICU 4.2
      */
     public static final int ABBREVIATED_NAME = 1;
+    
+    /**
+     * Constant for numeric style format. 
+     * NUMERIC strives to be as brief as possible. For example: 3:05:47.
+     * @draft ICU 52
+     */
+    public static final int NUMERIC = 2;
 
+    // For now we don't consider NUMERIC a full-fledged style. NUMERIC is
+    // congruent to ABBREVIATED_NAME unless formatPeriod() is being called.
     private static final int TOTAL_STYLES = 2;
 
     private static final long serialVersionUID = -3707773153184971529L;
@@ -89,6 +99,10 @@ public class TimeUnitFormat extends MeasureFormat {
     private transient PluralRules pluralRules;
     private transient boolean isReady;
     private int style;
+    
+    // When style is set to NUMERIC, this field is set to true and the style
+    // field becomes ABBREVIATED_NAME.
+    private boolean numeric;
 
     /**
      * Create empty format using full name style, for example, "hours". 
@@ -129,6 +143,10 @@ public class TimeUnitFormat extends MeasureFormat {
      * @stable ICU 4.2
      */
     public TimeUnitFormat(ULocale locale, int style) {
+        if (style == NUMERIC) {
+            style = ABBREVIATED_NAME;
+            numeric = true;
+        }
         if (style < FULL_NAME || style >= TOTAL_STYLES) {
             throw new IllegalArgumentException("style should be either FULL_NAME or ABBREVIATED_NAME style");
         }
@@ -226,7 +244,16 @@ public class TimeUnitFormat extends MeasureFormat {
         MessageFormat pattern = (MessageFormat)(countToPattern.get(count))[style];
         return pattern.format(new Object[]{amount.getNumber()}, toAppendTo, pos);
     }
-
+    
+    /**
+     * Formats a TimePeriod. Currently there is no way to parse a formatted TimePeriod.
+     * @param timePeriod the TimePeriod to format.
+     * @return the formatted string.
+     * @draft ICU 52
+     */
+    public String formatTimePeriod(TimePeriod timePeriod) {
+        return null;    
+    }
 
     /**
      * Parse a TimeUnitAmount.

icu4j/main/classes/core/src/com/ibm/icu/util/TimePeriod.java

@@ -0,0 +1,94 @@
+/*
+ *******************************************************************************
+ * Copyright (C) 2013, International Business Machines Corporation and         *
+ * others. All Rights Reserved.                                                *
+ *******************************************************************************
+ */
+package com.ibm.icu.util;
+
+import java.util.Iterator;
+
+/**
+ * TimePeriod represents a time period.  TimePeriod objects are immutable.
+ * <p>Example usage:
+ * <pre>
+ *   Period p = Period.forAmounts(
+ *       new TimeUnitAmount (TimeUnit.WEEK, 5),
+ *       new TimeUnitAmount (TimeUnit.DAY, 40),
+ *       new TimeUnitAmount (TimeUnit.HOUR, 2),
+ *       new TimeUnitAmount (TimeUnit.SECOND, 8));
+ * </pre>
+ * @draft ICU 52
+ */
+public final class TimePeriod implements Iterable<TimeUnitAmount> {
+       
+    /**
+     * Returns a new TimePeriod that matches the given time unit amounts.
+     * @param amounts the TimeUnitAmounts. Must be non-empty. Normalization of the
+     *   amounts and inclusion/exclusion of 0 amounts is up to caller.
+     * @return the new TimePeriod object
+     * @throws IllegalArgumentException if multiple TimeUnitAmount objects match
+     * the same time unit or if any but the smallest TimeUnit has a fractional value
+     * Or if amounts is empty.
+     * @draft ICU 52
+     */
+    public static TimePeriod forAmounts(TimeUnitAmount ...amounts) {
+            return null;
+    }
+
+    /**
+     * Returns a new TimePeriod that matches the given time unit amounts.
+     * @param amounts the TimeUnitAmounts. Must be non-empty. Normalization of the
+     *   amounts and inclusion/exclusion of 0 amounts is up to caller.
+     * @return the new TimePeriod object
+     * @throws IllegalArgumentException if multiple TimeUnitAmount objects match
+     * the same time unit or if any but the smallest TimeUnit has a fractional value
+     * Or if amounts is empty.
+     * @draft ICU 52
+     */
+    public static TimePeriod forAmounts(Iterable<TimeUnitAmount> amounts) {
+        return null;
+    }
+        
+    /**
+     * Gets the value for a specific time unit.
+     * @param timeUnit the time unit.
+     * @return the TimeUnitAmount or null if no value is present for given TimeUnit.
+     *  A non-existing value and a zero value are two different things.
+     * @draft ICU 52
+     */
+    public TimeUnitAmount getAmount(TimeUnit timeUnit) {
+        return null;
+    }
+
+    /**
+     * Returned iterator iterates over all TimeUnitAmount objects in this object.
+     * Iterated TimeUnitAmount objects are ordered from largest TimeUnit to
+     * smallest TimeUnit.
+     * @draft ICU 52
+     */
+    public Iterator<TimeUnitAmount> iterator() {
+      return null;
+    }
+
+    /**
+     * Returns the number of TimeUnitAmount objects in this object.
+     */
+    public int size() {
+      return 0;
+    }
+    
+    /**
+     * Two TimePeriod objects are equal if they contain equal TimeUnitAmount objects.
+     */
+    @Override
+    public boolean equals(Object rhs) {
+        return true;
+    }
+    
+    @Override
+    public int hashCode() {
+        return 0;
+    }
+}
+

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

@@ -1,6 +1,6 @@
 /*
  *******************************************************************************
- * Copyright (C) 2008-2012, International Business Machines Corporation and    *
+ * Copyright (C) 2008-2013, International Business Machines Corporation and    *
  * others. All Rights Reserved.                                                *
  *******************************************************************************
  */
@@ -30,12 +30,14 @@ public class TimeUnitTest extends TestFmwk {
         String[] locales = {"en", "sl", "fr", "zh", "ar", "ru", "zh_Hant"};
         for ( int locIndex = 0; locIndex < locales.length; ++locIndex ) {
             //System.out.println("locale: " + locales[locIndex]);
-            Object[] formats = new Object[] {
+            TimeUnitFormat[] formats = new TimeUnitFormat[] {
                 new TimeUnitFormat(new ULocale(locales[locIndex]), TimeUnitFormat.FULL_NAME),
-                new TimeUnitFormat(new ULocale(locales[locIndex]), TimeUnitFormat.ABBREVIATED_NAME)
+                new TimeUnitFormat(new ULocale(locales[locIndex]), TimeUnitFormat.ABBREVIATED_NAME),
+                new TimeUnitFormat(new ULocale(locales[locIndex]), TimeUnitFormat.NUMERIC)
+                
             };
             for (int style = TimeUnitFormat.FULL_NAME;
-                 style <= TimeUnitFormat.ABBREVIATED_NAME;
+                 style <= TimeUnitFormat.NUMERIC;
                  ++style) {
                 final TimeUnit[] values = TimeUnit.values();
                 for (int j = 0; j < values.length; ++j) {
@@ -43,18 +45,16 @@ public class TimeUnitTest extends TestFmwk {
                     double[] tests = {0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 5, 10, 100, 101.35};
                     for (int i = 0; i < tests.length; ++i) {
                         TimeUnitAmount source = new TimeUnitAmount(tests[i], timeUnit);
-                        String formatted = ((TimeUnitFormat)formats[style]).format(source);
+                        String formatted = formats[style].format(source);
                         //System.out.println(formatted);
                         logln(tests[i] + " => " + formatted);
                         try {
-                            TimeUnitAmount result = (TimeUnitAmount) ((TimeUnitFormat)formats[style]).parseObject(formatted);
+                            // Style should not matter when parsing.
-                            if (result == null || !source.equals(result)) {
+                            for (int parseStyle = TimeUnitFormat.FULL_NAME; parseStyle <= TimeUnitFormat.NUMERIC; parseStyle++) {
-                                errln("No round trip: " + source + " => " + formatted + " => " + result);
+                                TimeUnitAmount result = (TimeUnitAmount) formats[parseStyle].parseObject(formatted);
-                            }
+                                if (result == null || !source.equals(result)) {
-                            // mix style parsing
+                                    errln("No round trip: " + source + " => " + formatted + " => " + result);
-                            result = (TimeUnitAmount) ((TimeUnitFormat)formats[1 - style]).parseObject(formatted);
+                                }
-                            if (result == null || !source.equals(result)) {
-                                errln("No round trip: " + source + " => " + formatted + " => " + result);
                             }
                         } catch (ParseException e) {
                             errln(e.getMessage());
@@ -230,7 +230,7 @@ public class TimeUnitTest extends TestFmwk {
     public void TestTimeUnitFormat() {
         // Tests when "if (style < FULL_NAME || style >= TOTAL_STYLES)" is true
         // TOTAL_STYLES is 2
-        int[] cases = { TimeUnitFormat.FULL_NAME - 1, TimeUnitFormat.FULL_NAME - 2, 2, 3 };
+        int[] cases = { TimeUnitFormat.FULL_NAME - 1, TimeUnitFormat.FULL_NAME - 2, 3 };
         for (int i = 0; i < cases.length; i++) {
             try {
                 TimeUnitFormat tuf = new TimeUnitFormat(new ULocale("en_US"), cases[i]);