knot-date-utils-rb

Date and time utilities for Ruby. Provides convenient helpers for date parsing, formatting, business day calculation, relative time display, and timezone handling. Includes a C extension for performance-critical date arithmetic.

Installation

Add to your Gemfile:

gem 'knot-date-utils-rb', '~> 1.0'

Or install directly:

gem install knot-date-utils-rb

Usage

require 'date_utils'

Parsing dates from various formats

DateUtils.parse('2023-11-15')             # => #<Date: 2023-11-15>
DateUtils.parse('15/11/2023', '%d/%m/%Y') # => #<Date: 2023-11-15>
DateUtils.parse('Nov 15, 2023')           # => #<Date: 2023-11-15>
DateUtils.parse('invalid', fallback: Date.today) # => today's date on failure

Formatting

DateUtils.format(Date.today, :short)      # => "15 Nov 2023"
DateUtils.format(Date.today, :long)       # => "Wednesday, 15 November 2023"
DateUtils.format(Date.today, '%Y/%m/%d')  # => "2023/11/15"

Business day calculation

date = Date.new(2023, 11, 15)  # Wednesday

DateUtils.add_business_days(date, 3)
# => #<Date: 2023-11-20>  (skips weekend)

DateUtils.business_days_between(Date.new(2023, 11, 1), Date.new(2023, 11, 15))
# => 11

DateUtils.business_day?(Date.new(2023, 11, 11))  # Saturday
# => false

# With custom holidays
holidays = [Date.new(2023, 12, 25), Date.new(2024, 1, 1)]
DateUtils.add_business_days(Date.new(2023, 12, 22), 2, holidays: holidays)
# => #<Date: 2023-12-27>

Relative time

DateUtils.relative(Time.now - 45)         # => "45 seconds ago"
DateUtils.relative(Time.now - 3600)       # => "1 hour ago"
DateUtils.relative(Date.today - 3)        # => "3 days ago"
DateUtils.relative(Date.today + 7)        # => "in 7 days"

Timezone helpers

DateUtils::TZ.convert(Time.now, from: 'UTC', to: 'Europe/Paris')
# => 2023-11-15 11:22:01 +0100

DateUtils::TZ.in_zone('America/New_York') do
  DateUtils.format(Time.now, :long)
end
# => "Wednesday, 15 November 2023"  (in NY local time)

Date ranges

range = DateUtils::Range.new(Date.new(2023, 1, 1), Date.new(2023, 12, 31))

range.include?(Date.new(2023, 6, 15))  # => true
range.days                              # => 364
range.months                            # => 11
range.each_month.map { |d| d.strftime('%B') }
# => ["January", "February", ..., "December"]

Requirements

• Ruby >= 2.7.0
• A C compiler (for the native extension — falls back to pure Ruby if unavailable)

License

MIT License. See LICENSE for details.