Add humanize: true option to Localize.Unit.to_string/2, covering bit, byte, hertz and watt bases

The option renders any unit in the unit people expect for its
magnitude: bit-, byte-, hertz- and watt-based units scale through
the humanize/2 prefix ladder (system: :si or :iec, IEC restricted
to bits and bytes), and all other units render through the
usage-based preference pipeline with the struct's usage or
:default. An explicit :usage option keeps precedence. humanize/2
and humanize!/2 gain the hertz and watt bases as well.

Author: kipcole9

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+* `Localize.Unit.to_string/2` accepts `humanize: true` to render any unit in the unit people expect for its magnitude: bit-, byte-, hertz- and watt-based units scale through the `humanize/2` prefix ladder (honouring `system: :si | :iec`) and all other units render through usage-based preferences. An explicit `:usage` option keeps precedence for preference-scaled units.
+
+* `Localize.Unit.humanize/2` and `humanize!/2` also scale hertz- and watt-based units through the SI prefix ladder ("2.5 gigahertz", "3.2 gigawatts") — like bits and bytes, these are locale-invariant quantities that CLDR's unit preferences do not cover. IEC prefixes remain restricted to bit- and byte-based units.
+
 ## [0.47.0] — July 7th, 2026
 
 ### Added

cheatsheets/unit_formatting.md

@@ -123,22 +123,32 @@ result.name  #=> "mile"
 | `:us` | United States | mile, pound, fahrenheit |
 | `:uk` | United Kingdom | mile, stone, celsius |
 
-### Humanizing digital units (file sizes)
+### Humanizing (auto-scaling to the expected unit)
 
 ```elixir
+# One call for any unit kind
 Localize.Unit.new!(1_500_000, "byte")
-|> Localize.Unit.humanize!()
-|> Localize.Unit.to_string!(format: :narrow)
+|> Localize.Unit.to_string!(humanize: true, format: :narrow)
 #=> "1.5MB"
 
+Localize.Unit.new!(2_500_000, "hertz")
+|> Localize.Unit.to_string!(humanize: true, format: :narrow)
+#=> "2.5MHz"
+
+Localize.Unit.new!(1_500, "meter")
+|> Localize.Unit.to_string!(humanize: true, locale: :de)
+#=> "1,5 Kilometer"
+
+# Struct-level scaling for bit/byte/hertz/watt units
 {:ok, unit} = Localize.Unit.new(1_048_576, "byte")
 {:ok, humanized} = Localize.Unit.humanize(unit, system: :iec)
 {humanized.name, humanized.value}  #=> {"mebibyte", 1.0}
 ```
 
 | Option | Values | Notes |
 |---|---|---|
-| `:system` | `:si` (default), `:iec` | `:si` scales by 1000 (kilobyte, megabyte, ...); `:iec` by 1024 (kibibyte, mebibyte, ...) |
+| `:humanize` | `true`, `false` (default) | On `to_string/2`: bit/byte/hertz/watt units scale through the prefix ladder, all others use usage-based preferences |
+| `:system` | `:si` (default), `:iec` | `:si` scales by 1000 (kilobyte, megahertz, ...); `:iec` by 1024 (kibibyte, mebibyte, ...) — bits and bytes only |
 
 ## Arithmetic
 

guides/unit_formatting.md

@@ -229,15 +229,20 @@ iex> {:ok, m} = Localize.Unit.new(1, "meter")
 iex> {:error, _} = Localize.Unit.convert(m, "kilogram")
 ```
 
-## Humanizing digital units
+## Humanizing prefix-scaled units
 
-`Localize.Unit.humanize/2` converts a byte- or bit-based unit to the prefixed unit that best fits its magnitude — the conventional way to display file sizes. It selects the largest prefix such that the converted value is at least 1:
+`Localize.Unit.humanize/2` converts a bit-, byte-, hertz- or watt-based unit to the prefixed unit that best fits its magnitude — the conventional way to display file sizes, frequencies and power figures. It selects the largest prefix such that the converted value is at least 1:
 
 ```elixir
 iex> {:ok, unit} = Localize.Unit.new(1_500_000, "byte")
 iex> {:ok, humanized} = Localize.Unit.humanize(unit)
 iex> {humanized.name, humanized.value}
 {"megabyte", 1.5}
+
+iex> {:ok, unit} = Localize.Unit.new(2_500_000_000, "hertz")
+iex> {:ok, humanized} = Localize.Unit.humanize(unit)
+iex> {humanized.name, humanized.value}
+{"gigahertz", 2.5}
 ```
 
 Combined with the `:narrow` format width this produces compact file sizes:
@@ -254,7 +259,7 @@ iex> Localize.Unit.new!(2_750_000_000, "byte")
 "2.8GB"
 ```
 
-The `:system` option selects the prefix ladder: `:si` (powers of 1000 — kilobyte, megabyte, gigabyte, the default) or `:iec` (powers of 1024 — kibibyte, mebibyte, gibibyte):
+The `:system` option selects the prefix ladder: `:si` (powers of 1000 — kilobyte, megabyte, gigabyte, the default) or `:iec` (powers of 1024 — kibibyte, mebibyte, gibibyte). IEC prefixes apply only to bit- and byte-based units:
 
 ```elixir
 iex> {:ok, unit} = Localize.Unit.new(1_048_576, "byte")
@@ -263,13 +268,37 @@ iex> {humanized.name, humanized.value}
 {"mebibyte", 1.0}
 ```
 
-Note that CLDR provides display patterns (like `"MB"` in the narrow width) only for SI-prefixed digital units; IEC units format with their full names in all widths. Values below one kilobyte (or kibibyte) are returned unchanged, and already-prefixed units are rescaled from their base value. Non-digital units return an error:
+Note that CLDR provides display patterns (like `"MB"` in the narrow width) only for SI-prefixed units; IEC units format with their full names in all widths. Values below one kilo-unit (or kibi-unit) are returned unchanged, and already-prefixed units are rescaled from their base value. Units with any other base return an error — physical quantities are covered by usage-based preferences instead (see below):
 
 ```elixir
 iex> {:ok, meters} = Localize.Unit.new(5, "meter")
 iex> {:error, _} = Localize.Unit.humanize(meters)
 ```
 
+### Humanizing any unit: `humanize: true`
+
+The simplest way to render *any* unit in the unit people expect for its magnitude is the `:humanize` option on `to_string/2`:
+
+```elixir
+iex> Localize.Unit.new!(1_500_000, "byte") |> Localize.Unit.to_string(humanize: true, format: :narrow)
+{:ok, "1.5MB"}
+
+iex> Localize.Unit.new!(1_500, "meter") |> Localize.Unit.to_string(humanize: true, locale: :de)
+{:ok, "1,5 Kilometer"}
+
+iex> Localize.Unit.new!(1_500_000, "gram") |> Localize.Unit.to_string(humanize: true, locale: :en)
+{:ok, "1.653 tons"}
+```
+
+Underneath, the option dispatches by unit kind. Bit-, byte-, hertz- and watt-based units scale through the `humanize/2` prefix ladder above — the locale-invariant quantities that CLDR's unit-preference data does not cover ("kB", "MHz" and "GW" mean the same thing in every locale). Every other unit is rendered through the usage-based preference pipeline (see [Usage preferences](#usage-preferences) below) with the struct's usage or `:default`. CLDR unit preferences pick the display unit by territory *and* magnitude, which does more than prefix scaling could: grams scale to kilograms and then to tonnes (not to the technically-correct-but-unidiomatic megagram), and a US-locale reader sees miles, tons, feet and inches rather than SI units at all:
+
+```elixir
+iex> Localize.Unit.new!(1_500, "meter") |> Localize.Unit.to_string(humanize: true, usage: :road, locale: "en-US")
+{:ok, "0.932 miles"}
+```
+
+An explicit `:usage` option (as above) takes precedence for preference-scaled units, and is the ICU-compatible precise control — ICU triggers the same behaviour with the `usage()` setting on `NumberFormatter`. Use `humanize/2` directly when you want the scaled `%Localize.Unit{}` itself rather than a formatted string.
+
 ## Measurement system preferences
 
 `Localize.Unit.convert_measurement_system/2` converts a unit to the preferred unit for a measurement system. CLDR defines preferences for three systems:

lib/localize/unit.ex

@@ -591,6 +591,13 @@ defmodule Localize.Unit do
     end
   end
 
+  # Base units humanize/2 scales through the prefix ladder: the
+  # locale-invariant SI-prefixed quantities that CLDR's unit
+  # preference data does not cover. IEC binary prefixes are
+  # meaningful only for the digital bases.
+  @si_humanize_bases ~w(bit byte hertz watt)
+  @iec_humanize_bases ~w(bit byte)
+
   # Prefix ladders for humanize/2, largest factor first so the first
   # match is the prefix that scales the value into [1, 1000) or [1, 1024).
   @si_humanize_prefixes ~w(kilo mega giga tera peta exa zetta yotta)
@@ -607,37 +614,46 @@ defmodule Localize.Unit do
                        |> Enum.reverse()
 
   @doc """
-  Converts a digital unit (bytes or bits) to the prefixed unit that
-  best fits its magnitude, suitable for human-readable file sizes.
+  Converts a bit-, byte-, hertz- or watt-based unit to the prefixed
+  unit that best fits its magnitude — human-readable file sizes,
+  frequencies and power figures.
+
+  Selects the largest SI prefix (kilobyte, megahertz, gigawatt, ...)
+  or, for bits and bytes, IEC binary prefix (kibibyte, mebibyte, ...)
+  such that the converted value is at least `1`. Values smaller than
+  one kilo-unit (or kibi-unit) are returned unchanged.
 
-  Selects the largest SI prefix (kilobyte, megabyte, gigabyte, ...)
-  or IEC binary prefix (kibibyte, mebibyte, gibibyte, ...) such that
-  the converted value is at least `1`. Values smaller than one
-  kilobyte (or kibibyte) are returned unchanged.
+  These bases are the locale-invariant SI-prefixed quantities that
+  CLDR's unit preference data does not cover. For physical
+  quantities such as length or mass, use the `:usage` option on
+  `to_string/2` instead — CLDR preferences pick the display unit by
+  territory and magnitude.
 
   ### Arguments
 
   * `unit` is a `%Localize.Unit{}` struct with a value, based on
-    `"byte"` or `"bit"` (a bare or already-prefixed unit such as
-    `"byte"`, `"kilobyte"` or `"megabit"`).
+    `"bit"`, `"byte"`, `"hertz"` or `"watt"` (a bare or
+    already-prefixed unit such as `"byte"`, `"kilobyte"` or
+    `"megahertz"`).
 
   * `options` is a keyword list of options.
 
   ### Options
 
   * `:system` is the prefix system to scale with: `:si` (powers of
-    1000, the default) or `:iec` (powers of 1024). Note that CLDR
-    provides compact display patterns (like `"MB"`) only for
-    SI-prefixed digital units; IEC units format with their full
-    names in all format widths.
+    1000, the default) or `:iec` (powers of 1024, bit- and
+    byte-based units only). Note that CLDR provides compact display
+    patterns (like `"MB"`) only for SI-prefixed units; IEC units
+    format with their full names in all format widths.
 
   ### Returns
 
   * `{:ok, unit}` where `unit` is a new `%Localize.Unit{}` with the
     scaled value and prefixed unit name, or
 
-  * `{:error, reason}` if the unit has no value, is not a digital
-    (bit- or byte-based) unit, or the prefix system is invalid.
+  * `{:error, reason}` if the unit has no value, has an unsupported
+    base unit, or the prefix system is invalid or does not apply to
+    the base unit.
 
   ### Examples
 
@@ -648,6 +664,11 @@ defmodule Localize.Unit do
       iex> Localize.Unit.to_string(humanized, format: :narrow, locale: :en)
       {:ok, "1.5MB"}
 
+      iex> {:ok, unit} = Localize.Unit.new(2_500_000_000, "hertz")
+      iex> {:ok, humanized} = Localize.Unit.humanize(unit)
+      iex> {humanized.name, humanized.value}
+      {"gigahertz", 2.5}
+
       iex> {:ok, unit} = Localize.Unit.new(1_048_576, "byte")
       iex> {:ok, humanized} = Localize.Unit.humanize(unit, system: :iec)
       iex> {humanized.name, humanized.value}
@@ -665,23 +686,24 @@ defmodule Localize.Unit do
     system = Keyword.get(options, :system, :si)
 
     with :ok <- validate_prefix_system(system),
-         {:ok, base_name} <- digital_base_unit(unit),
+         {:ok, base_name} <- humanizable_base_unit(unit),
+         :ok <- validate_system_for_base(system, base_name),
          {:ok, base_unit} <- convert_unless_same(unit, base_name) do
       target_name = humanized_unit_name(base_unit.value, system, base_name)
       convert_unless_same(base_unit, target_name)
     end
   end
 
   @doc """
-  Converts a digital unit (bytes or bits) to the prefixed unit that
-  best fits its magnitude, raising on error.
+  Converts a bit-, byte-, hertz- or watt-based unit to the prefixed
+  unit that best fits its magnitude, raising on error.
 
   See `humanize/2` for details.
 
   ### Arguments
 
   * `unit` is a `%Localize.Unit{}` struct with a value, based on
-    `"byte"` or `"bit"`.
+    `"bit"`, `"byte"`, `"hertz"` or `"watt"`.
 
   * `options` is a keyword list of options. See `humanize/2`.
 
@@ -690,8 +712,8 @@ defmodule Localize.Unit do
   * A new `%Localize.Unit{}` with the scaled value and prefixed
     unit name, or
 
-  * raises an exception if the unit has no value, is not a digital
-    unit, or the prefix system is invalid.
+  * raises an exception if the unit has no value, has an unsupported
+    base unit, or the prefix system is invalid.
 
   ### Examples
 
@@ -720,24 +742,34 @@ defmodule Localize.Unit do
      )}
   end
 
-  defp digital_base_unit(%__MODULE__{parsed: {:unit, parts}} = unit) do
+  defp validate_system_for_base(:iec, base_name) when base_name not in @iec_humanize_bases do
+    {:error,
+     Localize.InvalidValueError.exception(
+       value: base_name,
+       expected: "a bit- or byte-based unit when system: :iec"
+     )}
+  end
+
+  defp validate_system_for_base(_system, _base_name), do: :ok
+
+  defp humanizable_base_unit(%__MODULE__{parsed: {:unit, parts}} = unit) do
     with [single_unit: single_unit] <- Keyword.get(parts, :numerator),
          [] <- Keyword.get(parts, :denominator),
-         base when base in ["bit", "byte"] <- Keyword.get(single_unit, :base),
+         base when base in @si_humanize_bases <- Keyword.get(single_unit, :base),
          power when power in [nil, 1] <- Keyword.get(single_unit, :power) do
       {:ok, base}
     else
-      _other -> not_digital_error(unit)
+      _other -> not_humanizable_error(unit)
     end
   end
 
-  defp digital_base_unit(%__MODULE__{} = unit), do: not_digital_error(unit)
+  defp humanizable_base_unit(%__MODULE__{} = unit), do: not_humanizable_error(unit)
 
-  defp not_digital_error(unit) do
+  defp not_humanizable_error(unit) do
     {:error,
      Localize.InvalidValueError.exception(
        value: unit.name,
-       expected: "a bit- or byte-based unit",
+       expected: "a bit-, byte-, hertz- or watt-based unit",
        context: "humanize"
      )}
   end
@@ -1008,6 +1040,15 @@ defmodule Localize.Unit do
   * `:format` is `:long`, `:short`, or `:narrow`.
     The default is `:long`.
 
+  * `:humanize` (single unit only) when `true` renders the unit in
+    the unit people expect for its magnitude: bit-, byte-, hertz-
+    and watt-based units are scaled through `humanize/2` (honouring
+    the `:system` option for `:si` or `:iec` prefixes), and all
+    other units are rendered through the usage-based preference
+    pipeline using the struct's `:usage` field or `:default`. An
+    explicit `:usage` option takes precedence for preference-scaled
+    units. The default is `false`.
+
   * `:usage` (single unit only) is the unit's intended usage. When
     given, triggers `localize/2` before formatting. Accepts an atom
     (`:person_height`) or a CLDR-style string (`"person-height"`). If
@@ -1060,6 +1101,14 @@ defmodule Localize.Unit do
       iex> Localize.Unit.to_string(unit, usage: :road, locale: "de-DE")
       {:ok, "2 Kilometer"}
 
+      iex> Localize.Unit.new!(1_500_000, "byte")
+      ...> |> Localize.Unit.to_string(humanize: true, format: :narrow)
+      {:ok, "1.5MB"}
+
+      iex> Localize.Unit.new!(1_500, "meter")
+      ...> |> Localize.Unit.to_string(humanize: true, locale: :de)
+      {:ok, "1,5 Kilometer"}
+
   """
   @spec to_string(t() | [t(), ...], Keyword.t()) :: {:ok, String.t()} | {:error, Exception.t()}
   def to_string(unit_or_units, options \\ [])
@@ -1069,15 +1118,40 @@ defmodule Localize.Unit do
   end
 
   def to_string(%__MODULE__{} = unit, options) do
-    if Keyword.has_key?(options, :usage) or not is_nil(unit.usage) do
-      preference_options = Keyword.take(options, [:usage, :locale])
-      list_options = Keyword.drop(options, [:usage])
+    with {:ok, unit, options} <- maybe_humanize(unit, options) do
+      if Keyword.has_key?(options, :usage) or not is_nil(unit.usage) do
+        preference_options = Keyword.take(options, [:usage, :locale])
+        list_options = Keyword.drop(options, [:usage])
 
-      with {:ok, parts} <- localize(unit, preference_options) do
-        format_unit_list(parts, list_options)
+        with {:ok, parts} <- localize(unit, preference_options) do
+          format_unit_list(parts, list_options)
+        end
+      else
+        Localize.Unit.Formatter.to_string(unit, merge_struct_format_options(unit, options))
       end
-    else
-      Localize.Unit.Formatter.to_string(unit, merge_struct_format_options(unit, options))
+    end
+  end
+
+  # `humanize: true` renders the unit the way people expect for its
+  # kind: bit-, byte-, hertz- and watt-based units scale through the
+  # `humanize/2` prefix ladder, every other unit goes through the
+  # usage-based preference pipeline with the struct's usage or
+  # `:default`. An explicit `:usage` option still wins for
+  # preference-scaled units.
+  defp maybe_humanize(unit, options) do
+    {humanize?, options} = Keyword.pop(options, :humanize, false)
+
+    cond do
+      humanize? != true ->
+        {:ok, unit, options}
+
+      match?({:ok, _base}, humanizable_base_unit(unit)) ->
+        with {:ok, humanized} <- humanize(unit, Keyword.take(options, [:system])) do
+          {:ok, humanized, options}
+        end
+
+      true ->
+        {:ok, unit, Keyword.put_new(options, :usage, unit.usage || :default)}
     end
   end
 

skills/localize/references/units.md

@@ -76,13 +76,24 @@ Localize.Unit.new!(1, "meter") |> Localize.Unit.convert("kilogram")
 
 `convert_measurement_system/2` targets `:metric`, `:us`, or `:uk` preferred units (1000 meters → mile for `:us`).
 
-## Humanizing digital units (file sizes)
+## Humanizing (auto-scaling to the expected unit)
 
-`humanize/2` and `humanize!/2` convert a byte- or bit-based unit to the prefix that best fits its magnitude — the idiomatic way to render file sizes. `system: :si` (powers of 1000, default) or `system: :iec` (powers of 1024); CLDR has compact narrow patterns (`"MB"`) only for SI prefixes, IEC units render with full names. Non-digital units return `InvalidValueError`.
+`to_string(unit, humanize: true)` renders any unit in the unit people expect for its magnitude: bit-, byte-, hertz- and watt-based units scale through the SI prefix ladder (or IEC with `system: :iec`, bits/bytes only), all other units go through usage-based preferences (struct usage or `:default`; an explicit `usage:` wins).
 
 ```elixir
-Localize.Unit.new!(1_500_000, "byte") |> Localize.Unit.humanize!() |> Localize.Unit.to_string(format: :narrow)
+Localize.Unit.new!(1_500_000, "byte") |> Localize.Unit.to_string(humanize: true, format: :narrow)
 #=> {:ok, "1.5MB"}
+Localize.Unit.new!(2_500_000, "hertz") |> Localize.Unit.to_string(humanize: true, format: :narrow)
+#=> {:ok, "2.5MHz"}
+Localize.Unit.new!(1_500, "meter") |> Localize.Unit.to_string(humanize: true, locale: :de)
+#=> {:ok, "1,5 Kilometer"}
+Localize.Unit.new!(1_500_000, "gram") |> Localize.Unit.to_string(humanize: true, locale: :en)
+#=> {:ok, "1.653 tons"}
+```
+
+`humanize/2` and `humanize!/2` are the struct-level API for the prefix-scaled bases (bit, byte, hertz, watt) — they convert to the prefixed unit that best fits the magnitude and return the scaled `%Localize.Unit{}`. `system: :si` (powers of 1000, default) or `system: :iec` (powers of 1024, bits/bytes only); CLDR has compact narrow patterns (`"MB"`, `"MHz"`) only for SI prefixes, IEC units render with full names. Other bases return `InvalidValueError`.
+
+```elixir
 Localize.Unit.new!(2_750_000_000, "byte") |> Localize.Unit.humanize!() |> Localize.Unit.to_string(format: :narrow, fractional_digits: 1)
 #=> {:ok, "2.8GB"}
 {:ok, iec} = Localize.Unit.new!(1_048_576, "byte") |> Localize.Unit.humanize(system: :iec)