class

Unit::Volume

Inherits Comparable < Unit::Formatter < Unit::Comparison < Unit::Arithmetic < Unit::Conversion < Reference < Object

Volume measurement class with comprehensive unit support

Supports both metric and US liquid volume units with precise conversions using BigDecimal for accuracy. Liter is used as the base unit for all conversions to maintain consistency and precision.

Focuses on US liquid measurements for cooking and recipe applications. Maintains high precision for accurate culinary conversions.

Examples: Volume.new(2.5, Volume::Unit::Cup) Volume.new(1.5, Volume::Unit::Liter) Volume.new(16, Volume::Unit::FluidOunce)

Constants

CONVERSION_FACTORS = {Volume::Unit::Liter => BigDecimal.new("1"), Volume::Unit::Milliliter => BigDecimal.new("0.001"), Volume::Unit::Gallon => BigDecimal.new("3.785411784"), Volume::Unit::Quart => BigDecimal.new("0.946352946"), Volume::Unit::Pint => BigDecimal.new("0.473176473"), Volume::Unit::Cup => BigDecimal.new("0.2365882365"), Volume::Unit::FluidOunce => BigDecimal.new("0.0295735295625")}

Conversion factors to liters (base unit)

All values are stored as BigDecimal for maximum precision Values are based on NIST Handbook 44 and US customary measurements

Constructors

from_json(string_or_io) : self

JSON deserialization

Source
from_yaml(string_or_io) : self

YAML deserialization

Source
new(value : Number, unit : Volume::Unit)

Creates a new volume with the given value and unit

Source
new(value : Number, unit_symbol : Symbol)

Creates a new volume with the given value and unit symbol

Source

Class methods

base_unit

Returns the base unit for volume measurements (liter)

Source
conversion_factor(unit : Volume::Unit)

Returns the conversion factor for the given unit

Source
conversion_factor(unit_symbol : Symbol)

Returns the conversion factor for the given unit symbol

Source
metric_unit?(unit : Volume::Unit)

Returns true if the given unit is metric

Source
us_liquid_unit?(unit : Volume::Unit)

Returns true if the given unit is a US liquid measurement

Source

Instance methods

inspect(io : IO) : Nil

Returns a detailed string representation for debugging

Source
symbol

Returns the symbol for this volume's unit

Source
to_json(json : JSON::Builder) : Nil

JSON serialization support

Source
to_s(io : IO) : Nil

Returns a readable string representation of the measurement

Source
to_weight(density_value : Number, density_unit : Symbol) : Weight

Convert this volume to weight given a density value and unit

This is a convenience method that creates a Density object internally from the provided value and unit, then performs the conversion.

# Using density value and unit without creating Density object
volume = Unit::Volume.new(250, :milliliter)
flour_weight = volume.to_weight(0.593, :gram_per_milliliter) # ~148 g

# Different density units supported
honey_weight = volume.to_weight(1.42, :g_per_cc)     # ~355 g
mercury_weight = volume.to_weight(13.534, :g_per_cc) # ~3.38 kg

@param density_value The numeric density value @param density_unit The unit of the density @return The weight that would occupy this volume at the given density @raise ArgumentError if density_value is zero or negative, or if density_unit is invalid

Source
to_weight(density : Density) : Weight

Convert this volume to weight given a density

This method calculates the mass that would occupy this volume at the given density, using the formula: mass = volume × density

# Using a Density object
volume = Unit::Volume.new(500, :milliliter)
water_density = Unit::Density.new(1.0, :gram_per_milliliter)
weight = volume.to_weight(water_density) # => 500 g

# Using density value and unit (creates Density internally)
weight = volume.to_weight(0.92, :gram_per_milliliter) # => 460 g

# With explicit naming for clarity
weight = volume.weight_given(water_density)

@param density The density of the material @return The weight that would occupy this volume at the given density @raise ArgumentError if density is zero or negative

Source
to_yaml(yaml : YAML::Nodes::Builder) : Nil

YAML serialization support

Source
unit

Unit of measurement

Source
unit_name(plural = false)

Returns the name of this volume's unit

Source
value

Value stored as BigDecimal for precision

Source
weight_given(density_value : Number, density_unit : Symbol) : Weight

Alias for to_weight with explicit naming for clarity (overload)

This method provides a more explicit name that can make code more readable, especially in complex expressions.

volume = Unit::Volume.new(250, :milliliter)
weight = volume.weight_given(0.593, :gram_per_milliliter)

@param density_value The numeric density value @param density_unit The unit of the density @return The weight that would occupy this volume at the given density

Source
weight_given(density : Density) : Weight

Alias for to_weight with explicit naming for clarity

This method provides a more explicit name that can make code more readable, especially in complex expressions.

volume = Unit::Volume.new(500, :milliliter)
weight = volume.weight_given(Unit::Density.new(1.0, :g_per_ml))

@param density The density of the material @return The weight that would occupy this volume at the given density

Source

Nested types