Skip to content
Rob Parham edited this page Aug 28, 2020 · 11 revisions

Protodate Logo

Contents

Constants

ProtoDate.MONTHS

An array of Month Names (January - December).

ProtoDate.DAYS

An array of day names (Sunday - Saturday).

ProtoDate.PROTODATE_VERSION

The current version of Protodate (eg. '1.1.1').

ProtoDate.MILLISECOND

Number 1 - represents a millisecond.

ProtoDate.SECOND

Number 1000 - represents a second.

ProtoDate.MINUTE

Number 60000 - represents a minute.

ProtoDate.HOUR

Number 3600000 - represents an hour.

ProtoDate.DAY

Number 86400000 - represents a day.

ProtoDate.YEAR

Number 31536000000 - represents a year.

Instance Methods

new ProtoDate().format(formatStr)

  • Format a date as a readable string.
  • @param {string} formatStr - A string to dictate how to format the date.
  • @returns {string|false} - The formatted date string or false if the instance is not a valid date.

new ProtoDate().elapsedSince(date)

  • Get the elapsed time between the instance date and the date given.
  • @param {ProtoDate} date - A starting or ending ProtoDate.
  • @returns {object} elapsed - The returned object contains 6 numeric properties and 2 methods:
    • elapsed.y {number} number of years elapsed between the two Dates.
    • elapsed.d {number} number of days elapsed between the two dates (after calculating years).
    • elapsed.h {number} number of hours elapsed between the two dates (after calculating days).
    • elapsed.m {number} number of months elapsed between the two dates (after calculating hours).
    • elapsed.s {number} number of seconds elapsed between the two dates (after calculating minutes).
    • elapsed.ms {number} number of milliseconds elapsed between the two dates (after calculating seconds).
    • elapsed.verbose {function} returns a verbose English string (eg. '3 years, 1 hour, and 42 seconds').
    • elapsed.clock {function} returns string displaying the elapsed time in hours, minutes, seconds and milliseconds (eg. '3:12:34.234').

new ProtoDate().plus(quantity, period)

  • Add a certain amount of time to the ProtoDate instance.
  • @param {number} quantity - The number of periods to add.
  • @param {number} period - Any of the ProtoDate period constants (eg. ProtoDate.DAY or ProtoDate.YEAR).
  • @returns {ProtoDate} - Mutates the date and returns itself.
  • @example - new ProtoDate().plus(3, ProtoDate.MINUTE).plus(30, ProtoDate.SECONDS) creates a ProtoDate instance 3 minutes and 30 seconds in the future.

new ProtoDate().minus(quantity, period)

  • Subtract a certain amount of time from the ProtoDate instance.
  • @param {number} quantity - The number of periods to subtract.
  • @param {number} period - Any of the ProtoDate period constants (eg. ProtoDate.DAY or ProtoDate.YEAR).
  • @returns {ProtoDate} - Mutates the date and returns itself.
  • @example - new ProtoDate().minus(3, ProtoDate.MINUTE).minus(30, ProtoDate.SECONDS) creates a ProtoDate instance 3 minutes and 30 seconds in the past.

new ProtoDate().getUnixTimestamp()

  • Get the unix timestamp of the date object
  • @returns {Number} - The unix timestamp
  • @example - var ts = new ProtoDate().getUnixTimestamp

new ProtoDate().getTimezone()

  • Get the timezone of the date object (This functionality is only available in the protodate.tz.* files)
  • @returns {String} - The timezone of the date object
  • @example - var tz = new ProtoDate().getTimezone() eg. 'America/New_York'

new ProtoDate().isDST()

  • Does the date take place during Daylight Savings Time (This functionality is only available in the protodate.tz.* files)
  • @returns {Boolean} - True if the date is during DST
  • @example - var dst = new ProtoDate().isDST() will be true if DST is currently in effect.

new ProtoDate().setTimezone()

  • Convert the date to another timezone (This functionality is only available in the protodate.tz.* files)
  • @param {string} timezone - A timezone string, eg 'America/Los_Angeles'
  • @returns {ProtoDate} - Returns the date object for chainability
  • @example - var sydney = new ProtoDate().setTimezone('Australia/Sydney') a date representing the current time in Sydney.

new ProtoDate().toDate()

  • Convert the ProtoDate object to Date object.
  • @returns {Date} - Returns a native Date object.
  • @example - var date = new ProtoDate().toDate()

Static Methods

ProtoDate.parse(dateStr[, formatStr])

  • Parse a date string and return a ProtoDate object.
  • @param {string} dateStr - The date string to parse (eg. 'January 3rd 2034' or '2034/01/03 23:00').
  • @param {string} formatStr - A format string explaining the format the date string is in. This parameter is optional, parse will attempt to guess the format if not provided but it's faster if the format is known.
  • @returns {ProtoDate|false} - The ProtoDate object or false if either parameter is nonsense.

ProtoDate.guessFormat(dateStr)

  • Guess the format string used for a given date string.
  • @param {string} dateStr - The date string to guess the format of.
  • @returns {string|false} - The probable format string or false if the input is nonsense.

ProtoDate.isDate(date)

  • Validate a date object.
  • @param {any} date - The object to test.
  • @returns {boolean} - true if the object is a valid Date (or ProtoDate) instance, else false.

ProtoDate.validateFormat(dateStr, formatStr)

  • Validate a date string against a format string.
  • @param {string} - The date string to test.
  • @param {string} - The format string to test the date string against.
  • @returns {boolean} - True if the date string matches the format string else false.

ProtoDate.isDSTObserved(timezone)

  • Does the given timezone ever observe Daylight Savings Time. (This functionality is only available in the protodate.tz.* files)
  • @param {string} timezone - A timezone string, eg 'America/Los_Angeles'
  • @returns {boolean} - True if the timezone ever observes DST.

ProtoDate.fromDate(date)

  • Get a ProtoDate object from a native Date object
  • @param {Date} date - A native Date object
  • @returns {ProtoDate} - The converted ProtoDate object.
  • @example - const protodate = ProtoDate.fromDate(new Date())

Formatting Reference

Each character represents part of a date format string. Characters listed as Parsable are understood by the parse method. All other characters, as well as characters escaped with a \ in the format string will be printed as-is.

format character Description Example returned values Parsable
Day -- -- --
d Day of the month, 2 digits with leading zeros 01 to 31
D A textual representation of a day, three letters Mon through Sun
j Day of the month without leading zeros 1 to 31
l (lowercase 'L') A full textual representation of the day of the week Sunday through Saturday
N ISO-8601 numeric representation of the day of the week 1 (for Monday) through 7 (for Sunday)
S English ordinal suffix for the day of the month, 2 characters st, nd, rd or th. Works well with j
w Numeric representation of the day of the week 0 (for Sunday) through 6 (for Saturday)
z The day of the year (starting from 0) 0 through 365
Week -- -- --
W ISO-8601 week number of year, weeks starting on Monday Example: 42 (the 42nd week in the year)
Month -- -- --
F A full textual representation of a month, such as January or March January through December
m Numeric representation of a month, with leading zeros 01 through 12
M A short textual representation of a month, three letters Jan through Dec
n Numeric representation of a month, without leading zeros 1 through 12
t Number of days in the given month 28 through 31
Year -- -- --
L Whether it's a leap year 1 if it is a leap year, 0 otherwise.
o ISO-8601 week-numbering year. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead. Examples: 1999 or 2003
Y A full numeric representation of a year, 4 digits Examples: 1999 or 2003
y A two digit representation of a year Examples: 99 or 03
Time -- -- --
a Lowercase Ante meridiem and Post meridiem am or pm
A Uppercase Ante meridiem and Post meridiem AM or PM
B Swatch Internet time 000 through 999
g 12-hour format of an hour without leading zeros 1 through 12
G 24-hour format of an hour without leading zeros 0 through 23
h 12-hour format of an hour with leading zeros 01 through 12
H 24-hour format of an hour with leading zeros 00 through 23
i Minutes with leading zeros 00 to 59
s Seconds, with leading zeros 00 through 59
v Milliseconds with leading zeros - 3 Digits. Example: 654
Timezone -- -- --
Z Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive. -1.1.15 through 1.1.15
Full Date/Time -- -- --
c ISO 8601 date 1.1.15T1.1.15.990Z
U Seconds since the Unix Epoch (January 1.1.15:00:00 GMT) 1.1.15

Timezone Reference

Complete list of the world's timezones and their corresponding countries.

Country Timezone
Afghanistan Asia/Kabul
Aland Islands Europe/Mariehamn
Albania Europe/Tirane
Algeria Africa/Algiers
American Samoa Pacific/Pago_Pago
Andorra Europe/Andorra
Angola Africa/Luanda
Anguilla America/Anguilla
Antarctica Antarctica/Casey
Antarctica Antarctica/Davis
Antarctica Antarctica/DumontDUrville
Antarctica Antarctica/Mawson
Antarctica Antarctica/McMurdo
Antarctica Antarctica/Palmer
Antarctica Antarctica/Rothera
Antarctica Antarctica/Syowa
Antarctica Antarctica/Troll
Antarctica Antarctica/Vostok
Antigua and Barbuda America/Antigua
Argentina America/Argentina/Buenos_Aires
Argentina America/Argentina/Catamarca
Argentina America/Argentina/Cordoba
Argentina America/Argentina/Jujuy
Argentina America/Argentina/La_Rioja
Argentina America/Argentina/Mendoza
Argentina America/Argentina/Rio_Gallegos
Argentina America/Argentina/Salta
Argentina America/Argentina/San_Juan
Argentina America/Argentina/San_Luis
Argentina America/Argentina/Tucuman
Argentina America/Argentina/Ushuaia
Armenia Asia/Yerevan
Aruba America/Aruba
Australia Antarctica/Macquarie
Australia Australia/Adelaide
Australia Australia/Brisbane
Australia Australia/Broken_Hill
Australia Australia/Currie
Australia Australia/Darwin
Australia Australia/Eucla
Australia Australia/Hobart
Australia Australia/Lindeman
Australia Australia/Lord_Howe
Australia Australia/Melbourne
Australia Australia/Perth
Australia Australia/Sydney
Austria Europe/Vienna
Azerbaijan Asia/Baku
Bahamas America/Nassau
Bahrain Asia/Bahrain
Bangladesh Asia/Dhaka
Barbados America/Barbados
Belarus Europe/Minsk
Belgium Europe/Brussels
Belize America/Belize
Benin Africa/Porto-Novo
Bermuda Atlantic/Bermuda
Bhutan Asia/Thimphu
Bolivia America/La_Paz
Bonaire, Saint Eustatius and Saba America/Kralendijk
Bosnia and Herzegovina Europe/Sarajevo
Botswana Africa/Gaborone
Brazil America/Araguaina
Brazil America/Bahia
Brazil America/Belem
Brazil America/Boa_Vista
Brazil America/Campo_Grande
Brazil America/Cuiaba
Brazil America/Eirunepe
Brazil America/Fortaleza
Brazil America/Maceio
Brazil America/Manaus
Brazil America/Noronha
Brazil America/Porto_Velho
Brazil America/Recife
Brazil America/Rio_Branco
Brazil America/Santarem
Brazil America/Sao_Paulo
British Indian Ocean Territory Indian/Chagos
British Virgin Islands America/Tortola
Brunei Asia/Brunei
Bulgaria Europe/Sofia
Burkina Faso Africa/Ouagadougou
Burundi Africa/Bujumbura
Cambodia Asia/Phnom_Penh
Cameroon Africa/Douala
Canada America/Atikokan
Canada America/Blanc-Sablon
Canada America/Cambridge_Bay
Canada America/Creston
Canada America/Dawson
Canada America/Dawson_Creek
Canada America/Edmonton
Canada America/Fort_Nelson
Canada America/Glace_Bay
Canada America/Goose_Bay
Canada America/Halifax
Canada America/Inuvik
Canada America/Iqaluit
Canada America/Moncton
Canada America/Nipigon
Canada America/Pangnirtung
Canada America/Rainy_River
Canada America/Rankin_Inlet
Canada America/Regina
Canada America/Resolute
Canada America/St_Johns
Canada America/Swift_Current
Canada America/Thunder_Bay
Canada America/Toronto
Canada America/Vancouver
Canada America/Whitehorse
Canada America/Winnipeg
Canada America/Yellowknife
Cape Verde Atlantic/Cape_Verde
Cayman Islands America/Cayman
Central African Republic Africa/Bangui
Chad Africa/Ndjamena
Chile America/Punta_Arenas
Chile America/Santiago
Chile Pacific/Easter
China Asia/Shanghai
China Asia/Urumqi
Christmas Island Indian/Christmas
Cocos Islands Indian/Cocos
Colombia America/Bogota
Comoros Indian/Comoro
Cook Islands Pacific/Rarotonga
Costa Rica America/Costa_Rica
Croatia Europe/Zagreb
Cuba America/Havana
Curaçao America/Curacao
Cyprus Asia/Famagusta
Cyprus Asia/Nicosia
Czech Republic Europe/Prague
Democratic Republic of the Congo Africa/Kinshasa
Democratic Republic of the Congo Africa/Lubumbashi
Denmark Europe/Copenhagen
Djibouti Africa/Djibouti
Dominica America/Dominica
Dominican Republic America/Santo_Domingo
East Timor Asia/Dili
Ecuador America/Guayaquil
Ecuador Pacific/Galapagos
Egypt Africa/Cairo
El Salvador America/El_Salvador
Equatorial Guinea Africa/Malabo
Eritrea Africa/Asmara
Estonia Europe/Tallinn
Ethiopia Africa/Addis_Ababa
Falkland Islands Atlantic/Stanley
Faroe Islands Atlantic/Faroe
Fiji Pacific/Fiji
Finland Europe/Helsinki
France Europe/Paris
French Guiana America/Cayenne
French Polynesia Pacific/Gambier
French Polynesia Pacific/Marquesas
French Polynesia Pacific/Tahiti
French Southern Territories Indian/Kerguelen
Gabon Africa/Libreville
Gambia Africa/Banjul
Georgia Asia/Tbilisi
Germany Europe/Berlin
Germany Europe/Busingen
Ghana Africa/Accra
Gibraltar Europe/Gibraltar
Greece Europe/Athens
Greenland America/Danmarkshavn
Greenland America/Godthab
Greenland America/Scoresbysund
Greenland America/Thule
Grenada America/Grenada
Guadeloupe America/Guadeloupe
Guam Pacific/Guam
Guatemala America/Guatemala
Guernsey Europe/Guernsey
Guinea Africa/Conakry
Guinea-Bissau Africa/Bissau
Guyana America/Guyana
Haiti America/Port-au-Prince
Honduras America/Tegucigalpa
Hong Kong Asia/Hong_Kong
Hungary Europe/Budapest
Iceland Atlantic/Reykjavik
India Asia/Kolkata
Indonesia Asia/Jakarta
Indonesia Asia/Jayapura
Indonesia Asia/Makassar
Indonesia Asia/Pontianak
Iran Asia/Tehran
Iraq Asia/Baghdad
Ireland Europe/Dublin
Isle of Man Europe/Isle_of_Man
Israel Asia/Jerusalem
Italy Europe/Rome
Ivory Coast Africa/Abidjan
Jamaica America/Jamaica
Japan Asia/Tokyo
Jersey Europe/Jersey
Jordan Asia/Amman
Kazakhstan Asia/Almaty
Kazakhstan Asia/Aqtau
Kazakhstan Asia/Aqtobe
Kazakhstan Asia/Atyrau
Kazakhstan Asia/Oral
Kazakhstan Asia/Qyzylorda
Kenya Africa/Nairobi
Kiribati Pacific/Enderbury
Kiribati Pacific/Kiritimati
Kiribati Pacific/Tarawa
Kuwait Asia/Kuwait
Kyrgyzstan Asia/Bishkek
Laos Asia/Vientiane
Latvia Europe/Riga
Lebanon Asia/Beirut
Lesotho Africa/Maseru
Liberia Africa/Monrovia
Libya Africa/Tripoli
Liechtenstein Europe/Vaduz
Lithuania Europe/Vilnius
Luxembourg Europe/Luxembourg
Macao Asia/Macau
Macedonia Europe/Skopje
Madagascar Indian/Antananarivo
Malawi Africa/Blantyre
Malaysia Asia/Kuala_Lumpur
Malaysia Asia/Kuching
Maldives Indian/Maldives
Mali Africa/Bamako
Malta Europe/Malta
Marshall Islands Pacific/Kwajalein
Marshall Islands Pacific/Majuro
Martinique America/Martinique
Mauritania Africa/Nouakchott
Mauritius Indian/Mauritius
Mayotte Indian/Mayotte
Mexico America/Bahia_Banderas
Mexico America/Cancun
Mexico America/Chihuahua
Mexico America/Hermosillo
Mexico America/Matamoros
Mexico America/Mazatlan
Mexico America/Merida
Mexico America/Mexico_City
Mexico America/Monterrey
Mexico America/Ojinaga
Mexico America/Tijuana
Micronesia Pacific/Chuuk
Micronesia Pacific/Kosrae
Micronesia Pacific/Pohnpei
Moldova Europe/Chisinau
Monaco Europe/Monaco
Mongolia Asia/Choibalsan
Mongolia Asia/Hovd
Mongolia Asia/Ulaanbaatar
Montenegro Europe/Podgorica
Montserrat America/Montserrat
Morocco Africa/Casablanca
Mozambique Africa/Maputo
Myanmar Asia/Yangon
Namibia Africa/Windhoek
Nauru Pacific/Nauru
Nepal Asia/Kathmandu
Netherlands Europe/Amsterdam
New Caledonia Pacific/Noumea
New Zealand Pacific/Auckland
New Zealand Pacific/Chatham
Nicaragua America/Managua
Niger Africa/Niamey
Nigeria Africa/Lagos
Niue Pacific/Niue
Norfolk Island Pacific/Norfolk
North Korea Asia/Pyongyang
Northern Mariana Islands Pacific/Saipan
Norway Europe/Oslo
Oman Asia/Muscat
Pakistan Asia/Karachi
Palau Pacific/Palau
Palestinian Territory Asia/Gaza
Palestinian Territory Asia/Hebron
Panama America/Panama
Papua New Guinea Pacific/Bougainville
Papua New Guinea Pacific/Port_Moresby
Paraguay America/Asuncion
Peru America/Lima
Philippines Asia/Manila
Pitcairn Pacific/Pitcairn
Poland Europe/Warsaw
Portugal Atlantic/Azores
Portugal Atlantic/Madeira
Portugal Europe/Lisbon
Puerto Rico America/Puerto_Rico
Qatar Asia/Qatar
Republic of the Congo Africa/Brazzaville
Reunion Indian/Reunion
Romania Europe/Bucharest
Russia Asia/Anadyr
Russia Asia/Barnaul
Russia Asia/Chita
Russia Asia/Irkutsk
Russia Asia/Kamchatka
Russia Asia/Khandyga
Russia Asia/Krasnoyarsk
Russia Asia/Magadan
Russia Asia/Novokuznetsk
Russia Asia/Novosibirsk
Russia Asia/Omsk
Russia Asia/Sakhalin
Russia Asia/Srednekolymsk
Russia Asia/Tomsk
Russia Asia/Ust-Nera
Russia Asia/Vladivostok
Russia Asia/Yakutsk
Russia Asia/Yekaterinburg
Russia Europe/Astrakhan
Russia Europe/Kaliningrad
Russia Europe/Kirov
Russia Europe/Moscow
Russia Europe/Samara
Russia Europe/Saratov
Russia Europe/Simferopol
Russia Europe/Ulyanovsk
Russia Europe/Volgograd
Rwanda Africa/Kigali
Saint Barthélemy America/St_Barthelemy
Saint Helena Atlantic/St_Helena
Saint Kitts and Nevis America/St_Kitts
Saint Lucia America/St_Lucia
Saint Martin America/Marigot
Saint Pierre and Miquelon America/Miquelon
Saint Vincent and the Grenadines America/St_Vincent
Samoa Pacific/Apia
San Marino Europe/San_Marino
Sao Tome and Principe Africa/Sao_Tome
Saudi Arabia Asia/Riyadh
Senegal Africa/Dakar
Serbia Europe/Belgrade
Seychelles Indian/Mahe
Sierra Leone Africa/Freetown
Singapore Asia/Singapore
Sint Maarten America/Lower_Princes
Slovakia Europe/Bratislava
Slovenia Europe/Ljubljana
Solomon Islands Pacific/Guadalcanal
Somalia Africa/Mogadishu
South Africa Africa/Johannesburg
South Georgia and the South Sandwich Islands Atlantic/South_Georgia
South Korea Asia/Seoul
South Sudan Africa/Juba
Spain Africa/Ceuta
Spain Atlantic/Canary
Spain Europe/Madrid
Sri Lanka Asia/Colombo
Sudan Africa/Khartoum
Suriname America/Paramaribo
Svalbard and Jan Mayen Arctic/Longyearbyen
Swaziland Africa/Mbabane
Sweden Europe/Stockholm
Switzerland Europe/Zurich
Syria Asia/Damascus
Taiwan Asia/Taipei
Tajikistan Asia/Dushanbe
Tanzania Africa/Dar_es_Salaam
Thailand Asia/Bangkok
Togo Africa/Lome
Tokelau Pacific/Fakaofo
Tonga Pacific/Tongatapu
Trinidad and Tobago America/Port_of_Spain
Tunisia Africa/Tunis
Turkey Europe/Istanbul
Turkmenistan Asia/Ashgabat
Turks and Caicos Islands America/Grand_Turk
Tuvalu Pacific/Funafuti
U.S. Virgin Islands America/St_Thomas
Uganda Africa/Kampala
Ukraine Europe/Kiev
Ukraine Europe/Uzhgorod
Ukraine Europe/Zaporozhye
United Arab Emirates Asia/Dubai
United Kingdom Europe/London
United States America/Adak
United States America/Anchorage
United States America/Boise
United States America/Chicago
United States America/Denver
United States America/Detroit
United States America/Indiana/Indianapolis
United States America/Indiana/Knox
United States America/Indiana/Marengo
United States America/Indiana/Petersburg
United States America/Indiana/Tell_City
United States America/Indiana/Vevay
United States America/Indiana/Vincennes
United States America/Indiana/Winamac
United States America/Juneau
United States America/Kentucky/Louisville
United States America/Kentucky/Monticello
United States America/Los_Angeles
United States America/Menominee
United States America/Metlakatla
United States America/New_York
United States America/Nome
United States America/North_Dakota/Beulah
United States America/North_Dakota/Center
United States America/North_Dakota/New_Salem
United States America/Phoenix
United States America/Sitka
United States America/Yakutat
United States Pacific/Honolulu
United States Minor Outlying Islands Pacific/Midway
United States Minor Outlying Islands Pacific/Wake
Uruguay America/Montevideo
Uzbekistan Asia/Samarkand
Uzbekistan Asia/Tashkent
Vanuatu Pacific/Efate
Vatican Europe/Vatican
Venezuela America/Caracas
Vietnam Asia/Ho_Chi_Minh
Wallis and Futuna Pacific/Wallis
Western Sahara Africa/El_Aaiun
Yemen Asia/Aden
Zambia Africa/Lusaka
Zimbabwe Africa/Harare