availability

(easily and quickly calculate schedule availability)

Build Status Gem Version read the docs

This library uses modular arithmetic and residue classes to calculate schedule availability for dates. Time ranges within a date are handled differently. The goal is to create an easy-to-use API for schedule availability that is very fast and lightweight that is also easy and lightweight to persist in a database.

Shout out to @dpmccabe for his original article and code.

gem install availability

Creating Availability instances is pretty simple. There are 5 variants of availabilities: Availability::Once, Availability::Daily, Availability::Weekly, Availability::Monthly, and Availability::Yearly. You can instantiate either of those directly (with the #new method), or you can use the equivalent factory methods exposed on Availability (e.g. Availability.once, Availability.yearly). Most availabilities will require at least an interval, a start_time, and a duration (see the RDocs for explanations of these).

There are a few convenience factory methods beyond the main factory methods:

  • Availability.every_{day,week,month,year} will create the appropriate availability with an interval of 1
  • Availability.every_two_{days,weeks,months,years} and Availability.every_other_{day,week,month,year} will create the appropriate availability with an interval of 2
  • There are other every_* factory methods for intervals of 3, 4, and 5 (e.g. every_three_months)

Primary API

#occurs_at?/1

This method takes a date or time and responds with a boolean indicating whether or not it is covered by the receiver.

#corresponds_to?/1

This method takes another availability and responds with a boolean indicating whether or not it is covered by the receiver.

#last_occurrence

This returns the last occurrence of the receiver, or nil if stops_by is not set.

#next_n_occurrences/2

This returns an enumerable object of the next N occurrences of this availability from the given date or time. If N is greater than 1,000 a lazy enumerable is returned, otherwise the enumerable is an instance of Array with the occurrences.

#next_occurrence/1

This returns a single time object for the next occurrence on or after the given date or time. If no occurrence exists, nil is returned.

Examples

# Every Monday from 9:00 AM to 10:00 AM starting on May 2, 2016
Availability.every_other_week(start_time: Time.new(2016, 5, 2, 9), duration: 1.hour)

# A business week starting on May 2, 2016 going from 1:30 PM until 2:00 PM every day
Availability.daily(start_time: Time.new(2016, 5, 2, 13, 30), stops_by: Time.new(2016, 5, 6), duration: 30.minutes)

# A semi-monthly availability occurring all day, without an end
Availability.every_other_month(start_time: Time.new(2016, 1, 1), duration: 1.day)

TODO

  • add more documentation

Authors

Contributors

Contributing

  • Do your best to adhere to the existing coding conventions and idioms.
  • Don't use hard tabs, and don't leave trailing whitespace on any line. Before committing, run git diff --check to make sure of this.
  • Do document every method you add using YARD annotations. Read the tutorial or just look at the existing code for examples.
  • Don't touch the availability.gemspec or VERSION files. If you need to change them, do so on your private branch only.
  • Do feel free to add yourself to the CREDITS file and the corresponding list in the the README. Alphabetical order applies.
  • Don't touch the AUTHORS file. If your contributions are significant enough, be assured we will eventually add you in there.
  • Do note that in order for us to merge any non-trivial changes (as a rule of thumb, additions larger than about 15 lines of code), we need an explicit on record from you. You can submit this dedication as a GitHub Issue in this repository. See public domain dedication for an example.

License

This is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying [UNLICENSE]UNLICENSE file.