Skip to content

Latest commit

 

History

History
508 lines (351 loc) · 11.7 KB

API.md

File metadata and controls

508 lines (351 loc) · 11.7 KB
Raw

API Documentation

Day.dart uses dart:core's DateTime class and expand its functionality to make it more useful.

Also inherit from Day.js, part of manipulations is immutable.

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 will 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 will call DateTime.fromMillisecondsSinceEpoch() to initialize a Day.

final d = Day.fromUnix(0);

From Day Instance

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

Clone

Call .clone() will return 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 associate with the unit from 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)

Different from Day.js, Day.dart won't create a new Instance after setting.

All set methods will change the origin instance.

You must call .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() support unit shorthand (See Above).

Use .setValue() for semantics.

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('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.

Due to the DateTime.parse can parse out-of-range date, as the doc described:

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 wanna receive a non-overflow date, you should use .addRound() method below.

final d = Day();

d.add(1, 'date');

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.

So if you wanna receive a non-overflow date, you should use .subtractRound() method below.

Refer to .add() for more details.

final d = Day();

d.subtract(1, 'date');

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 with specific format. If no format passed, the .format() will call .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 min 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 a number with the difference between two days by 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

Support unit shorthand. If the unit is null, it will be set to ms.

Compare To

Compare this day to other, returning zero if the values are equal.

-1 is before, 1 is after.

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

now.compareTo(afterNow); // -1

Is Before

Returns true if this day occurs before other.

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

now.isBefore(afterNow); // true

Is After

Returns true if this day occurs after 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();