# `BB.Robot.Units`
[🔗](https://github.com/beam-bots/bb/blob/main/lib/bb/robot/units.ex#L5)

Unit conversion functions for transforming `Localize.Unit` values into base
SI floats.

All functions in this module convert from `Localize.Unit.t()` structs to
native floats in SI base units, suitable for efficient numerical
computation.

# `extract_float`

```elixir
@spec extract_float(Localize.Unit.t()) :: float()
```

Extract the numeric value from a `Localize.Unit` as a float.

Handles integer, float, and `Decimal` values.

# `to_kilogram_square_meters`

```elixir
@spec to_kilogram_square_meters(Localize.Unit.t()) :: float()
```

Convert a moment of inertia unit to kg·m² (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_kilogram_square_meters(~u(0.5 kilogram_square_meter))
    0.5

# `to_kilogram_square_meters_or_nil`

```elixir
@spec to_kilogram_square_meters_or_nil(Localize.Unit.t() | nil) :: float() | nil
```

# `to_kilograms`

```elixir
@spec to_kilograms(Localize.Unit.t()) :: float()
```

Convert a mass unit to kilograms (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_kilograms(~u(1000 gram))
    1.0

    iex> import BB.Unit
    iex> BB.Robot.Units.to_kilograms(~u(2.5 kilogram))
    2.5

# `to_kilograms_or_nil`

```elixir
@spec to_kilograms_or_nil(Localize.Unit.t() | nil) :: float() | nil
```

# `to_linear_damping`

```elixir
@spec to_linear_damping(Localize.Unit.t()) :: float()
```

Convert a linear damping coefficient to N·s/m (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_linear_damping(~u(1.5 newton_second_per_meter))
    1.5

# `to_linear_damping_or_nil`

```elixir
@spec to_linear_damping_or_nil(Localize.Unit.t() | nil) :: float() | nil
```

# `to_meters`

```elixir
@spec to_meters(Localize.Unit.t()) :: float()
```

Convert a length unit to meters (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_meters(~u(100 centimeter))
    1.0

    iex> import BB.Unit
    iex> BB.Robot.Units.to_meters(~u(1.5 meter))
    1.5

# `to_meters_or_nil`

```elixir
@spec to_meters_or_nil(Localize.Unit.t() | nil) :: float() | nil
```

Convert an optional unit value to its base SI float, or return nil.

# `to_meters_per_second`

```elixir
@spec to_meters_per_second(Localize.Unit.t()) :: float()
```

Convert a linear velocity unit to meters per second (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_meters_per_second(~u(10 meter_per_second))
    10.0

# `to_meters_per_second_or_nil`

```elixir
@spec to_meters_per_second_or_nil(Localize.Unit.t() | nil) :: float() | nil
```

# `to_meters_per_square_second`

```elixir
@spec to_meters_per_square_second(Localize.Unit.t()) :: float()
```

Convert a linear acceleration unit to metres per second squared (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_meters_per_square_second(~u(9.81 meter_per_square_second))
    9.81

# `to_meters_per_square_second_or_nil`

```elixir
@spec to_meters_per_square_second_or_nil(Localize.Unit.t() | nil) :: float() | nil
```

# `to_newton`

```elixir
@spec to_newton(Localize.Unit.t()) :: float()
```

Convert a force unit to newtons (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_newton(~u(5 newton))
    5.0

# `to_newton_meters`

```elixir
@spec to_newton_meters(Localize.Unit.t()) :: float()
```

Convert a torque unit to newton-meters (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_newton_meters(~u(5 newton_meter))
    5.0

# `to_newton_meters_or_nil`

```elixir
@spec to_newton_meters_or_nil(Localize.Unit.t() | nil) :: float() | nil
```

# `to_newtons`

```elixir
@spec to_newtons(Localize.Unit.t()) :: float()
```

Convert a force unit to newtons (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_newtons(~u(10 newton))
    10.0

# `to_newtons_or_nil`

```elixir
@spec to_newtons_or_nil(Localize.Unit.t() | nil) :: float() | nil
```

# `to_radians`

```elixir
@spec to_radians(Localize.Unit.t()) :: float()
```

Convert an angle unit to radians (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_radians(~u(180 degree))
    :math.pi()

    iex> import BB.Unit
    iex> BB.Robot.Units.to_radians(~u(0 degree))
    0.0

# `to_radians_or_nil`

```elixir
@spec to_radians_or_nil(Localize.Unit.t() | nil) :: float() | nil
```

# `to_radians_per_second`

```elixir
@spec to_radians_per_second(Localize.Unit.t()) :: float()
```

Convert an angular velocity unit to radians per second (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_radians_per_second(~u(180 degree_per_second))
    :math.pi()

# `to_radians_per_second_or_nil`

```elixir
@spec to_radians_per_second_or_nil(Localize.Unit.t() | nil) :: float() | nil
```

# `to_radians_per_square_second`

```elixir
@spec to_radians_per_square_second(Localize.Unit.t()) :: float()
```

Convert an angular acceleration unit to radians per second squared (float).

## Examples

    iex> import BB.Unit
    iex> BB.Robot.Units.to_radians_per_square_second(~u(360 degree_per_square_second))
    :math.pi() * 2

# `to_radians_per_square_second_or_nil`

```elixir
@spec to_radians_per_square_second_or_nil(Localize.Unit.t() | nil) :: float() | nil
```

# `to_rotational_damping`

```elixir
@spec to_rotational_damping(Localize.Unit.t()) :: float()
```

Convert a rotational damping coefficient to N·m·s/rad (float).

Note: The DSL uses `newton_meter_second_per_degree` but we convert
to radians for consistency with other angular quantities.

# `to_rotational_damping_or_nil`

```elixir
@spec to_rotational_damping_or_nil(Localize.Unit.t() | nil) :: float() | nil
```

---

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