Nepali date & time
NepaliDateTime is a DateTime whose fields are in the Bikram Sambat (BS) calendar. It implements DateTime, so it works like the one you know:
- It stores an exact instant (
microsecondsSinceEpoch). - It shows its fields in a time zone: local, UTC, or Nepal Time (UTC+05:45).
- You can pass it anywhere a
DateTimeis expected for instant-based operations, such as comparing, sorting,differenceand epoch values.
The difference is that year, month and day are BS values, and weekday starts on Sunday.
final constitutionDay = NepaliDateTime.parse('2072-06-03T17:00:00');
print(constitutionDay); // 2072-06-03 17:00:00.000print(constitutionDay.year); // 2072print(constitutionDay.month); // 6 (Ashwin)print(constitutionDay.weekday); // 1 (Sunday)print(constitutionDay.toDateTime()); // 2015-09-20 17:00:00.000Creating dates
Section titled “Creating dates”| Constructor | Time zone | Like |
|---|---|---|
NepaliDateTime(year, [month, day, hour, minute, second, millisecond, microsecond]) |
local | DateTime(...) |
NepaliDateTime.utc(...) |
UTC | DateTime.utc(...) |
NepaliDateTime.nepal(...) |
Nepal Time | — |
NepaliDateTime.now() |
local | DateTime.now() |
NepaliDateTime.nepalNow() |
Nepal Time | — |
NepaliDateTime.fromDateTime(dateTime) |
same as dateTime |
— |
NepaliDateTime.fromMicrosecondsSinceEpoch(us, {isUtc}) |
local or UTC | DateTime.fromMicrosecondsSinceEpoch |
NepaliDateTime.fromMillisecondsSinceEpoch(ms, {isUtc}) |
local or UTC | DateTime.fromMillisecondsSinceEpoch |
NepaliDateTime.parse(string) / tryParse(string) |
depends on the string | DateTime.parse |
final local = NepaliDateTime(2080, 1, 1);final utc = NepaliDateTime.utc(2080, 1, 1);final npt = NepaliDateTime.nepal(2080, 1, 1);
print(utc.toIso8601String()); // 2080-01-01T00:00:00.000Zprint(npt.toIso8601String()); // 2080-01-01T00:00:00.000+05:45print(npt.toUtc()); // 2079-12-30 18:15:00.000ZMonths and weekdays have named constants:
NepaliDateTime(2081, NepaliDateTime.shrawan, 1);date.weekday == NepaliDateTime.saturday;| Months | Value |
|---|---|
baishakh, jestha, ashadh, shrawan, bhadra, ashwin |
1–6 |
kartik, mangsir, poush, magh, falgun, chaitra |
7–12 |
| Weekdays | Value |
|---|---|
sunday, monday, tuesday, wednesday, thursday, friday, saturday |
1–7 |
Supported range
Section titled “Supported range”NepaliDateTime.minYear is 1969 and NepaliDateTime.maxYear is 2250. Creating a date outside that range throws a RangeError. parse throws a FormatException instead.
Out-of-range values are normalised
Section titled “Out-of-range values are normalised”Like DateTime, components that are too large or too small roll over into the next or previous unit, using the real length of each BS month:
NepaliDateTime(2080, 1, 35); // 2080-02-04 (Baishakh 2080 has 31 days)NepaliDateTime(2080, 13); // 2081-01-01NepaliDateTime(2080, 2, 0); // 2080-01-31NepaliDateTime(2080, 1, 1, 25); // 2080-01-02 01:00:00.000Time zones
Section titled “Time zones”A NepaliDateTime is always one of three kinds:
| Kind | Created by | isUtc |
isNepalTime |
timeZoneName |
|---|---|---|---|---|
| Local | NepaliDateTime(...), now(), toLocal() |
false |
false |
the device’s zone |
| UTC | .utc(...), toUtc() |
true |
false |
UTC |
| Nepal Time | .nepal(...), nepalNow(), toNepalTime() |
false |
true |
NPT |
toLocal(), toUtc() and toNepalTime() keep the instant and change only how it’s shown:
final npt = NepaliDateTime.nepal(2081, 1, 1, 10, 30);
print(npt.toUtc().toIso8601String()); // 2081-01-01T04:45:00.000Zprint(npt.toUtc().toNepalTime().toIso8601String()); // 2081-01-01T10:30:00.000+05:45print(npt.timeZoneName); // NPTprint(npt.timeZoneOffset); // 5:45:00.000000“Now”: local time or Nepal time?
Section titled ““Now”: local time or Nepal time?”final now = NepaliDateTime.now(); // local time, like DateTime.now()final nowInNepal = NepaliDateTime.nepalNow(); // Nepal Time, on any deviceOn a device in Nepal the two are the same. On a device elsewhere, such as a user abroad, a CI server in UTC or a cloud function, now() gives the BS date at the device’s location, and nepalNow() gives the date in Nepal. Use nepalNow() when you need “today in Nepal”, for example for business days or Nepali holidays.
Converting between AD and BS
Section titled “Converting between AD and BS”toNepaliDateTime() on any DateTime, and toDateTime() on a NepaliDateTime, convert between the calendars. Both keep the instant and the time zone:
final bs = DateTime(2019, 8, 3, 14, 30, 15).toNepaliDateTime();print(bs); // 2076-04-18 14:30:15.000
final ad = bs.toDateTime();print(ad); // 2019-08-03 14:30:15.000A UTC DateTime gives a UTC NepaliDateTime. Add .toNepalTime() to show it in Nepal Time:
final instant = DateTime.utc(2024, 1, 1);
print(instant.toNepaliDateTime()); // 2080-09-16 00:00:00.000Zprint(instant.toNepaliDateTime().toNepalTime()); // 2080-09-16 05:45:00.000NepaliDateTime.fromDateTime(dateTime) does the same as dateTime.toNepaliDateTime(). If its argument already is a NepaliDateTime, both return it unchanged.
toDateTime() returns a UTC DateTime for a UTC value and a local DateTime otherwise, because a DateTime can’t hold Nepal Time on a device outside Nepal. The instant is always the same:
NepaliDateTime.utc(2080, 1, 1).toDateTime(); // 2023-04-14 00:00:00.000ZParsing
Section titled “Parsing”NepaliDateTime.parse accepts the same formats as DateTime.parse, but the date is in BS:
NepaliDateTime.parse('2080-01-15'); // 2080-01-15 00:00:00.000 (local)NepaliDateTime.parse('2080-01-15 10:30:00'); // 2080-01-15 10:30:00.000 (local)NepaliDateTime.parse('20800115'); // 2080-01-15 00:00:00.000 (local)NepaliDateTime.parse('2080-01-15T10:30:00Z'); // 2080-01-15 10:30:00.000ZNepaliDateTime.parse('2080-01-15T10:30:00.123456Z'); // 2080-01-15 10:30:00.123456ZNepaliDateTime.parse('2080-01-15T10:30:00+01:00'); // 2080-01-15 09:30:00.000ZNepaliDateTime.parse('2080-01-15T10:30:00+05:45'); // Nepal Time, 10:30- With no time zone, the result is local.
- With
Zor any offset, the result is UTC. The one exception is+05:45, which gives a Nepal Time value. - Invalid input, including years outside 1969–2250, throws a
FormatException.tryParsereturnsnullinstead.
NepaliDateTime.tryParse('2080/01/01'); // nullTo parse text in a custom layout such as Baishakh 15, 2080, extract the numbers yourself, then call the constructor.
Reading fields
Section titled “Reading fields”| Getter | Meaning |
|---|---|
year, month, day |
BS date (month 1 = Baishakh, day 1–32) |
hour, minute, second, millisecond, microsecond |
wall-clock time in the value’s time zone |
weekday |
1 (Sunday) – 7 (Saturday) |
totalDays |
number of days in this BS month |
totalDaysInYear |
number of days in this BS year |
isUtc, isNepalTime, timeZoneName, timeZoneOffset |
the time zone |
BS months have 29 to 32 days, and the lengths change from year to year:
NepaliDateTime(2081, 2).totalDays; // 32 (Jestha 2081)NepaliDateTime(2081, 9).totalDays; // 29 (Poush 2081)NepaliDateTime(2072).totalDaysInYear; // 365Changing dates
Section titled “Changing dates”copyWith replaces fields and keeps the time zone. The result is normalised like the constructor’s:
final date = NepaliDateTime.parse('2072-06-03T17:00:00');
date.copyWith(month: 2); // 2072-02-03 17:00:00.000date.copyWith(day: 40); // 2072-07-10 17:00:00.000date.mergeTime(10, 20, 30); // 2072-06-03 10:20:30.000mergeTime(hour, minute, second) keeps the date, sets the time, and clears milliseconds and microseconds.
Two common tasks:
// Last day of the month: day 0 of the next month.final first = NepaliDateTime(2081, 5, 1);first.copyWith(month: first.month + 1, day: 0); // 2081-05-31
// "Same day next month" can overflow. Jestha 2081 has 32 days, Ashadh 31.NepaliDateTime(2081, 2, 32).copyWith(month: 3); // 2081-04-01Arithmetic and comparison
Section titled “Arithmetic and comparison”add, subtract, difference, isBefore, isAfter, isAtSameMomentAs and compareTo work on the instant. They accept any DateTime, so you can mix AD and BS values:
NepaliDateTime(2080, 12, 25).add(const Duration(days: 10)); // 2081-01-05NepaliDateTime(2080, 1, 1).subtract(const Duration(days: 1)); // 2079-12-30
NepaliDateTime.utc(2081, 1, 1).difference(NepaliDateTime.utc(2080, 1, 1)).inDays; // 365
final bs = NepaliDateTime.utc(2080, 1, 1);bs.isBefore(DateTime.utc(2023, 4, 15)); // truebs.difference(DateTime.utc(2023, 1, 1)); // 2472:00:00.000000
final dates = <DateTime>[ NepaliDateTime.utc(2081, 1, 1), DateTime.utc(2020, 1, 1), NepaliDateTime.utc(2070, 1, 1),]..sort();// [2070-01-01 00:00:00.000Z, 2020-01-01 00:00:00.000Z, 2081-01-01 00:00:00.000Z]Equality
Section titled “Equality”Like DateTime, == is true only when the instant and the time zone both match. To compare only the instant, use isAtSameMomentAs:
final npt = NepaliDateTime.nepal(2080, 1, 1);
npt == NepaliDateTime.nepal(2080, 1, 1); // truenpt == npt.toUtc(); // false: different zonenpt.isAtSameMomentAs(npt.toUtc()); // trueFormatting
Section titled “Formatting”toString() and toIso8601String() match DateTime’s format. Nepal Time values end in +05:45 in ISO form:
NepaliDateTime.utc(2080, 1, 1).toString(); // 2080-01-01 00:00:00.000ZNepaliDateTime.nepal(2080, 1, 1).toIso8601String(); // 2080-01-01T00:00:00.000+05:45For anything else, use format or NepaliDateFormat:
final date = NepaliDateTime.parse('2072-06-03T17:00:00');
date.format('yyyy-MM-dd'); // 2072-06-03date.format('yyyy MMMM d, EEEE', .nepali); // २०७२ आश्विन ३, आइतबारNepaliDateFormat.yMMMMEEEEd().format(date); // Sunday, Ashwin 3, 2072Gotchas
Section titled “Gotchas”toNepaliDateTime()keeps the zone in 4.0. To get the 3.x behaviour, add.toNepalTime().DateTimemethods that take aDateTimetreat aNepaliDateTimeas an instant.DateTime(2023).isBefore(nepaliDate)works, butDateTime’s ownyearandmonthare still AD values.
See also
Section titled “See also”NepaliDateTimeAPIENepaliDateTimeextension (toNepaliDateTime())- Date formatting
- Relative time
