time_machine 0.2.0

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • new50

Dart Time Machine

Time Machine is a date and time API for Dart (port of Noda Time). Time Machine is timezone and culture sensitive. Intended targets are DartVM, Dart4Web, and Flutter.

Example Code:

// Sets up timezone and culture information
await TimeMachine.initialize();
print('Hello, ${DateTimeZone.local} from the Dart Time Machine!');

var tzdb = await DateTimeZoneProviders.tzdb;
var paris = await tzdb["Europe/Paris"];

var now = SystemClock.instance.getCurrentInstant();

print('\nBasic');
print('UTC Time: $now');
print('Local Time: ${now.inLocalZone()}');
print('Paris Time: ${now.inZone(paris)}');

print('\nFormatted');
print('UTC Time: ${now.toString('dddd yyyy-MM-dd HH:mm')}');
print('Local Time: ${now.inLocalZone().toString('dddd yyyy-MM-dd HH:mm')}');

print('\nFormatted and French');
var culture = await Cultures.getCulture('fr-FR');
print('UTC Time: ${now.toString('dddd yyyy-MM-dd HH:mm', culture)}');
print('Local Time: ${
  now.inLocalZone().toString('dddd yyyy-MM-dd HH:mm', culture)}');

print('\nParse French Formatted DateTimeZone');
// without the 'z' parsing will be forced to interpret the timezone as UTC
var localText = now
    .inLocalZone()
    .toString('dddd yyyy-MM-dd HH:mm z', culture);

var localClone = ZonedDateTimePattern
    .createWithCulture('dddd yyyy-MM-dd HH:mm z', culture)
    .parse(localText);
print(localClone.value);

VM

selection_116

Flutter

selection_117

Web

selection_118

A lot of functionality works at this time, but the public API is starting to stabilize. TZDB QoL changes are in progress. This is a preview release. Documentation was also ported, but some things changed for Dart and the documentation will have minor inaccuracies in some places.

Don't use any functions annotated with @internal. I don't intend to keep this annotation, but with part \ part of usage discouraged and no friend semantics, I'm unsure of the direction to go with this.

  • [ ] Prototype an automated tool to produce public interface files?

Todo:

  • [x] Port over major classes
  • [x] Port over corresponding unit tests
  • [ ] Dartification of the API
    • [X] First pass style updates
    • [X] Second pass ergonomics updates
    • [ ] Synchronous TZDB timezone provider
  • [ ] Non-Gregorian/Julian calendar systems
  • [X] Text formatting and Parsing
  • [X] Remove XML tags from documentation and format them for pub (human second pass still needed)
  • [X] Implement Dart4Web features
  • [ ] maybe: Create simple website with samples (at minimal a samples directory in github)

External data: Timezones (TZDB via Noda Time) and Culture (ICU via BCL) are produced by a C# tool that is not included in this repository.

I'm hoping that JS/VM specific functions will work via conditional imports. For testing atm, VM is default, but full JS support is planned. (fingers crossed that this makes it into Dart 2)

The unit testing framework uses reflection and won't work in Dart4Web 2.0 or later; we'll cross this bridge later.

Future Todo:

  • [ ] Produce our own TSDB files
  • [ ] Produce our own Culture files
  • [ ] Benchmarking & Optimizing Library for Dart

Flutter Specific Notes

You'll need this entry in your pubspec.yaml.

# The following section is specific to Flutter.
flutter:
  assets:
    - packages/time_machine/data/cultures/cultures.bin
    - packages/time_machine/data/tzdb/tzdb.bin

Your initialization function will look like this:

import 'package:flutter/services.dart';


await TimeMachine.initialize(rootBundle);

Once flutter gets Isolate.resolvePackageUri functionality, we'll be able to merge VM and the Flutter code paths and no asset entry or special import will be required. It would look just like the VM example.

DDC Specific Notes

class Foo {
  // Okay in Dart_VM 1.24 -- Okay in DartPad -- Okay in Dart2JS
  // not Okay in DDC
  @override String toString([int x = 0, int y = 0, int z = 0]) 
    => '${x + y+ x}';
}

void main() {
  var foo = new Foo();
  print(foo.toString());
  print(foo.toString(1, 2, 3));
}

Overriding toString() with optional arguments doesn't work in DDC. We use this technique to provide optional formatting. Instant and ZonedDateTime currently have toStringDDC functions available. Still investigating potential solutions.

Changelog

0.2.0

  • No more specific imports for your platform. Flutter usage was streamlined significantly.

0.1.1

  • Broke some things while making this work on many platforms. Fixed them (still need to do unit tests on js).

0.1.0

  • Made some changes to try and less confuse Pana.

0.0.4

  • Now works on Flutter, Web, and VM!

0.0.2

  • Many things have been Dartified. Constructors consolidated, names are lowercased, @private usage heavily reduced.

0.0.1

  • Initial version.

example/example.dart

// Copyright 2018 The Time Machine Authors. All rights reserved.
// Use of this source code is governed by the Apache License 2.0, as found in the LICENSE.txt file.

import 'dart:async';

// todo: consolidate import packages??? this seems a little much...
import 'package:time_machine/time_machine.dart';
import 'package:time_machine/time_machine_globalization.dart';
import 'package:time_machine/time_machine_text.dart';
import 'package:time_machine/time_machine_timezones.dart';

Future main() async {
  // todo: demonstrate a test clock
  // var clockForTesting = new FakeClock();

  try {
    // Sets up timezone and culture information
    await TimeMachine.initialize();
    print('Hello, ${DateTimeZone.local} from the Dart Time Machine!');

    var tzdb = await DateTimeZoneProviders.tzdb;
    var paris = await tzdb["Europe/Paris"];

    var now = SystemClock.instance.getCurrentInstant();

    print('\nBasic');
    print('UTC Time: $now');
    print('Local Time: ${now.inLocalZone()}');
    print('Paris Time: ${now.inZone(paris)}');

    print('\nFormatted');
    print('UTC Time: ${now.toString('dddd yyyy-MM-dd HH:mm')}');
    print('Local Time: ${now.inLocalZone().toString('dddd yyyy-MM-dd HH:mm')}');

    var culture = await Cultures.getCulture('fr-FR');
    print('\nFormatted and French ($culture)');
    print('UTC Time: ${now.toString('dddd yyyy-MM-dd HH:mm', culture)}');
    print('Local Time: ${now.inLocalZone().toString('dddd yyyy-MM-dd HH:mm', culture)}');

    print('\nParse French Formatted DateTimeZone');
    // without the 'z' parsing will be forced to interpret the timezone as UTC
    var localText = now
        .inLocalZone()
        .toString('dddd yyyy-MM-dd HH:mm z', culture);

    var localClone = ZonedDateTimePattern
        .createWithCulture('dddd yyyy-MM-dd HH:mm z', culture)
        .parse(localText);
    print(localClone.value);
  }
  catch (error, stack) {
    print(error);
    print(stack);
  }
}

Use this package as a library

1. Depend on it

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


dependencies:
  time_machine: "^0.2.0"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

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

3. Import it

Now in your Dart code, you can use:


      import 'package:time_machine/time_machine.dart';
  
Version Uploaded Documentation Archive
0.2.0 Jun 20, 2018 Go to the documentation of time_machine 0.2.0 Download time_machine 0.2.0 archive
0.1.1 Jun 19, 2018 Go to the documentation of time_machine 0.1.1 Download time_machine 0.1.1 archive
0.1.0 Jun 18, 2018 Go to the documentation of time_machine 0.1.0 Download time_machine 0.1.0 archive
0.0.4 Jun 18, 2018 Go to the documentation of time_machine 0.0.4 Download time_machine 0.0.4 archive
0.0.3 Jun 16, 2018 Go to the documentation of time_machine 0.0.3 Download time_machine 0.0.3 archive
0.0.2 Jun 13, 2018 Go to the documentation of time_machine 0.0.2 Download time_machine 0.0.2 archive
0.0.1 Jun 9, 2018 Go to the documentation of time_machine 0.0.1 Download time_machine 0.0.1 archive

Analysis

We analyzed this package on Jun 20, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0-dev.63.0
  • pana: 0.11.3

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
0 / 100
Health:
Code health derived from static analysis. [more]
99 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
99 / 100
Overall score:
Weighted score of the above. [more]
50
Learn more about scoring.

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:time_machine/time_machine.dart.

Suggestions

  • Fix analysis and formatting issues.

    Analysis or formatting checks reported 86 hints.

    Strong-mode analysis of lib/src/calendar_system.dart gave the following hint:

    line: 44 col: 23
    The value of the field '_copticId' isn't used.

    Strong-mode analysis of lib/src/duration.dart gave the following hint:

    line: 53 col: 20
    The value of the field '_maxNano' isn't used.

    Similar analysis of the following files failed:

    • lib/src/instant.dart (hint)
    • lib/src/offset_datetime.dart (hint)
    • lib/src/period.dart (hint)
    • lib/src/platforms/vm.dart (hint)
    • lib/src/platforms/web.dart (hint)
    • lib/src/text/format_helper.dart (hint)
    • lib/src/text/globalization/culture_io.dart (hint)
    • lib/src/text/globalization/time_machine_format_info.dart (hint)
    • lib/src/text/localdatetime_pattern.dart (hint)
    • lib/src/text/localtime_pattern.dart (hint)
    • lib/src/text/localtime_pattern_parser.dart (hint)
    • lib/src/text/patterns/stepped_pattern_builder.dart (hint)
    • lib/src/text/period_pattern.dart (hint)
    • lib/src/text/value_cursor.dart (hint)
    • lib/src/timezones/precalculated_datetimezone.dart (hint)
    • lib/src/timezones/timezone_info_interceptor.dart (hint)
    • lib/src/timezones/zone_local_mapping.dart (hint)
    • lib/src/timezones/zone_recurrence.dart (hint)
    • lib/src/timezones/zone_year_offset.dart (hint)
    • lib/src/timezones/zoneinterval.dart (hint)
    • lib/src/utility/binary_reader.dart (hint)
    • lib/src/utility/compare_info.dart (hint)
    • lib/src/yearmonthday_and_calendar.dart (hint)
    • lib/src/zoneddatetime.dart (hint)
  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.20.1 <2.0.0
collection ^1.14.5 1.14.10
logging ^0.11.3+1 0.11.3+1
meta ^1.1.2 1.1.5
quiver_hashcode ^1.0.0 1.0.0
resource ^2.1.2 2.1.4
Transitive dependencies
typed_data 1.1.5
Dev dependencies
matcher ^0.12.1+4
reflectable any
test ^0.12.0