diff options
Diffstat (limited to 'src/library/scala/math')
-rw-r--r-- | src/library/scala/math/BigDecimal.scala | 137 | ||||
-rw-r--r-- | src/library/scala/math/BigInt.scala | 27 | ||||
-rw-r--r-- | src/library/scala/math/Integral.scala | 2 | ||||
-rw-r--r-- | src/library/scala/math/Ordering.scala | 22 | ||||
-rw-r--r-- | src/library/scala/math/package.scala | 259 |
5 files changed, 266 insertions, 181 deletions
diff --git a/src/library/scala/math/BigDecimal.scala b/src/library/scala/math/BigDecimal.scala index bb337e7a1d..4bc0c0cf95 100644 --- a/src/library/scala/math/BigDecimal.scala +++ b/src/library/scala/math/BigDecimal.scala @@ -10,13 +10,12 @@ package scala package math -import java.{ lang => jl } -import java.math.{ MathContext, BigDecimal => BigDec } -import scala.collection.immutable.NumericRange import scala.language.implicitConversions +import java.math.{ MathContext, BigDecimal => BigDec } +import scala.collection.immutable.NumericRange -/** +/** * @author Stephane Micheloud * @author Rex Kerr * @version 1.1 @@ -44,17 +43,17 @@ object BigDecimal { val HALF_UP = Value(RM.HALF_UP.ordinal) val HALF_DOWN = Value(RM.HALF_DOWN.ordinal) val HALF_EVEN = Value(RM.HALF_EVEN.ordinal) - val UNNECESSARY = Value(RM.UNNECESSARY.ordinal) + val UNNECESSARY = Value(RM.UNNECESSARY.ordinal) } - + /** Constructs a `BigDecimal` using the decimal text representation of `Double` value `d`, rounding if necessary. */ def decimal(d: Double, mc: MathContext): BigDecimal = new BigDecimal(new BigDec(java.lang.Double.toString(d), mc), mc) /** Constructs a `BigDecimal` using the decimal text representation of `Double` value `d`. */ def decimal(d: Double): BigDecimal = decimal(d, defaultMathContext) - - /** Constructs a `BigDecimal` using the decimal text representation of `Float` value `f`, rounding if necessary. + + /** Constructs a `BigDecimal` using the decimal text representation of `Float` value `f`, rounding if necessary. * Note that `BigDecimal.decimal(0.1f) != 0.1f` since equality agrees with the `Double` representation, and * `0.1 != 0.1f`. */ @@ -66,18 +65,18 @@ object BigDecimal { * `0.1 != 0.1f`. */ def decimal(f: Float): BigDecimal = decimal(f, defaultMathContext) - + // This exists solely to avoid conversion from Int/Long to Float, screwing everything up. /** Constructs a `BigDecimal` from a `Long`, rounding if necessary. This is identical to `BigDecimal(l, mc)`. */ def decimal(l: Long, mc: MathContext): BigDecimal = apply(l, mc) - + // This exists solely to avoid conversion from Int/Long to Float, screwing everything up. /** Constructs a `BigDecimal` from a `Long`. This is identical to `BigDecimal(l)`. */ def decimal(l: Long): BigDecimal = apply(l) - + /** Constructs a `BigDecimal` using a `java.math.BigDecimal`, rounding if necessary. */ def decimal(bd: BigDec, mc: MathContext): BigDecimal = new BigDecimal(bd.round(mc), mc) - + /** Constructs a `BigDecimal` by expanding the binary fraction * contained by `Double` value `d` into a decimal representation, * rounding if necessary. When a `Float` is converted to a @@ -85,50 +84,50 @@ object BigDecimal { * also works for converted `Float`s. */ def binary(d: Double, mc: MathContext): BigDecimal = new BigDecimal(new BigDec(d, mc), mc) - + /** Constructs a `BigDecimal` by expanding the binary fraction * contained by `Double` value `d` into a decimal representation. * Note: this also works correctly on converted `Float`s. */ def binary(d: Double): BigDecimal = binary(d, defaultMathContext) - + /** Constructs a `BigDecimal` from a `java.math.BigDecimal`. The * precision is the default for `BigDecimal` or enough to represent * the `java.math.BigDecimal` exactly, whichever is greater. */ def exact(repr: BigDec): BigDecimal = { - val mc = + val mc = if (repr.precision <= defaultMathContext.getPrecision) defaultMathContext else new MathContext(repr.precision, java.math.RoundingMode.HALF_EVEN) new BigDecimal(repr, mc) } - + /** Constructs a `BigDecimal` by fully expanding the binary fraction * contained by `Double` value `d`, adjusting the precision as * necessary. Note: this works correctly on converted `Float`s also. */ def exact(d: Double): BigDecimal = exact(new BigDec(d)) - + /** Constructs a `BigDecimal` that exactly represents a `BigInt`. */ def exact(bi: BigInt): BigDecimal = exact(new BigDec(bi.bigInteger)) - + /** Constructs a `BigDecimal` that exactly represents a `Long`. Note that * all creation methods for `BigDecimal` that do not take a `MathContext` * represent a `Long`; this is equivalent to `apply`, `valueOf`, etc.. */ def exact(l: Long): BigDecimal = apply(l) - + /** Constructs a `BigDecimal` that exactly represents the number * specified in a `String`. */ def exact(s: String): BigDecimal = exact(new BigDec(s)) - + /** Constructs a `BigDecimal` that exactly represents the number * specified in base 10 in a character array. */ def exact(cs: Array[Char]): BigDecimal = exact(new BigDec(cs)) - + /** Constructs a `BigDecimal` using the java BigDecimal static * valueOf constructor. Equivalent to `BigDecimal.decimal`. @@ -137,7 +136,7 @@ object BigDecimal { * @return the constructed `BigDecimal` */ def valueOf(d: Double): BigDecimal = apply(BigDec valueOf d) - + /** Constructs a `BigDecimal` using the java BigDecimal static * valueOf constructor, specifying a `MathContext` that is * used for computations but isn't used for rounding. Use @@ -149,9 +148,9 @@ object BigDecimal { * @param mc the `MathContext` used for future computations * @return the constructed `BigDecimal` */ - @deprecated("MathContext is not applied to Doubles in valueOf. Use BigDecimal.decimal to use rounding, or java.math.BigDecimal.valueOf to avoid it.","2.11") + @deprecated("MathContext is not applied to Doubles in valueOf. Use BigDecimal.decimal to use rounding, or java.math.BigDecimal.valueOf to avoid it.", "2.11.0") def valueOf(d: Double, mc: MathContext): BigDecimal = apply(BigDec valueOf d, mc) - + /** Constructs a `BigDecimal` using the java BigDecimal static * valueOf constructor. * @@ -159,22 +158,22 @@ object BigDecimal { * @return the constructed `BigDecimal` */ def valueOf(x: Long): BigDecimal = apply(x) - + /** Constructs a `BigDecimal` using the java BigDecimal static * valueOf constructor. This is unlikely to do what you want; * use `valueOf(f.toDouble)` or `decimal(f)` instead. */ - @deprecated("Float arguments to valueOf may not do what you wish. Use decimal or valueOf(f.toDouble).","2.11") + @deprecated("Float arguments to valueOf may not do what you wish. Use decimal or valueOf(f.toDouble).", "2.11.0") def valueOf(f: Float): BigDecimal = valueOf(f.toDouble) - + /** Constructs a `BigDecimal` using the java BigDecimal static * valueOf constructor. This is unlikely to do what you want; * use `valueOf(f.toDouble)` or `decimal(f)` instead. */ - @deprecated("Float arguments to valueOf may not do what you wish. Use decimal or valueOf(f.toDouble).","2.11") + @deprecated("Float arguments to valueOf may not do what you wish. Use decimal or valueOf(f.toDouble).", "2.11.0") def valueOf(f: Float, mc: MathContext): BigDecimal = valueOf(f.toDouble, mc) - + /** Constructs a `BigDecimal` whose value is equal to that of the * specified `Integer` value. * @@ -247,7 +246,7 @@ object BigDecimal { * @return the constructed `BigDecimal` */ def apply(d: Double): BigDecimal = decimal(d, defaultMathContext) - + // note we don't use the static valueOf because it doesn't let us supply // a MathContext, but we should be duplicating its logic, modulo caching. /** Constructs a `BigDecimal` whose value is equal to that of the @@ -260,10 +259,10 @@ object BigDecimal { */ def apply(d: Double, mc: MathContext): BigDecimal = decimal(d, mc) - @deprecated("The default conversion from Float may not do what you want. Use BigDecimal.decimal for a String representation, or explicitly convert the Float with .toDouble.", "2.11") + @deprecated("The default conversion from Float may not do what you want. Use BigDecimal.decimal for a String representation, or explicitly convert the Float with .toDouble.", "2.11.0") def apply(x: Float): BigDecimal = apply(x.toDouble) - @deprecated("The default conversion from Float may not do what you want. Use BigDecimal.decimal for a String representation, or explicitly convert the Float with .toDouble.", "2.11") + @deprecated("The default conversion from Float may not do what you want. Use BigDecimal.decimal for a String representation, or explicitly convert the Float with .toDouble.", "2.11.0") def apply(x: Float, mc: MathContext): BigDecimal = apply(x.toDouble, mc) /** Translates a character array representation of a `BigDecimal` @@ -281,7 +280,7 @@ object BigDecimal { * into a `BigDecimal`. */ def apply(x: String): BigDecimal = exact(x) - + /** Translates the decimal String representation of a `BigDecimal` * into a `BigDecimal`, rounding if necessary. */ @@ -295,12 +294,12 @@ object BigDecimal { * @return the constructed `BigDecimal` */ def apply(x: BigInt): BigDecimal = exact(x) - + /** Constructs a `BigDecimal` whose value is equal to that of the * specified `BigInt` value, rounding if necessary. * * @param x the specified `BigInt` value - * @param mc the precision and rounding mode for creation of this value and future operations on it + * @param mc the precision and rounding mode for creation of this value and future operations on it * @return the constructed `BigDecimal` */ def apply(x: BigInt, mc: MathContext): BigDecimal = @@ -315,13 +314,13 @@ object BigDecimal { */ def apply(unscaledVal: BigInt, scale: Int): BigDecimal = exact(new BigDec(unscaledVal.bigInteger, scale)) - + /** Constructs a `BigDecimal` whose unscaled value is equal to that * of the specified `BigInt` value. * * @param unscaledVal the specified `BigInt` value * @param scale the scale - * @param mc the precision and rounding mode for creation of this value and future operations on it + * @param mc the precision and rounding mode for creation of this value and future operations on it * @return the constructed `BigDecimal` */ def apply(unscaledVal: BigInt, scale: Int, mc: MathContext): BigDecimal = @@ -329,8 +328,8 @@ object BigDecimal { /** Constructs a `BigDecimal` from a `java.math.BigDecimal`. */ def apply(bd: BigDec): BigDecimal = apply(bd, defaultMathContext) - - @deprecated("This method appears to round a java.math.BigDecimal but actually doesn't. Use new BigDecimal(bd, mc) instead for no rounding, or BigDecimal.decimal(bd, mc) for rounding.", "2.11") + + @deprecated("This method appears to round a java.math.BigDecimal but actually doesn't. Use new BigDecimal(bd, mc) instead for no rounding, or BigDecimal.decimal(bd, mc) for rounding.", "2.11.0") def apply(bd: BigDec, mc: MathContext): BigDecimal = new BigDecimal(bd, mc) /** Implicit conversion from `Int` to `BigDecimal`. */ @@ -398,11 +397,11 @@ object BigDecimal { * @version 1.1 */ final class BigDecimal(val bigDecimal: BigDec, val mc: MathContext) -extends ScalaNumber with ScalaNumericConversions with Serializable { +extends ScalaNumber with ScalaNumericConversions with Serializable with Ordered[BigDecimal] { def this(bigDecimal: BigDec) = this(bigDecimal, BigDecimal.defaultMathContext) import BigDecimal.RoundingMode._ import BigDecimal.{decimal, binary, exact} - + if (bigDecimal eq null) throw new IllegalArgumentException("null value for BigDecimal") if (mc eq null) throw new IllegalArgumentException("null MathContext for BigDecimal") @@ -423,7 +422,7 @@ extends ScalaNumber with ScalaNumericConversions with Serializable { scala.util.hashing.MurmurHash3.mixLast( temp.scaleByPowerOfTen(temp.scale).toBigInteger.hashCode, temp.scale ) } } - + /** Returns the hash code for this BigDecimal. * Note that this does not merely use the underlying java object's * `hashCode` because we compare `BigDecimal`s with `compareTo` @@ -444,15 +443,15 @@ extends ScalaNumber with ScalaNumericConversions with Serializable { */ override def equals (that: Any): Boolean = that match { case that: BigDecimal => this equals that - case that: BigInt => - that.bitLength > (precision-scale-2)*BigDecimal.deci2binary && + case that: BigInt => + that.bitLength > (precision-scale-2)*BigDecimal.deci2binary && this.toBigIntExact.exists(that equals _) - case that: Double => + case that: Double => !that.isInfinity && { val d = toDouble !d.isInfinity && d == that && equals(decimal(d)) } - case that: Float => + case that: Float => !that.isInfinity && { val f = toFloat !f.isInfinity && f == that && equals(decimal(f.toDouble)) @@ -468,7 +467,7 @@ extends ScalaNumber with ScalaNumericConversions with Serializable { * `isExactFloat`, `isBinaryFloat`, or `isDecimalFloat`, depending on the intended meaning. * By default, `decimal` creation is used, so `isDecimalFloat` is probably what you want. */ - @deprecated("What constitutes validity is unclear. Use `isExactFloat`, `isBinaryFloat`, or `isDecimalFloat` instead.", "2.11") + @deprecated("What constitutes validity is unclear. Use `isExactFloat`, `isBinaryFloat`, or `isDecimalFloat` instead.", "2.11.0") def isValidFloat = { val f = toFloat !f.isInfinity && bigDecimal.compareTo(new BigDec(f.toDouble)) == 0 @@ -477,48 +476,48 @@ extends ScalaNumber with ScalaNumericConversions with Serializable { * `isExactDouble`, `isBinaryDouble`, or `isDecimalDouble`, depending on the intended meaning. * By default, `decimal` creation is used, so `isDecimalDouble` is probably what you want. */ - @deprecated("Validity has distinct meanings. Use `isExactDouble`, `isBinaryDouble`, or `isDecimalDouble` instead.", "2.11") + @deprecated("Validity has distinct meanings. Use `isExactDouble`, `isBinaryDouble`, or `isDecimalDouble` instead.", "2.11.0") def isValidDouble = { val d = toDouble !d.isInfinity && bigDecimal.compareTo(new BigDec(d)) == 0 } - + /** Tests whether this `BigDecimal` holds the decimal representation of a `Double`. */ def isDecimalDouble = { val d = toDouble !d.isInfinity && equals(decimal(d)) } - + /** Tests whether this `BigDecimal` holds the decimal representation of a `Float`. */ def isDecimalFloat = { val f = toFloat !f.isInfinity && equals(decimal(f)) } - + /** Tests whether this `BigDecimal` holds, to within precision, the binary representation of a `Double`. */ def isBinaryDouble = { val d = toDouble !d.isInfinity && equals(binary(d,mc)) } - + /** Tests whether this `BigDecimal` holds, to within precision, the binary representation of a `Float`. */ def isBinaryFloat = { val f = toFloat !f.isInfinity && equals(binary(f,mc)) } - + /** Tests whether this `BigDecimal` holds the exact expansion of a `Double`'s binary fractional form into base 10. */ def isExactDouble = { val d = toDouble !d.isInfinity && equals(exact(d)) } - + /** Tests whether this `BigDecimal` holds the exact expansion of a `Float`'s binary fractional form into base 10. */ def isExactFloat = { val f = toFloat !f.isInfinity && equals(exact(f.toDouble)) } - + private def noArithmeticException(body: => Unit): Boolean = { try { body ; true } @@ -526,9 +525,9 @@ extends ScalaNumber with ScalaNumericConversions with Serializable { } def isWhole() = scale <= 0 || bigDecimal.stripTrailingZeros.scale <= 0 - + def underlying = bigDecimal - + /** Compares this BigDecimal with the specified BigDecimal for equality. */ @@ -538,22 +537,6 @@ extends ScalaNumber with ScalaNumericConversions with Serializable { */ def compare (that: BigDecimal): Int = this.bigDecimal compareTo that.bigDecimal - /** Less-than-or-equals comparison of BigDecimals - */ - def <= (that: BigDecimal): Boolean = compare(that) <= 0 - - /** Greater-than-or-equals comparison of BigDecimals - */ - def >= (that: BigDecimal): Boolean = compare(that) >= 0 - - /** Less-than of BigDecimals - */ - def < (that: BigDecimal): Boolean = compare(that) < 0 - - /** Greater-than comparison of BigDecimals - */ - def > (that: BigDecimal): Boolean = compare(that) > 0 - /** Addition of BigDecimals */ def + (that: BigDecimal): BigDecimal = new BigDecimal(this.bigDecimal add that.bigDecimal, mc) @@ -589,14 +572,14 @@ extends ScalaNumber with ScalaNumericConversions with Serializable { case x if x <= 0 => this case _ => that } - + /** Returns the maximum of this and that, or this if the two are equal */ def max (that: BigDecimal): BigDecimal = (this compare that) match { case x if x >= 0 => this case _ => that } - + /** Remainder after dividing this by that. */ def remainder (that: BigDecimal): BigDecimal = new BigDecimal(this.bigDecimal remainder that.bigDecimal, mc) @@ -635,7 +618,7 @@ extends ScalaNumber with ScalaNumericConversions with Serializable { val r = this.bigDecimal round mc if (r eq bigDecimal) this else new BigDecimal(r, this.mc) } - + /** Returns a `BigDecimal` rounded according to its own `MathContext` */ def rounded: BigDecimal = { val r = bigDecimal round mc @@ -657,7 +640,7 @@ extends ScalaNumber with ScalaNumericConversions with Serializable { /** Returns a `BigDecimal` whose scale is the specified value, and whose value is * numerically equal to this BigDecimal's. */ - def setScale(scale: Int): BigDecimal = + def setScale(scale: Int): BigDecimal = if (this.scale == scale) this else new BigDecimal(this.bigDecimal setScale scale, mc) diff --git a/src/library/scala/math/BigInt.scala b/src/library/scala/math/BigInt.scala index abc7371d9f..707a5c0769 100644 --- a/src/library/scala/math/BigInt.scala +++ b/src/library/scala/math/BigInt.scala @@ -109,7 +109,12 @@ object BigInt { * @author Martin Odersky * @version 1.0, 15/07/2003 */ -final class BigInt(val bigInteger: BigInteger) extends ScalaNumber with ScalaNumericConversions with Serializable { +final class BigInt(val bigInteger: BigInteger) + extends ScalaNumber + with ScalaNumericConversions + with Serializable + with Ordered[BigInt] +{ /** Returns the hash code for this BigInt. */ override def hashCode(): Int = if (isValidLong) unifiedPrimitiveHashcode() @@ -155,8 +160,8 @@ final class BigInt(val bigInteger: BigInteger) extends ScalaNumber with ScalaNum } ) && !bitLengthOverflow } - /** Some implementations of java.math.BigInteger allow huge values with bit length greater than Int.MaxValue . - * The BigInteger.bitLength method returns truncated bit length in this case . + /** Some implementations of java.math.BigInteger allow huge values with bit length greater than Int.MaxValue. + * The BigInteger.bitLength method returns truncated bit length in this case. * This method tests if result of bitLength is valid. * This method will become unnecessary if BigInt constructors reject huge BigIntegers. */ @@ -176,22 +181,6 @@ final class BigInt(val bigInteger: BigInteger) extends ScalaNumber with ScalaNum */ def compare (that: BigInt): Int = this.bigInteger.compareTo(that.bigInteger) - /** Less-than-or-equals comparison of BigInts - */ - def <= (that: BigInt): Boolean = compare(that) <= 0 - - /** Greater-than-or-equals comparison of BigInts - */ - def >= (that: BigInt): Boolean = compare(that) >= 0 - - /** Less-than of BigInts - */ - def < (that: BigInt): Boolean = compare(that) < 0 - - /** Greater-than comparison of BigInts - */ - def > (that: BigInt): Boolean = compare(that) > 0 - /** Addition of BigInts */ def + (that: BigInt): BigInt = new BigInt(this.bigInteger.add(that.bigInteger)) diff --git a/src/library/scala/math/Integral.scala b/src/library/scala/math/Integral.scala index ff1f695f6d..44009fd4a2 100644 --- a/src/library/scala/math/Integral.scala +++ b/src/library/scala/math/Integral.scala @@ -6,8 +6,6 @@ ** |/ ** \* */ - - package scala package math diff --git a/src/library/scala/math/Ordering.scala b/src/library/scala/math/Ordering.scala index 827cccc77e..37096d5ed0 100644 --- a/src/library/scala/math/Ordering.scala +++ b/src/library/scala/math/Ordering.scala @@ -224,42 +224,32 @@ object Ordering extends LowPriorityOrderingImplicits { implicit object Unit extends UnitOrdering trait BooleanOrdering extends Ordering[Boolean] { - def compare(x: Boolean, y: Boolean) = (x, y) match { - case (false, true) => -1 - case (true, false) => 1 - case _ => 0 - } + def compare(x: Boolean, y: Boolean) = java.lang.Boolean.compare(x, y) } implicit object Boolean extends BooleanOrdering trait ByteOrdering extends Ordering[Byte] { - def compare(x: Byte, y: Byte) = x.toInt - y.toInt + def compare(x: Byte, y: Byte) = java.lang.Byte.compare(x, y) } implicit object Byte extends ByteOrdering trait CharOrdering extends Ordering[Char] { - def compare(x: Char, y: Char) = x.toInt - y.toInt + def compare(x: Char, y: Char) = java.lang.Character.compare(x, y) } implicit object Char extends CharOrdering trait ShortOrdering extends Ordering[Short] { - def compare(x: Short, y: Short) = x.toInt - y.toInt + def compare(x: Short, y: Short) = java.lang.Short.compare(x, y) } implicit object Short extends ShortOrdering trait IntOrdering extends Ordering[Int] { - def compare(x: Int, y: Int) = - if (x < y) -1 - else if (x == y) 0 - else 1 + def compare(x: Int, y: Int) = java.lang.Integer.compare(x, y) } implicit object Int extends IntOrdering trait LongOrdering extends Ordering[Long] { - def compare(x: Long, y: Long) = - if (x < y) -1 - else if (x == y) 0 - else 1 + def compare(x: Long, y: Long) = java.lang.Long.compare(x, y) } implicit object Long extends LongOrdering diff --git a/src/library/scala/math/package.scala b/src/library/scala/math/package.scala index a75979385c..546efef114 100644 --- a/src/library/scala/math/package.scala +++ b/src/library/scala/math/package.scala @@ -11,28 +11,90 @@ package scala /** The package object `scala.math` contains methods for performing basic * numeric operations such as elementary exponential, logarithmic, root and * trigonometric functions. + * + * All methods forward to [[java.lang.Math]] unless otherwise noted. + * + * @see [[java.lang.Math]] + * + * @groupname math-const Mathematical Constants + * @groupprio math-const 10 + * + * @groupname minmax Minimum and Maximum + * @groupdesc minmax Find the min or max of two numbers. Note: [[scala.collection.TraversableOnce]] has + * min and max methods which determine the min or max of a collection. + * @groupprio minmax 20 + * + * @groupname rounding Rounding + * @groupprio rounding 30 + * + * @groupname explog Exponential and Logarithmic + * @groupprio explog 40 + * + * @groupname trig Trigonometric + * @groupdesc trig Arguments in radians + * @groupprio trig 50 + * + * @groupname angle-conversion Angular Measurement Conversion + * @groupprio angle-conversion 60 + * + * @groupname hyperbolic Hyperbolic + * @groupprio hyperbolic 70 + * + * @groupname abs Absolute Values + * @groupdesc abs Determine the magnitude of a value by discarding the sign. Results are >= 0. + * @groupprio abs 80 + * + * @groupname signum Signs + * @groupdesc signum Extract the sign of a value. Results are -1, 0 or 1. + * Note that these are not pure forwarders to the java versions. + * In particular, the return type of java.lang.Long.signum is Int, + * but here it is widened to Long so that each overloaded variant + * will return the same numeric type it is passed. + * @groupprio signum 90 + * + * @groupname root-extraction Root Extraction + * @groupprio root-extraction 100 + * + * @groupname polar-coords Polar Coordinates + * @groupprio polar-coords 110 + * + * @groupname ulp Unit of Least Precision + * @groupprio ulp 120 + * + * @groupname randomisation Pseudo Random Number Generation + * @groupprio randomisation 130 */ package object math { - /** The `double` value that is closer than any other to `e`, the base of + /** The `Double` value that is closer than any other to `e`, the base of * the natural logarithms. + * @group math-const */ @inline final val E = java.lang.Math.E - /** The `double` value that is closer than any other to `pi`, the ratio of + /** The `Double` value that is closer than any other to `pi`, the ratio of * the circumference of a circle to its diameter. + * @group math-const */ @inline final val Pi = java.lang.Math.PI - /** Returns a `double` value with a positive sign, greater than or equal + /** Returns a `Double` value with a positive sign, greater than or equal * to `0.0` and less than `1.0`. + * + * @group randomisation */ - def random: Double = java.lang.Math.random() + def random(): Double = java.lang.Math.random() + /** @group trig */ def sin(x: Double): Double = java.lang.Math.sin(x) + /** @group trig */ def cos(x: Double): Double = java.lang.Math.cos(x) + /** @group trig */ def tan(x: Double): Double = java.lang.Math.tan(x) + /** @group trig */ def asin(x: Double): Double = java.lang.Math.asin(x) + /** @group trig */ def acos(x: Double): Double = java.lang.Math.acos(x) + /** @group trig */ def atan(x: Double): Double = java.lang.Math.atan(x) /** Converts an angle measured in degrees to an approximately equivalent @@ -40,6 +102,7 @@ package object math { * * @param x an angle, in degrees * @return the measurement of the angle `x` in radians. + * @group angle-conversion */ def toRadians(x: Double): Double = java.lang.Math.toRadians(x) @@ -48,44 +111,10 @@ package object math { * * @param x angle, in radians * @return the measurement of the angle `x` in degrees. + * @group angle-conversion */ def toDegrees(x: Double): Double = java.lang.Math.toDegrees(x) - /** Returns Euler's number `e` raised to the power of a `double` value. - * - * @param x the exponent to raise `e` to. - * @return the value `e^a^`, where `e` is the base of the natural - * logarithms. - */ - def exp(x: Double): Double = java.lang.Math.exp(x) - - /** Returns the natural logarithm of a `double` value. - * - * @param x the number to take the natural logarithm of - * @return the value `logₑ(x)` where `e` is Eulers number - */ - def log(x: Double): Double = java.lang.Math.log(x) - - /** Returns the square root of a `double` value. - * - * @param x the number to take the square root of - * @return the value √x - */ - def sqrt(x: Double): Double = java.lang.Math.sqrt(x) - def IEEEremainder(x: Double, y: Double): Double = java.lang.Math.IEEEremainder(x, y) - - def ceil(x: Double): Double = java.lang.Math.ceil(x) - def floor(x: Double): Double = java.lang.Math.floor(x) - - /** Returns the `double` value that is closest in value to the - * argument and is equal to a mathematical integer. - * - * @param x a `double` value - * @return the closest floating-point value to a that is equal to a - * mathematical integer. - */ - def rint(x: Double): Double = java.lang.Math.rint(x) - /** Converts rectangular coordinates `(x, y)` to polar `(r, theta)`. * * @param x the ordinate coordinate @@ -93,110 +122,206 @@ package object math { * @return the ''theta'' component of the point `(r, theta)` in polar * coordinates that corresponds to the point `(x, y)` in * Cartesian coordinates. + * @group polar-coords */ def atan2(y: Double, x: Double): Double = java.lang.Math.atan2(y, x) - /** Returns the value of the first argument raised to the power of the - * second argument. + /** Returns the square root of the sum of the squares of both given `Double` + * values without intermediate underflow or overflow. + * + * The ''r'' component of the point `(r, theta)` in polar + * coordinates that corresponds to the point `(x, y)` in + * Cartesian coordinates. + * @group polar-coords + */ + def hypot(x: Double, y: Double): Double = java.lang.Math.hypot(x, y) + + // ----------------------------------------------------------------------- + // rounding functions + // ----------------------------------------------------------------------- + + /** @group rounding */ + def ceil(x: Double): Double = java.lang.Math.ceil(x) + /** @group rounding */ + def floor(x: Double): Double = java.lang.Math.floor(x) + + /** Returns the `Double` value that is closest in value to the + * argument and is equal to a mathematical integer. + * + * @param x a `Double` value + * @return the closest floating-point value to a that is equal to a + * mathematical integer. + * @group rounding + */ + def rint(x: Double): Double = java.lang.Math.rint(x) + + /** There is no reason to round a `Long`, but this method prevents unintended conversion to `Float` followed by rounding to `Int`. * - * @param x the base. - * @param y the exponent. - * @return the value `x^y^`. + * @note Does not forward to [[java.lang.Math]] + * @group rounding */ - def pow(x: Double, y: Double): Double = java.lang.Math.pow(x, y) - - /** There is no reason to round a `Long`, but this method prevents unintended conversion to `Float` followed by rounding to `Int`. */ - @deprecated("This is an integer type; there is no reason to round it. Perhaps you meant to call this with a floating-point value?", "2.11.0") + @deprecated("This is an integer type; there is no reason to round it. Perhaps you meant to call this with a floating-point value?", "2.11.0") def round(x: Long): Long = x /** Returns the closest `Int` to the argument. * * @param x a floating-point value to be rounded to a `Int`. * @return the value of the argument rounded to the nearest `Int` value. + * @group rounding */ def round(x: Float): Int = java.lang.Math.round(x) - + /** Returns the closest `Long` to the argument. * * @param x a floating-point value to be rounded to a `Long`. * @return the value of the argument rounded to the nearest`long` value. + * @group rounding */ def round(x: Double): Long = java.lang.Math.round(x) + /** @group abs */ def abs(x: Int): Int = java.lang.Math.abs(x) + /** @group abs */ def abs(x: Long): Long = java.lang.Math.abs(x) + /** @group abs */ def abs(x: Float): Float = java.lang.Math.abs(x) + /** @group abs */ def abs(x: Double): Double = java.lang.Math.abs(x) + /** @group minmax */ def max(x: Int, y: Int): Int = java.lang.Math.max(x, y) + /** @group minmax */ def max(x: Long, y: Long): Long = java.lang.Math.max(x, y) + /** @group minmax */ def max(x: Float, y: Float): Float = java.lang.Math.max(x, y) + /** @group minmax */ def max(x: Double, y: Double): Double = java.lang.Math.max(x, y) + /** @group minmax */ def min(x: Int, y: Int): Int = java.lang.Math.min(x, y) + /** @group minmax */ def min(x: Long, y: Long): Long = java.lang.Math.min(x, y) + /** @group minmax */ def min(x: Float, y: Float): Float = java.lang.Math.min(x, y) + /** @group minmax */ def min(x: Double, y: Double): Double = java.lang.Math.min(x, y) - /** Note that these are not pure forwarders to the java versions. - * In particular, the return type of java.lang.Long.signum is Int, - * but here it is widened to Long so that each overloaded variant - * will return the same numeric type it is passed. - */ + /** @group signum + * @note Forwards to [[java.lang.Integer]] + */ def signum(x: Int): Int = java.lang.Integer.signum(x) + /** @group signum + * @note Forwards to [[java.lang.Long]] + */ def signum(x: Long): Long = java.lang.Long.signum(x) + /** @group signum */ def signum(x: Float): Float = java.lang.Math.signum(x) + /** @group signum */ def signum(x: Double): Double = java.lang.Math.signum(x) // ----------------------------------------------------------------------- // root functions // ----------------------------------------------------------------------- - /** Returns the cube root of the given `Double` value. */ + /** Returns the square root of a `Double` value. + * + * @param x the number to take the square root of + * @return the value √x + * @group root-extraction + */ + def sqrt(x: Double): Double = java.lang.Math.sqrt(x) + + /** Returns the cube root of the given `Double` value. + * + * @param x the number to take the cube root of + * @return the value ∛x + * @group root-extraction + */ def cbrt(x: Double): Double = java.lang.Math.cbrt(x) // ----------------------------------------------------------------------- // exponential functions // ----------------------------------------------------------------------- - /** Returns `exp(x) - 1`. */ + /** Returns the value of the first argument raised to the power of the + * second argument. + * + * @param x the base. + * @param y the exponent. + * @return the value `x^y^`. + * @group explog + */ + def pow(x: Double, y: Double): Double = java.lang.Math.pow(x, y) + + /** Returns Euler's number `e` raised to the power of a `Double` value. + * + * @param x the exponent to raise `e` to. + * @return the value `e^a^`, where `e` is the base of the natural + * logarithms. + * @group explog + */ + def exp(x: Double): Double = java.lang.Math.exp(x) + + /** Returns `exp(x) - 1`. + * @group explog + */ def expm1(x: Double): Double = java.lang.Math.expm1(x) // ----------------------------------------------------------------------- // logarithmic functions // ----------------------------------------------------------------------- - /** Returns the natural logarithm of the sum of the given `Double` value and 1. */ + /** Returns the natural logarithm of a `Double` value. + * + * @param x the number to take the natural logarithm of + * @return the value `logₑ(x)` where `e` is Eulers number + * @group explog + */ + def log(x: Double): Double = java.lang.Math.log(x) + + /** Returns the natural logarithm of the sum of the given `Double` value and 1. + * @group explog + */ def log1p(x: Double): Double = java.lang.Math.log1p(x) - /** Returns the base 10 logarithm of the given `Double` value. */ + /** Returns the base 10 logarithm of the given `Double` value. + * @group explog + */ def log10(x: Double): Double = java.lang.Math.log10(x) // ----------------------------------------------------------------------- // trigonometric functions // ----------------------------------------------------------------------- - /** Returns the hyperbolic sine of the given `Double` value. */ + /** Returns the hyperbolic sine of the given `Double` value. + * @group hyperbolic + */ def sinh(x: Double): Double = java.lang.Math.sinh(x) - /** Returns the hyperbolic cosine of the given `Double` value. */ + /** Returns the hyperbolic cosine of the given `Double` value. + * @group hyperbolic + */ def cosh(x: Double): Double = java.lang.Math.cosh(x) - /** Returns the hyperbolic tangent of the given `Double` value. */ + /** Returns the hyperbolic tangent of the given `Double` value. + * @group hyperbolic + */ def tanh(x: Double):Double = java.lang.Math.tanh(x) // ----------------------------------------------------------------------- // miscellaneous functions // ----------------------------------------------------------------------- - /** Returns the square root of the sum of the squares of both given `Double` - * values without intermediate underflow or overflow. + /** Returns the size of an ulp of the given `Double` value. + * @group ulp */ - def hypot(x: Double, y: Double): Double = java.lang.Math.hypot(x, y) - - /** Returns the size of an ulp of the given `Double` value. */ def ulp(x: Double): Double = java.lang.Math.ulp(x) - /** Returns the size of an ulp of the given `Float` value. */ + /** Returns the size of an ulp of the given `Float` value. + * @group ulp + */ def ulp(x: Float): Float = java.lang.Math.ulp(x) + + /** @group rounding */ + def IEEEremainder(x: Double, y: Double): Double = java.lang.Math.IEEEremainder(x, y) } |