vy_date 0.4.0

vy_date #

Simple utilities for managing dates and periods.

Date class #

The Date class simply wraps the DateTime one. I believe that it is easier to manage dates this way because it frees you from the hassle of the time zones and prevents you doing the following potentially dangerous moves:

  • Involuntarily set minutes or seconds or so on. This can lead to problems when comparing dates
  • Have to work with dates from different time zones or mixed with UTC ones.

Pluses:

  • You can be sure that the difference in days is always correct.
  • Have some easy to use functions for formatting
  • Json formatting

Instances can be serialized with Json, in this case they are sent as a String with the date in format "YYYY-MM-DD".

Technically speaking, the date is transformed int an UTC DateTime instance. During insertion all references to time info are lost.

There are a couple of formatting functions and their counterparts for parsing the result. These methods require Intl to be initialized. Inside your application you have to import the Intl package:

import 'package:intl/date_symbol_data_local.dart';

and you have to initialize the locale you'll gonna use with the statement:

await initializeDateFormatting('en_US', null);

This is needed only once in the whole application, before using the formatting methods for the rquired locale, otherwise a LocaleDataException will be thrown

Usage #

A simple usage example:

import 'package:vy_date/vy_date.dart';

main() {
  Date date = Date.now();
}

DatePeriod class #

This class allows to manage a period between two dates. It is immutable, and has a companion class that allows to manage partial data before generating a correct instance of DatePeriod. This companion class is called DatePeriodAssembler and follows the logic of the Builder classes. I could have used the name DatePeriodBuilder, but I did not want to confuse how the class behave with those of the built_value package. The logic is + or - the same, but there is a difference: the data class (DatePeriod in this case) is not aware of the existence of an helper method, and could even be used alone, while the built_value package generated classes are tightly coupled together.

The class is comparable, the comparision is made first testing the start date and then, if equal, testing the period duration.

The DatePeriod class does not accept negative periods (i.e. those with the end period date before in time of the start period one).

You can even initialize the period with null values (even if this is discouraged). If a null start date is receive the conventional date 1970-01-01 is used, if the end date (or duration, depending on the constructor) is null, a period of one day is used.

The class is normally managed with initial and ending dates inclusive, but you can extract the exclusive end date with the appropriate getter if needed.

When converted to Json string the class is saved as Map containing the two dates into the above (see Date class) mentioned format.

Usage #

A simple usage example:

import 'package:vy_date/vy_date.dart';

void main() {
  DatePeriod period = DatePeriod(Date(2010, 1, 1), Date(2010, 1, 31));
  // print "31"
  print(period.inDays);
  
  DatePeriodAssembler periodAssembler = DatePeriodAssembler()
    ..startDate = Date(2010, 1, 1)
    ..exclusiveEndDate = Date(2010, 2, 1);
  // print "0"
  print(periodAssembler.generate().compareTo(period)); 
}

Features and bugs #

Please file feature requests and bugs at the issue tracker.

license.

0.4.0 #

  • DatePeriod transformed into an immutable class
  • Removed deprecated setter and getter for "startingDate"
  • Removed deprecated setter and getter for "endingDate"
  • Removed deprecated "getEndDate" method
  • Removed deprecated "getFirstExcludedDay" method
  • Removed deprecated "getDays" method
  • Static constructors have been transformed into factories

0.3.4 #

  • Added toYMdString() and parseYMdString()
  • Package Intl ^0.16.0 instead of ^0.15.7

0.3.3 #

  • Sdk 2.2.0 support
  • Call to DatePeriod.isInPeriod() was giving error if the date parameter was null. Now returns false.
  • Changed the way how the DatePeriod is serialized (toJson). Instead of saving the duration, it is saved the end date in format yyyy-mm-dd
  • Added the weekday getter

0.3.2 #

  • Sdk 2.1.0 support.
  • Some Linter rules applied

0.3.1 #

  • Dart 2 support

0.3.0 #

  • Initial version

example/example.dart

// Copyright (c) 2017, Giorgio. All rights reserved. Use of this source code
// is governed by a BSD-style license that can be found in the LICENSE file.

import 'package:intl/date_symbol_data_local.dart' show initializeDateFormatting;

import 'package:vy_date/vy_date.dart';

void main() async {
  Date date = Date.now();
  final Date nextDay = date.add(Duration(days: 1));
  final DatePeriodAssembler period = DatePeriodAssembler(date, nextDay);
  // prints: "Number of days: 2"
  print('Number of days: ${period.inDays}');
  // print "Difference in days: 1"
  print('Difference in days: ${nextDay.difference(date).inDays}');
  // prints "Date is before nextDay: true"
  print('Date is before nextDay: ${date.isBefore(nextDay)}');
  // print "Date is after nextDay: false"
  print('Date is after nextDay: ${date.isAfter(nextDay)}');

  date = Date(2020, 05, 12);

  // print "toString(): 2020-05-12"
  print('toString(): $date');
  // print "Month (May): 5"
  print('Month (May): ${date.month}');

  /// before using toYMdString() we have to initialize intl
  try {
    print('Date in YMD format: ${date.toYMdString('en_us')}');
  } catch (e) {
    print(e);
  }

  // this must be done just once for the whole application for each locale used
  await initializeDateFormatting('en_us');
  // print "Date in YMd format: 5/12/2020"
  print('Date in YMD format: ${date.toYMdString('en_us')}');

  /// intl initialization (as above) must have been performed before
  /// calling toYMMMMdString()
  // print "Date in YMMMMd format: May 12, 2020"
  print('Date in YMMMMd format: ${date.toYMMMMdString('en_us')}');

}

Use this package as a library

1. Depend on it

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


dependencies:
  vy_date: ^0.4.0

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:vy_date/vy_date.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
21
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
90
Overall:
Weighted score of the above. [more]
59
Learn more about scoring.

We analyzed this package on Feb 12, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.1
  • pana: 0.13.5

Health suggestions

Format lib/src/date_period.dart.

Run dartfmt to format lib/src/date_period.dart.

Format lib/vy_date.dart.

Run dartfmt to format lib/vy_date.dart.

Maintenance issues and suggestions

Support latest dependencies. (-10 points)

The version constraint in pubspec.yaml does not support the latest published versions for 1 dependency (intl).

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.2.0 <3.0.0
intl ^0.15.7 0.15.8 0.16.1
quiver ^2.0.1 2.1.2+1
Transitive dependencies
matcher 0.12.6
meta 1.1.8
path 1.6.4
stack_trace 1.9.3
Dev dependencies
pedantic 1.8.0
test ^1.6.0