diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,9 @@ +scalendar Change Log +================== + + +# History Of Changes +================= + +## Tue Oct 03 2017 + * Version 1.2 with clarified algorithm patent rights and recognition of authorship in README and LICENSE. diff --git a/LICENSE b/LICENSE --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,28 @@ LICENSE -The Author of The Algorithm is Martin Rayrole. +The MIT License -You can find the patent here: -https://www.researchgate.net/publication/311582722_Method_of_Managing_Resources_in_a_Telecommunication_Network_or_a_Computing_System +Copyright (c) 2017 Sebastian Pulido Gomez and Stack Builders Inc: Implementation +of source code. + +Author Of Algorithm: Martin Rayrole + + +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. diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,301 @@ +# scalendar: Haskell Library to deal with resource availability in a Calendar. + +[![Build Status](https://travis-ci.org/stackbuilders/scalendar.svg?branch=master)](https://travis-ci.org/stackbuilders/scalendar) + +This is a library for handling calendars and resource availability based on the +`top-nodes algorithm` and set operations. That's why it is called `scalendar`: Calendars +which which keep track of the availability of a set of resources. +Since the bare `top-nodes algorithm` is not enough to IDENTIFY which are the +specific resources which are available in a given period of time - for example, +the id of the rooms which can still be reserved in a given `(checkIn-checkOut)` +interval - it was necessary to generalize that algorithm to work on sets of +strings which identify the available resources in a period. That generalization +was pretty smooth since addition in numbers was replaced by set Union and substraction +in numbers was replaced by set Difference. Another important fact about sets is that +they do not allow duplicates, so every identifier is guaranteed to be unique. + + +# Introduction + + +# Data Types + +`scalendar` is a library based on binary trees, where a Calendar is defined as follows: + +``` +data Calendar = + Unit TimePeriod (Set Text) (Set Text) + | Node TimePeriod (Set Text) (Set Text) Calendar Calendar + +data TimePeriod = + TimeInterval UTCTime UTCTime + | TimeUnit UTCTime +``` + +The idea is that each node in the calendar will store a TimePeriod which is a data type which stores +a time-interval with an`start-date` and an `end-date`. + +The purpose is that terminal nodes (leaves) will represent a unit of time, `TimeUnit`, which in this case +is a nominal day or 86400 seconds. Thus non-terminal nodes are intended to store a `TimeInterval` and +leaves are intended to store `TimeUnits`. Both leaves and nodes store `Q` and `QN` sets, which are the +data structures which allow the Calendar to keep track of the availability of a set of resources. +For more information about the time representation according to the `top-nodes` +algorithm check [this](https://en.wikipedia.org/wiki/Top-nodes_algorithm) + +Knowing what the `Q` and `QN` sets mean is not quite important to use this library but +roughly: + - `QN(Node)` represents reserved elements for all reservations having this node as `top-node` + - `Q(Node) = U(Q(LeftChild), Q(RightChild)) U QN(Node)` + +In order to use this library, it only suffices to know the meaning of the following +data type: + +``` +data SCalendar = SCalendar + { calUnits :: Set Text + , calendar :: Calendar + } deriving (Eq, Show) +``` + +An `SCalendar` is only a product type of a set of identifiers and a group of available resources - for +example, the numbers which are used to identify rooms in a hotel `{"101", "102", ...}` - and a `Calendar`, +which is the tree that keeps track of the availability of that set of resources. + +Other important data types are: + + +- ``` + data Reservation = Reservation + { reservUnits :: Set Text + , reservPeriod :: TimePeriod + } + ``` + + which represents a set of resources we want to reserve over a `TimePeriod` in a `SCalendar`. + +- ``` + data Cancellation = Cancellation + { cancUnits :: Set Text + , cancPeriod :: TimePeriod + } + ``` + + which represents a set of resources we want to cancel over a `TimePeriod` in a `SCalendar` + +- ``` + data Report = Report + { reportPeriod :: TimePeriod + , totalUnits :: Set Text + , reservedUnits :: Set Text + , remainingUnits :: Set Text + } + ``` + which represents a `Report` for a given `TimePeriod` where a `Report` has the following + information: + - `totalUnits`: The set of total identifiers for resources which can be reserved in a + `SCalendar`. + - `reservedUnits`: The set of identifiers for resources which have been reserved for a `TimePeriod`. + - `remainingUnits`: The set of remaining identifiers for resources which can still be + reserved without creating conflicts in a `TimePeriod`. + + +# Creating a Calendar + +Functions to create Calendars are located in `Time.SCalendar.Types` + +To create a bare `Calendar` which is not associated to any set of identifiers we can use + +``` +createCalendar :: Integer -- Year. + -> Int -- Month. + -> Int -- Day. + -> Int -- NumDays. + -> Maybe Calendar +``` + +where + - `Year`: It is an `Integer` representing the starting year of the `Calendar`. For example + `2017`. + - `Month`: It is an `Int` representing the starting month of the `Calendar`. For + example, `2` is equivalent to February. + - `Day`: It is an `Int` representing the starting day of the `Calendar`. It can be + any number representing one of the days of `Month`. + - `NumDays`: It is the number of Days we want our `Calendar` to cover. The days covered + by it will always be a power of `2`. Thus if you input `30`, `createCalendar` will + find the first power of `2` which is greater or equal to `32`, in this case `2^5 = 32`. + +So if everything is ok, this function `Just` returns a new `Calendar` which is suitable for +the given `NumDays`. A new `Calendar` is one which has neither reservations nor cancellations. + +`createSCalendar` is almost like `createCalendar` but instead of returning a bare `Calendar`, +it returns an `SCalendar` which is a `Calendar` together with a set of identifiers (of type `Text`) +which uniquely identify a group of available resources. The following example create an `SCalendar` +of `2 ^ 8 = 512 days` starting from `2016-February-2` with a set of identifiers `{ a, b, c, d }` + +``` +createSCalendar :: Integer -- Year. + -> Int -- Month. + -> Int -- Day. + -> Int -- NumDays. + -> Set Text -- Set of Identifiers + -> Maybe SCalendar + +createSCalendar 2017 2 1 365 (Set.fromList ["a", "b", "c", "d"]) +``` + +# Checking Availability + +There are two functions to check availability for a reservation. The first one is + +``` +isQuantityAvailable :: Int -> TimePeriod -> SCalendar -> Bool +``` + +where `Int` is an amount of resource we want to reserve, `TimePeriod` is the period of +time we want to reserve for that amount of resource, and `SCalendar` is the calendar +where we want to check availability. Naturally, this function returns a `Bool` if the +amount of resources is available. +Note that here we are just concerned with the amount of resources and whether there is +some set of identifiers whose size is greater of equal to that amount. If we need +to check if a particular set of identifiers is available for reservation, we can +use the following function: + +``` +isReservAvailable :: Reservation -> SCalendar -> Bool +``` + +which is almost like the first function, but here we are taking into account the set +of strings which identifies the resources we want to reserve since we are providing +a `Reservation` as input. + + +# Adding reservations to a Calendar + +There are two pairs of functions to add reservations to a calendar: + +``` +reservPeriod' :: Reservation -> Calendar -> Maybe Calendar +``` + +which inserts reservations into a calendar without any constraint. That's it, this +function does not apply any availability check before making the `Reservation`. That's +why this function does not need a `SCalendar`, because it does not need to take +into account the set of total available resources. + +The safe version is `reservPeriod` (without the quote) which enforces the +`isReservAvailable` check over that reservation before adding it. Its type is + +``` +reservePeriod :: Reservation -> SCalendar -> Maybe SCalendar +``` + +where an `SCalendar` is needed because we are taking into account the set of total +available resources to make the validation. + +The other pair of functions are quite similar but are handy for adding a list of +reservations at once: + +``` +reserveManyPeriods' :: [Reservation] -> Calendar -> Maybe Calendar +``` +which adds several reservations at once in a Calendar without any availability check. + +``` +reserveManyPeriods :: [Reservation] -> SCalendar -> Maybe SCalendar +``` +which will return a `SCalendar` only with the reservations that pass the +`isReservAvailable` test. Here we must take into consideration that reservations will be +inserted in the same order they come in the input list. So, if a reservation conflicts +with the ones that have been already inserted, it will not be included in the `SCalendar`. + + + +# Removing Reservation: Cancellations + +There are two operations which allow us to remove reserved resources from a period of +time: + +``` +cancelPeriod :: Cancellation -> Calendar -> Maybe Calendar +``` + +This operation takes a `Cancellation` and returns a `Calendar` with that `Cancellation`'s +set of resource identifiers subtracted from that `Calendar` in that `Cancellation`'s +period of time. +Be careful with this operation because there is no restriction over the period you are +deleting. You may be deleting from several reservations, from periods of time which are +meaningless - which have already elapsed-, and so on. However, all this library is +intended to be used together with some persistent storage system which will allow you +to keep record of the exact dates and resources which are reserved or cancelled. + + +The other operation is + +``` +cancelManyPeriods :: [Cancellation] -> Calendar -> Maybe Calendar +``` +which is handy for cancelling a list of periods at once. + +Note that for cancellations we do not need a `SCalendar` because we don't need to make +any availability check. + + +# One important thing to note + +Since this calendar implementation uses `Sets` and `Set` operations, you don't have to worry +about things like updating the total number of resource identifiers for your `SCalendar`. +You can freely remove or add identifiers to your `SCalendar` and there will be no +conflicts while making availability checks, reservations, cancellations, and so on. + + +# Reports + +It is very useful to have an operation which can summarize some information about the +state of the calendar in a given period of time. That's why this library has + +``` +periodReport :: TimePeriod -> SCalendar -> Maybe Report +``` + +where `TimePeriod` is the interval of time you would like the `Report` to summarize and +`SCalendar` is the calendar we are working on. This function returns a `Report` over that +period of time with the following information: + - `totalUnits`: The set of total identifiers for resources in the `SCalendar`, + in other words, the set part of `(SCalendar set calendar)`. + - `reservedUnits`: The set of resources which have been reserved for that period of time. + - `remainingUnits`: The set of remaining resources which can still be reserved without + creating conflicts in a `TimePeriod`. + +Note that `totalUnits`, `reservedUnits`, `remainingUnits` are all of type `Set`, and that the type +of `Report` is : + + ``` + data Report = Report + { reportPeriod :: TimePeriod + , totalUnits :: Set Text + , reservedUnits :: Set Text + , remainingUnits :: Set Text + } + ``` + +# Have Fun! + +So if you find this library useful, have fun with it in applications which need some +sort of calendar and resource availability management!! + + + +# Acknowledgements + +The base code for this library was written by [Sebastián Pulido Gómez](https://github.com/sebashack) and +was sponsored by [Stack Builders](https://www.stackbuilders.com/) + +Thanks to [Mark Karpov](https://www.stackbuilders.com/) and [Javier Casas](https://github.com/javcasas) for +their code reviews and suggestions. + + +# Top-Nodes Algorithm Patent information + +The ideas used to implement this library come from an invention by [Martin Rayrole](https://worldwide.espacenet.com/publicationDetails/biblio?locale=en_EP&II=8&FT=D&CC=US&DB=EPODOC&NR=2004204978A1&date=20041014&ND=3&KC=A1&adjacent=true#). + +This version of the algorithm invented by Martin Rayrole now does not have any patent protection. You can verify that by clicking on the `Abandonment` section of this [web-page](https://register.epo.org/ipfwretrieve?lng=en&apn=US.76452604.A). Thus this now belongs to the public domain! diff --git a/scalendar.cabal b/scalendar.cabal --- a/scalendar.cabal +++ b/scalendar.cabal @@ -1,8 +1,12 @@ name: scalendar -version: 1.1.1 +version: 1.2.0 tested-with: GHC==7.10.3, GHC==8.0.2, GHC==8.2.1 -synopsis: This is a library for handling calendars and resource availability - based on the "top-nodes algorithm" and set operations. +synopsis: A library for handling calendars and resource availability over time. +description: scalendar is a library based on the "top-nodes algorithm", invented by + Martin Rayrole , and + set operations, which makes it easy to handle the availability of a set of + resources over time. + homepage: https://github.com/stackbuilders/scalendar license: MIT license-file: LICENSE @@ -12,6 +16,8 @@ category: Time build-type: Simple cabal-version: >=1.10 +extra-source-files: CHANGELOG.md + , README.md library hs-source-dirs: src @@ -35,7 +41,7 @@ , SCalendarTest.Constructors main-is: Test.hs build-depends: base - , scalendar + , SCalendar , hspec >= 2.4.2 && < 3.0 , QuickCheck >= 2.9.2 && < 3.0 , time