On Sun, 8 Dec 2019 at 12:32, Alex Herbert <alex.d.herb...@gmail.com> wrote:
> > > > 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". > > 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. > > I'd suggest one change: document the decision on the naming convention in the class(es) themselves. > > > >> > >> 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> >
