# `Angelus.Angle`
[🔗](https://github.com/MonsignorEduardo/angelus/blob/v0.0.2/lib/angelus/angle.ex#L1)

Angular math helpers for normalized astrological longitudes.

# `angle_error`

```elixir
@type angle_error() :: {:error, :invalid_angle}
```

# `deg_to_rad`

```elixir
@spec deg_to_rad(number()) :: float()
@spec deg_to_rad(term()) :: angle_error()
```

Converts degrees to radians.

Returns `{:error, :invalid_angle}` when the value is not a number.

## Examples

    iex> Angelus.Angle.deg_to_rad(180.0)
    :math.pi()

# `distance`

```elixir
@spec distance(number(), number()) :: float()
@spec distance(term(), term()) :: angle_error()
```

Returns the absolute angular distance between two angles in degrees.

The result is always in `[0.0, 180.0]`. Returns `{:error, :invalid_angle}`
if either argument is not a number.

## Examples

    iex> Angelus.Angle.distance(10.0, 350.0)
    20.0

# `dms`

```elixir
@spec dms(number()) :: {non_neg_integer(), non_neg_integer(), float()}
@spec dms(term()) :: angle_error()
```

Decomposes an angle into degrees, minutes, and seconds.

The input is first normalized to `[0.0, 360.0)` before decomposition.
Returns `{:error, :invalid_angle}` when the value is not a number.

## Examples

    iex> Angelus.Angle.dms(90.5)
    {90, 30, 0.0}

# `normalize`

```elixir
@spec normalize(number()) :: float()
@spec normalize(term()) :: angle_error()
```

Normalizes an angle to the range `[0.0, 360.0)`.

Returns `{:error, :invalid_angle}` when the value is not a number.

## Examples

    iex> Angelus.Angle.normalize(370.0)
    10.0

    iex> Angelus.Angle.normalize(-10.0)
    350.0

# `rad_to_deg`

```elixir
@spec rad_to_deg(number()) :: float()
@spec rad_to_deg(term()) :: angle_error()
```

Converts radians to degrees.

Returns `{:error, :invalid_angle}` when the value is not a number.

## Examples

    iex> Angelus.Angle.rad_to_deg(:math.pi())
    180.0

# `signed_distance`

```elixir
@spec signed_distance(number(), number()) :: float()
@spec signed_distance(term(), term()) :: angle_error()
```

Returns the shortest signed angular distance from `a` to `b` in degrees.

The result is in `(-180.0, 180.0]`. A positive value means `b` is ahead of
`a` in the counter-clockwise direction. Returns `{:error, :invalid_angle}` if
either argument is not a number.

## Examples

    iex> Angelus.Angle.signed_distance(10.0, 350.0)
    -20.0

    iex> Angelus.Angle.signed_distance(350.0, 10.0)
    20.0

---

*Consult [api-reference.md](api-reference.md) for complete listing*