1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 /*
19 * This is not the original file distributed by the Apache Software Foundation
20 * It has been modified by the Hipparchus project
21 */
22 package org.hipparchus;
23
24 import org.hipparchus.exception.MathRuntimeException;
25 import org.hipparchus.exception.NullArgumentException;
26
27
28 /**
29 * Interface representing <a href="http://mathworld.wolfram.com/Field.html">field</a> elements.
30 * @param <T> the type of the field elements
31 * @see Field
32 */
33 public interface FieldElement<T extends FieldElement<T>> {
34
35 /** Get the real value of the number.
36 * @return real value
37 */
38 double getReal();
39
40 /** Compute this + a.
41 * @param a element to add
42 * @return a new element representing this + a
43 * @throws NullArgumentException if {@code a} is {@code null}.
44 */
45 T add(T a) throws NullArgumentException;
46
47 /** Compute this - a.
48 * @param a element to subtract
49 * @return a new element representing this - a
50 * @throws NullArgumentException if {@code a} is {@code null}.
51 */
52 T subtract(T a) throws NullArgumentException;
53
54 /**
55 * Returns the additive inverse of {@code this} element.
56 * @return the opposite of {@code this}.
57 */
58 T negate();
59
60 /** Compute n × this. Multiplication by an integer number is defined
61 * as the following sum
62 * \[
63 * n \times \mathrm{this} = \sum_{i=1}^n \mathrm{this}
64 * \]
65 * @param n Number of times {@code this} must be added to itself.
66 * @return A new element representing n × this.
67 */
68 T multiply(int n);
69
70 /** Compute this × a.
71 * @param a element to multiply
72 * @return a new element representing this × a
73 * @throws NullArgumentException if {@code a} is {@code null}.
74 */
75 T multiply(T a) throws NullArgumentException;
76
77 /** Compute this ÷ a.
78 * @param a element to divide by
79 * @return a new element representing this ÷ a
80 * @throws NullArgumentException if {@code a} is {@code null}.
81 * @throws MathRuntimeException if {@code a} is zero
82 */
83 T divide(T a) throws NullArgumentException, MathRuntimeException;
84
85 /**
86 * Returns the multiplicative inverse of {@code this} element.
87 * @return the inverse of {@code this}.
88 * @throws MathRuntimeException if {@code this} is zero
89 */
90 T reciprocal() throws MathRuntimeException;
91
92 /** Get the {@link Field} to which the instance belongs.
93 * @return {@link Field} to which the instance belongs
94 */
95 Field<T> getField();
96
97 /** Check if an element is semantically equal to zero.
98 * <p>
99 * The default implementation simply calls {@code equals(getField().getZero())}.
100 * However, this may need to be overridden in some cases as due to
101 * compatibility with {@code hashCode()} some classes implements
102 * {@code equals(Object)} in such a way that -0.0 and +0.0 are different,
103 * which may be a problem. It prevents for example identifying a diagonal
104 * element is zero and should be avoided when doing partial pivoting in
105 * LU decomposition.
106 * </p>
107 * @return true if the element is semantically equal to zero
108 * @since 1.8
109 */
110 default boolean isZero() {
111 return equals(getField().getZero());
112 }
113
114 }