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 * http://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 package org.apache.commons.math3; 18 19 import org.apache.commons.math3.exception.DimensionMismatchException; 20 21 /** 22 * Interface representing a <a href="http://mathworld.wolfram.com/RealNumber.html">real</a> 23 * <a href="http://mathworld.wolfram.com/Field.html">field</a>. 24 * @param <T> the type of the field elements 25 * @see FieldElement 26 * @since 3.2 27 */ 28 public interface RealFieldElement<T> extends FieldElement<T> { 29 30 /** Get the real value of the number. 31 * @return real value 32 */ getReal()33 double getReal(); 34 35 /** '+' operator. 36 * @param a right hand side parameter of the operator 37 * @return this+a 38 */ add(double a)39 T add(double a); 40 41 /** '-' operator. 42 * @param a right hand side parameter of the operator 43 * @return this-a 44 */ subtract(double a)45 T subtract(double a); 46 47 /** '×' operator. 48 * @param a right hand side parameter of the operator 49 * @return this×a 50 */ multiply(double a)51 T multiply(double a); 52 53 /** '÷' operator. 54 * @param a right hand side parameter of the operator 55 * @return this÷a 56 */ divide(double a)57 T divide(double a); 58 59 /** IEEE remainder operator. 60 * @param a right hand side parameter of the operator 61 * @return this - n × a where n is the closest integer to this/a 62 * (the even integer is chosen for n if this/a is halfway between two integers) 63 */ remainder(double a)64 T remainder(double a); 65 66 /** IEEE remainder operator. 67 * @param a right hand side parameter of the operator 68 * @return this - n × a where n is the closest integer to this/a 69 * (the even integer is chosen for n if this/a is halfway between two integers) 70 * @exception DimensionMismatchException if number of free parameters or orders are inconsistent 71 */ remainder(T a)72 T remainder(T a) 73 throws DimensionMismatchException; 74 75 /** absolute value. 76 * @return abs(this) 77 */ abs()78 T abs(); 79 80 /** Get the smallest whole number larger than instance. 81 * @return ceil(this) 82 */ ceil()83 T ceil(); 84 85 /** Get the largest whole number smaller than instance. 86 * @return floor(this) 87 */ floor()88 T floor(); 89 90 /** Get the whole number that is the nearest to the instance, or the even one if x is exactly half way between two integers. 91 * @return a double number r such that r is an integer r - 0.5 ≤ this ≤ r + 0.5 92 */ rint()93 T rint(); 94 95 /** Get the closest long to instance value. 96 * @return closest long to {@link #getReal()} 97 */ round()98 long round(); 99 100 /** Compute the signum of the instance. 101 * The signum is -1 for negative numbers, +1 for positive numbers and 0 otherwise 102 * @return -1.0, -0.0, +0.0, +1.0 or NaN depending on sign of a 103 */ signum()104 T signum(); 105 106 /** 107 * Returns the instance with the sign of the argument. 108 * A NaN {@code sign} argument is treated as positive. 109 * 110 * @param sign the sign for the returned value 111 * @return the instance with the same sign as the {@code sign} argument 112 */ copySign(T sign)113 T copySign(T sign); 114 115 /** 116 * Returns the instance with the sign of the argument. 117 * A NaN {@code sign} argument is treated as positive. 118 * 119 * @param sign the sign for the returned value 120 * @return the instance with the same sign as the {@code sign} argument 121 */ copySign(double sign)122 T copySign(double sign); 123 124 /** 125 * Multiply the instance by a power of 2. 126 * @param n power of 2 127 * @return this × 2<sup>n</sup> 128 */ scalb(int n)129 T scalb(int n); 130 131 /** 132 * Returns the hypotenuse of a triangle with sides {@code this} and {@code y} 133 * - sqrt(<i>this</i><sup>2</sup> +<i>y</i><sup>2</sup>) 134 * avoiding intermediate overflow or underflow. 135 * 136 * <ul> 137 * <li> If either argument is infinite, then the result is positive infinity.</li> 138 * <li> else, if either argument is NaN then the result is NaN.</li> 139 * </ul> 140 * 141 * @param y a value 142 * @return sqrt(<i>this</i><sup>2</sup> +<i>y</i><sup>2</sup>) 143 * @exception DimensionMismatchException if number of free parameters or orders are inconsistent 144 */ hypot(T y)145 T hypot(T y) 146 throws DimensionMismatchException; 147 148 /** {@inheritDoc} */ reciprocal()149 T reciprocal(); 150 151 /** Square root. 152 * @return square root of the instance 153 */ sqrt()154 T sqrt(); 155 156 /** Cubic root. 157 * @return cubic root of the instance 158 */ cbrt()159 T cbrt(); 160 161 /** N<sup>th</sup> root. 162 * @param n order of the root 163 * @return n<sup>th</sup> root of the instance 164 */ rootN(int n)165 T rootN(int n); 166 167 /** Power operation. 168 * @param p power to apply 169 * @return this<sup>p</sup> 170 */ pow(double p)171 T pow(double p); 172 173 /** Integer power operation. 174 * @param n power to apply 175 * @return this<sup>n</sup> 176 */ pow(int n)177 T pow(int n); 178 179 /** Power operation. 180 * @param e exponent 181 * @return this<sup>e</sup> 182 * @exception DimensionMismatchException if number of free parameters or orders are inconsistent 183 */ pow(T e)184 T pow(T e) 185 throws DimensionMismatchException; 186 187 /** Exponential. 188 * @return exponential of the instance 189 */ exp()190 T exp(); 191 192 /** Exponential minus 1. 193 * @return exponential minus one of the instance 194 */ expm1()195 T expm1(); 196 197 /** Natural logarithm. 198 * @return logarithm of the instance 199 */ log()200 T log(); 201 202 /** Shifted natural logarithm. 203 * @return logarithm of one plus the instance 204 */ log1p()205 T log1p(); 206 207 // TODO: add this method in 4.0, as it is not possible to do it in 3.2 208 // due to incompatibility of the return type in the Dfp class 209 // /** Base 10 logarithm. 210 // * @return base 10 logarithm of the instance 211 // */ 212 // T log10(); 213 214 /** Cosine operation. 215 * @return cos(this) 216 */ cos()217 T cos(); 218 219 /** Sine operation. 220 * @return sin(this) 221 */ sin()222 T sin(); 223 224 /** Tangent operation. 225 * @return tan(this) 226 */ tan()227 T tan(); 228 229 /** Arc cosine operation. 230 * @return acos(this) 231 */ acos()232 T acos(); 233 234 /** Arc sine operation. 235 * @return asin(this) 236 */ asin()237 T asin(); 238 239 /** Arc tangent operation. 240 * @return atan(this) 241 */ atan()242 T atan(); 243 244 /** Two arguments arc tangent operation. 245 * @param x second argument of the arc tangent 246 * @return atan2(this, x) 247 * @exception DimensionMismatchException if number of free parameters or orders are inconsistent 248 */ atan2(T x)249 T atan2(T x) 250 throws DimensionMismatchException; 251 252 /** Hyperbolic cosine operation. 253 * @return cosh(this) 254 */ cosh()255 T cosh(); 256 257 /** Hyperbolic sine operation. 258 * @return sinh(this) 259 */ sinh()260 T sinh(); 261 262 /** Hyperbolic tangent operation. 263 * @return tanh(this) 264 */ tanh()265 T tanh(); 266 267 /** Inverse hyperbolic cosine operation. 268 * @return acosh(this) 269 */ acosh()270 T acosh(); 271 272 /** Inverse hyperbolic sine operation. 273 * @return asin(this) 274 */ asinh()275 T asinh(); 276 277 /** Inverse hyperbolic tangent operation. 278 * @return atanh(this) 279 */ atanh()280 T atanh(); 281 282 /** 283 * Compute a linear combination. 284 * @param a Factors. 285 * @param b Factors. 286 * @return <code>Σ<sub>i</sub> a<sub>i</sub> b<sub>i</sub></code>. 287 * @throws DimensionMismatchException if arrays dimensions don't match 288 * @since 3.2 289 */ linearCombination(T[] a, T[] b)290 T linearCombination(T[] a, T[] b) 291 throws DimensionMismatchException; 292 293 /** 294 * Compute a linear combination. 295 * @param a Factors. 296 * @param b Factors. 297 * @return <code>Σ<sub>i</sub> a<sub>i</sub> b<sub>i</sub></code>. 298 * @throws DimensionMismatchException if arrays dimensions don't match 299 * @since 3.2 300 */ linearCombination(double[] a, T[] b)301 T linearCombination(double[] a, T[] b) 302 throws DimensionMismatchException; 303 304 /** 305 * Compute a linear combination. 306 * @param a1 first factor of the first term 307 * @param b1 second factor of the first term 308 * @param a2 first factor of the second term 309 * @param b2 second factor of the second term 310 * @return a<sub>1</sub>×b<sub>1</sub> + 311 * a<sub>2</sub>×b<sub>2</sub> 312 * @see #linearCombination(Object, Object, Object, Object, Object, Object) 313 * @see #linearCombination(Object, Object, Object, Object, Object, Object, Object, Object) 314 * @since 3.2 315 */ linearCombination(T a1, T b1, T a2, T b2)316 T linearCombination(T a1, T b1, T a2, T b2); 317 318 /** 319 * Compute a linear combination. 320 * @param a1 first factor of the first term 321 * @param b1 second factor of the first term 322 * @param a2 first factor of the second term 323 * @param b2 second factor of the second term 324 * @return a<sub>1</sub>×b<sub>1</sub> + 325 * a<sub>2</sub>×b<sub>2</sub> 326 * @see #linearCombination(double, Object, double, Object, double, Object) 327 * @see #linearCombination(double, Object, double, Object, double, Object, double, Object) 328 * @since 3.2 329 */ linearCombination(double a1, T b1, double a2, T b2)330 T linearCombination(double a1, T b1, double a2, T b2); 331 332 /** 333 * Compute a linear combination. 334 * @param a1 first factor of the first term 335 * @param b1 second factor of the first term 336 * @param a2 first factor of the second term 337 * @param b2 second factor of the second term 338 * @param a3 first factor of the third term 339 * @param b3 second factor of the third term 340 * @return a<sub>1</sub>×b<sub>1</sub> + 341 * a<sub>2</sub>×b<sub>2</sub> + a<sub>3</sub>×b<sub>3</sub> 342 * @see #linearCombination(Object, Object, Object, Object) 343 * @see #linearCombination(Object, Object, Object, Object, Object, Object, Object, Object) 344 * @since 3.2 345 */ linearCombination(T a1, T b1, T a2, T b2, T a3, T b3)346 T linearCombination(T a1, T b1, T a2, T b2, T a3, T b3); 347 348 /** 349 * Compute a linear combination. 350 * @param a1 first factor of the first term 351 * @param b1 second factor of the first term 352 * @param a2 first factor of the second term 353 * @param b2 second factor of the second term 354 * @param a3 first factor of the third term 355 * @param b3 second factor of the third term 356 * @return a<sub>1</sub>×b<sub>1</sub> + 357 * a<sub>2</sub>×b<sub>2</sub> + a<sub>3</sub>×b<sub>3</sub> 358 * @see #linearCombination(double, Object, double, Object) 359 * @see #linearCombination(double, Object, double, Object, double, Object, double, Object) 360 * @since 3.2 361 */ linearCombination(double a1, T b1, double a2, T b2, double a3, T b3)362 T linearCombination(double a1, T b1, double a2, T b2, double a3, T b3); 363 364 /** 365 * Compute a linear combination. 366 * @param a1 first factor of the first term 367 * @param b1 second factor of the first term 368 * @param a2 first factor of the second term 369 * @param b2 second factor of the second term 370 * @param a3 first factor of the third term 371 * @param b3 second factor of the third term 372 * @param a4 first factor of the third term 373 * @param b4 second factor of the third term 374 * @return a<sub>1</sub>×b<sub>1</sub> + 375 * a<sub>2</sub>×b<sub>2</sub> + a<sub>3</sub>×b<sub>3</sub> + 376 * a<sub>4</sub>×b<sub>4</sub> 377 * @see #linearCombination(Object, Object, Object, Object) 378 * @see #linearCombination(Object, Object, Object, Object, Object, Object) 379 * @since 3.2 380 */ linearCombination(T a1, T b1, T a2, T b2, T a3, T b3, T a4, T b4)381 T linearCombination(T a1, T b1, T a2, T b2, T a3, T b3, T a4, T b4); 382 383 /** 384 * Compute a linear combination. 385 * @param a1 first factor of the first term 386 * @param b1 second factor of the first term 387 * @param a2 first factor of the second term 388 * @param b2 second factor of the second term 389 * @param a3 first factor of the third term 390 * @param b3 second factor of the third term 391 * @param a4 first factor of the third term 392 * @param b4 second factor of the third term 393 * @return a<sub>1</sub>×b<sub>1</sub> + 394 * a<sub>2</sub>×b<sub>2</sub> + a<sub>3</sub>×b<sub>3</sub> + 395 * a<sub>4</sub>×b<sub>4</sub> 396 * @see #linearCombination(double, Object, double, Object) 397 * @see #linearCombination(double, Object, double, Object, double, Object) 398 * @since 3.2 399 */ linearCombination(double a1, T b1, double a2, T b2, double a3, T b3, double a4, T b4)400 T linearCombination(double a1, T b1, double a2, T b2, double a3, T b3, double a4, T b4); 401 402 } 403