Persian Date
Javascript date library for parsing, validating, manipulating, and formatting Persian dates System.
from 1.0.0 persian date support gregorian calendar.
Inspired by momentjs
More info at wikipedia
Install
npm install persian-date --save-devbower install persian-date --save-dev
Browser
Webpack
require('persian-date');
Calendar and locale
toCalendar
default: persian
available option: persian
gregorian
from version 1.0.* persianDate
have an option that allows developers to set calendar type of Date object.
you can change calendar type globally or only in specific object
if you want change calendar type globally:
persianDate;2017; // 20172017; // "ژانویه"
or only on instance:
1396; // 2017
toLeapYearMode
default: algorithmic
available option: algorithmic
, astronomical
There is two popular way to determining leap years for the Persian calendar.
-
astronomical: occur whenever that number of days elapsed between equinoxes at the reference meridian.
-
algorithmic: based on Behrooz-Birashk proposed algorithm.
After version 1.0.* persianDate
support both algorithms and you can choose which algorithm use in your project.
currently, we have support 2 type of leap year mode algorithmic
, astronomical
.
you can change it globally like this example
persianDate
or change it in you instance
toLeapYearMode
only work when calendar type ispersian
, and doesnt any effect ongregorian
calendar
toLocale
default: fa
available option: fa
en
if you want change locale globally:
persianDate;1396617; // "۱۳۹۶-۰۶-۱۷ ۰۰:۰۰:۰۰ ق ظ"1396617; // "جمعه"1396617; // "شهریور" persianDate;1396617; // "1396-06-17 00:00:00 AM"1396617; // "Friday"1396617; // "Shahrivar"
or only on instance:
1396617; // "۱۳۹۶-۰۶-۱۷ ۰۰:۰۰:۰۰ ق ظ"1396617; // "جمعه"1396617; // "شهریور" persianDate;1396617; // "1397-07-07 00:00:00 AM"1396617; // "Friday"1396617; // "June"
after version 1.0.*, you must use
toLocale
insteadformatPersian
, for show persian or english digit.
Parse
Instead of modifying the native Date.prototype
, persianDate creates a wrapper for the Date object.
To get this wrapper object, simply call persianDate()
with one of the supported input types.
Now
;
To get the current date and time, just call persianDate()
with no parameters.
var now = ;
This is essentially the same as calling new persianDate(new Date())
.
Unix Offset (milliseconds)
/* Number */;
Similar to new Date(Number)
, you can create a persianDate by passing an integer value representing the number of milliseconds since the Unix Epoch (Jan 1 1970 12AM UTC).
var day = 1318781876406; // "۱۳۹۰-۰۷-۲۴ ۱۹:۴۷:۵۶ ب ظ"
Unix Timestamp (seconds)
persianDate;
To create a persianDate from a Unix timestamp (seconds since the Unix Epoch), use persianDate.unix(Number)
var day = 1318781876; // "۱۳۹۰-۰۷-۲۴ ۱۹:۴۷:۵۶ ب ظ"
This is implemented as persianDate(timestamp * 1000)
, so partial seconds in the input timestamp are included.
Date
;
You can create a persianDate
with a pre-existing native Javascript Date
object.
var day = 2011 9 16;var dayWrapper = day; // "۱۳۹۰-۰۷-۲۴ ۰۰:۰۰:۰۰ ق ظ"
This is the fastest way to get a persianDate.js wrapper.
Array
['year', 'month', 'day', 'hour', 'minute', 'second', 'millisecond']
1391 12 29 12 25 25 900;
You can create a persianDate with an array of numbers that mirror the parameters passed to new Date()
But As Persian Date Number Like [1393,2,22,11,22,30]
1393 1 14 1525 50125; // "۱۳۹۳-۰۱-۱۴ ۱۵:۲۵:۵۰ ب ظ"
Any value past the year is optional, and will default to the lowest possible number.
1392; // Farvardin 1st1392 6; // Shahrivar 1st1392 6 10; // Shahrivar 10th
Note: from 1.0.* you can pass gregorian date array to create gregorian date object. for this functionality you must change date object calendar type by
toCalendar('gregorian')
example:
persianDate;201722; // "۲۰۱۷-۰۲-۰۲ ۰۰:۰۰:۰۰ ق ظ"
ASP.NET JSON Date
new persianDate(String);
ASP.NET returns dates in JSON as /Date(1198908717056)/
or /Date(1198908717056-0700)/
If a string that matches this format is passed in, it will be parsed correctly.
"/Date(1198908717056-0700)/"; //"۱۳۸۶-۱۰-۰۸ ۰۹:۴۱:۵۷ ق ظ"
PesianDate Clone
new persianDate(persianDate);
All persianDate are mutable. If you want a clone of a persianDate, you can do so explicitly or implicitly.
Calling persianDate()
on a persianDate will clone it.
var a = 1392;var b = a;a;b; // 1392
var a = 1392;var b = a;a;b; // 1392
Get + Set
persainDate.js uses overloaded getters and setters. You may be familiar with this pattern from it's use in jQuery.
Calling these methods without parameters acts as a getter, and calling them with a parameter acts as a setter.
These map to the corresponding function on the native Date
object.
=== ; // true === ; // true
Millisecond
;; // 100;; // 100
Gets or sets the milliseconds.
Accepts numbers from 0 to 999. If the range is exceeded, it will bubble up to the seconds.
Second
;; // 10;; // 10
Gets or sets the seconds.
Accepts numbers from 0 to 59. If the range is exceeded, it will bubble up to the minutes.
Minute
;; // 20;; // 20
Gets or sets the minutes.
Accepts numbers from 0 to 59. If the range is exceeded, it will bubble up to the hours.
Hour
;; // 12;; // 12
Gets or sets the hour.
Accepts numbers from 0 to 23. If the range is exceeded, it will bubble up to the day.
Date of Month
;; // 23;; // 23
Gets or sets the day of the month.
Accepts numbers from 1 to 31. If the range is exceeded, it will bubble up to the months.
Note: persianDate#date is for the date of the month, and persianDate#day is for the day of the week.
Year
;; // 1390;; // 1390
Gets or sets the year.
Accepts numbers from -270,000 to 270,000.
Day of Week
; // Number; // Number
Gets the day of the week.
Note:
persianDate#date
is for the date of the month, andpersianDate#day
is for the day of the week.
Manipulate
Once you have a PersianDate , you may want to manipulate it in some way. There are a number of methods to help with this.
persianDate.js uses the fluent interface pattern, also known as method chaining. This allows you to do crazy things like the following.
;
Note: It should be noted that persianDates are mutable. Calling any of the manipulation methods will change the original persianDate.
If you want to create a copy and manipulate it, you should use persianDate#clone
before manipulating the persianDate.
Add
;
Mutates the original persianDate by adding time.
This is a pretty robust function for adding time to an existing persianDate. To add time, pass the key of what time you want to add, and the amount you want to add.
;
There are some shorthand keys as well if you're into that whole brevity thing.
;
Key | Alternate | Shorthand |
---|---|---|
years | year | y |
months | month | M |
weeks | week | w |
days | day | d |
hours | hour | h |
minutes | minute | m |
seconds | second | s |
milliseconds | millisecond | ms |
If you want to add multiple different keys at the same time, you can pass them in as an object literal.
; // with chaining
There are no upper limits for the amounts, so you can overload any of the parameters.
; // a million milliseconds; // 360 days
Subtract
;
Mutates the original persianDate by subtracting time.
This is exactly the same as persianDate#add
, only instead of adding time, it subtracts time.
;
Start of Time
;
Mutates the original persianDate by setting it to the start of a unit of time.
; // set to Farvardin 1st, 12:00 am this year; // set to the first of this month, 12:00 am; // set to the first day of this week, 12:00 am; // set to 12:00 am today; // set to now, but with 0 mins, 0 secs, and 0 ms; // set to now, but with 0 seconds and 0 milliseconds; // same as persianDate().milliseconds(0);
These shortcuts are essentially the same as the following.
;;
;
End of Time
;
Mutates the original persianDate by setting it to the end of a unit of time.
This is the same as persianDate#startOf
, only instead of setting to the start of a unit of time, it sets to the end of a unit of time.
; // set the persianDate to 12-31 11:59:59.999 pm this year
Display
Once parsing and manipulation are done, you need some way to display the persianDate.
Format
;;
This is the most robust display option. It takes a string of tokens and replaces them with their corresponding values.
; // "شنبه, فروردین ۱۲ ۱۳۹۶, ۵:۵۴:۱۱ ب ظ"; // "شنبه, ۵ب ظ"
This is the most robust display option. It takes a string of tokens and replaces them with their corresponding values.
Type | Tocken | Output |
---|---|---|
Month | M | ۱ ۲ ... ۱۱ ۱۲ |
MM | ۰۱ ۰۲ ... ۱۱ ۱۲ | |
MMM | فرو ارد ... اسف | |
MMMM | فروردین اردیبهشت ... اسفند | |
Day of month | D | ۱ ۲ ... ۳۰ ۳۱ |
DD | ۰۱ ۰۲ ... ۳۰ ۳۱ | |
Day of year | DDD | ۱ ۲ ... ۳۶۴ ۳۶۵ |
d | ۰ ۱ ... ۵ ۶ | |
dd | ش ی ... ج | |
ddd | شنبه یکشنبه ... جمعه | |
dddd | انارام مانتره سپند ... اشتاد | |
Week of Year | w | ۱ ۲ ... ۵۲ ۵۳ |
ww | ۰۱ ۰۲ ... ۵۲ ۵۳ | |
Year | YY | ۶۶ ۹۱ ... ۹۸ ۳۰ |
YYYY | ۱۳۶۶ ۱۳۹۱ ... ۱۳۹۸ ۱۴۰۱ | |
AM/PM | a | "ق ظ", "ب ظ" |
Hour | H | ۰ ۱ ... ۲۲ ۲۳ |
HH | ۰۰ ۰۱ ... ۲۲ ۲۳ | |
h | ۱ ۲ ... ۱۱ ۱۲ | |
hh | ۰۱ ۰۲ ... ۱۱ ۱۲ | |
Minute | m | ۰ ۱ ... ۵۸ ۵۹ |
mm | ۰۰ ۰۱ ... ۵۸ ۵۹ | |
Second | s | ۰ ۱ ... ۵۸ ۵۹ |
ss | ۰۰ ۰۱ ... ۵۸ ۵۹ | |
Unix Timestamp | X | 1360013296 |
Timezone | Z | -۰۴:۳۰ -۰۵:۰۰ ... +۰۴:۳۰ +۰۵:۰۰ |
ZZ | -۰۴۳۰ -۰۵:۰۰ ... +۰۴:۳۰ +۰۵:۰۰ |
Long Date formats
Type | Tocken | Output |
---|---|---|
Time | LT | "۴:۱۵ ب ظ" |
Month numeral, day of month, year | L | ۱۳۹۲/۰۲/۲۰ |
l | ۳۹۲/۲/۲۰ | |
Month name, day of month, year | LL | اردیبهشت ۲۰ ۱۳۹۲ |
ll | ارد ۲۰ ۱۳۹۲ | |
Month name, day of month, year, time | LLL | اردیبهشت ۱۳۹۲ ۲۰ ۴:۲۳ ب ظ |
lll | ارد ۱۳۹۲ ۲۰ ۴:۲۳ ب ظ | |
Month name, day of month, day of week, year, time | LLLL | جمعه ۲۰ اردیبهشت ۱۳۹۲ ۴:۲۵ ب ظ |
llll | ج ۲۰ ارد ۱۳۹۲ ۴:۲۷ ب ظ |
Default format
ISO8601 format YYYY-MM-DDTHH:mm:ssZ
"۱۳۹۱-۱۰-۰۴ ۱۱:۲۷:۵۳ ق ظ"
Format To Persian digit
Deprecated as 1.0.* instead use toLocale
By Default persianDate format, use Persian Number System, for engilsh number Set formatPersian Option as false
var d = 1391;d; //"۱۳۹۱-۰۱-۰۱ ۰۰:۰۰:۰۰ ق ظ"windowformatPersian = false;d; //"1391-01-01 00:00:00 AM"
Also you can set golbal config like this
windowformatPersian = false;
Note: After Set Global config you can set config for every instance
var d = 1391;d; //"۱۳۹۱-۰۱-۰۱ ۰۰:۰۰:۰۰ ق ظ"windowformatPersian = false;d; //"1391-01-01 00:00:00 AM"dformatPersian = true;d; //"۱۳۹۱-۰۱-۰۱ ۰۰:۰۰:۰۰ ق ظ"
Difference
new persianDate().diff(PersianDate|String|Boolean);
Accept 3 argument, (ccmparable persianDate object, difference key, boolean value that make returned output float)
To get the difference in milliseconds, use persianDate#diff
.
var a = 1392 1 29;var b = 1392 1 28;a // 86400000
To get the difference in another unit of measurement, pass that measurement as the second argument.
var a = 1392 1 29;var b = 13921 28;a; // 1
The supported measurements are years, months, weeks, days, hours, minutes, and seconds. For ease of development, the singular forms are supported .
var a = 1391 1;var b = 1392 5;a;a;
If the persianDate is later than the persianDate you are passing to persianDate.fn.diff
, the return value will be negative.
var a = ;var b = ;a; // -1000b; // 1000
A easy way to think of this is by replacing .diff(
with a minus operator.
a;b;
Unix Offset (milliseconds)
;
persianDate#valueOf
simply outputs the number of milliseconds since the Unix Epoch, just like Date#valueOf
.
1318874398806; // 13188743988061318874398806; // "۱۳۹۰-۰۷-۲۵ ۲۱:۲۹:۵۸ ب ظ"
To get a Unix timestamp (the number of seconds since the epoch) from a persianDate
, use persianDate#unix
.
Unix Timestamp (seconds)
;
persianDate#unix
outputs a Unix timestamp (the of seconds since the Unix Epoch).
1318874398806; // 1318874398
This value is floored to the nearest second, and does not include a milliseconds component.
Timezone Offset
;
Get the timezone offset in minutes.
; // (60, 120, 240, -270, etc.)
Days in Month
;
Get the number of days in the current month.
13921; // 3113928; // 30139212; // 29139112; // 30
As Javascript Date
;
To get the native Date
object that persianDate.js
wraps, use persianDate#toDate
.
This will return the Date
that the persianDate
uses.
As Array
;
This returns an array that mirrors the parameters from new persianDate()
.
; // [1391, 1, 4, 14, 40, 16, 154];
Range Name
Helper method that return date range name like week days name, month names, month days names (specially in persian calendar).
persianDate; persianDateweekdays;// ["شنبه", "یکشنبه", "دوشنبه", "سه شنبه", "چهار شنبه", "پنجشنبه", "جمعه"] persianDateweekdaysMin;// ["ش", "ی", "د", "س", "چ", "پ", "ج"] persianDatemonths;// ["فروردین", "اردیبهشت", "خرداد", "تیر", "مرداد", "شهریور", "مهر", "آبان", "آذر", "دی", "بهمن", "اسفند"] persianDatemonthsShort; // ["فرو", "ارد", "خرد", "تیر", "مرد", "شهر", "مهر", "آبا", "آذر", "دی", "بهم", "اسف"] persianDatepersianDaysName0; // "اورمزد"
Also You can get Gregorian calendar range names
persianDatemonths;// ["ژانویه", "فوریه", "مارس", "آوریل", "مه", "ژوئن", "ژوئیه", "اوت", "سپتامبر", "اکتبر", "نوامبر", "دسامبر"] persianDatemonths;// ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"] persianDateweekDayes;// ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'] persianDateweekDayesShort;// ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] persianDateweekDayesMin;// ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa']
Query
Is Leap Year
;
persianDate#isLeapYear
returns true if that year is a leap year, and false
if it is not. base on object calendarType.
1391; // true1392; // false1393; // false1394; // false1395; // true1396; // false
Is Daylight Saving Time
;
persianDate#isDST
checks if the current persianDate is in daylight savings time.
1396 1 1; // false1396 1 2; // true1396 6 30; // true1396 6 31; // false
Based on Persian DST wiki
Is a PersianDat
var obj = ; // options 1; // true //option 2persianDate;
To check if a variable is a persianDate object, use persianDate().isPersianDate()
.
; // false; // false; // true
Is Same Month
Check date object with given date object month similarity
// options 1var a = 139611;var b = 1396112;b; // true var a = 139611;var b = 1397112;b; // false // options 2var a = 139611;var b = 1396112;persianDate; // true var a = 139611;var b = 1397112;persianDate; // false
Is Same Day
Check date object with given date object day similarity
// options 1var a = 139611;var b = 139611;b; // true var a = 139611;var b = 139621;b; // false // options 2var a = 1396112;var b = 1396112;persianDate; // true var a = 1396112;var b = 1397112;persianDate; // false
license
Freely distributable under the terms of the MIT license.