Repository: JuliaLang/julia
File: base/float.jl (Julia)

Code before:
    eps()

Return the *machine epsilon* of the floating point type `T` (`T = Float64` by
default). This is defined as the gap between 1 and the next largest value representable by
`typeof(one(T))`, and is equivalent to `eps(one(T))`.  (Since `eps(T)` is a
bound on the *relative error* of `T`, it is a "dimensionless" quantity like [`one`](@ref).)

# Examples
```jldoctest
julia> eps()
2.220446049250313e-16

julia> eps(Float32)
1.1920929f-7

julia> 1.0 + eps()
1.0000000000000002

julia> 1.0 + eps()/2
1.0
```

For complex inputs `T`, `eps(T)` is defined as the distance bound to the nearest
floating-point complex value, i.e. for ``z=a+ib`` and the closest floating-point
complex value ``z̃=ã+ib̃=fl(a)+ifl(b)`` where ``fl(x)`` is the closest
floating-point value to a real ``x``, ``eps(z)`` satisfies ``|z - z̃| ≤ eps(z)/2``.
"""
eps(::Type{<:AbstractFloat})

"""
    eps(x::AbstractFloat)

Return the *unit in last place* (ulp) of `x`. This is the distance between consecutive
representable floating point values at `x`. In most cases, if the distance on either side
of `x` is different, then the larger of the two is taken, that is

    eps(x) == max(x-prevfloat(x), nextfloat(x)-x)

The exceptions to this rule are the smallest and largest finite values
(e.g. `nextfloat(-Inf)` and `prevfloat(Inf)` for [`Float64`](@ref)), which round to the
smaller of the values.

The rationale for this behavior is that `eps` bounds the floating point rounding
error. Under the default `RoundNearest` rounding mode, if ``y`` is a real number and ``x``
is the nearest floating point number to ``y``, then

```math
|y-x| \\leq \\operatorname{eps}(x)/2.
```

See also: [`nextfloat`](@ref), [`issubnormal`](@ref), [`floatmax`](@ref).

Review comment (bug):
It would be good to frame this as a strict generalization of the definition, since it is also true for real numbers, and then give complex numbers as a special case.

```suggestion
More generally, for any floating-point numeric type, `eps` corresponds to an
upper bound on the distance to the nearest floating-point complex value: if ``\text{fl}(x)`` is the closest
floating-point value to a number ``x`` (e.g. an arbitrary real number), then ``\text{fl}(x)``
satisfies ``|x - \text{fl}(x)| ≤ \text{eps}(x)/2``, not including overflow cases.
This allows the definition of `eps` to be extended to complex numbers,
for which ``\text{fl}(a + ib) = \text{fl}(a) + i \text{fl}(b)``.
```

(Note that `eps(x)` and `fl(x)` should ideally be typeset with the AMS `\mathoperator` so that they aren't italicized, but that isn't supported in all LaTeX-math environments, and so I used `\text` instead to get $\text{eps}(x)$ and $\text{fl}(x)$.)

Code after:
    eps()

Return the *machine epsilon* of the floating point type `T` (`T = Float64` by
default). This is defined as the gap between 1 and the next largest value representable by
`typeof(one(T))`, and is equivalent to `eps(one(T))`.  (Since `eps(T)` is a
bound on the *relative error* of `T`, it is a "dimensionless" quantity like [`one`](@ref).)

# Examples
```jldoctest
julia> eps()
2.220446049250313e-16

julia> eps(Float32)
1.1920929f-7

julia> 1.0 + eps()
1.0000000000000002

julia> 1.0 + eps()/2
1.0
```

More generally, for any floating-point numeric type, `eps` corresponds to an
upper bound on the distance to the nearest floating-point complex value: if ``\text{fl}(x)`` is the closest
floating-point value to a number ``x`` (e.g. an arbitrary real number), then ``\text{fl}(x)``
satisfies ``|x - \text{fl}(x)| ≤ \text{eps}(x)/2``, not including overflow cases.
This allows the definition of `eps` to be extended to complex numbers,
for which ``\text{fl}(a + ib) = \text{fl}(a) + i \text{fl}(b)``.
"""
eps(::Type{<:AbstractFloat})

"""
    eps(x::AbstractFloat)

Return the *unit in last place* (ulp) of `x`. This is the distance between consecutive
representable floating point values at `x`. In most cases, if the distance on either side
of `x` is different, then the larger of the two is taken, that is

    eps(x) == max(x-prevfloat(x), nextfloat(x)-x)

The exceptions to this rule are the smallest and largest finite values
(e.g. `nextfloat(-Inf)` and `prevfloat(Inf)` for [`Float64`](@ref)), which round to the
smaller of the values.

The rationale for this behavior is that `eps` bounds the floating point rounding
error. Under the default `RoundNearest` rounding mode, if ``y`` is a real number and ``x``
is the nearest floating point number to ``y``, then

```math
|y-x| \\leq \\operatorname{eps}(x)/2.
```