> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truemath.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Unit functions
> Read a value's unit with unit, and extract its numeric portion — optionally converted to a target unit — with unitvalue.
These functions inspect the unit of a [unit number](/math/types/unit-numbers) and separate it from the numeric value. Each accepts a single value or a [table](/math/types/tables), returning the same shape.
## Unit \[unit]
```
unit(value)
```
Returns `value`'s unit as text, or an empty string when the value is unitless. Given a [table](/math/types/tables), returns a table of unit strings, one per cell. `unit` takes exactly one argument.
```
unit(34) => ""
unit(34 ft) => "ft"
unit([34ft; 15; 25 in]) => ["ft"; ""; "in"]
```
The unit comes back in [canonical form](/math/units), not as it was written: `unit(34')` returns `"ft"`, and squared units use a superscript — `unit(2 m^2)` returns `"m²"` and `unit(34 USD/ft^2)` returns `"USD/ft²"`.
## Unit value \[unitvalue]
```
unitvalue(value)
unitvalue(value; unit)
```
Returns the numeric portion of `value` with its unit stripped. When `unit` is given, `value` is first converted to that unit and then the numeric portion is returned. Given a [table](/math/types/tables), each cell is converted and stripped, returning a table of numbers.
```
unitvalue(34 ft) => 34
unitvalue(34) => 34
unitvalue(4ft; "in") => 48
unitvalue([4ft; 2ft; 3ft]; "in") => [48; 24; 36]
```
`unit` must be a **quoted** unit string compatible with `value`'s dimension. A bare token (`unitvalue(4ft; in)`) is read as a variable, not a unit. A unit that doesn't match the value's dimension — including applying a unit to a unitless value (`unitvalue(34; "in")`) — returns an incompatible-units error. In a table, an incompatible cell carries the error in place while the other cells still convert.
`unitvalue` returns a plain number with no unit attached. To convert a value but keep it a unit number, [cast](/math/units#casting-to-a-specific-unit) it instead — `(4ft) in` is `48in`, whereas `unitvalue(4ft; "in")` is the bare number `48`.
## When to strip a unit
Keep units wherever you can. Dividing them out by hand discards the [dimensional safety](/introduction/guarantees#dimensional-safety) that stops a calculation from returning a confident but nonsensical result, and the unit itself is information the caller depends on. Reach for `unitvalue` only when a unit would otherwise make an operation meaningless — most often when a value is really a count that happens to carry a unit.
This starts at variable design: model dimensional quantities as [unit-carrying values](/concepts/units-and-precision#model-quantities-as-unit-carrying-values), and you rarely need to strip at all. Scattered `unitvalue` and `unit` calls are usually a sign that a variable was declared as a bare number when it should have carried a unit.
Some operations do genuinely need a scalar. Looping and totaling a yearly cost over a holding period are good examples. Here the period is acting as a count of years rather than a duration to carry forward: multiplying the amount by it directly would carry the period's unit into the product instead of giving a plain dollar figure and error, so you strip it to a number of years first:
```
total_cost = yearly_cost * unitvalue(holding_period; "yr")
```
Passing the explicit `"yr"` rather than a bare `unitvalue(holding_period)` makes the result independent of how the period was entered: whether the caller said months or years, it converts to years and returns that number.
### Strip for the equation, not for the domain
Ideally, a stripped value is for use inside the equation that strips it only. The example above strips `holding_period` and multiplies it in the same expression — the bare number never outlives the line that needs it, and the result, `total_cost`, is still a [unit number](/math/types/unit-numbers) in currency.
Storing a stripped scalar as a [variable](/concepts/variables) that *other* [activities](/concepts/activities) consume is where this goes wrong. The bare number has lost its dimension, so downstream it no longer combines with the dimensional values around it: multiply a payoff period that is now a plain `271.04` by a currency payment and there is nothing to validate the combination — you get an incompatible-units error, or worse, a confident answer that assumes a unit nobody can see. Either way the [dimensional safety](/introduction/guarantees#dimensional-safety) the strip discarded was exactly what would have caught the mistake.
So when a value feeds later activities, keep it in its unit. If a downstream result is what you actually want, compute it with a function that returns it in units rather than reconstructing it from a stripped scalar — for a payoff total, total the payments directly instead of multiplying a unitless month count by a payment. Reserve `unitvalue` for the scalar a single equation genuinely needs, and let that scalar end at the equation that needed it.
Stripping a unit is a deliberate, lossy step — like [rounding](/math/functions/rounding-and-numeric), it throws away something the engine was carrying for you. Strip only the value that genuinely needs to be unitless, at the point you use it, and leave the rest of the calculation in units. When you need a value in a different unit but still a [unit number](/math/types/unit-numbers), [cast](/math/units#casting-to-a-specific-unit) it instead.