zero_fill 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 230c97d7f63d983b8a950e92e3fc5fb5d5af681b
+  data.tar.gz: 8dbcb7cdf4fb7353ab9679537c96b00b4cd00e3b
+SHA512:
+  metadata.gz: f84736c91adeea9ae4f2382409355e8d21c5012aa1bbbc4d9ef4e8c761e960f832b7c525989a045169ccb1be0a63c96e487df49ba632bc47490b48caf35542fb
+  data.tar.gz: 17e3731d76e0c888229ab4585641212a38c436150f8e7113f1016645b1100d85070e03ba1a9eb726d6367aaa1881b9d61f594003bfe8d39498cd9f5b3267cfe8

data/.gitignore

@@ -0,0 +1,3 @@
+*.gem
+.bundle
+tmp

data/Gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+group :test do
+  gem "rake"
+  gem "rspec", "~>2.14.1"
+end

data/Gemfile.lock

@@ -0,0 +1,20 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.2.5)
+    rake (10.1.0)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.4)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake
+  rspec (~> 2.14.1)

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 MOBI Wireless Management
+
+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,121 @@
+ZeroFill
+=====
+
+ZeroFill makes it easy to add any missing dates to a series of dates. Popular use cases include calendars and charts with no data for some dates.
+
+Compatible with Ruby 1.9.3 and 2.0.0 (and has no dependencies!). Untested in 1.8.7 but should work.
+
+Example
+------
+
+For instance, say you want to output some info for these days:
+
+```
+July 29:   10
+July 31:   7
+August 2:  3
+```
+Wait - what about July 30 and August 1, the days missing from that list? ZeroFill can help!
+
+```
+July 29:   10
+July 30:   0
+July 31:   7
+August 1:  0
+August 2:  3
+```
+Voila! You have a series of 5 dates with zeros added for the missing dates.
+
+Usage
+====
+
+__Simply pass a series (array or hash) into__ `ZeroFill.by_date()`
+
+1. Pass a __hash__ of pairs of Dates (or DateTimes) and content (a string, integer, or whatever!):
+```ruby
+myDates = {
+  Date.parse("2013-07-29") => 10, #Monday
+  Date.parse("2013-07-31") => 7,  #Wednesday
+  Date.parse("2013-08-02") => 3   #Friday
+}
+ZeroFill.by_date(myDates)
+```
+
+2. Or, pass an __array of hashes__. Each hash includes a Date or DateTime object and the value. _Note: the name of the keys in the hash are irrelevant as long as they are consistent throughout the array. ZeroFill automatically detects which key represents a Date/DateTime object_
+```ruby
+myDates = [
+  { date: Date.parse("2013-07-31"), content: "My Birthday" },
+  { date: Date.parse("2013-07-14"), content: "Movie Night" }
+]
+ZeroFill.by_date(myDates)
+```
+
+Get fancy with options:
+--------------------------
+
+1. Return all dates for any __months__ represented in your date series:
+```ruby
+myDates = [
+  { date: Date.parse("2013-07-31"), content: "My Birthday" },
+  { date: Date.parse("2013-08-13"), content: "First day of class" }
+]
+ZeroFill.by_date(myDates, includes: :month)
+=> All dates in July & August
+```
+
+1. Return all dates for any __weeks__ represented in your date series:
+```ruby
+myDates = [
+  { date: Date.parse("2013-07-31"), content: "My Birthday" }
+]
+ZeroFill.by_date(myDates, includes: :week)
+=> All dates in the week of Saturday, July 28 to Sunday, August 3
+```
+
+1. __Sort dates__ from latest to earliest (Default is ascending - earliest to latest)
+```ruby
+ZeroFill.by_date(myDates, order: :descending)
+```
+
+1. __Change the default value__ of Zero Filled dates (Default is 0)
+```ruby
+ZeroFill.by_date(myDates, default_value: "Nothing Found!")
+=> All missing dates' values are populated with "Nothing Found"
+```
+
+1. __Specify the start date__ of returned dates. For instance, to return dates starting with July 10:
+```ruby
+ZeroFill.by_date(myDates, start_at: Date.parse("2013-07-10"))
+=> Returns dates from July 10 until the latest date in your series.
+```
+
+1. __Specify the end date__ of returned dates. For instance, to return dates ending with August 7:
+```ruby
+ZeroFill.by_date(myDates, end_at: Date.parse("2013-08-07"))
+=> Returns dates from earliest date in your series through August 7
+```
+
+TODOs
+====
+
+* by_hour option - allow ZeroFill of hours. Include full-day support (like month option for by_date)
+* by_month option - ZeroFill by month including support for full-year
+* Support passing date strings instead of date objects
+* Date padding option: Allow padding of the results by X days (i.e. show 3 days after the end of the series)
+
+Contributions
+=====
+Knock out TODOs, add support for more input types, more formatting options, etc.
+
+1. Fork the repo
+1. Create a branch with a thoughtful name
+1. Hack away
+1. Add tests
+1. Make sure the tests pass by running `rake`
+1. Document any new options in the README
+1. Squash your commits into logical groups
+1. Submit a pull request and we'll see what happens!
+
+Credits
+=====
+Copyright (c) 2013, developed and maintained by [MOBI Wireless Management](http://www.mobiwm.com/), and is released under the open MIT License. See the LICENSE file in this repository for details.

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec

data/lib/array_series.rb

@@ -0,0 +1,53 @@
+class ZeroFill::ArraySeries < ZeroFill
+
+private #######################################################################
+
+  def initialize(series, options={})
+    @new_series = []
+    setup(series, options)
+  end
+
+  def validate_data_structure
+    arr = @series.sample
+    raise TypeError, "Array elements must be hashes" unless arr.is_a? Hash
+    raise TypeError, "Array elements must be hashes with two key/value pairs (a date and metadata)" unless arr.length == 2
+    @date_key, @info_key = if arr.values.first.kind_of?(Date)
+      [arr.keys.first, arr.keys.last]
+    elsif arr.values.kind_of?(Date)
+      [arr.keys.last, arr.keys.first]
+    else
+      raise TypeError, "No date object found for #{arr.inspect}"
+    end
+  end
+
+  def set_new_series_date_value!(current_date)
+    matching_date = between_input_series?(current_date) ? date_values.detect{|c| c[@date_key] == current_date} : nil
+    @new_series << {
+      @date_key => current_date,
+      @info_key => (matching_date ? matching_date[@info_key] : @options[:default_value])
+    }
+  end
+
+  def sort_series!
+    @series.sort!{|a,b| a[@date_key] <=> b[@date_key] }
+  end
+
+  def reverse_series!
+    @new_series.reverse!
+  end
+
+  def first_date
+    @first_date ||= @series.empty? ? nil : @series.first[@date_key]
+  end
+
+  def last_date
+    @last_date ||= @series.empty? ? nil : @series.last[@date_key]
+  end
+
+  def date_values
+    @date_values ||= @series.each do |day|
+      day[@date_key] = day[@date_key].to_date
+    end
+  end
+
+end

data/lib/hash_series.rb

@@ -0,0 +1,36 @@
+class ZeroFill::HashSeries < ZeroFill
+
+private #######################################################################
+
+  def initialize(series, options={})
+    @new_series = {}
+    setup(series, options)
+  end
+
+  def validate_data_structure
+    first_key = @series.keys.first
+    raise TypeError, "Hash keys must be a Date or DateTime" unless first_key.kind_of?(Date)
+  end
+
+  def set_new_series_date_value!(current_date)
+    matching_date = @series[current_date]
+    @new_series[current_date] = matching_date || @options[:default_value]
+  end
+
+  def sort_series!
+    @series = Hash[@series.sort{|a,b| a[0] <=> b[0] }]
+  end
+
+  def reverse_series!
+    @new_series = Hash[@new_series.to_a.reverse]
+  end
+
+  def first_date
+    @first_date ||= @series.empty? ? nil : @series.keys.first
+  end
+
+  def last_date
+    @last_date ||= @series.empty? ? nil : @series.keys.last
+  end
+
+end

data/lib/zero_fill.rb

@@ -0,0 +1,95 @@
+require "date"
+class ZeroFill
+
+  # by_date is a factory
+  def self.by_date(series, options={})
+    return series if series.empty? && !date_options_present?(options)
+
+    if series.is_a? Hash
+      zf = ZeroFill::HashSeries.new(series, options)
+    elsif series.is_a? Array
+      zf = ZeroFill::ArraySeries.new(series, options)
+    else
+      raise TypeError, "Date series must be a hash or array"
+    end
+    zf.series_by_date
+  end
+
+  def series_by_date
+    populate_new_series
+    reverse_series! if @options[:order].to_sym == :descending
+    @new_series
+  end
+
+private #######################################################################
+
+  def initialize(series, options={})
+    raise NotImplementedError, "Use the ZeroFill.by_date factory"
+  end
+
+  def setup(series, options)
+    @series = series
+    unless @series.empty?
+      validate_data_structure
+      sort_series!
+    end
+    validate_date_options(options)
+
+    @options = {
+      order: :ascending,
+      start_at: first_date,
+      end_at: last_date,
+      default_value: 0
+    }.merge(options)
+
+    set_range_series if @options[:includes]
+  end
+
+  def between_input_series?(current_date)
+    @series.empty? || (current_date >= first_date && current_date <= last_date)
+  end
+
+  def set_range_series
+    include_full_months_for_date_range if @options[:includes].to_sym == :month
+    include_full_weeks_for_date_range if @options[:includes].to_sym == :week
+  end
+
+  def include_full_months_for_date_range
+    @options[:start_at] = Date.civil(first_date.year, first_date.month, 1)
+    @options[:end_at] = Date.civil(last_date.year, last_date.month, -1)    # -1 gives us the last day of the month
+  end
+
+  def include_full_weeks_for_date_range
+    # Wednesday 2013-04-19 is the 3rd day of the week
+    # So, 2013-04-19 minus 3 (days) returns the previous Sunday
+    day_of_week = first_date.wday
+    @options[:start_at] = first_date - day_of_week
+
+    # Thursday, 2013-04-20 is the 4th day of the week
+    # There are 6 days in the week (zero indexed). So, 6 minus 4 = 2 days until Saturday. So add 2 to the date to get the next Saturday
+    day_of_week = last_date.wday
+    @options[:end_at] = last_date + (6 - day_of_week)
+  end
+
+  def populate_new_series
+    (@options[:start_at].to_date..@options[:end_at].to_date).each do |current_date|
+      set_new_series_date_value!(current_date)
+    end
+  end
+
+  def date_options_present?(options)
+    ZeroFill.date_options_present?(options)
+  end
+
+  def self.date_options_present?(options)
+    !options[:start_at].nil? && !options[:end_at].nil?
+  end
+
+  def validate_date_options(options)
+    raise ArgumentError, "Start At Date cannot be after End At Date" if date_options_present?(options) && (options[:start_at] > options[:end_at])
+  end
+
+end
+
+require "hash_series"
+require "array_series"

data/spec/integration_spec.rb

@@ -0,0 +1,106 @@
+require 'spec_helper'
+
+describe "Arguments" do
+  it "series can accept an array of hashes" do
+    ZeroFill.by_date(series_array_of_hashes).count.should == 6
+  end
+
+  it "series can accept a hash of key/value pairs" do
+    ZeroFill.by_date(series_hash).count.should == 6
+  end
+
+  it "should return an empty hash/array if it receives an empty series" do
+    ZeroFill.by_date({}).should == {}
+    ZeroFill.by_date([]).should == []
+    ZeroFill.by_date([], :start_at => Date.today).should == []
+    ZeroFill.by_date([], :end_at => Date.today).should == []
+  end
+
+  it "should reject invalid series input" do
+    expect { ZeroFill.by_date([["herp"]]) }.to raise_exception TypeError
+    expect { ZeroFill.by_date([{:herp => "derp"}]) }.to raise_exception TypeError
+  end
+
+end
+
+describe "Results" do
+  it "should properly sort dates ascending (default behavior)" do
+    ZeroFill.by_date(series_array_of_hashes).map{|hash| hash[:date].to_s }.should == [
+      "2013-07-27", "2013-07-28", "2013-07-29", "2013-07-30", "2013-07-31", "2013-08-01"
+    ]
+    ZeroFill.by_date(series_hash).keys.map(&:to_s).should == [
+      "2013-07-27", "2013-07-28", "2013-07-29", "2013-07-30", "2013-07-31", "2013-08-01"
+    ]
+  end
+
+  it "should return values for each date" do
+    series = ZeroFill.by_date(series_hash)
+    series[Date.parse("2013-07-27")].should == 10
+    series[Date.parse("2013-07-28")].should == 0
+    series[Date.parse("2013-08-01")].should == 7
+
+    series = ZeroFill.by_date(series_array_of_hashes_string_values)
+    series.first[:comida].should == "paella"
+    series.last[:comida].should == "tamale"
+    series[1][:comida].should == 0
+  end
+end
+
+describe "Options" do
+  it "should return calendar months for included dates" do
+    month_series = ZeroFill.by_date(series_array_of_hashes, includes: :month)
+    month_series.count.should == 62
+    month_series.first[:date].to_s.should == "2013-07-01"
+    month_series.last[:date].to_s.should == "2013-08-31"
+  end
+
+  it "should return calendar weeks for included dates" do
+    week_series = ZeroFill.by_date(series_array_of_hashes, includes: :week)
+    week_series.count.should == 14
+    week_series.first[:date].to_s.should == "2013-07-21"
+    week_series.last[:date].to_s.should == "2013-08-03"
+  end
+
+
+  it "should allow missing dates to have a custom default value" do
+    series = ZeroFill.by_date(series_array_of_hashes_string_values, default_value: "order pizza")
+    series[1][:comida].should == "order pizza"
+  end
+
+  it "should create dates starting with the start_at date" do
+    start_date = Date.parse("2013-07-26")
+    array_series = ZeroFill.by_date(series_array_of_hashes, start_at: start_date)
+    array_series.count.should == 7
+    array_series.first[:date].should == start_date
+
+    hash_series = ZeroFill.by_date(series_hash, start_at: start_date)
+    hash_series.count.should == 7
+    hash_series.keys.first.should == start_date
+  end
+
+  it "should create dates through the end_at date" do
+    end_date = Date.parse("2013-08-10")
+
+    array_series = ZeroFill.by_date(series_array_of_hashes, end_at: end_date)
+    array_series.count.should == 15
+    array_series.last[:date].to_s.should == end_date.to_s
+
+    hash_series = ZeroFill.by_date(series_hash, end_at: end_date)
+    hash_series.count.should == 15
+    hash_series.keys.last.to_s.should == end_date.to_s
+  end
+
+  it "should accept a start_at and end_at date with an empty series" do
+    ZeroFill.by_date([], start_at: Date.parse("2013-07-01"), end_at: Date.parse("2013-07-30")).count.should == 30
+    ZeroFill.by_date({}, start_at: Date.parse("2013-07-01"), end_at: Date.parse("2013-07-30")).count.should == 30
+  end
+
+  it "should be able to sort series dates descending" do
+    ZeroFill.by_date(series_array_of_hashes, order: :descending).map{|hash| hash[:date].to_s }.should == [
+      "2013-08-01", "2013-07-31", "2013-07-30", "2013-07-29", "2013-07-28", "2013-07-27"
+    ]
+    ZeroFill.by_date(series_hash, order: :descending).keys.map{|date| date.to_s }.should == [
+      "2013-08-01", "2013-07-31", "2013-07-30", "2013-07-29", "2013-07-28", "2013-07-27"
+    ]
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,27 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'zero_fill'
+
+def series_array_of_hashes
+  @series_array_of_hashes ||= [
+    { date: Date.parse("2013-07-27"), count: 10 },
+    { date: Date.parse("2013-08-01"), count: 7 },
+    { date: Date.parse("2013-07-30"), count: 3 }
+  ]
+end
+
+def series_array_of_hashes_string_values
+  @series_array_of_hashes ||= [
+    { dia: Date.parse("2013-07-27"), comida: "paella" },
+    { dia: Date.parse("2013-08-01"), comida: "tamale" },
+    { dia: Date.parse("2013-07-30"), comida: "fajita" }
+  ]
+end
+
+def series_hash
+  @date_list_hash ||= {
+    Date.parse("2013-07-27") => 10,
+    Date.parse("2013-08-01") => 7,
+    Date.parse("2013-07-30") => 3
+  }
+end

data/zero_fill.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+Gem::Specification.new do |spec|
+  spec.name         = 'zero_fill'
+  spec.version      = '0.2.0'
+  spec.authors      = ['MOBI Wireless Management', 'Steve Hodges']
+  spec.email        = 'gems@mobiwm.com'
+  spec.homepage     = 'https://github.com/mobi/zerofill'
+  spec.summary      = 'Adds missing dates in a series of dates'
+  spec.description  = 'Add missing dates from a date series, such as days in a month.'
+  spec.license      = 'MIT'
+  spec.required_ruby_version = '>= 1.9.3'
+
+  spec.files        = `git ls-files`.split("\n")
+  spec.test_files   = `git ls-files -- {spec}/*`.split("\n")
+
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec', '~>2.14.1'
+  spec.require_paths = ['lib']
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: zero_fill
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- MOBI Wireless Management
+- Steve Hodges
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-01-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.14.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.14.1
+description: Add missing dates from a date series, such as days in a month.
+email: gems@mobiwm.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- lib/array_series.rb
+- lib/hash_series.rb
+- lib/zero_fill.rb
+- spec/integration_spec.rb
+- spec/spec_helper.rb
+- zero_fill.gemspec
+homepage: https://github.com/mobi/zerofill
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.1.9
+signing_key: 
+specification_version: 4
+summary: Adds missing dates in a series of dates
+test_files: []