[threeten-dev] [threeten-develop] Rough draft of TemporalAmount

[Stephen Colebourne]

On 26 January 2013 19:10, Roger Riggs <Roger.Riggs at oracle.com> wrote:
> Some revisions and comments inline:
>
> javadoc:
>    http://cr.openjdk.java.net/~rriggs/javadoc-temporalamount/
>
> webrev:
>    http://cr.openjdk.java.net/~rriggs/webrev-temporalamount/

SimplePeriod getUnits should use Collections.singletonList

Duration.getUnits() should use a nested class, like in Integer (IntegerCache).

The first Javadoc change in Period is wrong.

The proposed default implementation of addTo() makes sense and is the
goal I want to achieve. I'm happy enough with a list of units (defined
as largest to smallest), accessible via get(Unit). This definition
will correctly scale for future JDK releases.

We shouldn't preclude adding addition conversions into the get(Unit)
method with the initial Javadoc.
ie. in JDK 1.8 get(MILLIS) -> exception, but in JDK 1.9 it returns
get(NANOS)/1,000,000

Stephen


> On 1/25/2013 10:54 AM, Stephen Colebourne wrote:
>> On 25 January 2013 15:21, Roger Riggs<Roger.Riggs at oracle.com>  wrote:
>>> So, the simplest option is
>>> Duration = SECONDS + NANOS
>>> Period + YEARS + MONTHS + DAYS + NANOS
>>>
>>> The javadoc for Period describes itself has supporting the most commonly
>>> used units
>>> including "time units with an exact duration".  To be consistent get(unit)
>>> should follow
>>> that pattern.
>> I think that we need to require that the combination of getUnits() and
>> get() returns the complete state of the object.
>>
>> A Period is an amount, created by adding the total of years, months
>> days and time (in nanos). A user querying the period should be able to
>> get the total "amount". If hours/minutes/seconds are supported, then
>> get(HOURS)+get(MINUTES)+get(SECONDS)+get(NANOS) should be the total
>> amount, and all other units would be an error.
> right
>>
>> The alternate model for the interface is that it is just a "friendly"
>> get, like Temporal, that returns as much as it can. But we don't have
>> the rest of the infrastructure to do that in terms of converting a
>> user type of HALF_YEARS from the provided type of YEARS.
> All Units have a Duration, sometimes estimated that can be used for
> conversions
> if deemed necessary.
>>
>> Given that there are multiple choices this gets tricky.
>>
>> (I note again that adding this interface is risky because we don't
>> have the use cases to validate it. Adder and Subtractor are safe and
>> cannot be wrong. This interface may well not be what we really need,
>> forcing a TemporalAmount2 in the future)
>>
>> I would say that these models:
>>   Period = YEARS + MONTHS + DAYS + NANOS
>>   Period = YEARS + MONTHS + DAYS + HOURS + MINUTES(excluding hours) +
>> SECONDS(excl hr/min) + NANOS(excl hr/min/sec)
>> provides sufficient data for later default interface methods. (ie.
>> where only the above units can be queried.) The former is a more
>> accurate representation of the state of the class and easier for
>> framework code to work with. The latter is more designed for human
>> code.
> Period is defined to be the 7 values that make up the amount and with
> the Units and Durations the caller can convert to any desired Unit.
>>
>> The choice of providing a general conversion mechanism using durations
>> in get(Unit) may be nice for users, but it would be non-extensible in
>> future JDKs (default interface methods would have insufficient
>> information to work with).
> The methods getUnits and get(unit) provide a complete picture of the
> TemporalAmount
> (as long as there is no overlap between the units) any caller can
> iterate over the
> supported Units and get the total value.
>
> And the missing information is?
>
> For example, the default method for addTo(Temporal) might be:
>      Temporal plus(Temporal t) {
>          Temporal accum = t;
>           for (TemporalUnit unit: this.getUnits()) {
>               long v = this.get(unit);
>               if (v != 0) {
>                   accum = accum.plus(v, unit);
>               }
>          }
>          return accum;
>       }
>
> Changing getUnits to return List<TemporalUnit> and returning them
> in decreasing duration will allow predicable use and results.
>>
>>
>> Given all this, I think  Period = YEARS + MONTHS + DAYS + NANOS is the
>> simplest model. But since its not very user friendly, it may be best
>> to return it as a Map<Unit,Long>, or to rename get(Unit) to something
>> less attractive.
> The TemporalAmount is already effectively a Map<Unit, Long>.
>
> Roger
>
>
> ------------------------------------------------------------------------------
> Master Visual Studio, SharePoint, SQL, ASP.NET, C# 2012, HTML5, CSS,
> MVC, Windows 8 Apps, JavaScript and much more. Keep your skills current
> with LearnDevNow - 3,200 step-by-step video tutorials by Microsoft
> MVPs and experts. ON SALE this month only -- learn more at:
> http://p.sf.net/sfu/learnnow-d2d
> _______________________________________________
> threeten-develop mailing list
> threeten-develop at lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/threeten-develop