You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ah...@apache.org on 2019/12/08 01:00:40 UTC
[commons-numbers] 02/03: Added getAbsolute() to complement
getArgument().
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 <ah...@apache.org>
AuthorDate: Sun Dec 8 00:54:03 2019 +0000
Added getAbsolute() to complement getArgument().
---
.../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);
+ }
+
+ /**
+ * Compute the absolute of this complex number
+ * (C++11 grammar).
+ *
+ * @return the absolute of {@code this}.
+ * @see #getAbsolute()
*/
public double abs() {
return getAbsolute(real, imaginary);
@@ -1837,7 +1857,8 @@ public final class Complex implements Serializable {
/**
* Compute the argument of this complex number.
- * The argument is the angle phi between the positive real axis and
+ *
+ * <p>The argument is the angle phi between the positive real axis and
* the point representing this number in the complex plane.
* The value returned is between -PI (not inclusive)
* and PI (inclusive), with negative values returned for numbers with
diff --git a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexTest.java b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexTest.java
index 57e03d3..776405a 100644
--- a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexTest.java
+++ b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexTest.java
@@ -177,17 +177,22 @@ public class ComplexTest {
}
@Test
- public void testAbs() {
+ public void testAbsolute() {
final Complex z = Complex.ofCartesian(3.0, 4.0);
- Assertions.assertEquals(5.0, z.abs(), 1.0e-5);
+ Assertions.assertEquals(5.0, z.getAbsolute());
}
@Test
- public void testAbsNaN() {
- Assertions.assertTrue(Double.isNaN(NAN.abs()));
- // The result is infinite if either argument is infinite
- Assertions.assertEquals(inf, Complex.ofCartesian(inf, nan).abs());
- Assertions.assertEquals(inf, Complex.ofCartesian(nan, inf).abs());
+ public void testAbsoluteNaN() {
+ // The result is NaN if either argument is NaN and the other is not infinite
+ Assertions.assertEquals(nan, NAN.getAbsolute());
+ Assertions.assertEquals(nan, Complex.ofCartesian(3.0, nan).getAbsolute());
+ Assertions.assertEquals(nan, Complex.ofCartesian(nan, 3.0).getAbsolute());
+ // The result is positive infinite if either argument is infinite
+ Assertions.assertEquals(inf, Complex.ofCartesian(inf, nan).getAbsolute());
+ Assertions.assertEquals(inf, Complex.ofCartesian(-inf, nan).getAbsolute());
+ Assertions.assertEquals(inf, Complex.ofCartesian(nan, inf).getAbsolute());
+ Assertions.assertEquals(inf, Complex.ofCartesian(nan, -inf).getAbsolute());
}
@Test
@@ -1282,6 +1287,7 @@ public class ComplexTest {
Assertions.assertEquals(z.getImaginary(), z.imag(), "imag");
Assertions.assertEquals(z.conjugate(), z.conj(), "conj");
Assertions.assertEquals(z.getArgument(), z.arg(), "arg");
+ Assertions.assertEquals(z.getAbsolute(), z.abs(), "abs");
}
}
@@ -1296,7 +1302,7 @@ public class ComplexTest {
// This is prone to floating-point error so use a delta
Assertions.assertEquals(lnz.getReal() / ln10, log10z.getReal(), 1e-12, "real");
// This test should be exact
- final double abs = z.abs();
+ final double abs = z.getAbsolute();
Assertions.assertEquals(Math.log10(abs), log10z.getReal(), "real");
Assertions.assertEquals(lnz.getImaginary(), log10z.getImaginary(), "imag");
}
Re: [commons-numbers] 02/03: Added getAbsolute() to complement getArgument().
Posted by Gilles Sadowski <gi...@gmail.com>.
2019-12-08 18:52 UTC+01:00, Alex Herbert <al...@gmail.com>:
>
>
>> …
>
> Would this also apply to conjugate() and conj()?
>
> ISO C99 uses conj().
+1 (Why not?)
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [commons-numbers] 02/03: Added getAbsolute() to complement
getArgument().
Posted by Alex Herbert <al...@gmail.com>.
> …
Would this also apply to conjugate() and conj()?
ISO C99 uses conj().
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [commons-numbers] 02/03: Added getAbsolute() to complement
getArgument().
Posted by Alex Herbert <al...@gmail.com>.
> On 8 Dec 2019, at 14:52, Gilles Sadowski <gi...@gmail.com> wrote:
>
> Le dim. 8 déc. 2019 à 13:32, Alex Herbert <alex.d.herbert@gmail.com <ma...@gmail.com>> a écrit :
>>
>>
>>
>>> On 8 Dec 2019, at 11:24, Gilles Sadowski <gilleseran@gmail.com <ma...@gmail.com>> wrote:
>>>
>>> Hi.
>>>
>>> 2019-12-08 10:45 UTC+01:00, Alex Herbert <alex.d.herbert@gmail.com <ma...@gmail.com> <mailto:alex.d.herbert@gmail.com <ma...@gmail.com>>>:
>>>> On Sun, 8 Dec 2019, 01:50 Gilles Sadowski, <gi...@gmail.com> wrote:
>>>>
>>>>> 2019-12-08 2:00 UTC+01:00, aherbert@apache.org <ah...@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 <ah...@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.
OK, I’ll update and add the “Cartesian representation of a complex number” in the class javadoc, along with Sebb’s suggestion to document the choice of method names (e.g. abs() rather than magnitude()). I’ll also correct the class javadoc which refers to the old definition of equals where different NaNs were equal. I hadn’t noticed before.
>
> 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-unsubscribe@commons.apache.org
>>>>> For additional commands, e-mail: dev-help@commons.apache.org
>>>>>
>>>>>
>>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org <ma...@commons.apache.org> <mailto:dev-unsubscribe@commons.apache.org <ma...@commons.apache.org>>
>>> For additional commands, e-mail: dev-help@commons.apache.org <ma...@commons.apache.org> <mailto:dev-help@commons.apache.org <ma...@commons.apache.org>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org <ma...@commons.apache.org>
> For additional commands, e-mail: dev-help@commons.apache.org <ma...@commons.apache.org>
Re: [commons-numbers] 02/03: Added getAbsolute() to complement getArgument().
Posted by Gilles Sadowski <gi...@gmail.com>.
Le dim. 8 déc. 2019 à 13:32, Alex Herbert <al...@gmail.com> a écrit :
>
>
>
> > On 8 Dec 2019, at 11:24, Gilles Sadowski <gi...@gmail.com> wrote:
> >
> > Hi.
> >
> > 2019-12-08 10:45 UTC+01:00, Alex Herbert <alex.d.herbert@gmail.com <ma...@gmail.com>>:
> >> On Sun, 8 Dec 2019, 01:50 Gilles Sadowski, <gi...@gmail.com> wrote:
> >>
> >>> 2019-12-08 2:00 UTC+01:00, aherbert@apache.org <ah...@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 <ah...@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-unsubscribe@commons.apache.org
> >>> For additional commands, e-mail: dev-help@commons.apache.org
> >>>
> >>>
> >>
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org <ma...@commons.apache.org>
> > For additional commands, e-mail: dev-help@commons.apache.org <ma...@commons.apache.org>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [commons-numbers] 02/03: Added getAbsolute() to complement getArgument().
Posted by sebb <se...@gmail.com>.
On Sun, 8 Dec 2019 at 12:32, Alex Herbert <al...@gmail.com> wrote:
>
>
> > On 8 Dec 2019, at 11:24, Gilles Sadowski <gi...@gmail.com> wrote:
> >
> > Hi.
> >
> > 2019-12-08 10:45 UTC+01:00, Alex Herbert <alex.d.herbert@gmail.com
> <ma...@gmail.com>>:
> >> On Sun, 8 Dec 2019, 01:50 Gilles Sadowski, <gi...@gmail.com>
> wrote:
> >>
> >>> 2019-12-08 2:00 UTC+01:00, aherbert@apache.org <ah...@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 <ah...@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-unsubscribe@commons.apache.org
> >>> For additional commands, e-mail: dev-help@commons.apache.org
> >>>
> >>>
> >>
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org <mailto:
> dev-unsubscribe@commons.apache.org>
> > For additional commands, e-mail: dev-help@commons.apache.org <mailto:
> dev-help@commons.apache.org>
>
Re: [commons-numbers] 02/03: Added getAbsolute() to complement
getArgument().
Posted by Alex Herbert <al...@gmail.com>.
> On 8 Dec 2019, at 11:24, Gilles Sadowski <gi...@gmail.com> wrote:
>
> Hi.
>
> 2019-12-08 10:45 UTC+01:00, Alex Herbert <alex.d.herbert@gmail.com <ma...@gmail.com>>:
>> On Sun, 8 Dec 2019, 01:50 Gilles Sadowski, <gi...@gmail.com> wrote:
>>
>>> 2019-12-08 2:00 UTC+01:00, aherbert@apache.org <ah...@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 <ah...@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.
>
>>
>> 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-unsubscribe@commons.apache.org
>>> For additional commands, e-mail: dev-help@commons.apache.org
>>>
>>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org <ma...@commons.apache.org>
> For additional commands, e-mail: dev-help@commons.apache.org <ma...@commons.apache.org>
Re: [commons-numbers] 02/03: Added getAbsolute() to complement getArgument().
Posted by Gilles Sadowski <gi...@gmail.com>.
Hi.
2019-12-08 10:45 UTC+01:00, Alex Herbert <al...@gmail.com>:
> On Sun, 8 Dec 2019, 01:50 Gilles Sadowski, <gi...@gmail.com> wrote:
>
>> 2019-12-08 2:00 UTC+01:00, aherbert@apache.org <ah...@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 <ah...@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).
>
> 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-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [commons-numbers] 02/03: Added getAbsolute() to complement getArgument().
Posted by Alex Herbert <al...@gmail.com>.
On Sun, 8 Dec 2019, 01:50 Gilles Sadowski, <gi...@gmail.com> wrote:
> 2019-12-08 2:00 UTC+01:00, aherbert@apache.org <ah...@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 <ah...@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 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.
Then all methods should be the C99 names.
> 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-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
Re: [commons-numbers] 02/03: Added getAbsolute() to complement getArgument().
Posted by Gilles Sadowski <gi...@gmail.com>.
2019-12-08 2:00 UTC+01:00, aherbert@apache.org <ah...@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 <ah...@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.
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-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org