{"id":26285739,"url":"https://github.com/billaul/period","last_synced_at":"2025-05-07T14:41:32.714Z","repository":{"id":56896206,"uuid":"319368949","full_name":"billaul/period","owner":"billaul","description":"Smart-Period aims to simplify Time-range manipulation","archived":false,"fork":false,"pushed_at":"2021-05-02T19:40:32.000Z","size":95,"stargazers_count":25,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-16T02:48:35.359Z","etag":null,"topics":["period","ruby","time-range"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/billaul.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-07T15:53:44.000Z","updated_at":"2024-06-16T08:11:08.000Z","dependencies_parsed_at":"2022-08-21T01:50:33.181Z","dependency_job_id":null,"html_url":"https://github.com/billaul/period","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/billaul%2Fperiod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/billaul%2Fperiod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/billaul%2Fperiod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/billaul%2Fperiod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/billaul","download_url":"https://codeload.github.com/billaul/period/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252897371,"owners_count":21821430,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["period","ruby","time-range"],"created_at":"2025-03-14T19:38:00.075Z","updated_at":"2025-05-07T14:41:32.691Z","avatar_url":"https://github.com/billaul.png","language":"Ruby","readme":"# Smart-Period [![Gem Version](https://badge.fury.io/rb/smart-period.svg)](https://badge.fury.io/rb/smart-period) [![Code Climate](https://codeclimate.com/github/billaul/period.svg)](https://codeclimate.com/github/billaul/period) [![Inline docs](http://inch-ci.org/github/billaul/period.svg)](http://inch-ci.org/github/billaul/period)\n\n⚠️ This gem will no longer receive any updates       \n⚠️ If you want to access to new awesome features, like endless-period support :hushed:      \n⚠️ Take a look to his successor [ActivePeriod](https://github.com/billaul/active_period) 🥳\n\nSmart-Period aims to simplify Time-range manipulation. \n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'period'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install smart-period\n\n## Usage\n\n**Smart-Period** was designed to simplify time-range manipulation, specialy with rails and user input   \n\n**Warning** :\n- A time-range take place between two date and it's different from an abstract duration of time\n- **Smart-Period** is limited at full day of time and will always round the starting and ending to the beginning and the ending of the day\n\n\n## Quick view (TL;DR)\n``` ruby\nrequire 'period'\n\n# Get all user created today\nUser.where(created_at: Period.today)\n\n# Get how many weeks there is from the beginning of time ?\nPeriod.new('01/01/1970'..Time.now).weeks.count\n\n# Is Trump still in charge ?\nTime.now.in? Period.new('20/01/2017'...'20/01/2021')\n\n# Get the week of an arbitrary date\nPeriod.week('24/04/1990')\n\n# Write a date for me (I18n supported)\nPeriod.new('20/01/2017'...'20/01/2021').to_s\n=\u003e \"From the 20 January 2017 to the 19 January 2021 included\"\n```\n\n## Detailed view\n\nThere's two way to create and manipulate a period of time `FreePeriod` and `StandardPeriod`\n\n### FreePeriod of time\n\nYou can declare **FreePeriod** as simply as :\n\n```ruby\n# With Date objects\nPeriod.new(3.month.ago..Date.today)\n# or with Strings\nPeriod.new('01/01/2000'...'01/02/2000')\n# or with a mix\nPeriod.new('01/01/2000'..1.week.ago)\n# or in a rails Controller with params\nPeriod.new(params[:start_date]..params[:end_date])\n```\n\n**FreePeriod** can be manipulated with `+` and `-`          \nDoing so will move the start **and** the end of the period   \n```ruby\nPeriod.new('01/01/2000'..'05/01/2000') + 3.day\n# is equal to\nPeriod.new('04/01/2000'..'08/01/2000')\n```\n\n### Standard Period of time\n\nUsing **StandardPeriod** you are limited to strictly bordered periods of time      \nThese periods are `day`, `week`, `month`, `quarter` and `year`\n\n```ruby\n# To get the week, 42th day ago\nPeriod.week(42.day.ago)\n# To get the first month of 2020\nPeriod.month('01/01/2020')\n# or if you like it verbious\nPeriod::Month.new('01/01/2020')\n# or if you need the current week\nPeriod.week(Time.now)\n```\n\n**Note** : If you ask for a `month`, `quarter` of `year`, the day part of your param doesn't matter `01/01/2020` give the same result as `14/01/2020` or `29/01/2020`\n\n**StandardPeriod** can be manipulated with `+` and `-` and will always return a **StandardPeriod** of the same type           \n```ruby\n# Subtraction are made from the start of the period\nPeriod.month('10/02/2000') - 1.day\n# Return the previous month\n# Addition are made from the end\nPeriod.month('10/02/2000') + 1.day\n# Return the next month\nPeriod.week('10/02/2000') + 67.day\n# Return a week\n```\n**StandardPeriod** also respond to `.next` and `.prev`\n```ruby\nPeriod.month('01/01/2000').next.next.next\n# Return the month of April 2020\n```\n\nYou can quickly access close period of time with `.(last|this|next)_(day|week|month|quarter|year)` and `.yesterday` `.today` `.tomorrow`\n\n```ruby\nPeriod.this_week\n# Same as Period.week(Time.now) but shorter\nPeriod.next_month\n# Return the next month\nPeriod.last_year\n# Return the last year\nPeriod.today\n# No comment\n```\n\n## HasMany\n\n**FreePeriod** and some **StandardPeriod** respond to `.days`, `.weeks`, `.months`, `.quarters` and `.years`    \nThese methods return an array of **StandardPeriod** who are overlapping the current period\n\n| HasMany -\u003e [\\\u003cStandardPeriod\u003e] | .days | .weeks | .months | .quarters | .years |\n|-------------------------------|:----:|:-----:|:------:|:--------:|:-----:|\n| FreePeriod                    |   X  |   X   |    X   |     X    |   X   |\n| StandardPeriod::Day           |      |       |        |          |       |\n| StandardPeriod::Week          |   X  |       |        |          |       |\n| StandardPeriod::Month         |   X  |   X   |        |          |       |\n| StandardPeriod::Quarter       |   X  |   X   |    X   |          |       |\n| StandardPeriod::Year          |   X  |   X   |    X   |     X    |       |\n\n#### Example\n```ruby\n# Get how many weeks there is from the beginning of time ?\nPeriod.new('01/01/1970'..Time.now).weeks.count\n# How many day in the current quarter\nPeriod.this_quarter.days.count\n# Get all the quarters overlapping a Period of time\nPeriod.new(...).quarters\n```\n\n## BelongsTo\n\n**StandardPeriod** respond to `.day`, `.week`, `.month`, `.quarter` and `.year`        \nThese methods return a **StandardPeriod** who include the current period    \n**FreePeriod** does not respond to these methods\n\n| BelongTo -\u003e StandardPeriod | .day | .week | .month | .quarter | .year |\n|----------------------------|:---:|:----:|:-----:|:-------:|:----:|\n| FreePeriod                 |     |      |       |         |      |\n| StandardPeriod::Day        |     |   X  |   X   |    X    |   X  |\n| StandardPeriod::Week       |     |      |   X   |    X    |   X  |\n| StandardPeriod::Month      |     |      |       |    X    |   X  |\n| StandardPeriod::Quarter    |     |      |       |         |   X  |\n| StandardPeriod::Year       |     |      |       |         |      |\n\n#### Example with BelongTo and HasMany\n\n```ruby\n# Get the first day, of the last week, of the second month, of the current year\nPeriod.this_year.months.second.weeks.last.days.first\n```\n\n## ActiveRecord\n\nAs **Period** inherite from **Range**, you can natively use them in **ActiveRecord** query\n\n```ruby\n# Get all book published this year\nBook.where(published_at: Period.this_year)\n```\n\n## Rails Controller\n\nIn a Controller, use the error handling to validate the date for you\n\n```ruby\nclass BookController \u003c ApplicationController\n  def between # match via GET and POST\n    # Default value for first display\n    params[:from] ||= 1.month.ago\n    params[:to]   ||= Time.now\n\n    begin\n      # Retrieve books from the DB\n      @books = Book.where(published: Period.new(params[:from]..params[:to]))\n    rescue ArgumentError =\u003e e\n      # Period will handle mis-formatted date and incoherent period\n      # I18n is supported for errors messages\n      flash[:alert] = e.message\n    end\n  end\nend\n```\n\n## I18n and to_s\n\nI18n is supported for `en` and `fr`   \n\n```ruby\nPeriod.new('01/01/2000'...'01/02/2001').to_s\n=\u003e \"From the 01 January 2000 to the 31 January 2001 included\"\nI18n.locale = :fr\nPeriod.new('01/01/2000'...'01/02/2001').to_s\n=\u003e \"Du 01 janvier 2000 au 31 janvier 2001 inclus\"\n```\nErrors are also supported\n```ruby\nPeriod.new 'Foo'..'Bar'\n#=\u003e ArgumentError (The start date is invalid)\nPeriod.new '01/02/3030'..'Bar'\n#=\u003e ArgumentError (The end date is invalid)\nPeriod.new '01/02/3030'..'01/01/2020'\n#=\u003e ArgumentError (The start date is greater than the end date)\n```\n\nSee `locales/en.yml` to implement your language support\n\nIf you need to change the format for a single call\n\n```ruby\n  period.to_s(format: 'Your Format')\n  # or\n  period.strftime('Your Format')\n```\nFor a FreePeriod or if you need to print the start and the end of your period differently, use `.i18n`\n```ruby\n  period.i18n do |from, to|\n    \"You have from #{from.strftime(...)} until #{to.strftime(...)} to deliver the money !\"\n  end\n```\n\n## The tricky case of Weeks\n\nWeeks are implemented following the [ISO 8601](https://en.wikipedia.org/wiki/ISO_week_date)      \nSo `Period.this_month.weeks.first` doesn't necessarily include the first days of the month\n\n## TimeZone\n\nTime zone are supported, you have nothing to do   \nIf you change the global `Time.zone` of your app, you have nothing to do    \nIf your Period [begin in a time zone and end in another](https://en.wikipedia.org/wiki/Daylight_saving_time), you have nothing to do\n\n## Bug reports\n\nIf you discover any bugs, feel free to create an [issue on GitHub](https://github.com/billaul/period/issues)        \nPlease add as much information as possible to help us in fixing the potential bug     \nWe also encourage you to help even more by forking and sending us a pull request\n\nNo issues will be addressed outside GitHub\n\n## Maintainer\n\n* Myself (https://github.com/billaul)\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbillaul%2Fperiod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbillaul%2Fperiod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbillaul%2Fperiod/lists"}