doc

Jiffy

Jiffy is a Flutter (Android, IOS and Web) date time package inspired by momentjs for parsing, manipulating, querying and formatting dates

Table of content

• Parsing
  • Now
  • String
  • String Formating
  • Maps
  • Unix Timestamp
  • Jiffy Cloning
  • DateTime
  • List
  • UTC
• Get
  • Millisecond
  • Second
  • Minute
  • Hour
  • Date of Month
  • Days in Month
  • Day of Week
  • Day of Year
  • Week of Year
  • Month
  • Quarter
  • Year
• Manipulation
  • Add
  • Subtract
  • Start of Time
  • End of Time
  • Local
  • UTC
• Display
  • Format
  • Time from Now
  • Time from X
  • Difference
  • Unix Timestamp (Milliseconds)
  • Unix Timestamp (Seconds)
• Query
  • Is Before
  • Is Same
  • Is After
  • Is Same or Before
  • Is Same or After
  • Is Between
  • Is Leap Year
  • Is Jiffy
  • Is DateTime
• Locale Support

Parsing

Now

To get the date now, just call Jiffy() without passing any parameters. This will return a Jiffy instance. See below

Jiff(); // Returns a Jiffy instance
Jiffy().dateTime; // Returns a dart DateTime.now()
Jiffy().format(); // Return a ISO 8601 date time format

String

Creating a Jiffy from a string. See below

Jiffy("2021-5-25"); // A calendar date part
Jiffy("2021/5/25"); // A calendar date part separated by slash "/"
Jiffy("2021525"); // Basic (short) full date
Jiffy("2021-5-25 12:00:00.000"); // An hour, minute, second, and millisecond time part
Jiffy("2021-5-25T12:00:00.000"); // ISO date format
Jiffy("2021-5-25T12:00:00.000Z"); // ISO date format (UTC)

String Formatting

To get a Jiffy date from a string, pass the string and its pattern to Jiffy as is parameters. See below

Jiffy("2021-5-25", "yyyy-MM-dd");
Jiffy("25-5-2021", "dd-MM-yyyy");
Jiffy("5-2021", "MM-yyyy");

You can also parse ordinal date formats. The date pattern for the ordinal date is do

Jiffy("Jan 19th", "MMM do");
Jiffy("19th January 2021", "do MMMM yyyy");

Note: Jiffy runs on top of the Intl DateFormat package, so you can find all the date time patterns used by Jiffy here

This is also same for Jiffy default formats. See below

Jiffy().MMMEd; // Tue, May 25
Jiffy("2021-5-25", "yyyy-MM-dd").yMMMMd; // May 25, 2021

Maps

You can also create a Jiffy from a Map, Supported key pairs are,

[ year, month, day, hour, minute, second and millisecond ]. See below

Jiffy({
  "hour": 19,
  "minutes": 20
});

Jiffy({
  "year": 2019,
  "month": 10,
  "day": 19,
  "hour": 19
});

Unix Timestamp

Jiffy can also parse timestamp milliseconds and seconds. Just call Jiffy.unix() which return a dart Datetime. See below

// Parsing a timestamp in milliseconds
Jiffy.unixFromMillisecondsSinceEpoch(1318781876406);

// Parsing a timestamp in seconds
Jiffy.unixFromSecondsSinceEpoch(1318781876).format(); // 2011-10-16T19:17:56.000

Note: Jiffy.unixFromMillisecondsSinceEpoch() or Jiffy.unixFromSecondsSinceEpoch returns a timestamp base on local time. You can also get it in UTC which returns a UTC in dart Datetime. See below

Jiffy.unixFromMillisecondsSinceEpoch(1318781876406).utc();

Jiffy Cloning

Jiffy date time can be created from another Jiffy instance, a way of cloning.

var jiffy1 = Jiffy([2021]);
var jiffy2 = Jiffy(jiffy1);
jiffy1.add(years: 10);
jiffy1.year; // 2031
jiffy2.year; // 2021

Or you can use the clone method itself

var jiffy1 = Jiffy([2021]);
var jiffy2 = jiffy1.clone();
jiffy1.add(years: 10);
jiffy1.year; // 2031
jiffy2.year; // 2021

DateTime

Jiffy date time can be created from a dart DateTime instance. See below

var dateTime = DateTime.now();
Jiffy(dateTime);

Jiffy(DateTime(2021, 5, 25)).yMMMM; // May 2021

List

You can also create Jiffy from a List. But they should mirror the following order

[ year, month, day, hour, minute, second, millisecond ]

Jiffy([2021]); // January 1st 2021
Jiffy([2021, 10]); // October 1st 2021
Jiffy([2021, 10, 19]); // October 19th 2021

UTC

Get date time in UTC. See below

// In local time
Jiffy().format(); // 2021-03-02T14:35:24.363919

// Change to UTC
var jiffy = (Jiffy()..utc());
jiffy.format(); // 2021-03-02T11:35:24.363919

Get

Millisecond

Get millisecond (Returns from 0 - 999)

Jiffy().millisecond;

Second

Get second (Returns from 0 - 59)

Jiffy().second;

Minute

Get minute (Returns from 0 - 59)

Jiffy().minute;

Hour

Get hour (Returns from 0 - 23)

Jiffy().hour;

Date of month

Get date of month (Returns from 1 - 31)

Jiffy().date;

Days in month

Get days in a month (Returns from 28 - 31)

Jiffy().daysInMonth;

Day of week

Get day of week (Returns from 1 - 7 that is [Sunday - Saturday] depending on locale start of week)

Jiffy().day;

Day of year

Get day o year (Returns from 1 - 366)

Jiffy().dayOfYear;

Week of year

Get week of year

Jiffy().week;

Month

Get month (Returns from 1 - 12 [Jan - Dec])

Jiffy().month;

Quarter

Get quarter (Returns from 1 - 4)

Jiffy().quarter;

Year

Get year

Jiffy().year;

Manipulation

Add

This adds time to Jiffy by the following units years, months, weeks, days, hours, minutes, seconds and milliseconds, microseconds and duration. See below

Jiffy().add(years: 1);
Jiffy().add(days: 3);
Jiffy().add(months: 3, duration: Duration(days: 3));
Jiffy().add(years: 1, weeks: 3, duration: Duration(days: 3));

Below are the params that can be used

[ years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, duration ]

var jiffy = Jiffy()
    .startOf(Units.DAY)
    .add(days: 7, months: 1)
    .subtract(years: 1);
jiffy.yMMMdjm; // Apr 8, 2020 9:00 PM

Note: Months and year are added in respect to how many days there are in a months and if a year is a leap year. See below

Jiffy("2021-1-31", "yyyy-MM-dd").yMMMd; // Jan 31, 2021
Jiffy("2021-1-31", "yyyy-MM-dd").add(months: 1).yMMMd; // Feb 28, 2021

Subtract

This subtracts time from Jiffy by the following units years, months, weeks, days, hours, minutes, seconds and milliseconds. See below

Jiffy().subtract(years: 1);
Jiffy().subtract(days: 3);

Start of Time

This set the Jiffy date time to a specific unit in time in terms of years, months, weeks, days, hours, minutes, seconds and milliseconds. See below

The units that are available are,

[ Units.MILLISECOND, Units.SECOND, Units.MINUTE, Units.HOUR, Units.DAY, Units.WEEK, Units.MONTH, Units.YEAR ]

Jiffy().startOf(Units.YEAR);    // Set to January 1st, 12:00 am this year
Jiffy().startOf(Units.MONTH);   // Set to the first of this month, 12:00 am
Jiffy().startOf(Units.WEEK);    // Set to the first day of this week, 12:00 am
Jiffy().startOf(Units.DAY);     // Set to 12:00 am today
Jiffy().startOf(Units.HOUR);    // Set to now, but with 0 mins, 0 secs, and 0 ms
Jiffy().startOf(Units.MINUTE);  // Set to now, but with 0 seconds and 0 milliseconds
Jiffy().startOf(Units.SECONDS);  // Set to now, but with 0 milliseconds;

var jiffy = Jiffy()
    .startOf(Units.DAY)
    .add(days: 1);
    .format("MMMM do yyyy, h:mm:ss a"); // March 3rd 2021, 12:00:00 AM

End of Time

This set the Jiffy date time to a specific unit in time in terms of years, months, weeks, days, hours, minutes, seconds and milliseconds. See below

Jiffy().endOf(Units.YEAR);    // Set to December 31st, 23:59:59:999 this year
Jiffy().endOf(Units.MONTH);   // Set to the end of this month, 23:59:59:999
Jiffy().endOf(Units.WEEK);    // Set to the end day of this week, 23:59:59:999
Jiffy().endOf(Units.DAY);     // Set to 23:59:59:999 today

Local

Sets Jiffy to local time. See below

var jiffy = Jiffy().utc(); // Time in utc
jiffy.local(); // Set to local

UTC

Sets Jiffy to UTC time. See below

var jiffy = Jiffy(); // Time in local
jiffy.utc(); // Set to utc

Display

Format

The format function takes in a string pattern, which can be found here, and format them. See below

Jiffy().format("MMMM do yyyy, h:mm:ss a"); // October 19th 2019, 7:00:53 PM
Jiffy().format("EEEE"); // Saturday
Jiffy().format("yyyy [escaped] yyyy"); // 2019 escaped 2019

// Not passing a string pattern for format method will return an ISO Date format
Jiffy().format(); // 2019-10-19T19:00:53.090646

You can also use Intl Dateformat default methods to format. See below

Jiffy().yMMMMd; // October 19, 2019
Jiffy().yMMMMEEEEdjm; // Saturday, October 19, 2019 7:00 PM

Time from Now

This method is used to get the relative time from now. See below

Jiffy("2007-1-29").fromNow(); // 14 years ago
Jiffy([2022, 10, 29]).fromNow(); // in a year
Jiffy(DateTime(2050, 10, 29)).fromNow(); // in 30 years

var jiffy = Jiffy().startOf(Units.HOUR).fromNow(); // 9 minutes ago

Time from X

This method is used to get the relative time from a specific date time. See below

var jiffy1 = Jiffy("2007-1-28");
var jiffy2 = Jiffy("2017-1-29", "yyyy-MM-dd");

jiffy1.from(jiffy2); // a day ago

jiffy1.from([2017, 1, 30]); // 2 days ago

Difference

Used to get the difference between two Jiffy date times. See below

// By default, diff method, get the difference in milliseconds
var jiffy1 = Jiffy("2007-1-28", "yyyy-MM-dd");
var jiffy2 = Jiffy("2017-1-29", "yyyy-MM-dd");
jiff1.diff(jiffy2); // 86400000

Getting difference in another unit of measurement. The units that are available are,

[ Units.MILLISECOND, Units.SECOND, Units.MINUTE, Units.HOUR, Units.DAY, Units.WEEK, Units.MONTH, Units.YEAR ]

Jiffy([2007, 1, 28]).diff([2017, 1, 29], Units.DAY); // -3654

Also by default diff will truncate the result to return a whole number. To get decimal numbers, just pass a third param as true. See below

var jiffy1 = Jiffy("2008-10", "yyyy-MM");
var jiffy2 = Jiffy("2007-1", "yyyy-MM");

jiff1.diff(jiffy2, Units.YEAR); // 1
jiff1.diff(jiffy2, Units.YEAR, true); // 1.75

Note: Months and years are added in respect to how many days there are in a months and if its a year is a leap year.

Unix Timestamp (Milliseconds)

To get timestamp in milliseconds see below

Jiffy().valueOf();

Unix Timestamp (Seconds)

To get timestamp in seconds see below

Jiffy().unix();

Query

Is Before

Check if date time is before another date time. See below

var jiffy1 = Jiffy("2021-10-20");
var jiffy2 = Jiffy("2021-10-21");
jiffy1.isBefore(jiffy2); // true

You can also check in terms of units of measurement. The below example checks if year is before.

var jiffy1 = Jiffy([2020, 10, 20]);

var jiffy2 = Jiffy("2020-12-31", "yyyy-MM-dd");
var jiffy3 = Jiffy("2021-01-01", "yyyy-MM-dd");

jiffy1.isBefore(jiffy2, Units.YEAR); // false
jiffy1.isBefore(jiffy3, Units.YEAR); // true

Is Same

Check if date time is same with another date time. See below

var jiffy1 = Jiffy("2021-10-20", "yyyy-MM-dd");
var jiffy2 = Jiffy("2021-10-20", "yyyy-MM-dd");
jiffy1.isSame(jiffy2); // true

You can also check in terms of units of measurement. The below example checks if years are the same.

var jiffy1 = Jiffy("2021-10-20", "yyyy-MM-dd");

var jiffy2 = Jiffy("2020-12-31", "yyyy-MM-dd");
var jiffy3 = Jiffy("2021-01-01", "yyyy-MM-dd");

jiffy1.isSame(jiffy2, Units.YEAR); // false
jiffy1.isSame(jiffy3, Units.YEAR); // true

Is After

Check if date time is after another date time. See below

var jiffy1 = Jiffy("2021-10-20", "yyyy-MM-dd");
var jiffy2 = Jiffy("2021-10-19", "yyyy-MM-dd");
jiffy1.isAfter(jiffy2); // true

You can also check in terms of units of measurement. The below example checks if year is after.

var jiffy1 = Jiffy("2021-10-20", "yyyy-MM-dd");

var jiffy2 = Jiffy("2021-01-01", "yyyy-MM-dd");
var jiffy3 = Jiffy("2020-12-31", "yyyy-MM-dd");

jiffy1.isAfter(jiffy2, Units.YEAR); // false
jiffy1.isAfter(jiffy3, Units.YEAR); // true

Is Same or Before

Check if date time is same or before with another date time. See below

var jiffy1 = Jiffy("2021-10-20", "yyyy-MM-dd");

var jiffy2 = Jiffy("2020-12-31", "yyyy-MM-dd");
var jiffy3 = Jiffy("2021-12-31", "yyyy-MM-dd");
var jiffy4 = Jiffy("2022-01-01", "yyyy-MM-dd");

jiffy1.isSameOrBefore(jiffy2, Units.YEAR); // false
jiffy1.isSameOrBefore(jiffy3, Units.YEAR); // true
jiffy1.isSameOrBefore(jiffy4, Units.YEAR); // true

Is Same or After

Check if date time is same or after with another date time. See below

var jiffy1 = Jiffy("2021-10-20", "yyyy-MM-dd");

var jiffy2 = Jiffy("2022-12-31", "yyyy-MM-dd");
var jiffy3 = Jiffy("2021-01-01", "yyyy-MM-dd");
var jiffy4 = Jiffy("2020-12-31", "yyyy-MM-dd");

jiffy1.isSameOrAfter(jiffy2, Units.YEAR); // false
jiffy1.isSameOrAfter(jiffy3, Units.YEAR); // true
jiffy1.isSameOrAfter(jiffy4, Units.YEAR); // true

Is Between

Check if a date time is between two date times. See below

var jiffy1 = Jiffy("2021-10-20", "yyyy-MM-dd");

var jiffy2 = Jiffy("2021-01-01", "yyyy-MM-dd");
var jiffy3 = Jiffy("2023-01-01", "yyyy-MM-dd");

var jiffy4 = Jiffy("2020-12-31", "yyyy-MM-dd");
var jiffy5 = Jiffy("2023-01-01", "yyyy-MM-dd");

jiffy1.isBetween(jiffy2, jiffy3, Units.YEAR); // false
jiffy1.isBetween(jiffy4, jiffy5, Units.YEAR); // true

Is LeapYear

Check if date time is a leap year or not. See below

Jiffy("2019", "yyyy").isLeapYear; // false
Jiffy("2016", "yyyy").isLeapYear; // true

Is Jiffy

Check if it is a Jiffy instance. See below

Jiffy.isJiffy("string"); // false
Jiffy.isJiffy(Jiffy()); // true
Jiffy.isJiffy(DateTime.now()); // false

Is DateTime

Check if it is a dart DateTime instance. See below

Jiffy.isDateTime("string"); // false
Jiffy.isDateTime(DateTime.now()); // true
Jiffy.isDateTime(Jiffy()); // false

Locale Support

await Jiffy.locale("fr");
Jiffy().yMMMMEEEEdjm; // samedi 19 octobre 2019 19:25

Below are the locales that are supported in Jiffy. More will be added

Key	Locale
English	en / en_sg / en_au / en_ca / en_gb / en_ie / en_il / en_nz
Spanish	es / es_do / es_us
Chinese	zh / zh_cn / zh_hk / zh_tw
Japanese	ja
German	de / de_at / de_ch
French	fr / fr_ch / fr_ca
Indonesian	id
Italian	it / it_ch
Korean	ko
Russian	ru
Ukrainian	uk
Hindi	hi
Arabic	ar / ar_ly / ar_dz / ar_kw / ar_sa / ar_ma / ar_tn
Portuguese	pt / pt_br
Polish	pl
Turkish	tr
Swedish	sv
Norwegian	nb
Persian	fa
Azerbaijani	az
Dutch	nl
Thailand	th

Getting and setting locales in Jiffy always returns a future

// Get the locale (By default, the locale is "en")
await Jiffy.locale(); // en

// To set locale
await Jiffy.locale("fr");
Jiffy().yMMMMEEEEdjm; // samedi 19 octobre 2019 19:25

await Jiffy.locale("ar");
Jiffy().yMMMMEEEEdjm; // السبت، ١٩ أكتوبر ٢٠١٩ ٧:٢٧ م

await Jiffy.locale("zh-cn");
Jiffy().yMMMMEEEEdjm; // 2019年10月19日星期六 下午7:28

Get all available locales

To get all available locales in Jiffy run the following

Jiffy.getAllAvailableLocales() // returns all locales