Basic Usage

A simple description of the usage of Instant.

Importing Instant

Edit your pubspec.yaml to include the latest version of Instant:

packages:
    instant: ^0.1.1

You can also use the "any" designation, although this isn't recommended due to possible breaking changes in Instant's future

Then, run pub packages get:

$ pub packages get

Lastly, import Instant in the desired file's header:

import 'pacakges:instant/instant.dart';

Using Instant

Instant revolves around the Dart class of DateTime. If you don't have a decent knowledge of this class yet, you probably want to read up; we'll be using it in a minute to get going.

You can start (or continue) learning about DateTime at https://api.dartlang.org/stable/2.5.2/dart-core/DateTime-class.html, the official Dart documentation on the class.

Now, Instant has three main branches (timezones, times, and dates); they're all interrelated and very closely tied together. The basic usage is demonstrated below:

usage1.dart

import 'pacakges:instant/instant.dart';

DateTime SanFran = curDateTimeByZone(zone: "PDT"); //current DateTime in PDT timezone
print(formatTime(time: SanFran)); //prints current time in PDT
print(formatDate(date: SanFran)); //prints current date in PDT

Easy, right? This would take you much longer traditionally, and might force you to create helper functions, integrate them, etc.

This is just the start of Instant's power. Let's take a closer look at each of the three lines above.

Time Zones

DateTime SanFran = dateTimeByZone(zone: "PDT"); //current DateTime in PDT timezone
DateTime NewYork = dateTimeByZone(zone: "EST"); //we can do this with any timezone worldwide
DateTime plus5 = dateTimeByUtcOffset(offset: 5) //we can also do it by UTC offset
DateTime local = DateTime.now() //of course, we can also take the local DateTime

All four of the above options are completely valid and will be accepted by Instant's other methods. You can mix and match, depending on your needs, helping you integrate to whatever extent you want.

Times

//Simple, no frills. Returns out hours, minutes, and seconds in 24
//hour time, and with ':' as the divider: 
formatTime(time: SanFran); //23:04:08

//Still pretty simple. However, now we get a different divider:
formatTime(time: SanFran, divider: "."); //23.04.08

//What if we don't want 24 hr time, and we want 12 hr time with AM or PM 
//appendaged to the end of the returned string?
formatTime(time: SanFran, divider: ".", is24hr: false); //11.04.08 P.M.

//Let's get rid of those pesky seconds, too!
formatTime(time: SanFran, is24hr: false, format: "HHMM"); //11:04 P.M

Pay particular attention to the last edit. The format field is extremely modular. You can use the chunks "HH" (hours), "MM" (minutes), "SS" (seconds), and "III" (milliseconds) in any order with any combination, leaving as many out as you like. As long as they are in a String with only those components, the program will figure it out.

Dates

//Simple, no frills. Returns out month, date, and year with '/' 
//as the divider: 
formatDate(date: SanFran); /* 10/12/2019 */

//Still pretty simple. However, now we get a different divider:
formatTime(time: SanFran, divider: "."); /* 10.12.2019 */

//You know what? I only need 2 digits for the year. Let's do that:
formatTime(time: SanFran, format: "MMDDYY"); /* 10/12/19 */

Again, pay attention to the last edit. You can again use the chunks "YY" (years-2), "YYYY" (years-4), "MM" (months), and "DD" (days) in any order with any combination, leaving as many out as you like. As long as they are in a String with only those components, the program will figure it out.

The above is a pretty good summary of the basics of Instant. However, there's a lot more to go over beyond these three functions. Make sure to check out Advanced Usage to see how to use all of Instant's features.