Advanced Usage

Using every one of Instant's features, and doing it well.

Picking Back Up

We now know (or, at least, assume that you know) the basics of Instant from Basic Usage. If not, this section assumes you have that knowledge, so go give it a read.

pageBasic Usage

Moving on, there's a few different topics this section aims to cover:

• Taking Differences between DateTimes

• Inbuilt functions dealing with current local DateTime

• Converting between timezones

Taking Differences

Taking differences between DateTimes is one of the most valuable things that we can do with Instant, and also one of the most practical.

Suppose we start with a DateTime:

DateTime first = curDateTimeByZone(zone: 'PST');

Then, some unknown amount of time elapses. Of course, you could deal with Dart's clunky stopwatch to measure this period, but this way is much cleaner:

DateTime second = curDateTimeByZone(zone: 'PST');
var diff = diffInSecs(first, second);

This gives you a clean int value for seconds that transpired in between. From there, you can do what you want: convert it to a Duration, display the difference, do calculations. But the power is back in your hands.

The other major advantage is the amount of units you can get the difference in:

//These all work well
var diff = diffInMillisecs(first, second);
var diff2 = diffInSecs(first, second);
var diff3 = diffInMins(first, second);
var diff4 = diffInHrs(first, second);
var diff5 = diffInDays(first, second);
var diff6 = diffInWeeks(first, second);
var diff7 = diffInMonths(first, second);
var diff8 = diffInYears(first, second);

This again provides you with some great flexibility in use.

However, if you still want to use a Stopwatch-esque class, take a look at the Stopwatch tab on the left.

Functions Dealing in (Local) Current Time

For convenience, because local time is what we most often deal with, Instant offers a number of abstractions just dealing in the current local time. Most of these are self-explanatory. They also have analogues which take in DateTimes instead of using the local timezones. Both are below, side-by-side:

Local Time

local.dart

//You also have formatCurTime, but it's the same idea
String formatCurDate({String format = "MMDDYYYY", String divider = "/"})

// Returns the current local date in words (ex. January 3, 2019)
String curDateInWords()

// Returns local current DateTime's millisecond as a # String formatted III (ex. '004').
String curMillisecAsString()

// Returns local current DateTime's second as a # String formatted SS (ex. '04').
String curSecAsString() 

// Returns local current DateTime's minute as a # String formatted MM (ex. '04').
String curMinAsString() 

// Returns local current DateTime's hour as a # String formatted HH (ex. '14').
String curHrAsString()

// Returns local current day as a # String formatted DD (ex. '04').
String curDayAsString()

// Returns local current month as a # String formatted MM (ex. '04').
String curMonthAsString()

// Returns local current year as a # String formatted YYYY (ex. '2019').
String curYearAsString()

/// Returns current day of the week as a text String (ex. "Monday").
String curWeekdayAsString()

// Returns current millisecond as an int (0...999).
// NO GIVEN DATETIME ANALOGUE, use DateTime().millisecond instead
int curMillisecAsInt()

// Returns current second as an int (0...59).
// NO GIVEN DATETIME ANALOGUE, use DateTime().second instead
int curSecAsInt()

// Returns current minute as an int (0...59).
// NO GIVEN DATETIME ANALOGUE, use DateTime().minute instead
int curMinAsInt()

// Returns current hour as an int (0...23).
// NO GIVEN DATETIME ANALOGUE, use DateTime().hour instead
int curHrAsInt()

// Returns current day as an int (1...31).
// NO GIVEN DATETIME ANALOGUE, use DateTime().day instead
int curDayAsInt()

// Returns current month as an int (1...12).
// NO GIVEN DATETIME ANALOGUE, use DateTime().month instead
int curMonthAsInt()

// Returns current year as an int (2019...Infinity).
// NO GIVEN DATETIME ANALOGUE, use DateTime().year instead
int curYearAsInt()

Given DateTime

given.dart

//You also have formatTime, but it's the same idea
String formatDate({@required DateTime date, String format = "MMDDYYYY", String divider = "/"})

// Returns a date in words (ex. January 3, 2019)
String dateInWords({@required DateTime date})

// Returns a DateTime's millisecond as a # String formatted III (ex. '004').
String millisecAsString({@required DateTime time})

// Returns a DateTime's second as a # String formatted SS (ex. '04').
String secAsString({@required DateTime time}) 

// Returns a DateTime's minute as a # String formatted MM (ex. '04').
String minAsString({@required DateTime date}) 

// Returns a DateTime's hour as a # String formatted HH (ex. '14').
String hrAsString({@required DateTime date})

// Returns given DateTime's day as a # String formatted DD (ex. '04').
String dayAsString({@required DateTime date})

// Returns given DateTime's month as a # String formatted MM (ex. '04').
String monthAsString({@required DateTime date})

// Returns given DateTime's year as a # String formatted YYYY (ex. '2019').
String yearAsString({@required DateTime date})

/// Returns given DateTime's day of the week as a text String (ex. "Monday").
String weekdayAsString({@required DateTime date})

Converting Between Timezones

This is by far the shortest section, but that might be expected. It's basically an extension on a method you (hopefully) should remember from Basic Usage.

I'm talking about DateTime conversion between timezones. We've already seen getting the current time in a timezone:

DateTime curInSFO = curDateTimeByZone(zone: "PDT");

But what if we later need that San Francisco DateTime to become a New York DateTime? Or a Paris DateTime? Or what if we have some historical data to make into a Moscow DateTime? Enter conversion:

DateTime curInSFO = curDateTimeByZone(zone: "PDT");
DateTime SFOtoNY = dateTimeToZone(zone: "EDT", datetime: curInSFO);
DateTime NYtoPRS = dateTimeToZone(zone: "CEST", datetime: SFOtoNY);

DateTime history = DateTime.fromMillisecondsSinceEpoch(20000);
DateTime historyMoscow = dateTimeToZone(zone: "MSK", datetime: history); 

Essential? No. Useful? Yeah.

A new way to use Instant...

You might notice an arrow below. That will take you to the newest feature of Instant: an brand-new Stopwatch class!