timezone 0.5.6

  • Readme
  • Changelog
  • Installing
  • 92

TimeZone #

This package provides the IANA time zone database and time zone aware DateTime class, TZDateTime.

The current Time Zone database version is 2019c. See the announcement for details.

Initialization #

TimeZone objects require time zone data, so the first step is to load one of our time zone databases.

We provide three different APIs to load a database: one which is base64-encoded into a Dart library, one for browsers, and one for standalone environments.

Initialization from Dart library #

This is the recommended way to initialize a time zone database for non-browser environments. Each Dart libary found in lib/data, for example lib/data/latest.dart, contains a single no-argument function, initializeTimeZones.

import 'package:timezone/data/latest.dart';
void main() {

Initialization for browser environment #

Import package:timezone/browser.dart library and run async function Future initializeTimeZone([String path]).

import 'package:timezone/browser.dart';

Future<void> setup() async {
  await initializeTimeZone();
  final detroit = getLocation('America/Detroit');
  final now = new TZDateTime.now(detroit);

Initialization for standalone environment #

Import package:timezone/standalone.dart library and run async function Future initializeTimeZone([String path]).

import 'package:timezone/standalone.dart';

Future<void> setup() async {
  await initializeTimeZone();
  final detroit = getLocation('America/Detroit');
  final now = new TZDateTime.now(detroit);

Local Location #

By default, when library is initialized, local location will be UTC.

To overwrite local location you can use setLocalLocation(Location location) function.

Future<void> setup() async {
  await initializeTimeZone();
  final detroit = getLocation('America/Detroit');


Location #

Each location in the database represents a national region where all clocks keeping local time have agreed since 1970. Locations are identified by continent or ocean and then by the name of the location, which is typically the largest city within the region. For example, America/New_York represents most of the US eastern time zone; America/Phoenix represents most of Arizona, which uses mountain time without daylight saving time (DST); America/Detroit represents most of Michigan, which uses eastern time but with different DST rules in 1975; and other entries represent smaller regions like Starke County, Indiana, which switched from central to eastern time in 1991 and switched back in 2006.

The tz database

Get location by Olsen time zone ID #

final detroit = getLocation('America/Detroit');

We don't provide any functions to get locations by time zone abbreviations because of the ambiguities.

Alphabetic time zone abbreviations should not be used as unique identifiers for UTC offsets as they are ambiguous in practice. For example, "EST" denotes 5 hours behind UTC in English-speaking North America, but it denotes 10 or 11 hours ahead of UTC in Australia; and French-speaking North Americans prefer "HNE" to "EST".

The tz database

TimeZone #

TimeZone objects represents time zone and contains offset, DST flag, and name in the abbreviated form.

final timeInUtc = new DateTime.utc(1995, 1, 1);
final timeZone = detroit.timeZone(timeInUtc.millisecondsSinceEpoch);

TimeZone aware DateTime #

The TZDateTime class implements the DateTime interface from dart:core, and contains information about location and time zone.

final date = new TZDateTime(detroit, 2014, 11, 17);

Converting DateTimes between time zones #

To convert between time zones, just create a new TZDateTime object using from constructor and pass Location and DateTime to the constructor.

final localTime = new DateTime(2010, 1, 1);
final detroitTime = new TZDateTime.from(time, detroit);

This constructor supports any objects that implement DateTime interface, so you can pass a native DateTime object or our TZDateTime.

Time Zone databases #

We are using IANA Time Zone Database to build our databases.

We are currently building three different database variants:

  • default (doesn't contain deprecated and historical zones with some exceptions like US/Eastern). 361kb
  • all (contains all data from the IANA time zone database). 443kb
  • 2015-2025 (default database that contains historical data from 2015 until 2025). 85kb

Updating Time Zone databases #

Script for updating Time Zone database, it will automatically download the IANA time zone database and compile into our native format.

$ pub run tool/get -s 2014h

The argument -s is for specifying source version.

0.5.6 #

  • Time zone database updated to 2019c. For your convenience here is the announcement for 2019c.
  • Dart-importable databases made available in lib/data. README.md has more details.

0.5.5 #

  • Time zone database updated to 2019b. For your convenience here is the announcement for 2019b.
  • Convenience database symlinks added for convenience at
    • lib/data/latest.tzf
    • lib/data/latest_2015-2025.tzf
    • lib/data/latest_all.tzf

0.5.4 #

  • TZDateTime.utc is accessible before time zone database is initialized (thanks @jsmarr).
  • Fix dropping microseconds when creating TZDateTime (thanks @jsmarr).

0.5.3 #

  • Time zone database updated to 2019a. For your convenience here is the announcement for 2019a.

0.5.2 #

  • Time zone database updated to 2018i. For your convenience here are the announcements for 2018h and 2018i.

0.5.1 #

  • Time zone database updated to 2018g. For your convenience here are the announcements for 2018d, 2018e, 2018f, and 2018g.

0.5.0 #

  • Support a package-directory-free environment. In Dart 1.19, timezone is now compatible with pub get --no-packages-dir.
  • Breaking: Remove initializeTimeZoneSync method; it is incompatible with the async method for resolving package URIs.
  • Fix all strong mode errors (thanks @har79).
  • Add microsecond support (thanks @har79).
  • Improve interaction between TZDateTime and native DateTime (thanks @har79).
  • Fix TimeZone's == (thanks @har79).
  • Many new dartdoc comments (thanks @har79).
  • Fix for calling new TZDateTime.from() with a non-UTC DateTime object (thanks @tomaine2002).
  • Support Dart 2.
  • Time zone database updated to 2018c. For your convenience here are the announcements for 2015c, 2015d, 2015e, 2015f, 2015g, 2016a, 2016b, 2016c, 2016d, 2016e, 2016f, 2016g, 2016h, 2016i, 2017a, 2017b, 2017c, and 2018c.

0.4.3 #

  • Fix Dart 1.14 incompatibility further.

0.4.2 #

  • Bad pub publish. Ignore.

0.4.1 #

  • Fix Dart 1.14 incompatibility with packageRoot returning null.

0.4.0 #

  • Remove usage of tuple package.
  • Upgrade unittest package to test.
  • Fix database URL for "latest" database.
  • Add tool/dartfmt for formatting source.

0.3.1 #

  • generate_data_subset script is removed. It will be available as a separate package.

0.3.0 #

  • Time zone database updated to 2015b.
  • Removed local location detection heuristics (didn't worked properly). Local location is initialized with UTC location by default, use setLocalLocation to change local location.
  • Time zone database format is changed; data is aligned.

0.2.5 #

  • Fixed bug with String formatting (invalid offsets for minutes).

0.2.4 #

  • Fixed bug with Calendar-type constructor.

0.2.3 #

  • Added initializeTimeZoneSync function for standalone environments.
  • Fixed bug with script path on Windows.

0.2.2 #

  • TimeZone database updated to "2014j".
  • "args" and "path" moved from dev dependencies to dependencies.

0.2.1 #

  • tzfile library renamed to tzdata.
  • Added zone1970.tab parser to tzdata library.
  • Removed package:collection dependency.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  timezone: ^0.5.6

2. Install it

You can install packages from the command line:

with pub:

$ pub get

with Flutter:

$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:timezone/timezone.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Dec 10, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.0
  • pana: 0.13.1+4

Health suggestions

Format lib/data/latest.dart.

Run dartfmt to format lib/data/latest.dart.

Format lib/data/latest_2015-2025.dart.

Run dartfmt to format lib/data/latest_2015-2025.dart.

Format lib/data/latest_all.dart.

Run dartfmt to format lib/data/latest_all.dart.

Maintenance suggestions

The package description is too short. (-12 points)

Add more detail to the description field of pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and timezone.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
path ^1.3.0 1.6.4
Dev dependencies
args any
glob any
logging any
pedantic ^1.4.0
test any