> For the complete documentation index, see [llms.txt](https://akushwarrior2.gitbook.io/instant/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://akushwarrior2.gitbook.io/instant/adv-use.md). # Advanced Usage ## 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. {% content-ref url="/pages/-Lr0IAMqGBNpWfeMKwYe" %} [Basic Usage](/instant/basic-use.md) {% endcontent-ref %} 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: ```dart 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: ```dart 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: ```dart //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: {% tabs %} {% tab title="Local Time" %} {% code title="local.dart" %} ```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() ``` {% endcode %} {% endtab %} {% tab title="Given DateTime" %} {% code title="given.dart" %} ```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}) ``` {% endcode %} {% endtab %} {% endtabs %} ## 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: ```dart 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: ```dart 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! --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://akushwarrior2.gitbook.io/instant/adv-use.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.