ElementaryFunctions.swift

//===--- ElementaryFunctions.swift ----------------------------*- swift -*-===//
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//

/// A type that has elementary functions available.
///
/// An ["elementary function"][elfn] is a function built up from powers, roots,
/// exponentials, logarithms, trigonometric functions (sin, cos, tan) and
/// their inverses, and the hyperbolic functions (sinh, cosh, tanh) and their
/// inverses.
///
/// Conformance to this protocol means that all of these building blocks are
/// available as static functions on the type.
///
/// ```swift
/// let x: Float = 1
/// let y = Float.sin(x) // 0.84147096
/// ```
///
/// There are three broad families of functions defined by
/// `ElementaryFunctions`:
/// - Exponential, trigonometric, and hyperbolic functions:
/// `exp`, `expMinusOne`, `cos`, `sin`, `tan`, `cosh`, `sinh`, and `tanh`.
/// - Logarithmic, inverse trigonometric, and inverse hyperbolic functions:
/// `log`, `log(onePlus:)`, `acos`, `asin`, `atan`, `acosh`, `asinh`, and
/// `atanh`.
/// - Power and root functions:
/// `pow`, `sqrt`, and `root`.
///
/// `ElementaryFunctions` conformance implies `AdditiveArithmetic`, so addition
/// and subtraction and the `.zero` property are also available.
///
/// There are two other protocols that you are more likely to want to use
/// directly:
///
/// `RealFunctions` refines `ElementaryFunctions` and includes
/// additional functions specific to real number types.
///
/// `Real` conforms to `RealFunctions` and `FloatingPoint`, and is the
/// protocol that you will want to use most often for generic code.
///
/// See Also:
///
/// - `RealFunctions`
/// - `Real`
///
/// [elfn]: http://en.wikipedia.org/wiki/Elementary_function
publicprotocolElementaryFunctions:AdditiveArithmetic{
 /// The [exponential function][wiki] e^x whose base `e` is the base of the
 /// natural logarithm.
 ///
 /// See also `expMinusOne()`, as well as `exp2()` and `exp10()`
 /// defined for types conforming to `RealFunctions`.
 ///
 /// [wiki]: https://en.wikipedia.org/wiki/Exponential_function
staticfunc exp(_ x:Self)->Self

 /// exp(x) - 1, computed in such a way as to maintain accuracy for small x.
 ///
 /// When `x` is close to zero, the expression `.exp(x) - 1` suffers from
 /// catastrophic cancellation and the result will not have full accuracy.
 /// The `.expMinusOne(x)` function gives you a means to address this problem.
 ///
 /// As an example, consider the expression `(x + 1)*exp(x) - 1`. When `x`
 /// is smaller than `.ulpOfOne`, this expression evaluates to `0.0`, when it
 /// should actually round to `2*x`. We can get a full-accuracy result by
 /// using the following instead:
 /// ```
 /// let t = .expMinusOne(x)
 /// return x*(t+1) + t // x*exp(x) + (exp(x)-1) = (x+1)*exp(x) - 1
 /// ```
 /// This re-written expression delivers an accurate result for all values
 /// of `x`, not just for small values.
 ///
 /// See also `exp()`, as well as `exp2()` and `exp10()` defined for types
 /// conforming to `RealFunctions`.
staticfunc expMinusOne(_ x:Self)->Self

 /// The [hyperbolic cosine][wiki] of `x`.
 /// ```
 /// e^x + e^-x
 /// cosh(x) = ------------
 /// 2
 /// ```
 ///
 /// See also `sinh()`, `tanh()` and `acosh()`.
 ///
 /// [wiki]: https://en.wikipedia.org/wiki/Hyperbolic_function
staticfunc cosh(_ x:Self)->Self

 /// The [hyperbolic sine][wiki] of `x`.
 /// ```
 /// e^x - e^-x
 /// sinh(x) = ------------
 /// 2
 /// ```
 ///
 /// See also `cosh()`, `tanh()` and `asinh()`.
 ///
 /// [wiki]: https://en.wikipedia.org/wiki/Hyperbolic_function
staticfunc sinh(_ x:Self)->Self

 /// The [hyperbolic tangent][wiki] of `x`.
 /// ```
 /// sinh(x)
 /// tanh(x) = ---------
 /// cosh(x)
 /// ```
 ///
 /// See also `cosh()`, `sinh()` and `atanh()`.
 ///
 /// [wiki]: https://en.wikipedia.org/wiki/Hyperbolic_function
staticfunc tanh(_ x:Self)->Self

 /// The [cosine][wiki] of `x`.
 ///
 /// For real types, `x` may be interpreted as an angle measured in radians.
 ///
 /// See also `sin()`, `tan()` and `acos()`.
 ///
 /// [wiki]: https://en.wikipedia.org/wiki/Cosine
staticfunc cos(_ x:Self)->Self


 /// The [sine][wiki] of `x`.
 ///
 /// For real types, `x` may be interpreted as an angle measured in radians.
 ///
 /// See also `cos()`, `tan()` and `asin()`.
 ///
 /// [wiki]: https://en.wikipedia.org/wiki/Sine
staticfunc sin(_ x:Self)->Self

 /// The [tangent][wiki] of `x`.
 ///
 /// For real types, `x` may be interpreted as an angle measured in radians.
 ///
 /// See also `cos()`, `sin()` and `atan()`, as well as `atan2(y:x:)` for
 /// types that conform to `RealFunctions`.
 ///
 /// [wiki]: https://en.wikipedia.org/wiki/Tangent
staticfunc tan(_ x:Self)->Self

 /// The [natural logarithm][wiki] of `x`.
 ///
 /// See also `log(onePlus:)`, as well as `log2()` and `log10()` for types
 /// that conform to `RealFunctions`.
 ///
 /// [wiki]: https://en.wikipedia.org/wiki/Logarithm
staticfunc log(_ x:Self)->Self

 /// log(1 + x), computed in such a way as to maintain accuracy for small x.
 ///
 /// See also `log()`, as well as `log2()` and `log10()` for types
 /// that conform to `RealFunctions`.
staticfunc log(onePlus x:Self)->Self

 /// The [inverse hyperbolic cosine][wiki] of `x`.
 /// ```
 /// cosh(acosh(x)) ≅ x
 /// ```
 /// See also `asinh()`, `atanh()` and `cosh()`.
 ///
 /// [wiki]: https://en.wikipedia.org/wiki/Inverse_hyperbolic_function
staticfunc acosh(_ x:Self)->Self

 /// The [inverse hyperbolic sine][wiki] of `x`.
 /// ```
 /// sinh(asinh(x)) ≅ x
 /// ```
 /// See also `acosh()`, `atanh()` and `sinh()`.
 ///
 /// [wiki]: https://en.wikipedia.org/wiki/Inverse_hyperbolic_function
staticfunc asinh(_ x:Self)->Self

 /// The [inverse hyperbolic tangent][wiki] of `x`.
 /// ```
 /// tanh(atanh(x)) ≅ x
 /// ```
 /// See also `acosh()`, `asinh()` and `tanh()`.
 ///
 /// [wiki]: https://en.wikipedia.org/wiki/Inverse_hyperbolic_function
staticfunc atanh(_ x:Self)->Self

 /// The [arccosine][wiki] (inverse cosine) of `x`.
 ///
 /// For real types, the result may be interpreted as an angle measured in
 /// radians.
 /// ```
 /// cos(acos(x)) ≅ x
 /// ```
 /// See also `asin()`, `atan()` and `cos()`.
 ///
 /// [wiki]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions
staticfunc acos(_ x:Self)->Self

 /// The [arcsine][wiki] (inverse sine) of `x`.
 ///
 /// For real types, the result may be interpreted as an angle measured in
 /// radians.
 /// ```
 /// sin(asin(x)) ≅ x
 /// ```
 /// See also `acos()`, `atan()` and `sin()`.
 ///
 /// [wiki]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions
staticfunc asin(_ x:Self)->Self

 /// The [arctangent][wiki] (inverse tangent) of `x`.
 ///
 /// For real types, the result may be interpreted as an angle measured in
 /// radians.
 /// ```
 /// tan(atan(x)) ≅ x
 /// ```
 /// See also `acos()`, `asin()` and `tan()`, as well as `atan2(y:x:)` for
 /// types that conform to `RealArithmetic`.
 ///
 /// [wiki]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions
staticfunc atan(_ x:Self)->Self

 /// exp(y * log(x)) computed with additional internal precision.
 ///
 /// The edge-cases of this function are defined based on the behavior of the
 /// expression `exp(y log x)`, matching IEEE 754's `powr` operation.
 /// In particular, this means that if `x` and `y` are both zero, `pow(x,y)`
 /// is `nan` for real types and `infinity` for complex types, rather than 1.
 ///
 /// There is also a `pow(_:Self,_:Int)` overload, whose behavior is defined
 /// in terms of repeated multiplication, and hence returns 1 for this case.
 ///
 /// See also `sqrt()` and `root()`.
staticfunc pow(_ x:Self, _ y:Self)->Self

 /// `x` raised to the nth power.
 ///
 /// The edge-cases of this function are defined in terms of repeated
 /// multiplication or division, rather than exp(n log x). In particular,
 /// `Float.pow(0, 0)` is 1.
 ///
 /// See also `sqrt()` and `root()`.
staticfunc pow(_ x:Self, _ n:Int)->Self

 /// The [square root][wiki] of `x`.
 ///
 /// See also `pow()` and `root()`.
 ///
 /// [wiki]: https://en.wikipedia.org/wiki/Square_root
staticfunc sqrt(_ x:Self)->Self

 /// The nth root of `x`.
 ///
 /// See also `pow()` and `sqrt()`.
staticfunc root(_ x:Self, _ n:Int)->Self
}