WeekSauce 
WeekSauce is a simple class that functions as a days-of-the-week bitmask. Useful for things that repeat weekly, and/or can occur on one or more days of the week.
It was extracted from a Rails app, and is primarily intended to used as an ActiveRecord attribute serializer, but it should work fine outside of Rails too.
Installation
It's a gem, so:
gem install week_sauce
or, if you're using Bundler, put this in your Gemfile:
gem 'week_sauce'
The Basics
week = WeekSauce.new(16) # init with bitmask (optional)
week.blank? #=> false
week.one? #=> true
week.thursday? #=> true
week = WeekSauce.new # defaults to a zero-bitmask
week.blank? #=> true
# Mark the weekend
week.set(:saturday, :sunday)
from = Time.parse("2013-04-01") # A Monday
week.next_date(from) #=> Sat, 06 Apr 2013
week.dates_in(from..from + 1.week) => [Sat, 06 Apr 2013 , Sun, 07 Apr 2013]Usage with ActiveRecord
class Workout < ActiveRecord::Base
serialize :days, WeekSauce
end
workout = Workout.find_by_kind("Weights")
workout.days.inspect #=> "20: Tuesday, Thursday"
workout.days.set!(:tuesday, :thursday) # sets only those days
workout.saveThe underlying days database column can be either a string or integer type.
API
Individual days can be set and read using Fixnums, strings, symbols or Date/Time objects. Additionally, there are named methods for getting and setting each of the week's days:
time = Time.parse("2013-04-01") # A Monday
# These are all equivalent
week.monday = true
week[:monday] = true
week["monday"] = true # case-insensitive
week[1] = true
week["1"] = true
week[time] = true
week[time.to_date] = true
# And these are equivalent too
week.monday #=> true
week.monday? #=> true
week[:monday] #=> true
week["monday"] #=> true (again, case-insensitive)
week[1] #=> true
week["1"] #=> true
week[time] #=> true
week[time.to_date] #=> trueNote that similar to Date#wday, Sunday is 0, Monday is 1 and so forth.
Several days can be set or unset using the so-named methods:
# arguments can also be Fixnums or Date/Time objects
week.set(:monday, :wednesday) # set those days to true
week.unset(:monday, :wednesday) # set those days to falseThese also have "exclusive" versions:
week.set!(:monday, :wednesday) # sets *only* those days to true, all others to false
week.unset!(:monday, :wednesday) # sets *only* those days to false, all others to trueThere are also a few value-checking methods:
week.blank? # true if no days are set
week.one? # true if exactly 1 day is set
week.any? # true if at least 1 day is set
week.many? # true if at least 2 days are set
week.all? # true if all days are set
# The == comparison operator works with other WeekSauce objects and Fixnums
week == other_week #=> true if the bitmask values match
week == 123 #=> true if the bitmask value == 123And a couple of methods to find dates matching the week's bitmask:
week.dates_in(from..to) # find matching dates in a range of dates
week.next_date # finds next matching date from today
week.next_date(some_date) # finds next matching date from (and including) some_dateIn this example, some_date may be either a Date or a Time object. If it's the latter, it'll be converted using #to_date.
If ActiveSupport's time zone support is available, next_date with no argument will default to the time zone-aware Date.current instead of Date.today.
Lastly, a few utility methods:
week.to_i #=> the raw integer bitmask
week.to_a #=> array of the selected days' names, e.g. [:monday, :thursday]
week.to_hash #=> hash with day names as keys, and the day's boolean state as value
week.count #=> number of days set (0..7)
week.inspect #=> string describing the bitmask values and days, e.g. "3: Sunday, Monday"Odds and ends
The gem was extracted from a Rails 3.2 app, and requires Ruby 1.9.2 or higher. The requirement is undoubtedly overkill, but the specs currently use the 1.9+ hash syntax. It could be converted very easily though (feel free!).
The code has good test coverage (using RSpec), and is tested against a few 1.9 and 2.0 rubies using TravisCI.