smalltime 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 04123df6d8a7d7b789729fba23d69233f706654cf47d103c3d68d4bc91f32a90
+  data.tar.gz: 7a12888c2ba88c08948dfdd92ec403f5404823d07449c8171d98c7783b4867db
+SHA512:
+  metadata.gz: fda736d0f883fad117a1260384695e69428003b422ed5694016050e3dc94b5b13243e3003002239928935721556483d284fc25b7abd7c849601ec501285cec34
+  data.tar.gz: 658d45e19966745e11d40f7da38e08e47d9c1030764c4adb4dfb646ef716de3816850bd7d45c64d4d7bf112ec54bfc2c0faa496817f0b2ab826476d134203207

data/lib/smalltime/configuration.rb

@@ -0,0 +1,14 @@
+module Smalltime
+  class Configuration
+    attr_accessor :maximum_unit, :strict
+
+    def initialize
+      @strict = false
+      @maximum_unit = nil
+    end
+
+    def strict?
+      @strict
+    end
+  end
+end

data/lib/smalltime/numeric.rb

@@ -0,0 +1,16 @@
+require "smalltime"
+
+class Numeric
+  Smalltime::Units.constants.each do |unit|
+    unit = unit.downcase
+    plural_unit = "#{unit}s"
+
+    define_method unit do
+      Smalltime::Duration.new("#{plural_unit}": self)
+    end
+
+    define_method plural_unit do
+      Smalltime::Duration.new("#{plural_unit}": self)
+    end
+  end
+end

data/lib/smalltime.rb

@@ -0,0 +1,359 @@
+# frozen_string_literal: true
+
+require "smalltime/configuration"
+
+# Smalltime is a drop-in replacement for ActiveSupport::Duration that supports arbitrary
+# precision, no floating point arithmetic, and advanced formatting capabilities. It has
+# no dependencies and can cooperate with ActiveSupport::Durations.
+module Smalltime
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset
+      @configuration = Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def units
+      unts = configuration.strict? ? STRICT_UNITS : NONSTRICT_UNITS
+
+      unts[0..unts.find_index do |u|
+        u.names.include?(Smalltime.configuration.maximum_unit)
+      end]
+    end
+
+    def unit_by_name(name)
+      (configuration.strict? ? STRICT_UNITS : NONSTRICT_UNITS).find do |unit|
+        names = [unit.name, unit.plural, unit.shortname].map { |s| s.to_s }
+        names += names.map { |s| s.to_sym }
+        names.include?(name)
+      end
+    end
+  end
+
+  class Unit
+    # Initialize a new unit with the given names, equal to the given base unit
+    # multiplied by the given multiplier.
+    def initialize(singular_name, plural_name, shortname, base: 1, multiplier: 1)
+      @singular_name = singular_name
+      @plural_name = plural_name
+      @shortname = shortname
+      @base = base
+      @multiplier = multiplier
+    end
+
+    def *(other)
+      if other.is_a?(Numeric)
+        return @base * @multiplier * other
+      end
+
+      (@base * @multiplier) * (other.base * other.multiplier)
+    end
+
+    attr_reader :multiplier, :shortname
+
+    def to_sym
+      @plural_name.to_sym
+    end
+
+    def name
+      @singular_name
+    end
+
+    def pluralize
+      @plural_name
+    end
+    alias_method :plural, :pluralize
+
+    def names
+      [
+        @singular_name.to_s,
+        @plural_name.to_s,
+        @shortname.to_s,
+        @singular_name.to_sym,
+        @plural_name.to_sym,
+        @shortname.to_sym
+      ]
+    end
+
+    def inspect
+      "#<Smalltime::#{@plural_name}>"
+    end
+
+    private
+
+    attr_reader :base
+  end
+
+  YOCTOSECOND = Unit.new(:yoctosecond, :yoctoseconds, :ys)
+  ZEPTOSECOND = Unit.new(:zeptosecond, :zeptoseconds, :zs, base: YOCTOSECOND, multiplier: 1000)
+  ATTOSECOND = Unit.new(:attosecond, :attoseconds, :as, base: ZEPTOSECOND, multiplier: 1000)
+  FEMTOSECOND = Unit.new(:femtosecond, :femtoseconds, :fs, base: ATTOSECOND, multiplier: 1000)
+  PICOSECOND = Unit.new(:picosecond, :picoseconds, :ps, base: FEMTOSECOND, multiplier: 1000)
+  NANOSECOND = Unit.new(:nanosecond, :nanoseconds, :ns, base: PICOSECOND, multiplier: 1000)
+  MICROSECOND = Unit.new(:microsecond, :microseconds, :µs, base: NANOSECOND, multiplier: 1000)
+  MILLISECOND = Unit.new(:millisecond, :milliseconds, :ms, base: MICROSECOND, multiplier: 1000)
+  CENTISECOND = Unit.new(:centisecond, :centiseconds, :cs, base: MILLISECOND, multiplier: 10)
+  DECISECOND = Unit.new(:decisecond, :deciseconds, :ds, base: CENTISECOND, multiplier: 10)
+
+  STRICT_SECOND = Unit.new(:second, :seconds, :s, base: DECISECOND, multiplier: 10)
+  STRICT_MINUTE = Unit.new(:minute, :minutes, :min, base: STRICT_SECOND, multiplier: 60)
+  STRICT_HOUR = Unit.new(:hour, :hours, :h, base: STRICT_MINUTE, multiplier: 60)
+  STRICT_DAY = Unit.new(:day, :days, :d, base: STRICT_HOUR, multiplier: 24)
+  STRICT_WEEK = Unit.new(:week, :weeks, :w, base: STRICT_DAY, multiplier: 7)
+  STRICT_MONTH = Unit.new(:month, :months, :mo, base: STRICT_WEEK, multiplier: 4) # Warning: approximate
+  STRICT_YEAR = Unit.new(:year, :years, :y, base: STRICT_MONTH, multiplier: 12)
+  STRICT_DECADE = Unit.new(:decade, :decades, :dy, base: STRICT_YEAR, multiplier: 10)
+  STRICT_CENTURY = Unit.new(:century, :centuries, :c, base: STRICT_DECADE, multiplier: 10)
+  STRICT_MILLENIUM = Unit.new(:millenium, :millenia, :mi, base: STRICT_CENTURY, multiplier: 10)
+
+  NONSTRICT_SECOND = Unit.new(:second, :seconds, :s, base: MILLISECOND, multiplier: 1000)
+  NONSTRICT_MINUTE = Unit.new(:minute, :minutes, :m, base: NONSTRICT_SECOND, multiplier: 60)
+  NONSTRICT_HOUR = Unit.new(:hour, :hours, :h, base: NONSTRICT_MINUTE, multiplier: 60)
+  NONSTRICT_DAY = Unit.new(:day, :days, :d, base: NONSTRICT_HOUR, multiplier: 24)
+  NONSTRICT_WEEK = Unit.new(:week, :weeks, :w, base: NONSTRICT_DAY, multiplier: 7)
+  NONSTRICT_MONTH = Unit.new(:month, :months, :mo, base: NONSTRICT_WEEK, multiplier: 4) # Warning: approximate
+  NONSTRICT_YEAR = Unit.new(:year, :years, :y, base: NONSTRICT_MONTH, multiplier: 12)
+  NONSTRICT_DECADE = Unit.new(:decade, :decades, :dy, base: NONSTRICT_YEAR, multiplier: 10)
+  NONSTRICT_CENTURY = Unit.new(:century, :centuries, :c, base: NONSTRICT_DECADE, multiplier: 10)
+  NONSTRICT_MILLENIUM = Unit.new(:millenium, :millenia, :mi, base: NONSTRICT_CENTURY, multiplier: 10)
+
+  STRICT_UNITS = [
+    YOCTOSECOND, ZEPTOSECOND, ATTOSECOND, FEMTOSECOND, PICOSECOND, NANOSECOND,
+    MICROSECOND, MILLISECOND, CENTISECOND, DECISECOND, STRICT_SECOND, STRICT_MINUTE,
+    STRICT_HOUR, STRICT_DAY, STRICT_WEEK, STRICT_MONTH, STRICT_YEAR, STRICT_DECADE,
+    STRICT_CENTURY, STRICT_MILLENIUM
+  ]
+  NONSTRICT_UNITS = [
+    YOCTOSECOND, ZEPTOSECOND, ATTOSECOND, FEMTOSECOND, PICOSECOND, NANOSECOND,
+    MICROSECOND, MILLISECOND, NONSTRICT_SECOND, NONSTRICT_MINUTE, NONSTRICT_HOUR,
+    NONSTRICT_DAY, NONSTRICT_WEEK, NONSTRICT_MONTH, NONSTRICT_YEAR, NONSTRICT_DECADE,
+    NONSTRICT_CENTURY, NONSTRICT_MILLENIUM
+  ]
+
+  # Duration represents a segment of time.
+  class Duration
+    # Create a new smalltime. A smalltime is an arbitrarily precise duration immune to
+    # floating point errors and having advanced formatting capabilities.
+    def initialize(
+      millenia: 0,
+      centuries: 0,
+      decades: 0,
+      years: 0,
+      months: 0,
+      weeks: 0,
+      days: 0,
+      hours: 0,
+      minutes: 0,
+      seconds: 0,
+      deciseconds: 0,
+      centiseconds: 0,
+      milliseconds: 0,
+      microseconds: 0,
+      nanoseconds: 0,
+      picoseconds: 0,
+      femtoseconds: 0,
+      attoseconds: 0,
+      zeptoseconds: 0,
+      yoctoseconds: 0
+    )
+      @parts = {
+        yoctoseconds: yoctoseconds,
+        zeptoseconds: zeptoseconds,
+        attoseconds: attoseconds,
+        femtoseconds: femtoseconds,
+        picoseconds: picoseconds,
+        nanoseconds: nanoseconds,
+        microseconds: microseconds,
+        milliseconds: milliseconds,
+        centiseconds: centiseconds,
+        deciseconds: deciseconds,
+        seconds: seconds,
+        minutes: minutes,
+        hours: hours,
+        days: days,
+        weeks: weeks,
+        months: months,
+        years: years,
+        decades: decades,
+        centuries: centuries,
+        millenia: millenia
+      }
+
+      Smalltime.units[0..-2].each.with_index do |unit, i|
+        next unless @parts.key?(unit.plural)
+
+        div, mod = @parts[unit.plural].divmod(Smalltime.units[i + 1].multiplier)
+        @parts[unit.plural] = mod
+        @parts[Smalltime.units[i + 1].plural] += div
+      end
+    end
+
+    def millenia
+      @parts[:millenia]
+    end
+
+    def centuries
+      @parts[:centuries]
+    end
+
+    def decades
+      @parts[:decades]
+    end
+
+    def years
+      @parts[:years]
+    end
+
+    def months
+      @parts[:months]
+    end
+
+    def weeks
+      @parts[:weeks]
+    end
+
+    def days
+      @parts[:days]
+    end
+
+    def hours
+      @parts[:hours]
+    end
+
+    def minutes
+      @parts[:minutes]
+    end
+
+    def seconds
+      @parts[:seconds]
+    end
+
+    def deciseconds
+      @parts[:deciseconds]
+    end
+
+    def centiseconds
+      @parts[:centiseconds]
+    end
+
+    def milliseconds
+      @parts[:milliseconds]
+    end
+
+    def microseconds
+      @parts[:microseconds]
+    end
+
+    def nanoseconds
+      @parts[:nanoseconds]
+    end
+
+    def picoseconds
+      @parts[:picoseconds]
+    end
+
+    def femtoseconds
+      @parts[:femtoseconds]
+    end
+
+    def attoseconds
+      @parts[:attoseconds]
+    end
+
+    def zeptoseconds
+      @parts[:zeptoseconds]
+    end
+
+    def yoctoseconds
+      @parts[:yoctoseconds]
+    end
+
+    # Given a part key like :seconds, returns the next-biggest part key like :minutes.
+    # If `by` is given, instead returns the part `by` levels bigger. For example,
+    # `bigger_part(:seconds, by: 2)` returns `:hours`.
+    def bigger_part(part, by: 1)
+      @parts.keys[@parts.keys.find_index(part) + by]
+    end
+
+    # Given a part key like :minutes, returns the next-smallest part key like :seconds.
+    # If `by` is given, instead returns the part `by` levels smaller. For example,
+    # `smaller_part(:hours, by: 2)` returns `:seconds`.
+    def smaller_part(part, by: 1)
+      @parts.keys[@parts.keys.find_index(part) - by]
+    end
+
+    def precision
+      @parts.each do |unit, value|
+        return unit if value != 0
+      end
+    end
+
+    def to_s
+    end
+
+    # Create a new Smalltime::Duration out of seconds. This method is provided as a drop-in replacement for
+    # ActiveSupport::Duration.build.
+    #
+    # @param seconds [Fixnum] the number of total seconds in the duration
+    # @return [Smalltime] the new smalltime duration
+    def build(seconds)
+      new(seconds: seconds)
+    end
+
+    # Return a duration formatted like "HH:MM:SS". If precise is true, it returns a time
+    # like "HH:MM:SS.cc" instead.
+    #
+    # When sign is :always, the returned value always has a "+" or "-" in front of it.
+    # When sign is :never, the returned value never has a sign in front of it. When sign
+    # is :negative, only negative values have a sign (default).
+    def clocklike(precise: false, sign: :negative)
+      format = ["%02d", ":%02d", ":%02d"]
+      components = [hours, minutes, seconds]
+
+      if precise
+        format << ".%02d"
+        components << (milliseconds / 10)
+      end
+
+      if sign == :always || (sign == :negative && negative?)
+        format[0] = "%0+2d"
+      end
+
+      Kernel.format(format.join, *components)
+    end
+
+    # Return a duration imprecisely formatted like "123s" or "4mo 3d". The number of
+    # units displayed is `units`, with the largest nonzero unit being the first and the
+    # remaining ones sequentially getting more precise (e.g. "3mo 21d", "4h 0m").
+    #
+    # If the duration is exactly 0, "-" is returned.
+    def casual(units: 1)
+      string_components = []
+
+      units.times do |unit_offset|
+        return "-" if biggest_nonzero_unit.nil?
+        u = Smalltime.unit_by_name(smaller_part(biggest_nonzero_unit, by: unit_offset))
+        string_components << "#{@parts[u.pluralize.to_sym]}#{u.shortname}"
+      end
+
+      return "-" if string_components.empty?
+      string_components.join(" ")
+    end
+
+    def biggest_nonzero_unit
+      @parts.to_a.reverse.to_h.find do |unit, val|
+        if val != 0
+          return unit
+        end
+      end
+    end
+  end
+end

data/lib/smalltime.rbs

@@ -0,0 +1,53 @@
+# Smalltime is a drop-in replacement for ActiveSupport::Duration that supports arbitrary
+# precision, no floating point arithmetic, and advanced formatting capabilities. It has
+# no dependencies and can cooperate with ActiveSupport::Durations.
+module Smalltime
+  module Units
+    YOCTOSECOND: ::Integer
+    ZEPTOSECOND: ::Integer
+    ATTOSECOND: ::Integer
+    FEMTOSECOND: ::Integer
+    PICOSECOND: ::Integer
+    NANOSECOND: ::Integer
+    MICROSECOND: ::Integer
+    MILLISECOND: ::Integer
+    CENTISECOND: ::Integer
+    DECISECOND: ::Integer
+    SECOND: ::Integer
+    MINUTE: ::Integer
+    HOUR: ::Integer
+    DAY: ::Integer
+    WEEK: ::Integer
+    MONTH: ::Integer
+    YEAR: ::Integer
+    DECADE: ::Integer
+    CENTURY: ::Integer
+    MILLENIUM: ::Integer
+  end
+
+  # Duration represents a segment of time.
+  class Duration
+    # Create a new smalltime. A smalltime is an arbitrarily precise duration immune to
+    # floating point errors and having advanced formatting capabilities.
+    def initialize: (?seconds: ::Integer seconds, ?deciseconds: ::Integer deciseconds, ?centiseconds: ::Integer centiseconds, ?milliseconds: ::Integer milliseconds, ?microseconds: ::Integer microseconds, ?nanoseconds: ::Integer nanoseconds, ?picoseconds: ::Integer picoseconds, ?femtoseconds: ::Integer femtoseconds, ?attoseconds: ::Integer attoseconds, ?zeptoseconds: ::Integer zeptoseconds, ?yoctoseconds: ::Integer yoctoseconds) -> void
+
+    def precision: () -> untyped
+
+    def to_s: () -> nil
+
+    # Create a new Smalltime::Duration out of seconds. This method is provided as a drop-in replacement for
+    # ActiveSupport::Duration.build.
+    #
+    # @param seconds [Fixnum] the number of total seconds in the duration
+    # @return [Smalltime] the new smalltime duration
+    def build: (untyped seconds) -> untyped
+
+    # format returns a time like "HH:MM:SS". If precise is true, it returns a time like
+    # "HH:MM:SS.cc" instead.
+    #
+    # When sign is :always, the returned value always has a "+" or "-" in front of it.
+    # When sign is :never, the returned value never has a sign in front of it. When sign
+    # is :negatives, only negative values have a sign (default).
+    def format: (?precise: bool precise, ?sign: ::Symbol sign) -> ("-" | untyped)
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: smalltime
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Benjamin Carlsson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-05-15 00:00:00.000000000 Z
+dependencies: []
+description: |2
+      Smalltime is a Ruby duration library that focuses on providing a great experience
+      when working with small durations like hours, minutes, seconds, milliseconds,
+      nanoseconds, or smaller (down to yoctoseconds).
+
+      Smalltime does not perform any floating point calculations, so there is no risk of
+      floating point errors.
+email: ben@twos.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/smalltime.rb
+- lib/smalltime.rbs
+- lib/smalltime/configuration.rb
+- lib/smalltime/numeric.rb
+homepage: https://rubygems.org/gems/smalltime
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: Subsecond Ruby durations without floating point arithmetic
+test_files: []