{"id":25066812,"url":"https://github.com/fatulm/shamsi_date","last_synced_at":"2025-04-12T10:15:57.927Z","repository":{"id":45101483,"uuid":"161029052","full_name":"FatulM/shamsi_date","owner":"FatulM","description":"A Flutter and Dart package for using Jalali (Shamsi, Solar, Persian, Jalaali, شمسی or خورشیدی) calendar.   You can convert, format and manipulate Jalali and Gregorian (Miladi or میلادی) date and times.","archived":false,"fork":false,"pushed_at":"2024-08-18T14:28:22.000Z","size":411,"stargazers_count":80,"open_issues_count":0,"forks_count":12,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-12T10:15:30.955Z","etag":null,"topics":["calendar","dart","date","datetime","flutter","gregorian","jalaali","jalali","julian","persian","shamsi","solar","time"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/shamsi_date","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FatulM.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-09T10:44:12.000Z","updated_at":"2025-04-05T16:24:58.000Z","dependencies_parsed_at":"2024-07-07T12:31:34.344Z","dependency_job_id":"ab7142ed-51d4-4fda-bb00-2eb29fc55f2b","html_url":"https://github.com/FatulM/shamsi_date","commit_stats":{"total_commits":263,"total_committers":5,"mean_commits":52.6,"dds":0.03041825095057038,"last_synced_commit":"0ecb207ba96db2d671e3cf87beecf7c5d539602e"},"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FatulM%2Fshamsi_date","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FatulM%2Fshamsi_date/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FatulM%2Fshamsi_date/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FatulM%2Fshamsi_date/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FatulM","download_url":"https://codeload.github.com/FatulM/shamsi_date/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248550617,"owners_count":21122934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calendar","dart","date","datetime","flutter","gregorian","jalaali","jalali","julian","persian","shamsi","solar","time"],"created_at":"2025-02-06T20:28:08.432Z","updated_at":"2025-04-12T10:15:57.888Z","avatar_url":"https://github.com/FatulM.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A Flutter and Dart package for using Jalali (Shamsi, Solar, Persian, Jalaali, شمسی or خورشیدی) calendar. You can convert, format and manipulate Jalali and Gregorian (Miladi or میلادی) date and times.\n\n[![pub](https://img.shields.io/pub/v/shamsi_date.svg?color=blue\u0026label=shamsi_date)](https://pub.dev/packages/shamsi_date)\n[![build](https://img.shields.io/github/actions/workflow/status/FatulM/shamsi_date/.github/workflows/build.yml?branch=master\u0026label=build)](https://github.com/FatulM/shamsi_date/actions/workflows/build.yml)\n[![coverage](https://img.shields.io/codecov/c/gh/FatulM/shamsi_date?label=coverage)](https://codecov.io/gh/FatulM/shamsi_date)\n\nThis is a pure dart package and Algorithm is based on popular JavaScript library [jalaali-js](https://github.com/jalaali/jalaali-js) with more than 20k monthly downloads.\n\nThis package has a lot of unit tests with high test coverage for ensuring its correctness.\n\n## Key Features\n\n- Convert between [Jalali][], [Gregorian][] and Flutter's [DateTime][] objects.\n- Access year, month, day, weekday, Julian day number, month length and ... through getters.\n- Format Jalali and Georgian dates with an easy and powerful syntax using [DateFormatter][].\n- Ensure Jalali and Georgian dates validity.\n- Check if a Jalali or Gregorian year is leap.\n- Immutable date objects with copy methods for easy manipulation.\n- Compare Dates easily with comparison operators or by using [Comparable][].\n- Add or subtract days with `+` and `-` operators.\n- Find distance between dates by methods and `^` operator.\n- Add years, months and days separately or as a combination with methods.\n- High code coverage with a lot of unit tests.\n- Null-Safe API.\n- Support time information.\n\n## Recent Changes\n\nAs of version `1.0.4` there is a `mNAf` getter on `JalaliFormatter` to get month names in **Afghanistan**.\n\nAs of version `1.0.3` there is a `fromMillisecondsSinceEpoch` factory method for Jalali and Gregorian.\n\nAs of version `1.0.1` there is `time` getter for Jalali and Gregorian to acquire time information in Duration.\n\nAs of version `1.0.0` Jalali and Gregorian include **time information**.\n\n## Issues and feature requests\n\nIf you want a new feature, or you found an issue, please make an issue on GitHub, so I can see your request.\n\n## Usage\n\nAdd it to your pubspec.yaml file:\n\n```yaml\ndependencies:\n    shamsi_date: ^latest.version\n```\n\nThen depend on it:\n\n```dart\nimport 'package:shamsi_date/shamsi_date.dart';\n```\n\n[Jalali][] class is used for **Shamsi (Jalali, Persian, شمسی or خورشیدی)** date and [Gregorian][] class is used for **Gregorian (Miladi or میلادی)** date. Jalali and Gregorian classes are the subclasses of [Date][].\n\nJalali and Gregorian can be instantiated with providing `year`, `month` and `day` among other ways:\n\n```dart\nJalali j = Jalali(year, month, day);\nGregorian g = Gregorian(year, month, day);\n```\n\nyou can also provide time information with `hour`, `minute`, `second` and `millisecond`.\n\n```dart\nJalali j = Jalali(year, month, day, hour, minute, second, millisecond);\nGregorian g = Gregorian(year, month, day, hour, minute, second, millisecond);\n```\n\nMonth and day has default value of `1` if you don't specify them, so `Jalali(year, month)` is equivalent to `Jalali(year, month, 1)` and `Gregorian(year)` is equivalent to `Gregorian(year, 1, 1)`. And also hour, minute, second and millisecond will default to `0` if not provided.\n\nConstructor arguments should be non-null or exception will be thrown immediately. This ensures objects being in valid state when created. So year, month and day are always non-null. Almost all methods, operators, constructors and factories should have non-null arguments, and they will return non-null objects. For example year, month and day getters will return non-null results. The only exception for methods which can accept null arguments are methods with optional arguments like `add(...)` and `copy(...)`. **in nullsafe version:** nullable and non-nullable argument and return types are checked statically.\n\nAll created date instances are valid. When creating a date instance either by using constructors and factories or by using methods and operators on an existing date instance, if the new date is invalid (by its month or day being out of range), or it is out of computable range, a [DateException][] exception is thrown. So if you think the new date instance can become invalid or out of range you should surround it with try-catch and catching `DateException`. Minimum computable date is `Gregorian(560,3,20)` or equivalently `Jalali(-61,1,1)` and Maximum computable date is `Gregorian(3798,12,31)` or equivalently `Jalali(3177,10,11)`. For example:\n\n```dart\nvoid main() {\n  try {\n    Jalali jv = Jalali(1398, 13, 1); // not valid!\n  } on DateException catch (e) {\n    // prints: DateException: Jalali month is out of valid range.\n    print(e);\n  }\n}\n```\n\nJalali and Gregorian objects are immutable. So using operators and methods will give you  new object and does not manipulate the object in place, like String objects. Almost all other objects in shamsi_date library are immutable too.\n\nYou can access `year`, `month`, `day`, `hour`, `minute`, `second` and `millisecond` through getters on Jalali or Gregorian dates. You can get week day number of Jalali and Gregorian by using `weekDay` getter. Week days range from 1 to 7. Jalali week starts with `Shanbe` and Gregorian week starts with `Monday`. Month length can be accessed using `monthLength` getter. Month length is sensitive to leap years. you can check if the year is a leap year by `isLeapYear()` method. Julian day number is also accessible through `julianDayNumber` getter. for example:\n\n```dart\nJalali j = Jalali(1397, 5, 6, 12, 56, 34, 585);\n\nint jy = j.year; // 1397\nint jm = j.month; // 5\nint jd = j.day; // 6\nint jth = j.hour; // 12\nint jtm = j.minute; // 56\nint jts = j.second; // 34\nint jtms = j.millisecond; // 585\n\nint wd = j.weekDay; // wd = 1 (Shanbe)\n\n// month length of 1397/5\n// note: day value is not important for monthLength\nint ml = j.monthLength; // ml = 31\n\n// check if 1397 is a leap year\n// note: month and day values are not important for isLeapYear() method\nbool ly = j.isLeapYear(); // ly = false (1397 is not leap year)\n\n// and equivalently for Gregorian date objects ...\n```\n\nYou can convert Jalali dates to Gregorian by using `toGregorian()` method and convert Gregorian to Jalali date by using `toJalali()` method. There are also factory methods `Jalali.fromGregorian(...)` and `Gregorian.fromJalali(...)` which can be used alternatively.\n\n```dart\nJalali j = Jalali(1397, 5, 6);\n// convert to Gregorian:\nGregorian j2g1 = j.toGregorian(); // -\u003e 2018/8/28\n// or equivalently:\nGregorian j2g2 = Gregorian.fromJalali(j);\n\nGregorian g = Gregorian(2019, 10, 26);\n// convert to Jalali:\nJalali g2j1 = g.toJalali(); // -\u003e 1398/8/4\n// or equivalently:\nJalali g2j2 = Jalali.fromGregorian(g);\n```\n\nYou can convert [DateTime][] objects directly to Jalali or Gregorian dates by using `fromDateTime(dateTime)` static methods. Convert Jalali and Gregorian to DateTime by using `toDateTime()` method. You can pass `hour`, `minute` and other time details to arguments. There is also `toUtcDateTime` for UTC date times. Get Jalali and Gregorian dates for now by using `now()` factory.\n\n```dart\n// convert from DateTime\nJalali j = Jalali.fromDateTime(dateTime);\nGregorian g = Gregorian.fromDateTime(dateTime);\n\n// convert to DateTime\nDateTime j2dt = j.toDateTime();\nDateTime g2dt = g.toDateTime();\n\n// and also convert to UTC:\nDateTime j2dt2 = j.toUtcDateTime();\n\n// get now\nJalali jNow = Jalali.now();\nGregorian gNow = Gregorian.now();\n```\n\nFor converting [DateTime][] you can also use extension methods.\n\n```dart\nDateTime dt = DateTime.now();\nJalali j = dt.toJalali();\nGregorian g = dt.toGregorian();\n```\n\nAlso you can create Jalali and Gregorian dates using millisecondsSinceEpoch factory method, which supports making dates in UTC timezone.\n\n```dart\nJalali j = Jalali.fromMillisecondsSinceEpoch(1722782031520);\n```\n\nBut keep in mind that Jalali and Gregorian dates do not store timezone information, So they won't store millisecondsSinceEpoch property internally.\n\nJalali and Georgian dates are immutable, so you can not change their properties in place. if you want only to change some fields of a Jalali or Gregorian date you can use `copy(...)` method or `withYear`, `withMonth` and `withDay` methods on an existing object. These methods can be chained. copy method changes all fields at one. **note** that copy and with*() methods are not safe, and it is your responsibility to avoid problems like month length bound (for example changing month of `31 Farvardin 1390` to `Esfand`) or leap crash (for example being in last day of year in a leap year and changing year to a non-leap one) in intermediate steps. order of operations is important.\n\nFor example for getting date at start of this month in Jalali: (copy method makes another object instance and leaves the original one unchanged)\n\n```dart\nJalali j1 = Jalali.now().withDay(1); // correct way\n// or by using copy method:\nJalali j2 = Jalali.now().copy(day: 1); // also correct\n\n// DON NOT do it like this:\nJalali j3 = Jalali(Jalali.now().year, Jalali.now().month, 1); // INCORRECT\n```\nOr if you want to get last day of the last month of this Jalali year:\n```dart\n// at first go to first day of last month: (Avoid leap crash)\nJalali tmp = Jalali.now().withDay(1).withMonth(12);\n// since we can be in a leap year we use monthLength for going to last day:\nJalali j = tmp.withDay(tmp.monthLength);\n\n// or by using copy method:\nJalali tmp1 = Jalali.now().copy(month: 12, day: 1);\nJalali j1 = tmp.copy(day: tmp1.monthLength);\n```\nor to find 3rd day of 2nd month of this year:\n```dart\nJalali j = Jalali.now().withDay(3).withMonth(2);\n\n// or by using copy method:\nJalali j1 = Jalali.now().copy(month: 2, day: 3);\n```\nOr If you want your Jalali and Gregorian objects to fall back to today if null is provided as their constructor arguments you can use copy method from now factory method, for example for Jalali:\n```dart\nJalali j = Jalali.now().copy(year: y, month: m, day: d);\n// y, m and d can be null\n```\n\nYou can find distance between Jalali and Gregorian dates by using `^` operator. Note that `-` operator is for something else. Or you can use `distanceTo` and `distanceFrom` methods.\n```dart\nint distance11 = Jalali.now() ^ Jalali(1395, 10, 1);\n// or\nint distance12 = Jalali.now().distanceFrom(Jalali(1395, 10, 1));\n// or\nint distance13 = Jalali(1395, 10, 1).distanceTo(Jalali.now());\n\n// and similarly for Gregorian\nint distance2 = Gregorian(2021) ^ Gregorian(2020);\n```\n\nYou can add and subtract days to Jalali and Gregorian using `+` and `-` operators. It is guaranteed to give you a bound valid date. for example, it will go to next month or next year if needed, and they won't have leap crash.\n\nYou can add years, months or days to  Jalali and Gregorian using `addYears`, `addMonths` and `addDays`. These methods can be chained, and they will not have range crash. `addDays` can change month and year. `addMonths` can change year. **note** that it is your responsibility to avoid leap crash.\n\nIf you want you can add a combination of days, months or years to a date object with `add` method. **note** that `add` method is not safe and does not manipulate result to become bound valid, it is your responsibility. **It is recommended** to use addYear, addMonth and addDay methods over add method. **note** By using addYears, addMonth and addDay you can put day out of month length bounds. addMonth is safe for month overflow.\n\n```dart\nJalali j1 = Jalali(1398, 8, 4);\n// add days\nJalali j2 = j1 + 3; // -\u003e 1398/8/7\n// result will be manipulated to become valid:\nJalali j3 = j1 + 30; // -\u003e 1398/9/4\nJalali j4 = j1 + 365; // -\u003e 1399/8/4\n// subtract days\nJalali j5 = j1 - 2; // -\u003e 1398/8/2\n\n// add years, months and days:\nJalali j6 = j1.addYears(1).addMonths(2).addDays(3); // 1399/10/7\n// or:\nJalali j60 = j1.add(years: 1, months: 2, days: 3); // 1399/10/7\n// add years and days only:\nJalali j7 = j1.addYears(1).addDays(3); // 1399/8/7\n// or:\nJalali j70 = j1.add(years: 1, days: 3); // 1399/8/7\n// add months only:\nJalali j8 = j1.addMonths(2); // 1398/10/3\n// or:\nJalali j80 = j1.add(months: 2); // 1398/10/3\n// if you want to subtract you can add negative value:\nJalali j9 = j1.addYears(-1); // 1397/8/3\n// or:\nJalali j90 = j1.add(years: -1); // 1397/8/3\n\n// addYears, addMonths and addDays methods are bound safe\n// add(...) method is NOT bound safe\n```\n\nDate formatting is easy. You should make a function for custom formatting and then pass your Jalali or Gregorian dates to this function.\n\nFor example if you want to format as `WeekDayName Day MonthName TwoDigitYear` you make a function for it:\n\n```dart\nString format1(Date d) {\n  final f = d.formatter;\n\n  return '${f.wN} ${f.d} ${f.mN} ${f.yy}';\n}\n\n// example output for Jalali: \"پنج شنبه 21 دی 91\"\n// example output for Gregorian: \"Thursday 10 January 13\"\n```\n\nOr if you are living in **Afghanistan** you can use:\n\n```dart\nString format1Af(Jalali d) {\n  final f = d.formatter;\n\n  return '${f.wN} ${f.d} ${f.mNAf} ${f.yy}';\n}\n\n// example output: \"پنج شنبه 21 جدی 91\"\n```\n\nOr if you want to format as `FourDigitYear/TwoDigitMonth/TwoDigitDay` or `YYYY/MM/DD`, you make a function for it:\n\n```dart\nString format2(Date d) {\n  final f = d.formatter;\n\n  return '${f.yyyy}/${f.mm}/${f.dd}';\n}\n```\nThen use it like before.\n\n**Note** that formatter formats digits in English so if you want Persian digits you can use fonts with Persian digits or apply a simple mapping to formatter output to change English digits to Persian.\n\nJalali and Georgian dates support `toString()` method. For Jalali, it is semantically equivalent to use a formatter as `Jalali(Y,M,D)` which means:\n\n```dart\nString toStringFormatter(Jalali d) {\n  final f = d.formatter;\n\n  return 'Jalali(${f.y},${f.m},${f.d})';\n}\n```\nFor Georgian, toString() is equivalent to using a formatter as `Georgian(Y,M,D)`.\n\nNote: in the following code toString() is called implicitly:\n\n```dart\nvoid main() {\n    print(Jalali.now());\n    final str = 'today is: ${Georgian.now()}';\n}\n```\nUse toString() of Jalali and Georgian dates only for development purpose, like for debugging, logging or ... **You should** use formatters for showing dates on the UI.\n\n**Note** also that you do not need for example to use `int.parse()` on formatter output of `Jalali.now().formatter.m` for accessing its month, simply use `Jalali.now().month`.\n\n[DateFormatter][] has these getters:\n- y: year (whatever length it has). year should be positive.\n- yy: two digit year. year should be between 1000 and 9999.\n- yyyy: four digit year. year should be between 0 and 9999.\n- m: month (whatever length it has).\n- mm: two-digit month.\n- mN: month name.\n- mNAf: month name in **Afghanistan**. (**ONLY** for `JalaliFormatter`.)\n- d: day (whatever length it has).\n- dd: two digit day.\n- wN: week day name.\n\nYou can get date formatter by using `formatter` getter on Jalali and Gregorian date objects. Simply cash this formatter in a Jalali value and then use string interpolation (as we have shown in examples) for making your desired output. This way of formatting is more powerful (and arguably easier) than using templates.\n\nJalali and Gregorian classes are [Comparable][], so you can compare them using `compareTo` method. You can also use comparison operators to compare them. They also support `equals` and `hashCode` functions. So you can safely use Sets and Maps of Jalali and Gregorian dates.\n\n```dart\nJalali j1 = Jalali(1397, 1, 1);\nJalali j2 = Jalali(1397, 2, 1);\n\nbool b1 = j1 \u003c j2; // b1 = true\nbool b2 = j1 \u003e= j2; // b2 = false\n// using Comparable compareTo\nbool b3 = j1.compareTo(j2) \u003e 0; // b3 = false (means j1 \u003e j2 is false)\nbool b4 = j1.compareTo(j2) \u003c= 0; // b4 = true (means j1 \u003c= j2 is true)\nbool b5 = j1 == j2; // b5 = false\nbool b6 = j1 != j2; // b6 = true\n```\n\n## Example\n\nHere is a complete example. If you did not find what you are looking for, you can check `test/shamsi_date_test.dart` file which includes unit tests.\n\n```dart\nimport 'package:shamsi_date/shamsi_date.dart';\n\nvoid main() {\n  // Gregorian to Jalali conversion\n  Gregorian g1 = Gregorian(2013, 1, 10, 12, 56, 34, 585);\n  Jalali j1 = g1.toJalali();\n  print('$g1 == $j1');\n  // prints: Gregorian(2013,1,10) == Jalali(1391,10,21)\n  // you can write Jalali.fromGregorian(g1) instead of g1.toJalali()\n\n  // access year, month and day through getters\n  // for Jalali:\n  int j1y = j1.year; // j1y = 1391\n  int j1m = j1.month; // j1m = 10\n  int j1d = j1.day; // j1d = 21\n  int j1th = j1.hour; // j1th = 12\n  int j1tm = j1.minute; // j1tm = 56\n  int j1ts = j1.second; // j1ts = 34\n  int j1tms = j1.millisecond; // j1tms = 585\n  print('j1 is $j1y-$j1m-$j1d:$j1th-$j1tm-$j1ts-$j1tms');\n  // prints: j1 is 1397-10-21:12-56-34-585\n  // NOTE: use formatters for formatting dates\n  // and for Gregorian:\n  int g1y = g1.year; // g1y = 2013\n  int g1m = g1.month; // g1m = 1\n  int g1d = g1.day; // g1d = 10\n  print('g1 is $g1y-$g1m-$g1d'); // prints: g1 is 2013-1-10\n  // NOTE: use formatters for formatting dates\n\n  // Jalali to Gregorian conversion\n  Jalali j2 = Jalali(1391, 10, 21);\n  Gregorian g2 = j1.toGregorian();\n  print('$j2 == $g2');\n  // prints: Jalali(1391,10,21) == Gregorian(2013,1,10)\n  // also can use Gregorian.fromJalali(j1) instead of j1.toGregorian()\n\n  // find weekDay\n  print('$j1 has weekDay ${j1.weekDay}'); // -\u003e 6\n  // 6 means \"پنج شنیه\"\n  print('$g1 has weekDay ${g1.weekDay}'); // -\u003e 4\n  // 4 means \"Thursday\"\n\n  // find month length\n  print('Jalali 1390/12 month length? '\n      '${Jalali(1390, 12).monthLength}'); // -\u003e 29\n  print('Gregorian 2000/2 month length? '\n      '${Gregorian(2000, 2).monthLength}'); // -\u003e 29\n\n  // check leap year\n  print('1390 Jalali is leap year? '\n      '${Jalali(1390).isLeapYear()}'); // -\u003e false\n  print('2000 Gregorian is leap year? '\n      '${Gregorian(2000).isLeapYear()}'); // -\u003e true\n\n  // validity:\n  // ALL created instances are considered VALID\n  // if you think a date might invalid, use try-catch:\n  try {\n    Jalali jv = Jalali(1398, 13, 1); // not valid!\n    print(jv); // this line is not reached\n  } on DateException catch (e) {\n    // prints: DateException: Jalali month is out of valid range.\n    print(e);\n  }\n  // making leap crash will also throw exception:\n  // for ex: Jalali(1394, 12, 30) will crash, since\n  //  1394 is not leap year\n  // creating dates out of computable range also throws DateException.\n\n  // convert DateTime object to Jalali and Gregorian\n  DateTime dateTime = DateTime.now();\n  print('now is $dateTime');\n  print('now is ${Gregorian.fromDateTime(dateTime)} in Gregorian');\n  print('now is ${Jalali.fromDateTime(dateTime)} in Jalali');\n  // convert to DateTime\n  print('$j1 is ${j1.toDateTime()}');\n  print('$g1 is ${g1.toDateTime()}');\n\n  // convert Jalali and Gregorian to DateTime\n  print('$j1 as DateTime is ${j1.toDateTime()}');\n  print('$g1 as DateTime is ${g1.toDateTime()}');\n\n  // find today with now() factory method\n  print('now is ${Gregorian.now()} in Gregorian');\n  print('now is ${Jalali.now()} in Jalali');\n  // find out which jalali year is this year:\n  int thisJalaliYear = Jalali.now().year;\n  print('this Jalali year is $thisJalaliYear');\n\n  // copy method\n  print('$j1 with year = 1300 is ${j1.copy(year: 1300)}');\n  print('$j1 with hour = 23 is ${j1.copy(hour: 23)}');\n  // prints: 1391/10/21 with year = 1300 is 1300/10/21\n  print('$g1 with month = 1 and day = 2 is ${g1.copy(month: 1, day: 2)}');\n  // prints: 2013/1/10 with month = 1 and day = 2 is 2013/1/2\n\n  // withYear, withMonth and withDay methods:\n  // these methods can be chained\n  // it is recommended to use these methods over copy method\n  print('$j1 with year = 1300 is ${j1.withYear(1300)}');\n  // prints: 1391/10/21 with year = 1300 is 1300/10/21\n  print('$g1 with month = 1 and day = 2 is ${g1.withDay(2).withMonth(1)}');\n  // prints: 2013/1/10 with month = 1 and day = 2 is 2013/1/2\n\n  // for example for getting date at start of this month in Jalali:\n  print(Jalali.now().copy(day: 1));\n  // for example to find 3rd day of 2nd month of this year:\n  print(Jalali.now().copy(month: 2, day: 3));\n  // DON NOT do it like this:\n  print(Jalali(Jalali.now().year, Jalali.now().month, 1)); // INCORRECT\n  // for example if you want to get\n  // the last day of the last month of this Jalali year:\n  Jalali tmp = Jalali.now().copy(month: 12, day: 1);\n  // since we can be in a leap year we use monthLength:\n  print(tmp.copy(day: tmp.monthLength));\n\n  // add and subtract days\n  Jalali d1 = Jalali(1398, 8, 4);\n  // add days\n  print(d1 + 3); // -\u003e 1398/8/7\n  // result will be manipulated to become valid:\n  print(d1 + 30); // -\u003e 1398/9/4\n  print(d1 + 365); // -\u003e 1399/8/4\n  // subtract days\n  print(d1 - 2); // -\u003e 1398/8/2\n  // add years, months and days:\n  print(d1.add(years: 1, months: 2, days: 3)); // 1399/10/7\n  // add years and days only:\n  print(d1.add(years: 1, days: 3)); // 1399/8/7\n  // add months only:\n  print(d1.add(months: 2)); // 1398/10/3\n  // add hours and minutes:\n  print(d1.add(hours: 1, minutes: 30)); // 1398/10/3\n  // if you want to subtract you can add negative value:\n  print(d1.add(years: -1)); // 1397/8/3\n  // and also for Gregorian\n\n  // you can find distance between two days with \"^\" operator\n  int distance11 = Jalali.now() ^ Jalali(1395, 10);\n  int distance12 = Jalali.now().distanceFrom(Jalali(1395, 10));\n  int distance13 = Jalali(1395, 10).distanceTo(Jalali.now());\n  print('distance $distance11 $distance12 $distance13');\n  // and similarly for Gregorian\n\n  // or you can use addYears, addMonths and addDays method\n  // it is recommended to use these methods over add method\n  // these methods are bound valid which means result will be\n  //  manipulated to become valid, but add method is not\n  print(d1.addDays(30)); // -\u003e 1398/9/4\n  print(d1.addDays(365)); // -\u003e 1399/8/4\n  print(d1.addYears(1).addMonths(2).addDays(3)); // 1399/10/7\n  print(d1.addYears(1).addDays(3)); // 1399/8/7\n  print(d1.addMonths(2)); // 1398/10/3\n  print(d1.addYears(-1)); // 1397/8/3\n\n  // formatting examples:\n\n  // example one:\n  String format1(Date d) {\n    final f = d.formatter;\n\n    return '${f.wN} ${f.d} ${f.mN} ${f.yy}';\n  }\n\n  print(format1(j1)); // prints: پنج شنبه 21 دی 91\n  print(format1(g1)); // prints: Thursday 10 January 13\n\n  // for Afghani people:\n  String format1Af(Jalali d) {\n    final f = d.formatter;\n\n    return '${f.wN} ${f.d} ${f.mNAf} ${f.yy}';\n  }\n\n  print(format1Af(j1)); // prints: پنج شنبه 21 جدی 91\n\n  // example two:\n  String format2(Date d) {\n    final f = d.formatter;\n\n    return '${f.dd}/${f.mm}/${f.yyyy}';\n  }\n\n  print(format2(j1)); // prints: 21/10/1391\n  print(format2(g1)); // prints: 10/01/2013\n\n  // DO NOT use formatter for accessing year, month or other properties\n  // of date objects they are available as getters on date objects\n  // INCORRECT EXAMPLE, DO NOT USE THIS:\n  int j1y1 = int.parse(j1.formatter.yyyy); // INCORRECT\n  print(\"j1's year is $j1y1\");\n  // use this:\n  int j1y2 = j1.year; // correct\n  print(\"j1's year is $j1y2\");\n  // also using toString() for showing dates on UI is not recommended,\n  // use custom formatter.\n\n  // comparing dates examples:\n  print(j1 \u003e j2); // -\u003e false\n  print(j1.compareTo(j2) \u003e 0); // -\u003e false\n  print(j1 \u003c= j2); // -\u003e true\n  print(j1.compareTo(j2) \u003c= 0); // -\u003e true\n  print(g1 \u003e= g2); // -\u003e true\n  print(g1.compareTo(g2)); // -\u003e 0\n  print(g1 == g2); // -\u003e true\n  print(g1 != g1); // -\u003e false\n\n  // if you want to compare Jalali with Georgian\n  // you can convert one type to another,\n  // for example:\n  print(j1.toGregorian() == g1); // -\u003e true\n  // but if you don't want to convert them you can use julianDayNumber\n  // (this approach is not recommended)\n  print(j1.julianDayNumber == g1.julianDayNumber); // -\u003e true\n  // this means that they are equal\n  // you can also use other comparison operators\n\n  // you can use extension methods for DateTime\n  final dtn = DateTime.now();\n  print(dtn);\n  final jn = dtn.toJalali();\n  print(jn);\n  final gn = dtn.toGregorian();\n  print(gn);\n\n  // also you can create a Jalali or Gregorian date from\n  // milliseconds since epoch\n  print(Jalali.fromMillisecondsSinceEpoch(1722782031520));\n  print(Gregorian.fromMillisecondsSinceEpoch(1722782031520));\n  // also there is a isUtc argument to control timezone\n  // which is false by default\n  print(Jalali.fromMillisecondsSinceEpoch(1722782031520, isUtc: true));\n\n  // you can create dates using julian day number using factory method\n  print(Jalali.fromJulianDayNumber(2460527));\n  // or also provide time information\n  print(Jalali.fromJulianDayNumber(2460527, 15, 36, 12, 156));\n  // or get julian day number thr\n  print(Jalali.now().julianDayNumber);\n\n  // also you can get time information using time getter\n  // this will result in a time duration from start of the day\n  print(Jalali.now().time);\n  // or get it in seconds or milliseconds\n  print(Jalali.now().time.inSeconds);\n  print(Jalali.now().time.inMicroseconds);\n}\n```\n\n[Jalali]: https://pub.dev/documentation/shamsi_date/latest/shamsi_date/Jalali-class.html\n[Gregorian]: https://pub.dev/documentation/shamsi_date/latest/shamsi_date/Gregorian-class.html\n[DateTime]: https://api.flutter.dev/flutter/dart-core/DateTime-class.html\n[Date]: https://pub.dev/documentation/shamsi_date/latest/shamsi_date/Date-class.html\n[DateFormatter]: https://pub.dev/documentation/shamsi_date/latest/shamsi_date/DateFormatter-class.html\n[Comparable]: https://api.flutter.dev/flutter/dart-core/Comparable-class.html\n[DateException]: https://pub.dev/documentation/shamsi_date/latest/shamsi_date/DateException-class.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffatulm%2Fshamsi_date","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffatulm%2Fshamsi_date","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffatulm%2Fshamsi_date/lists"}