philiprehberger-duration

Immutable Duration value object with parsing, arithmetic, and formatting

Requirements

Ruby >= 3.1

Installation

Add to your Gemfile:

gem "philiprehberger-duration"

Or install directly:

gem install philiprehberger-duration

Usage

require "philiprehberger/duration"

d = Philiprehberger::Duration.parse("2h 30m")
d.to_seconds   # => 9000.0
d.to_human     # => "2 hours, 30 minutes"
d.to_iso8601   # => "PT2H30M"

Parsing

Duration = Philiprehberger::Duration

Duration.parse("2 weeks 3 days")  # human string
Duration.parse("1 day 3 hours")   # human string
Duration.parse("PT2H30M")         # ISO 8601
Duration.parse("P2W")             # ISO 8601 weeks
Duration.parse(3600)              # numeric seconds

Use Duration.parse? for a non-raising variant that returns nil on invalid input:

Duration.parse?("2h 30m")  # => Duration("2 hours, 30 minutes")
Duration.parse?("xyz")     # => nil
Duration.parse?("")        # => nil
Duration.parse?(nil)       # => nil

Arithmetic

d1 = Duration.parse("2h")
d2 = Duration.parse("30m")

d1 + d2   # => Duration("2 hours, 30 minutes")
d1 - d2   # => Duration("1 hour, 30 minutes")
d2 * 3    # => Duration("1 hour, 30 minutes")
d1 / 2    # => Duration("1 hour")

Comparison

Duration.parse("2h") > Duration.parse("1h")   # => true
Duration.parse("60m") == Duration.parse("1h")  # => true

Short Format

Duration.parse("2h 30m").to_short      # => "2h 30m"
Duration.from_hash(weeks: 1).to_short  # => "1w"
Duration.zero.to_short                  # => "0s"

Between Two Times

Duration.between(start_time, end_time).to_human  # => "3 hours, 15 minutes"

Time Arithmetic

d = Duration.parse("2h 30m")

d.from_now          # => Time.now + 9000 seconds
d.ago               # => Time.now - 9000 seconds
d.since(start_time) # => start_time + 9000 seconds
d.before(deadline)  # => deadline - 9000 seconds

Component Accessors

d = Philiprehberger::Duration.parse("2 weeks 1 day 2 hours 30 minutes 45 seconds")
d.weeks    # => 2
d.days     # => 1
d.hours    # => 2
d.minutes  # => 30
d.seconds  # => 45
d.to_hash  # => { weeks: 2, days: 1, hours: 2, minutes: 30, seconds: 45 }

Rounding

d = Philiprehberger::Duration.parse("1h 45m")
d.round(:hour).to_human  # => "2 hours"

Total Conversion

d = Philiprehberger::Duration.parse("2h 30m")
d.to_minutes  # => 150.0
d.to_hours    # => 2.5
d.to_days     # => 0.104166...
d.to_weeks    # => 0.014880...
d.to_i        # => 9000
d.to_f        # => 9000.0

Constructing from Components

d = Philiprehberger::Duration.from_hash(weeks: 1, days: 2, hours: 3)
d.to_human  # => "1 week, 2 days, 3 hours"

Custom Formatting

d = Philiprehberger::Duration.parse("1 day 2h 3m 4s")
d.format("%D days %T")  # => "1 days 02:03:04"
d.format("%H:%M:%S")    # => "02:03:04"
Philiprehberger::Duration.zero.zero?  # => true

API

Method	Description
`Duration.parse(input)`	Parse human string, ISO 8601, or numeric seconds
`Duration.parse?(input)`	Non-raising variant of `parse` — returns `nil` on `nil`, empty, or invalid input
`Duration.from_hash(**components)`	Construct from named components (weeks, days, hours, minutes, seconds)
`Duration.between(time_a, time_b)`	Duration between two Time objects
`Duration.zero`	Zero-length duration
`#zero?`	Whether the duration is zero
`#format(pattern)`	strftime-style formatter (`%W %D %H %M %S %T %s %%`)
`#to_seconds`	Total seconds as float
`#to_minutes`	Total minutes as float
`#to_hours`	Total hours as float
`#to_days`	Total days as float
`#to_weeks`	Total weeks as float
`#to_i`	Total seconds as integer
`#to_f`	Total seconds as float
`#to_human`	Human-readable string
`#to_iso8601`	ISO 8601 formatted string
`#weeks`	Extracted week component
`#days`	Extracted day component (0-6)
`#hours`	Extracted hour component (0-23)
`#minutes`	Extracted minute component (0-59)
`#seconds`	Extracted second component (0-59)
`#to_hash`	Components as `{ weeks:, days:, hours:, minutes:, seconds: }`
`#from_now`	`Time.now + to_seconds`
`#ago`	`Time.now - to_seconds`
`#since(time)`	`time + to_seconds`
`#before(time)`	`time - to_seconds`
`#round(unit)`	Round to nearest `:week`, `:day`, `:hour`, `:minute`, or `:second`
`#to_short`	Compact format like "2h 30m" or "1w"
`#+`, `#-`, `#*`, `#/`	Arithmetic operations
`<`, `>`, `==`, `<=>`	Comparison (via Comparable)

Development

bundle install
bundle exec rspec
bundle exec rubocop

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT