Module: Tins::Unit

Defined in:
lib/tins/unit.rb

Overview

A module for parsing and formatting unit specifications with support for various prefix types and unit formats.

Examples:

Basic usage

Tins::Unit.parse('1.5 GB').round # => 1610612736
Tins::Unit.format(1610612736, unit: 'B') # => "1.500000 GB"
Tins::Unit.parse('1000 mb', prefix: 1000).round # => 1000000000

Defined Under Namespace

Classes: FormatParser, ParserError, Prefix, UnitParser

Constant Summary collapse

PREFIX_LC =

An array of prefix objects for lowercase decimal prefixes (k, M, G…) based on 1000-step increments.

[
  '', 'k', 'm', 'g', 't', 'p', 'e', 'z', 'y',
].each_with_index.map { |n, i| Prefix.new(n.freeze, 1000, 1000 ** i, false) }.freeze
PREFIX_UC =

An array of prefix objects for uppercase binary prefixes (K, M, G…) based on 1024-step increments.

[
  '', 'K', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y',
].each_with_index.map { |n, i| Prefix.new(n.freeze, 1024, 1024 ** i, false) }.freeze
PREFIX_IEC_UC =

An array of prefix objects for uppercase binary prefixes (Ki, Mi, Gi…) based on 1024-step increments.

[
  '', 'Ki', 'Mi', 'Gi', 'Ti', 'Pi', 'Ei', 'Zi', 'Yi',
].each_with_index.map { |n, i| Prefix.new(n.freeze, 1024, 1024 ** i, false) }.freeze
PREFIX_SI_UC =

An array of prefix objects for uppercase SI unit prefixes (K, M, G…) based on 1000-step increments.

[
  '', 'K', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y',
].each_with_index.map { |n, i| Prefix.new(n.freeze, 1000, 1000 ** i, false) }.freeze
PREFIX_F =

An array of prefix objects for fractional prefixes (m, µ, n…) based on 1000-step decrements.

[
  '', 'm', 'µ', 'n', 'p', 'f', 'a', 'z', 'y',
].each_with_index.map { |n, i| Prefix.new(n.freeze, 1000, 1000 ** -i, true) }.freeze

Class Method Summary collapse

Class Method Details

.format(value, format: '%f %U', prefix: 1024, unit: ?b) ⇒ Object

Format a value using unit prefixes and a specified format template.

This method takes a numerical value and formats it according to the given format string, inserting the appropriate unit prefix based on the specified prefix type and unit identifier.

Parameters:

  • value (Numeric) —

    the numerical value to format

  • format (String) (defaults to: '%f %U') —

    the format template to use for output, default is ‘%f %U’

  • prefix (Object) (defaults to: 1024) —

    the prefix configuration to use, default is 1024 (binary prefixes)

  • unit (String, Symbol) (defaults to: ?b) —

    the unit identifier to append, default is ?b (bytes)



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/tins/unit.rb', line 89

def format(value, format: '%f %U', prefix: 1024, unit: ?b)
  prefixes = prefixes(prefix)
  first_prefix = prefixes.first or
    raise ArgumentError, 'a non-empty array of prefixes is required'
  if value.zero?
    result = format.sub('%U', unit)
    result %= value
  else
    prefix = prefixes[
      (first_prefix.fraction ? -1 : 1) * Math.log(value.abs) / Math.log(first_prefix.step)
    ]
    result = format.sub('%U', "#{prefix.name}#{unit}")
    result %= (value / prefix.multiplier.to_f)
  end
end

.parse(string, format: '%f %U', unit: ?b, prefix: nil) ⇒ Object

Parse the string using the specified format and unit information

This method takes a string and parses it according to a given format template, extracting numerical values and their associated units. It supports various prefix types and unit specifications for flexible parsing.

Parameters:

  • string (String) —

    the input string to parse

  • format (String) (defaults to: '%f %U') —

    the format template to use for parsing (default: ‘%f %U’)

  • unit (String, Symbol) (defaults to: ?b) —

    the unit identifier to use (default: ?b)

  • prefix (Object) (defaults to: nil) —

    the prefix configuration to use (default: nil)

Returns:

  • (Object) —

    the parsed result based on the format and unit specifications



317
318
319
320
 
# File 'lib/tins/unit.rb', line 317

def parse(string, format: '%f %U', unit: ?b, prefix: nil)
  prefixes = prefixes(prefix)
  FormatParser.new(format, UnitParser.new(string, unit, prefixes)).parse
end

.parse?(string, **options) ⇒ Object?

The parse? method attempts to parse a string using the specified options and returns nil if parsing fails.

Parameters:

  • string (String) —

    the string to parse

  • options (Hash) —

    the options to pass to the parse method

Returns:

  • (Object, nil) —

    the parsed result or nil if parsing fails



328
329
330
331
332
 
# File 'lib/tins/unit.rb', line 328

def parse?(string, **options)
  parse(string, **options)
rescue ParserError
  nil
end

.prefixes(identifier) ⇒ Array

The prefixes method returns an array of prefix objects based on the given identifier.

This method maps different identifier symbols and values to predefined arrays of prefix objects, allowing for flexible configuration of unit prefixes.

Parameters:

  • identifier (Symbol, Integer, Array) —

    the identifier specifying which prefix set to return

Returns:

  • (Array) —

    an array of prefix objects corresponding to the identifier



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/tins/unit.rb', line 62

def prefixes(identifier)
  case identifier
  when :uppercase, :uc, 1024
    PREFIX_UC
  when :iec_uppercase, :iec_uc
    PREFIX_IEC_UC
  when :lowercase, :lc, 1000
    PREFIX_LC
  when :fraction, :f, :si_greek, 0.001
    PREFIX_F
  when :si_uc, :si_uppercase
    PREFIX_SI_UC
  when Array
    identifier
  end
end