month

Ruby gem for working with calendar months.

Install

Using Bundler:

$ bundle add month

Using RubyGems:

$ gem install month

Feature tour

You can create a new Month object with a year and month number:

Month.new(2014, 1)  # January 2014

Alternatively you can use the Month method to cast various date/time objects to Month objects:

Month(Date.new(2014, 1, 31))  # January 2014

Month(Time.at(1234567890))  # February 2009

The method will idempotently return Month objects as-is:

Month(Month.new(2014, 1))  # January 2014, same object

Use the Month.parse method to parse a YYYY-MM formatted string:

Month.parse('2014-01')  # January 2014

The #year attribute will return the year of the month:

Month.new(2014, 1).year  # 2014

The #number attribute will return the number of the month:

Month.new(2014, 1).number  # 1

The #name method will return the name of the month as a symbol:

Month.new(2014, 1).name  # :January

Alternatively you can use predicate methods to test for a given month:

Month.new(2014, 1).january?  # true

Month.new(2014, 2).january?  # false

The #to_s method will return a YYYY-MM formatted string representation of the month:

Month.new(2014, 1).to_s  # "2014-01"

You can add/subtract an integer number of months:

Month.new(2014, 1) + 1  # February 2014

Month.new(2014, 1) - 1  # December 2013

The #step method iterates between 2 months, similar to Date#step:

Month.new(2014, 1).step(Month.new(2014, 12)) do |month|
  ...
end

The #include? method can be used to test if the month includes a date:

Month.new(2014, 1).include?(Date.new(2014, 1, 31))  # true

The #dates method returns a range containing the dates in the month:

Month.new(2014, 1).dates  # Range containing 31 Date objects

The #length method returns the number of days in the month:

Month.new(2014, 1).length  # 31

Month objects can be used in case expressions to match date/time objects:

case datetime
when month
  puts "Date/time is in #{month}"
end

Month objects can be used as hash keys for counting, grouping etc:

totals = {
  Month.new(2014, 1) => 0
}

Month objects can be used in ranges:

months = Month.new(2014, 1) .. Month.new(2014, 12)

Month objects are comparable:

Month.new(2014, 1) < Month.new(2014, 2)  # true

Month objects are ractor-safe.

Bonus extras

The Month::Methods module provides methods for constructing Month objects and Date objects in a manner that closely resembles written english:

include Month::Methods

month = January 2014

date = January 15, 2014

It is not included globally by default; you can either include it within your own modules/classes or globally within your own application/script.

Thanks

This current implementation is an accidental rewrite of an older library/gem with the same name/purpose (fhwang / month). Thanks to Francis for kindly allowing me to re-use the same gem name.