Le dim. 8 déc. 2019 à 13:32, Alex Herbert <alex.d.herb...@gmail.com> a écrit :
>
>
>
> > On 8 Dec 2019, at 11:24, Gilles Sadowski <gillese...@gmail.com> wrote:
> >
> > Hi.
> >
> > 2019-12-08 10:45 UTC+01:00, Alex Herbert <alex.d.herb...@gmail.com
> > <mailto:alex.d.herb...@gmail.com>>:
> >> On Sun, 8 Dec 2019, 01:50 Gilles Sadowski, <gillese...@gmail.com> wrote:
> >>
> >>> 2019-12-08 2:00 UTC+01:00, aherb...@apache.org <aherb...@apache.org>:
> >>>> This is an automated email from the ASF dual-hosted git repository.
> >>>>
> >>>> aherbert pushed a commit to branch master
> >>>> in repository https://gitbox.apache.org/repos/asf/commons-numbers.git
> >>>>
> >>>> commit 65f60835e2afe26bdaba9665d62edb25195bfff6
> >>>> Author: Alex Herbert <aherb...@apache.org>
> >>>> AuthorDate: Sun Dec 8 00:54:03 2019 +0000
> >>>>
> >>>> Added getAbsolute() to complement getArgument().
> >>>
> >>> Is that name part of the reference?
> >>> If not, "getMagnitude" or "getModulus" would be clearer.
> >>>
> >>
> >> There was an arg() and abs() as in C99. But also a getArgument() but not a
> >> getAbsolute().
> >>
> >> The API is still a bit inconsistent. For example there is proj() but not
> >> getProjection().
> >
> > I recall that Eric and I had a discussion (on this ML) about whether
> > to use the Java convention or copy names from another source.
> >
> >>
> >> I think we should drop getArgument() and getAbsolute() in favour of the C99
> >> arg() and abs(). The only methods with get on the front should be for the
> >> properties real and imaginary.
> >
> > IMO, that "argument" and "magnitude" are not properties is an
> > "implementation detail".
Sorry, one consideration not taken into account in the above statement:
the class "Complex", as a ValJO, might be defined as the "Cartesian
representation of a complex number". That's also what would be deduced
from the "toString()" and "parse(String)" methods.
The fields "real" and "imaginary" are indeed "properties" and part of the API.
Hence, perhaps better to remove "getAbsolute()" and "getArgument()",
so that o.a. things the user is aware that a computation will be performed
for each call.
Regards,
Gilles
> > If we'd decide to not follow the Java convention for method names
> > (i.e. adhering to another standard is deemed better -- IIRC, Eric
> > mentioned it would be easier for developer to port codes from
> > C++), then "getReal()" and "getImaginary()" could be dropped.
> >
> > IIRC, at some point, we wondered whether to implement a low-level
> > class that could hold
> > * re
> > * im
> > and/or
> > * mag
> > * arg
> > to allow using the most favourable representation for a given
> > computation.
> > Eventually, we stuck to the simple plan (on the basis that it hasn't
> > been done that way in the C++ standard library).
>
> Perhaps on that basis we should leave the getX() methods for those values
> that can be used to represent a Complex, implementation details hidden. Thus
> we have these with their C99 equivalents:
>
> getReal() or real()
> getImaginary() or imag()
> getAbsolute() or abs()
> getArgument() or arg()
>
> Removing all the getX methods moves away from the Java convention for
> properties. The C99 aliases make it easy to port code. All other methods
> should use the C99 names.
>
> This is how the class currently stands so no changes.
>
> >
> >>
> >> Then all methods should be the C99 names.
> >
> > I'm fine with removing the aliases.
> > But then we need to have a look at the "Quaternion" class and
> > apply the same decision, for minimal API consistency between
> > implementations of related concepts.
> >
> > Best,
> > Gilles
> >
> >>>
> >>>> ---
> >>>> .../apache/commons/numbers/complex/Complex.java | 33
> >>>> ++++++++++++++++++----
> >>>> .../commons/numbers/complex/ComplexTest.java | 22
> >>>> +++++++++------
> >>>> 2 files changed, 41 insertions(+), 14 deletions(-)
> >>>>
> >>>> diff --git
> >>>>
> >>> a/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
> >>>>
> >>> b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
> >>>> index bbee805..92f4c2a 100644
> >>>> ---
> >>>>
> >>> a/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
> >>>> +++
> >>>>
> >>> b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
> >>>> @@ -284,13 +284,33 @@ public final class Complex implements
> >>> Serializable {
> >>>> return this;
> >>>> }
> >>>>
> >>>> - /**
> >>>> - * Return the absolute value of this complex number.
> >>>> - * This code follows the <a
> >>>> href="http://www.iso-9899.info/wiki/The_Standard";>ISO C Standard</a>,
> >>> Annex
> >>>> G,
> >>>> - * in calculating the returned value (i.e. the hypot(x,y) method)
> >>>> - * and in handling of NaNs.
> >>>> + /**
> >>>> + * Return the absolute value of this complex number. This is also
> >>>> called norm, modulus,
> >>>> + * or magnitude.
> >>>> + * <pre>abs(a + b i) = sqrt(a^2 + b^2)</pre>
> >>>> + *
> >>>> + * <p>If either component is infinite then the result is positive
> >>>> infinity. If either
> >>>> + * component is NaN and this is not {@link #isInfinite() infinite}
> >>> then
> >>>> the result is NaN.
> >>>> + *
> >>>> + * <p>This code follows the
> >>>> + * <a href="http://www.iso-9899.info/wiki/The_Standard";>ISO C
> >>>> Standard</a>, Annex G,
> >>>> + * in calculating the returned value using the {@code hypot(x,y)}
> >>>> method.
> >>>> *
> >>>> * @return the absolute value.
> >>>> + * @see #isInfinite()
> >>>> + * @see #isNaN()
> >>>> + * @see Math#hypot(double, double)
> >>>> + */
> >>>> + public double getAbsolute() {
> >>>> + return getAbsolute(real, imaginary);
> >>>> + }
> >>>> +
> >>>
> >>> ---------------------------------------------------------------------
> >>> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> >>> For additional commands, e-mail: dev-h...@commons.apache.org
> >>>
> >>>
> >>
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> > <mailto:dev-unsubscr...@commons.apache.org>
> > For additional commands, e-mail: dev-h...@commons.apache.org
> > <mailto:dev-h...@commons.apache.org>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
