class

Unit::Weight

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

Weight measurement class with comprehensive unit support

This class represents mass/weight measurements and supports both metric and imperial units with precise conversions. All conversions use gram as the base unit to maintain consistency and precision.

Units Supported

Metric Units

gram (g) - Base unit
kilogram (kg) - 1000 grams
milligram (mg) - 0.001 grams
tonne (t) - 1,000,000 grams

Imperial Units

pound (lb) - 453.59237 grams
ounce (oz) - 28.349523125 grams
slug - 14593.903 grams

Examples

# Creating weights
weight = Unit::Weight.new(10.5, :kilogram)
heavy = Unit::Weight.new(1, :tonne)
light = Unit::Weight.new(500, :gram)

# Converting between units
pounds = weight.convert_to(:pound) # => 23.15 lb
grams = weight.to(:gram)           # => 10500 g

# Arithmetic operations
total = weight + Unit::Weight.new(5, :pound)
doubled = weight * 2

# Parsing from strings
parsed = Unit::Parser.parse("2.5 kg", Unit::Weight)

Constants

CONVERSION_FACTORS = {Weight::Unit::Gram => BigDecimal.new("1"), Weight::Unit::Kilogram => BigDecimal.new("1000"), Weight::Unit::Milligram => BigDecimal.new("0.001"), Weight::Unit::Tonne => BigDecimal.new("1000000"), Weight::Unit::Pound => BigDecimal.new("453.59237"), Weight::Unit::Ounce => BigDecimal.new("28.349523125"), Weight::Unit::Slug => BigDecimal.new("14593.903")}

Conversion factors to grams (base unit)

All values are stored as BigDecimal for maximum precision Values are based on internationally accepted conversion standards

Constructors

from_json(string_or_io) : self

JSON deserialization

from_yaml(string_or_io) : self

YAML deserialization

new(value : Number, unit : Weight::Unit)

Creates a new weight measurement with the given value and unit.

# Using symbols (recommended)
weight = Unit::Weight.new(5.5, :kilogram)

# Using enum values
weight = Unit::Weight.new(10, Unit::Weight::Unit::Pound)

# Various numeric types supported
Unit::Weight.new(100, :gram)                      # Int32
Unit::Weight.new(2.5, :kilogram)                  # Float64
Unit::Weight.new(BigDecimal.new("0.001"), :tonne) # BigDecimal

@param value The numeric value (any Number type) @param unit The unit as enum value or symbol @raise ArgumentError if value is NaN or infinite

new(value : Number, unit_symbol : Symbol)

Creates a new weight with the given value and unit symbol

Class methods

base_unit

Returns the base unit for weight measurements.

All weight conversions go through gram as the base unit to ensure consistency and minimize compound conversion errors.

Unit::Weight.base_unit # => Unit::Weight::Unit::Gram

conversion_factor(unit : Weight::Unit)

Returns the conversion factor to grams for the given unit.

This factor represents how many grams are in one unit of the given type.

Unit::Weight.conversion_factor(Unit::Weight::Unit::Kilogram) # => BigDecimal("1000")
Unit::Weight.conversion_factor(:pound)                       # => BigDecimal("453.59237")

conversion_factor(unit_symbol : Symbol)

Returns the conversion factor for the given unit symbol

metric_unit?(unit : Weight::Unit)

Checks if the given unit is part of the metric system.

Unit::Weight.metric_unit?(:kilogram) # => true
Unit::Weight.metric_unit?(:pound)    # => false

Instance methods

inspect(io : IO) : Nil

Returns a detailed string representation for debugging

symbol

Returns the symbol for this weight's unit

to_json(json : JSON::Builder) : Nil

JSON serialization support

to_s(io : IO) : Nil

Returns a readable string representation of the measurement

to_volume(density_value : Number, density_unit : Symbol) : Volume

Convert this weight to volume 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
weight = Unit::Weight.new(200, :gram)
flour_volume = weight.to_volume(0.593, :gram_per_milliliter) # ~337 mL

# Different density units supported
honey_volume = weight.to_volume(1.42, :g_per_cc) # ~141 mL
oil_volume = weight.to_volume(62.4, :lb_per_gal) # ~3193 mL

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

to_volume(density : Density) : Volume

Convert this weight to volume given a density

This method calculates the volume that would be occupied by this mass at the given density, using the formula: volume = mass / density

# Using a Density object
weight = Unit::Weight.new(500, :gram)
water_density = Unit::Density.new(1.0, :gram_per_milliliter)
volume = weight.to_volume(water_density) # => 500 mL

# Using density value and unit (creates Density internally)
volume = weight.to_volume(0.92, :gram_per_milliliter) # => ~543 mL

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

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

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

YAML serialization support

unit

The unit of this weight measurement

unit_name(plural = false)

Returns the name of this weight's unit

value

The numeric value of the weight measurement, stored as BigDecimal for precision

volume_given(density_value : Number, density_unit : Symbol) : Volume

Alias for to_volume with explicit naming for clarity (overload)

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

weight = Unit::Weight.new(200, :gram)
volume = weight.volume_given(0.593, :gram_per_milliliter)

@param density_value The numeric density value @param density_unit The unit of the density @return The volume occupied by this weight at the given density

volume_given(density : Density) : Volume

Alias for to_volume with explicit naming for clarity

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

weight = Unit::Weight.new(500, :gram)
volume = weight.volume_given(Unit::Density.new(1.0, :g_per_ml))

@param density The density of the material @return The volume occupied by this weight at the given density

Nested types