Skip to content

API.md

Latest commit

 

History

History
516 lines (357 loc) · 12 KB

API.md

File metadata and controls

516 lines (357 loc) · 12 KB
Raw

API Documentation

Day.dart uses dart:core's DateTime class and expands its functionality to make dates easier to work with.

Day.dart also inherits from Day.js and retains the immutability of some of its operations.

Import

import 'package:day/day.dart';

With plugins:

import 'package:day/day.dart';
import 'package:day/plugins/is_leap_year.dart';

Constructor

Without Parameter

If you don't pass a parameter to Day, it returns the current time.

final now = Day();

From String

ISO 8601 string.

Day.fromString('2019-04-30T10:30:30.000Z');

From DateTime

Pass a DateTime instance.

final now = Day.fromDateTime(DateTime.now());

From Unix

This calls DateTime.fromMillisecondsSinceEpoch() to initialize a Day.

final d = Day.fromUnix(0);

From Day Instance

final now = Day();
final afterNow = Day.fromDayInstance(now);

Clone

Calling .clone() returns a new day instance.

final now = Day();
final nowClone = now.clone();

Get And Set

Year .year()

Gets or sets the year.

final d = Day();

d.year();
d.year(2020);

Month .month()

Gets or sets the month. Starts at 1.

final d = Day();

d.month();
d.month(1);

Day of the month .date()

Gets or sets the date. Starts at 1.

final d = Day();

d.date();
d.date(1);

Day of the week .weekday()

Get the weekday. Starts at 1. (Only Get, No Set)

final d = Day();

d.weekday();

Hour .hour()

Gets or sets the hour.

final d = Day();

d.hour();
d.hour(12);

Minute .minute()

Gets or sets the minute.

final d = Day();

d.minute();
d.minute(45);

Second .second()

Gets or sets the second.

final d = Day();

d.second();
d.second(55);

Millisecond .millisecond()

Gets or sets the millisecond.

final d = Day();

d.millisecond();
d.millisecond(128);

Get .get(String unit)

Returns a number associated with the unit of a Day instance.

final d = Day();

d.get('month');
d.get('date');
d.get('weekday');

List of all available units

Unit Shorthand Description
year y Year
month M Month (January as 1, December as 12)
date d Date of Month
weekday w Day of Week (Monday as 1, Sunday as 7)
hour h Hour
minute m Minute
second s Second
millisecond ms Millisecond

Set .set(String unit, int val)

Unlike Day.js, Day.dart won't create a new instance after setting.

All set methods change the original instance.

You must call the .finished() method to apply all changes.

For example:

final d = Day.fromString('2019-04-30T10:30:30.000Z');

d
  ..setYear(2020)
  ..setMonth(5)
  ..setDate(1)
  ..finished();

List of all available methods

Only .set() supports unit shorthand (see above).

Use .setValue() with full unit names.

d
  ..set('y', 2020)
  ..set('M', 5)
  ..set('d', 1)
  ..finished();
Method Shorthand Shorthand2
.setYear() setValue('year', 2020) set('y', 2020)
.setMonth() setValue('month', 5) set('M', 5)
.setDate() setValue('date', 1) set('d', 1)
.setHour() setValue('hour', 11) set('h', 11)
.setMinute() setValue('minute', 31) set('m', 31)
.setSecond() setValue('second', 31) set('s', 31)
.setMillisecond() setValue('millisecond', 1) set('ms', 1)

Manipulating

Day.fromString('2019-04-30')
  .add(1, 'date')
  .subtract(1, 'year')
  .toString(); // 2018-05-01 00:00:00.000

Add .add(int val, String unit)

Returns a cloned day with a specified amount of time added.

Use week or w to add whole weeks.

Due to the fact that DateTime.parse can parse out-of-range dates, as its documentation describes:

This method accepts out-of-range component values and interprets them as overflows into the next larger component. For example, "2020-01-42" will be parsed as 2020-02-11, because the last valid date in that month is 2020-01-31, so 42 days is interpreted as 31 days of that month plus 11 days into the next month.

So if you want a date without overflow, use the .addRound() method below.

final d = Day();

d.add(1, 'date');
d.add(1, 'week');
d.add(1, 'w');

Add Round .addRound(int val, String unit)

Returns a cloned day with a specified amount of time added but rounded to the last day of the current month if overflowed.

final d = Day.fromString('2022-03-31T15:52:50.000Z');

d.add(1, 'month'); // 2022-05-01T15:52:50.000Z
d.addRound(1, 'month'); // 2022-04-30T15:52:50.000Z

Subtract .subtract(int val, String unit)

Returns a cloned day with a specified amount of time subtracted.

Use week or w to subtract whole weeks.

So if you want a date without overflow, use the .subtractRound() method below.

Refer to .add() for more details.

final d = Day();

d.subtract(1, 'date');
d.subtract(1, 'week');
d.subtract(1, 'w');

Subtract Round .subtractRound(int val, String unit)

Returns a cloned day with a specified amount of time subtracted but rounded to the last day of the current month if overflowed.

final d = Day.fromString('2022-03-31T15:52:50.000Z');

d.subtract(1, 'month'); // 2022-03-03T15:52:50.000Z
d.subtractRound(1, 'month'); // 2022-02-28T15:52:50.000Z

Inc (Same as add)

A .add() shorthand.

final d = Day();

d.inc(1, 'date');

Dec (Same as subtract)

A .subtract() shorthand.

final d = Day();

d.dec(1, 'date');

Displaying

Format .format()

Returns a string in a specific format. If no format is passed, .format() calls .toIso8601String().

Day().format(); // 2019-05-08T16:38:31.721959
Day.fromString('2019-05-08').format('YYYY-MM-DDTHH:mm:ss'); // 2019-05-08T00:00:00

List of all available formats

Format Output Description
[escape] escape Escape string in []
YY 19 Two-digit year
YYYY 2019 Four-digit year
M 1-12 The month, beginning at 1
MM 01-12 The month, 2 digits
MMM Jan-Dec The abbreviated month name
MMMM January-December The full month name
D 1-31 The day of the month
DD 01-31 The day of the month, 2 digits
W 1-7 The day of the week
WW Mo-Su The minimal name of the day of the week
WWW Mon-Sun The short name of the day of the week
WWWW Monday-Sunday The name of the day of the week
H 0-23 The hour
HH 00-23 The hour, 2 digits
h 1-12 The hour, 12 hour clock
hh 01-12 The hour, 12 hour clock, 2 digits
m 0-59 The minute
mm 00-59 The minute, 2 digits
s 0-59 The second
ss 00-59 The second, 2 digits
SSS 000-999 The millisecond, 3 digits
A AM PM
a am pm

As String

Returns a human-readable string for this day.

Day().toString();

As ISO 8601 String

Returns an ISO-8601 full-precision extended format representation.

Day().toIso8601String();

Time zone Name

The time zone name.

Day().timeZoneName;

Time zone Offset

The time zone offset, which is the difference between local time and UTC.

Day().timeZoneOffset;

Query

Difference

Returns the difference between two days as a number in the specified unit.

final d1 = Day.fromString('2019-04-30T10:30:30.000Z');
final d2 = Day.fromString('2021-05-01T10:30:30.000Z');

d1.diff(d2, 'y'); // -2

Supports unit shorthand. If the unit is omitted, it defaults to ms.

Compare To

Compares this day to another, returning zero if the values are equal.

Returns -1 if before, 1 if after.

final now = Day();
final afterNow = now.add(1, 's');

now.compareTo(afterNow); // -1

Is Before

Returns true if this day occurs before the other.

final now = Day();
final afterNow = now.add(1, 's');

now.isBefore(afterNow); // true

Is After

Returns true if this day occurs after the other.

final now = Day();
final afterNow = now.add(1, 's');

now.isAfter(afterNow); // false

Is Utc

True if this day is set to UTC time.

Day().isUtc;

Transformation

To Utc

Returns this day in the UTC time zone.

Day().toUtc();

To Local

Returns this day in the local time zone.

Day.fromString('2019-04-30T10:30:30.000Z').toLocal();

To DateTime

Returns this day's DateTime instance.

Day.fromString('2019-04-30T10:30:30.000Z').toDateTime();