week_sauce 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Daniel Høier Øhrgaard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,89 @@
+# 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 or one or more days
+of the week.
+
+Extracted from a Rails app, it's intended to be used an ActiveRecord
+attribute serializer, but it should work fine outside of Rails.
+
+## Basic usage
+
+    week = WeekSauce.new(16) # set a specific bitmask
+    week.blank?     #=> false
+    week.one?       #=> true
+    week.thursday?  #=> true
+    
+    week = WeekSauce.new     # defaults to a zero-bitmask
+    week.blank? #=> true
+    
+    # Mark off the weekend
+    week.set(:saturday, :sunday)
+    
+    from = Time.parse("2013-04-01") # A Monday
+    week.next_date(from)            #=> "2013-04-06" (a Saturday)
+    
+    week.dates_in(from..from + 1.week) => ["2013-04-06", "2013-04-07"]
+
+## Rails usage
+
+    class Workout < ActiveRecord::Base
+      serialize :days, WeekSauce
+    end
+    
+    workout = Workout.find_by_kind("Weights")
+    workout.days.to_s #=> "Monday, Wednesday"
+    workout.days.set!(:tuesday, :thursday) # sets only those days
+    workout.save
+
+## API
+
+Individual days can be set and read using Fixnums, symbols or Date/Time
+objects. Additionally, there are named methods for getting and setting
+each of the week's days:
+
+    # These are all equivalent
+    week.monday   = true
+    week[:monday] = true
+    week[1]       = true
+    
+    time = Time.parse("2013-04-01") # A Monday
+    week[time] = true
+    week[time.to_date] = true
+    
+    # And these are equivalent too
+    week.monday   #=> true
+    week.monday?  #=> true
+    week[:monday] #=> true
+    week[1]       #=> true
+    week[time]    #=> true
+
+_Note that similar to `Date#wday`, Sunday is `0`, Monday is `1` and so forth._
+
+There 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
+
+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 false
+
+These also have "exclusive" versions
+
+    week.set!(:monday, :wednesday)   # sets *only* those days to true, all others to false
+    week.unset!(:monday, :wednesday) # set *only* those days to false, all others to true
+
+Lastly, dates matching the week's bitmask can be calculated
+
+    week.dates_in(from..to)   # find matching dates in a range
+    
+    week.next_date            # finds next matching date from today
+    week.next_date(some_date) # finds next matching date from (and including) some_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`.

data/lib/week_sauce.rb

@@ -0,0 +1,277 @@
+require 'date'
+
+# WeekSauce is a simple class that functions as a days-of-the-week bitmask.
+# Useful for things that repeat weekly, and/or can occur or one or more days
+# of the week.
+# 
+# Extracted from a Rails app, it's intended to be used an ActiveRecord
+# attribute serializer, but it should work fine outside of Rails.
+# 
+# == Basic usage
+# 
+#     week = WeekSauce.new(16) # set a specific bitmask
+#     week.blank?     #=> false
+#     week.one?       #=> true
+#     week.thursday?  #=> true
+#     
+#     week = WeekSauce.new     # defaults to a zero-bitmask
+#     week.blank? #=> true
+#     
+#     # Mark off the weekend
+#     week.set(:saturday, :sunday)
+#     
+#     from = Time.parse("2013-04-01") # A Monday
+#     week.next_date(from)            #=> "2013-04-06" (a Saturday)
+#     
+#     week.dates_in(from..from + 1.week) => ["2013-04-06", "2013-04-07"]
+# 
+# == Rails usage
+# 
+#     class Workout < ActiveRecord::Base
+#       serialize :days, WeekSauce
+#     end
+#     
+#     workout = Workout.find_by_kind("Weights")
+#     workout.days.to_s #=> "Monday, Wednesday"
+#     workout.days.set!(:tuesday, :thursday) # sets only those days
+#     workout.save
+# 
+class WeekSauce
+  MAX_VALUE = 2**7 - 1
+  DAY_NAMES = %w(sunday monday tuesday wednesday thursday friday saturday).map(&:to_sym).freeze
+  DAY_BITS  = Hash[ DAY_NAMES.zip(Array.new(7) { |i| 2**i }) ].freeze
+  
+  class << self
+    # ActiveRecord attribute serialization support
+    # 
+    # Create a WeekSauce instance from a stringified integer
+    # bitmask. The value will be clamped (see #new)
+    def load(string)
+      self.new(string.to_i)
+    rescue NoMethodError => err
+      self.new
+    end
+    
+    # ActiveRecord attribute serialization support
+    # 
+    # Dump a WeekSauce instance to a stringified instance bitmask
+    def dump(instance)
+      if instance.is_a?(self)
+        instance.to_i.to_s
+      else
+        "0"
+      end
+    end
+  end
+  
+  # Init a new WeekSauce instance. If +value+ is omitted, the new
+  # instance will default to a bitmask of zero, i.e. no days set.
+  # 
+  # If a +value+ argument is given, +to_i+ will be called on it,
+  # and the resulting integer will be clamped to 0..127
+  def initialize(value = nil)
+    @value = [[0, value.to_i].max, MAX_VALUE].min
+  end
+  
+  # Compare this instance against another instance, or a Fixnum
+  def ==(arg)
+    case arg
+    when self.class, Fixnum
+      to_i == arg.to_i
+    else
+      false
+    end
+  end
+  
+  # Returns +true+ if no days are set, +false+ otherwise.
+  # Opposite of #any?
+  def blank?
+    @value == 0
+  end
+  
+  # Returns +true+ if all days are set, +false+ otherwise
+  def all?
+    @value == MAX_VALUE
+  end
+  
+  # Returns +true+ if any of the week's 7 days are set, +false+ otherwise.
+  # Opposite of #blank?
+  def any?
+    !blank?
+  end
+  
+  # Returns +true+ if exactly one day is set, +false+ otherwise
+  def one?
+    any? && @value & (@value - 1) == 0
+  end
+  
+  # Returns +true+ if two or days are set, +false+ otherwise
+  def many?
+    any? && !one?
+  end
+  
+  DAY_BITS.each do |day, bit|
+    define_method(day) do
+      get_bit bit
+    end
+    alias_method :"#{day.to_s}?", day
+    
+    define_method("#{day.to_s}=") do |bool|
+      set_bit bit, bool
+    end
+  end
+  
+  # Returns +true+ if the given weekday is set, +false+ if it isn't,
+  # and +nil+ if the argument was invalid.
+  # 
+  # The +wday+ argument can be a Fixnum from 0 (Sunday) to 6 (Saturday),
+  # a symbol specifying the day's name (e.g. +:tuesday+, +:friday+), or
+  # a Date or Time instance
+  def [](wday)
+    get_bit coerce_to_bit(wday)
+  end
+  
+  # Set or unset the given day. See #[] for possible +wday+ values.
+  # Invalid +wday+ values are ignored.
+  def []=(wday, bool)
+    set_bit coerce_to_bit(wday), bool
+  end
+  
+  # Set the given days. Like #[], arguments can be symbols, Fixnums,
+  # or Date/Time objects
+  def set(*days)
+    days.each do |day|
+      self[day] = true
+    end
+  end
+  
+  # Exclusive version of #set - clears the week, and sets only
+  # the days passed. Returns +self+
+  def set!(*days)
+    blank!
+    set(*days)
+    self
+  end
+  
+  # Unset the given days. Like #[], arguments can be symbols,
+  # Fixnums, or Date/Time objects
+  def unset(*days)
+    days.each do |day|
+      self[day] = false
+    end
+  end
+  
+  # Exclusive version of #unset - sets all days to true and
+  # then unsets days passed. Returns +self+
+  def unset!(*days)
+    all!
+    unset(*days)
+    self
+  end
+  
+  # Set all days to +false+. Returns +self+
+  def blank!
+    @value = 0
+    self
+  end
+  
+  # Set all days to +true+. Returns +self+
+  def all!
+    @value = MAX_VALUE
+    self
+  end
+  
+  # Returns the raw bitmask integer
+  def to_i
+    @value
+  end
+  
+  # Returns an array of "set" day names as symbols
+  def to_a
+    DAY_NAMES.select { |day| self[day] }
+  end
+  
+  # Returns a string with the bitmask value and a list of
+  # "set" days, or a simple message if all/no days are set
+  def inspect
+    if blank?
+      "0: No days set"
+    elsif all?
+      "#{MAX_VALUE}: All days set"
+    else
+      list = to_a.map { |day| day.to_s.sub(/./, &:upcase) }.join(", ")
+      "#{@value}: #{list}"
+    end
+  end
+  
+  # Returns a hash where the keys are the week's 7 days
+  # as symbols, and the values are booleans
+  def to_hash
+    Hash[ DAY_NAMES.map { |day| [day, self[day]] } ]
+  end
+  
+  # Return the next date matching the bitmask, or +nil+ if the
+  # week is blank.
+  # 
+  # If no +from_date+ argument is given, it'll default to
+  # <tt>Date.current</tt> if ActiveSupport is available,
+  # or <tt>Date.today</tt> otherwise.
+  # 
+  # If +from_date+ is given, #next_date will return the first
+  # matching date from - and including - +from_date+
+  def next_date(from_date = nil)
+    return nil if blank?
+    from_date ||= if Date.respond_to?(:current)
+      Date.current
+    else
+      Date.today
+    end
+    from_date = from_date.to_date
+    until self[from_date.wday]
+      from_date = from_date.succ
+    end
+    from_date.dup
+  end
+  
+  # Return all dates in the given +date_range+ that match the
+  # bitmask. If the week's blank, an empty array will be
+  # returned.
+  # 
+  # Note that the range is converted to an array, which
+  # is then filtered, so if the range is "backwards" (high to
+  # low) an empty array will be returned
+  def dates_in(date_range)
+    return [] if blank?
+    date_range.to_a.select { |date| self[date.wday] }
+  end
+  
+  protected
+  
+    def get_bit(bit) #:nodoc:
+      if DAY_BITS.values.include?(bit)
+        @value & bit > 0
+      end
+    end
+    
+    def set_bit(bit, set) #:nodoc:
+      if DAY_BITS.values.include?(bit)
+        if set
+          @value = @value | bit
+        else
+          @value = @value & (MAX_VALUE ^ bit)
+        end
+      end
+    end
+    
+    def coerce_to_bit(wday) #:nodoc:
+      case wday
+      when Symbol
+        DAY_BITS[wday]
+      when Fixnum
+        (0..6).include?(wday) ? 2**wday : nil
+      when Date, Time
+        2**wday.wday
+      end
+    end
+  
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: week_sauce
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Daniel Høier Øhrgaard
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: tzinfo
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.3.29
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.3.29
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+description: A simple gem to serialize selected days of the week as a bitmask
+email: daniel@stimulacrum.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/week_sauce.rb
+- README.md
+- MIT-LICENSE
+homepage: https://github.com/Flambino/week_sauce
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Day-of-week bitmask
+test_files: []