Jiff

Parse, validate, manipulate, and display dates in Ruby.

Installation

Add this line to your application's Gemfile:

gem 'jiff'

And then execute:

$ bundle

Or install it yourself as:

$ gem install jiff

Usage

Create a new Jiff set to the current date/time:

Jiff.new

or create one using an unix timestamp:

Jiff.new 1414612800

Access the date/time object at any point:

j = Jiff.new
j.date
# -> 1992-06-08 10:30:15 +0100

Get

Once you have created a Jiff, you can access any of the data within it. Overloaded getters and setters are used here, thus calling a method without parameters treats it as a getter, and calling them with a parameter treats it as a setter.

Note - not all methods currently have setter functionality (see #3).

.year

Gets the year.

Jiff.new.year
# -> 2014

.quarter

Gets the quarter (1..4).

Jiff.new.quarter
# -> 3

.month

Gets the month (1..12).

Jiff.new.month
# -> 6

.week_of_year

Gets the week of the year, where a week starts on Monday (0..53).

0 - week partially in previous year.
1-52 - weeks fully in current year.
53 - week partially in next year.

Jiff.new.week_of_year
# -> 24

.day_of_year

Gets the day of the year (1..366).

Jiff.new.day_of_year
# -> 260

.day_of_week

Gets the day of the week (1..7), where 1 is Monday.

Jiff.new.day_of_week
# -> 2

.day

Gets the day of the month (1..31).

Jiff.new.day
# -> 14

.hour

Gets the hour (0..23).

Jiff.new.hour
# -> 15

.minute

Gets the minutes (0..59).

Jiff.new.minute
# -> 31

.second

Gets the seconds (0..60).

Jiff.new.second
# -> 55

.millisecond

Gets the milliseconds (0..999).

Jiff.new.millisecond
# -> 456

Manipulate

After creating a Jiff, you can manipulate it in a number of ways. The fluent interface pattern, also known as method chaining, is used. Allowing you to write more readable code and do crazy stuff such as:

Jiff.new.add(14, 'd').add(6, 'M').subtract(10, 'y').week_of_year
# -> 39

.add

Add a specific amount of time to your current Jiff:

Jiff.new.add(amount, type)

To add time, pass the key of what time unit you want to add, and the amount you want to add.

.subtract

Subtract a specific amount of time from your current Jiff:

Jiff.new.subtract(amount, type)

This is exactly the same as .add, only instead of adding time, it subtracts time.

Keys

Shorthand	Key
y	year
M	month
w	week
d	day
h	hour
m	minute
s	second
ms	millisecond

Nearest

You can round any Jiff to the nearest; hour, minute or second.

j = Jiff.new

j.date
# -> 2014-10-29 22:41:59 +0000

j.nearest('hour').date
# -> 2014-10-29 23:00:00 +0000

To round, pass the key of the time unit you want to round to (see table above).

Timezone

Once you have created a Jiff, you can alter its timezone.

.timezone

Gets the timezone.

Jiff.new.timezone
# -> "BST"

.timezone(location)

Sets the timezone.

Jiff.new.timezone 'London'

Contributing

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Create a new Pull Request.

Please create an issue if you find a bug or think of an enhancement that could be made.

Credits

Heavily influenced by Moment.js