luxon

<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <base data-ice="baseUrl" href="./"> <title data-ice="title">Luxon</title> <link type="text/css" rel="stylesheet" href="css/style.css"> <link type="text/css" rel="stylesheet" href="css/prettify-tomorrow.css"> <script src="script/prettify/prettify.js"></script> <script src="script/manual.js"></script> <link data-ice="userStyle" rel="stylesheet" href="user/css/0-styles.css"> </head> <body class="layout-container manual-root manual-index" data-ice="rootContainer"> <header><span class="luxon-title">Luxon</span> <a href="./">Home</a> <a href="identifiers.html">Reference</a> <a href="source.html">Source</a> <a data-ice="repoURL" href="https://github.com/icambron/luxon" class="repo-url-github">Repository</a> <div class="search-box"> <span> <img src="./image/search.png"> <span class="search-input-edge"></span><input class="search-input"><span class="search-input-edge"></span> </span> <ul class="search-result"></ul> </div> </header> <nav class="navigation" data-ice="nav"><div class="manual-toc-root"> <div data-ice="manual" data-toc-name="design"> <ul class="manual-toc"> <li data-ice="manualNav" class="indent-h1 manual-color manual-color-design" data-section-count="■■" data-link="manual/design/install.html"><a href="manual/design/install.html" data-ice="link">Install guide</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/design/install.html"><a href="manual/design/install.html#basic-browser-setup" data-ice="link">Basic browser setup</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/design/install.html"><a href="manual/design/install.html#node" data-ice="link">Node</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/design/install.html"><a href="manual/design/install.html#amd-system-js-requirejs-etc-" data-ice="link">AMD (System.js, RequireJS, etc)</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/design/install.html"><a href="manual/design/install.html#es6" data-ice="link">ES6</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/design/install.html"><a href="manual/design/install.html#webpack" data-ice="link">Webpack</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/design/install.html"><a href="manual/design/install.html#meteor" data-ice="link">Meteor</a></li> <li data-ice="manualNav" class="indent-h1 manual-color manual-color-design" data-section-count="■■■■" data-link="manual/design/tour.html"><a href="manual/design/tour.html" data-ice="link">A quick tour</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/design/tour.html"><a href="manual/design/tour.html#your-first-datetime" data-ice="link">Your first DateTime</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/design/tour.html"><a href="manual/design/tour.html#creating-a-datetime" data-ice="link">Creating a DateTime</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/design/tour.html"><a href="manual/design/tour.html#create-from-an-object" data-ice="link">Create from an object</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/design/tour.html"><a href="manual/design/tour.html#parse-from-iso-8601" data-ice="link">Parse from ISO 8601</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/design/tour.html"><a href="manual/design/tour.html#getting-to-know-your-datetime-instance" data-ice="link">Getting to know your DateTime instance</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/design/tour.html"><a href="manual/design/tour.html#tostring" data-ice="link">toString</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/design/tour.html"><a href="manual/design/tour.html#getting-at-components" data-ice="link">Getting at components</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/design/tour.html"><a href="manual/design/tour.html#other-fun-accessors" data-ice="link">Other fun accessors</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/design/tour.html"><a href="manual/design/tour.html#formatting-your-datetime" data-ice="link">Formatting your DateTime</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/design/tour.html"><a href="manual/design/tour.html#transforming-your-datetime" data-ice="link">Transforming your DateTime</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/design/tour.html"><a href="manual/design/tour.html#immutability" data-ice="link">Immutability</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/design/tour.html"><a href="manual/design/tour.html#math" data-ice="link">Math</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/design/tour.html"><a href="manual/design/tour.html#set" data-ice="link">Set</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/design/tour.html"><a href="manual/design/tour.html#intl" data-ice="link">Intl</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/design/tour.html"><a href="manual/design/tour.html#time-zones" data-ice="link">Time zones</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/design/tour.html"><a href="manual/design/tour.html#durations" data-ice="link">Durations</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/design/tour.html"><a href="manual/design/tour.html#intervals" data-ice="link">Intervals</a></li> </ul> </div> <div data-ice="manual" data-toc-name="usage"> <ul class="manual-toc"> <li data-ice="manualNav" class="indent-h1 manual-color manual-color-usage" data-section-count="■■" data-link="manual/usage/intl.html"><a href="manual/usage/intl.html" data-ice="link">Intl</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/intl.html"><a href="manual/usage/intl.html#how-locales-work" data-ice="link">How locales work</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/intl.html"><a href="manual/usage/intl.html#setting-locale" data-ice="link">Setting locale</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/intl.html"><a href="manual/usage/intl.html#checking-what-you-got" data-ice="link">Checking what you got</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/intl.html"><a href="manual/usage/intl.html#methods-affected-by-the-locale" data-ice="link">Methods affected by the locale</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/intl.html"><a href="manual/usage/intl.html#formatting" data-ice="link">Formatting</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/intl.html"><a href="manual/usage/intl.html#parsing" data-ice="link">Parsing</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/intl.html"><a href="manual/usage/intl.html#listing" data-ice="link">Listing</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/intl.html"><a href="manual/usage/intl.html#numberingsystem" data-ice="link">numberingSystem</a></li> <li data-ice="manualNav" class="indent-h1 manual-color manual-color-usage" data-section-count="■■■■■" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html" data-ice="link">Time zones and offsets</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#don-t-worry-" data-ice="link">Don't worry!</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#terminology" data-ice="link">Terminology</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#luxon-works-with-time-zones" data-ice="link">Luxon works with time zones</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#specifying-a-zone" data-ice="link">Specifying a zone</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#iana-support" data-ice="link">IANA support</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#creating-datetimes" data-ice="link">Creating DateTimes</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#local-by-default" data-ice="link">Local by default</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#creating-datetimes-in-a-zone" data-ice="link">Creating DateTimes in a zone</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#strings-that-specify-an-offset" data-ice="link">Strings that specify an offset</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#setzone" data-ice="link">setZone</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#changing-zones" data-ice="link">Changing zones</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#setzone" data-ice="link">setZone</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#keepcalendartime" data-ice="link">keepCalendarTime</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#accessors" data-ice="link">Accessors</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#dst-weirdness" data-ice="link">DST weirdness</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#invalid-times" data-ice="link">Invalid times</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#ambiguous-times" data-ice="link">Ambiguous times</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#math-across-dsts" data-ice="link">Math across DSTs</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/zones.html"><a href="manual/usage/zones.html#changing-the-default-zone" data-ice="link">Changing the default zone</a></li> <li data-ice="manualNav" class="indent-h1 manual-color manual-color-usage" data-section-count="■" data-link="manual/usage/calendars.html"><a href="manual/usage/calendars.html" data-ice="link">Calendars</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/calendars.html"><a href="manual/usage/calendars.html#fully-supported-calendars" data-ice="link">Fully supported calendars</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/calendars.html"><a href="manual/usage/calendars.html#output-calendars" data-ice="link">Output calendars</a></li> <li data-ice="manualNav" class="indent-h1 manual-color manual-color-usage" data-section-count="■■■■" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html" data-ice="link">Formatting</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#technical-formats-strings-for-computers-" data-ice="link">Technical formats (strings for computers)</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#iso-8601" data-ice="link">ISO 8601</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#http-and-rfc-2822" data-ice="link">HTTP and RFC 2822</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#tolocalestring-strings-for-humans-" data-ice="link">toLocaleString (strings for humans)</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#the-basics" data-ice="link">The basics</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#intl-datetimeformat" data-ice="link">Intl.DateTimeFormat</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#presets" data-ice="link">Presets</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#intl" data-ice="link">Intl</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#formatting-with-tokens-strings-for-cthulhu-" data-ice="link">Formatting with tokens (strings for Cthulhu)</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#consider-alternatives" data-ice="link">Consider alternatives</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#toformat" data-ice="link">toFormat</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#intl" data-ice="link">Intl</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#escaping" data-ice="link">Escaping</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#standalone-vs-format-tokens" data-ice="link">Standalone vs format tokens</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#macro-tokens" data-ice="link">Macro tokens</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/formatting.html"><a href="manual/usage/formatting.html#table-of-tokens" data-ice="link">Table of tokens</a></li> <li data-ice="manualNav" class="indent-h1 manual-color manual-color-usage" data-section-count="■■■" data-link="manual/usage/parsing.html"><a href="manual/usage/parsing.html" data-ice="link">Parsing</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/parsing.html"><a href="manual/usage/parsing.html#parsing-technical-formats" data-ice="link">Parsing technical formats</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/parsing.html"><a href="manual/usage/parsing.html#iso-8601" data-ice="link">ISO 8601</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/parsing.html"><a href="manual/usage/parsing.html#http-and-rfc2822" data-ice="link">HTTP and RFC2822</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/parsing.html"><a href="manual/usage/parsing.html#ad-hoc-parsing" data-ice="link">Ad-hoc parsing</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/parsing.html"><a href="manual/usage/parsing.html#consider-alternatives" data-ice="link">Consider alternatives</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/parsing.html"><a href="manual/usage/parsing.html#fromstring" data-ice="link">fromString</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/parsing.html"><a href="manual/usage/parsing.html#intl" data-ice="link">Intl</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/parsing.html"><a href="manual/usage/parsing.html#limitations" data-ice="link">Limitations</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/parsing.html"><a href="manual/usage/parsing.html#debugging" data-ice="link">Debugging</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/parsing.html"><a href="manual/usage/parsing.html#table-of-tokens" data-ice="link">Table of tokens</a></li> <li data-ice="manualNav" class="indent-h1 manual-color manual-color-usage" data-section-count="■■■" data-link="manual/usage/math.html"><a href="manual/usage/math.html" data-ice="link">Math</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/math.html"><a href="manual/usage/math.html#calendar-math-vs-time-math" data-ice="link">Calendar math vs time math</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/math.html"><a href="manual/usage/math.html#the-basics" data-ice="link">The basics</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/math.html"><a href="manual/usage/math.html#which-units-use-which-math-" data-ice="link">Which units use which math?</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/math.html"><a href="manual/usage/math.html#how-to-think-about-calendar-math" data-ice="link">How to think about calendar math</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/math.html"><a href="manual/usage/math.html#dsts" data-ice="link">DSTs</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/math.html"><a href="manual/usage/math.html#time-math" data-ice="link">Time math</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/math.html"><a href="manual/usage/math.html#math-with-multiple-units" data-ice="link">Math with multiple units</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/math.html"><a href="manual/usage/math.html#duration-math" data-ice="link">Duration math</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/math.html"><a href="manual/usage/math.html#basics" data-ice="link">Basics</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/math.html"><a href="manual/usage/math.html#diffs" data-ice="link">Diffs</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/math.html"><a href="manual/usage/math.html#casual-vs-longterm-conversion-accuracy" data-ice="link">Casual vs longterm conversion accuracy</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/math.html"><a href="manual/usage/math.html#losing-information" data-ice="link">Losing information</a></li> <li data-ice="manualNav" class="indent-h1 manual-color manual-color-usage" data-section-count="■■" data-link="manual/usage/validity.html"><a href="manual/usage/validity.html" data-ice="link">Validity</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/validity.html"><a href="manual/usage/validity.html#invalid-datetimes" data-ice="link">Invalid DateTimes</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/validity.html"><a href="manual/usage/validity.html#reasons-a-datetimes-can-be-invalid" data-ice="link">Reasons a DateTimes can be invalid</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/validity.html"><a href="manual/usage/validity.html#debugging-invalid-datetimes" data-ice="link">Debugging invalid DateTimes</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/validity.html"><a href="manual/usage/validity.html#invalidreason" data-ice="link">invalidReason</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/usage/validity.html"><a href="manual/usage/validity.html#throwoninvalid" data-ice="link">throwOnInvalid</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/validity.html"><a href="manual/usage/validity.html#invalid-durations" data-ice="link">Invalid Durations</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/usage/validity.html"><a href="manual/usage/validity.html#invalid-intervals" data-ice="link">Invalid Intervals</a></li> </ul> </div> <div data-ice="manual" data-toc-name="reference"> <ul class="manual-toc"> <li data-ice="manualNav" class="indent-h1 manual-color manual-color-reference" data-section-count="■■" data-link="identifiers.html"><a href="identifiers.html" data-ice="link">API reference</a></li> <li data-ice="manualNav" class="indent-h2" data-link="identifiers.html"><a href="identifiers.html#class" data-ice="link">Class</a></li> <li data-ice="manualNav" class="indent-h2" data-link="identifiers.html"><a href="identifiers.html#interface" data-ice="link">Interface</a></li> </ul> </div> <div data-ice="manual" data-toc-name="faq"> <ul class="manual-toc"> <li data-ice="manualNav" class="indent-h1 manual-color manual-color-faq" data-section-count="■■" data-link="manual/faq/matrix.html"><a href="manual/faq/matrix.html" data-ice="link">Support matrix</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/faq/matrix.html"><a href="manual/faq/matrix.html#what-works-everywhere" data-ice="link">What works everywhere</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/faq/matrix.html"><a href="manual/faq/matrix.html#new-capabilities-and-how-they-re-used" data-ice="link">New capabilities and how they're used</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/faq/matrix.html"><a href="manual/faq/matrix.html#the-matrix" data-ice="link">The matrix</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/faq/matrix.html"><a href="manual/faq/matrix.html#what-happens-if-a-feature-isn-t-supported-" data-ice="link">What happens if a feature isn't supported?</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/faq/matrix.html"><a href="manual/faq/matrix.html#polyfills" data-ice="link">Polyfills</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/faq/matrix.html"><a href="manual/faq/matrix.html#intl" data-ice="link">Intl</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/faq/matrix.html"><a href="manual/faq/matrix.html#zones" data-ice="link">Zones</a></li> <li data-ice="manualNav" class="indent-h1 manual-color manual-color-faq" data-section-count="■■■■" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html" data-ice="link">For Moment users</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#immutability" data-ice="link">Immutability</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#other-api-style-differences" data-ice="link">Other API style differences</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#major-functional-differences" data-ice="link">Major functional differences</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#datetime-method-equivalence" data-ice="link">DateTime method equivalence</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#creation" data-ice="link">Creation</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#getters-and-setters" data-ice="link">Getters and setters</a></li> <li data-ice="manualNav" class="indent-h4" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#basic-information-getters" data-ice="link">Basic information getters</a></li> <li data-ice="manualNav" class="indent-h4" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#unit-getters" data-ice="link">Unit getters</a></li> <li data-ice="manualNav" class="indent-h4" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#programmatic-get-and-set" data-ice="link">Programmatic get and set</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#transformation" data-ice="link">Transformation</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#query" data-ice="link">Query</a></li> <li data-ice="manualNav" class="indent-h3" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#output" data-ice="link">Output</a></li> <li data-ice="manualNav" class="indent-h4" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#basics" data-ice="link">Basics</a></li> <li data-ice="manualNav" class="indent-h4" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#humanization" data-ice="link">Humanization</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#durations" data-ice="link">Durations</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/faq/moment.html"><a href="manual/faq/moment.html#intervals" data-ice="link">Intervals</a></li> </ul> </div> <div data-ice="manual" data-toc-name="changelog"> <ul class="manual-toc"> <li data-ice="manualNav" class="indent-h1 manual-color manual-color-changelog" data-section-count="■" data-link="manual/changelog/changelog.html"><a href="manual/changelog/changelog.html" data-ice="link">Changelog</a></li> <li data-ice="manualNav" class="indent-h2" data-link="manual/changelog/changelog.html"><a href="manual/changelog/changelog.html#0-4" data-ice="link">0.4</a></li> </ul> </div> </div> </nav> <div class="content" data-ice="content"><div class="github-markdown"> <div class="manual-cards"> <div class="manual-card-wrap" data-ice="cards"> <h1 data-ice="label" class="manual-color manual-color-design" data-section-count="■■"><span data-ice="label-inner">Install guide</span></h1> <div class="manual-card"> <div data-ice="card"><h1>Install guide</h1><p>Luxon provides different builds for different JS environments. See below for a link to the right one and instructions on how to use it.</p><h2>Basic browser setup</h2><ul> <li><a href="./manual/../../global/luxon.js">Download full</a></li> <li><a href="./manual/../../global/luxon.min.js">Download minified</a></li> </ul><p>Just include Luxon in a script tag. You can access its various classes through the <code>luxon</code> global.</p><pre><code class="lang-html"><code class="source-code prettyprint"><script src="luxon.js"></script></code> </code></pre><p>You may wish to alias the classes you use:</p><pre><code class="lang-js"><code class="source-code prettyprint">var DateTime = luxon.DateTime;</code> </code></pre><h2>Node</h2><p>Install via NPM:</p><pre><code><code class="source-code prettyprint">npm install --save luxon</code> </code></pre><pre><code class="lang-js"><code class="source-code prettyprint">var luxon = require('luxon');</code> </code></pre><h2>AMD (System.js, RequireJS, etc)</h2><ul> <li><a href="./manual/../../amd/luxon.js">Download full</a></li> <li><a href="./manual/../../amd/luxon.min.js">Download minified</a></li> </ul><pre><code class="lang-js"><code class="source-code prettyprint">requirejs(['luxon'], function(luxon) { //... });</code> </code></pre><h2>ES6</h2><ul> <li><a href="./manual/../../es6/luxon.js">Download full</a></li> <li><a href="./manual/../../es6/luxon.min.js">Download minified</a></li> </ul><pre><code class="lang-js"><code class="source-code prettyprint">import { DateTime } from 'luxon';</code> </code></pre><h2>Webpack</h2><pre><code><code class="source-code prettyprint">npm install --save luxon</code> </code></pre><pre><code class="lang-js"><code class="source-code prettyprint">import { DateTime } from 'luxon';</code> </code></pre><h2>Meteor</h2><p>Help wanted.</p></div> <a data-ice="link" href="manual/design/install.html"></a> </div> </div> <div class="manual-card-wrap" data-ice="cards"> <h1 data-ice="label" class="manual-color manual-color-design" data-section-count="■■■■"><span data-ice="label-inner">A quick tour</span></h1> <div class="manual-card"> <div data-ice="card"><h1>A quick tour</h1><p>Luxon is a library that makes it easier to work with dates and times in Javascript. If you want, add and subtract them, format and parse them, ask them hard questions, and so on, Luxon provides a much easier and comprehensive interface than the native types it wraps. We're going to talk about the most immediately useful subset of that interface.</p><p>This is going to be a bit brisk, but keep in mind that the API docs are comprehensive, so if you want to know more, feel free to <a href="./manual/../identifiers.html">dive into them</a>.</p><h2>Your first DateTime</h2><p>The most important class in Luxon is <a href="./manual/../class/src/datetime.js~DateTime.html">DateTime</a>. A DateTime represents a specific millisecond in time, along with a time zone and a locale. Here's one that represents May 15, 2017 at 8:30 in the morning:</p><pre><code class="lang-js"><code class="source-code prettyprint">var dt = DateTime.local(2017, 5, 15, 8, 30);</code> </code></pre><p>To get the current time, just do this:</p><pre><code class="lang-js"><code class="source-code prettyprint">var now = DateTime.local();</code> </code></pre><p><a href="./manual/../class/src/datetime.js~DateTime.html#static-method-local">DateTime.local</a> takes any number of arguments, all the way out to milliseconds. Underneath, this is just a Javascript Date object. But we've decorated it with lots of useful methods.</p><h2>Creating a DateTime</h2><p>There are lots of ways to create a DateTime by parsing strings or constructing them out of parts. You've already seen one, <code>DateTime.local()</code>, but let's talk about two more.</p><h3>Create from an object</h3><p>The most powerful way to create a DateTime instance is to provide an object containing all the information:</p><pre><code class="lang-js"><code class="source-code prettyprint">dt = DateTime.fromObject({day: 22, hour: 12, zone: 'America/Los_Angeles', numberingSystem: 'beng'})</code> </code></pre><p>Don't worry too much about the properties you don't understand yet; the point is that you can set every attribute of a DateTime when you create it. One thing to notice from the example is that we just set the day and hour; the year and month get defaulted to the current one and the minutes, seconds, and milliseconds get defaulted to 0. So <a href="./manual/../class/src/datetime.js~DateTime.html#static-method-fromObject">DateTime.fromObject</a> is sort of the power user interface.</p><h3>Parse from ISO 8601</h3><p>Luxon has lots of parsing capabilities, but the most important one is parsing <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> strings, because they're more-or-less the standard wire format for dates and times. Use <a href="./manual/../class/src/datetime.js~DateTime.html#static-method-fromISO">DateTime.fromISO</a>.</p><pre><code class="lang-js"><code class="source-code prettyprint">DateTime.fromISO("2017-05-15") //=> May 15, 2017 at midnight DateTime.fromISO("2017-05-15T08:30:00") //=> May 15, 2017 at 8:30</code> </code></pre><p>You can parse a bunch of other formats, including <a href="./manual/usage/parsing.html">your own custom ones</a>.</p><h2>Getting to know your DateTime instance</h2><p>Now that we've made some DateTimes, let's see what we can ask of it.</p><h3>toString</h3><p>The first thing we want to see is the DateTime as a string. Luxon returns ISO 8601 strings:</p><pre><code class="lang-js"><code class="source-code prettyprint">DateTime.local().toString() //=> '2017-09-14T03:20:34.091-04:00'</code> </code></pre><h3>Getting at components</h3><p>We can get at the components of the time individually through getters. For example:</p><pre><code class="lang-js"><code class="source-code prettyprint">dt = DateTime.local() dt.year //=> 2017 dt.month //=> 9 dt.day //=> 14 dt.second //=> 47 dt.weekday //=> 4</code> </code></pre><h3>Other fun accessors</h3><pre><code class="lang-js"><code class="source-code prettyprint">dt.zoneName //=> 'America/New_York' dt.offset //=> -240 dt.daysInMonth //=> 30</code> </code></pre><p>There are lots more!</p><h2>Formatting your DateTime</h2><p>You may want to output your DateTime to a string for a machine or a human to read. Luxon has lots of tools for this, but two of them are most important. If you want to format a human-readable string, use <code>toLocaleString</code>:</p><pre><code class="lang-js"><code class="source-code prettyprint">dt.toLocaleString() //=> '9/14/2017' dt.toLocaleString({ month: 'long', day: 'numeric', hour: 'numeric', minute: 'numeric'}) //=> 'September 14, 3:21 AM'</code> </code></pre><p>This works well across different locales (languages) by letting the browser figure out what order the different parts go in and how to punctuate them.</p><p>If you want the string read by another program, you almost certainly want to use <code>toISO</code>:</p><pre><code class="lang-js"><code class="source-code prettyprint">dt.toISO() //=> '2017-09-14T03:21:47.070-04:00'</code> </code></pre><p>Custom formats are also supported. See <a href="./manual/usage/formatting.html">formatting</a>.</p><h2>Transforming your DateTime</h2><h3>Immutability</h3><p>Luxon objects are immutable. That means that you can't alter them in place, just create altered copies. Throughout the documentation, we use terms like "alter", "change", and "set" loosely, but rest assured we mean "create a new instance with different properties".</p><h3>Math</h3><p>This is easier to show than to tell. All of these calls return new DateTime instances:</p><pre><code class="lang-js"><code class="source-code prettyprint">var dt = DateTime.local(); dt.plus({hours: 3, minutes: 2}); dt.minus({days: 7}); dt.startOf('day'); dt.endOf('hour');</code> </code></pre><h3>Set</h3><p>You can create new instances by overriding specific properties:</p><pre><code class="lang-js"><code class="source-code prettyprint">var dt = DateTime.local(); dt.set({hour: 3}).hour //=> 3</code> </code></pre><h2>Intl</h2><p>Luxon provides several different Intl capabilities, but the most important one is in formatting:</p><pre><code class="lang-js"><code class="source-code prettyprint">var dt = DateTime.local(); var f = {month: 'long', day: 'numeric'}; dt.setLocale('fr').toLocaleString(f) //=> '14 septembre' dt.setLocale('en-GB).toLocaleString(f) //=> '14 September' dt.setLocale('en-US).toLocaleString(f) //=> 'September 14'</code> </code></pre><p>Luxon's Info class can also list months or weekdays for different locales:</p><pre><code class="lang-js"><code class="source-code prettyprint">Info.months('long', {locale: 'fr'}) //=> [ 'janvier', 'février', 'mars', 'avril', ... ]</code> </code></pre><h2>Time zones</h2><p>Luxon supports time zones. There's a whole <a href="./manual/usage/zones.html">big section</a> about it. But briefly, you can create DateTimes in specific zones and change their zones:</p><pre><code class="lang-js"><code class="source-code prettyprint">DateTime.fromObject({zone: 'America/Los_Angeles'}) // now, but expressed in LA's local time DateTime.local().setZone('America/Los_Angeles') // same</code> </code></pre><p>Luxon also supports UTC directly:</p><pre><code class="lang-js"><code class="source-code prettyprint">DateTime.utc(2017, 5, 15); DateTime.utc(); DateTime.local().toUTC(); DateTime.utc().toLocal();</code> </code></pre><h2>Durations</h2><p>The Duration class represents a quantity of time such as "2 hours and 7 minutes". You create them like this:</p><pre><code class="lang-js"><code class="source-code prettyprint">var dur = Duration.fromObject({hours: 2, minutes: 7});</code> </code></pre><p>They can be add or subtracted from DateTimes like this:</p><pre><code class="lang-js"><code class="source-code prettyprint">dt.plus(dur);</code> </code></pre><p>They have getters just like DateTime:</p><pre><code class="lang-js"><code class="source-code prettyprint">dur.hours //=> 2 dur.minutes //=> 7 dur.seconds //=> 0</code> </code></pre><p>And some other useful stuff:</p><pre><code class="lang-js"><code class="source-code prettyprint">dur.as('seconds') //=> 7620 dur.toObject() //=> { hours: 2, minutes: 7 } dur.toISO() //=> 'PT2H7M'</code> </code></pre><p>You can also format, negate, and normalize them. See it all in the <a href="./manual/../class/src/duration.js~Duration.html">Duration API docs</a>.</p><h2>Intervals</h2><p>Intervals are a specific period of time, such as "between now and midnight". They're really a wrapper for two DateTimes that form its endpoints. Here's what you can do with them:</p><pre><code class="lang-js"><code class="source-code prettyprint">now = DateTime.local(); later = DateTime.local(2020, 10, 12); i = Interval.fromDateTimes(now, later); i.length() //=> 97098768468 i.length('years', true) //=> 3.0762420239726027 i.contains(DateTime.local(2019)) //=> true i.toISO() //=> '2017-09-14T04:07:11.532-04:00/2020-10-12T00:00:00.000-04:00' i.toString() //=> '[2017-09-14T04:07:11.532-04:00 – 2020-10-12T00:00:00.000-04:00)</code> </code></pre><p>Intervals can be split up into smaller intervals, perform set-like operations with other intervals, and few other handy features. See the <a href="./manual/../class/src/interval.js~Interval.html">Interval API docs</a>.</p></div> <a data-ice="link" href="manual/design/tour.html"></a> </div> </div> <div class="manual-card-wrap" data-ice="cards"> <h1 data-ice="label" class="manual-color manual-color-usage" data-section-count="■■"><span data-ice="label-inner">Intl</span></h1> <div class="manual-card"> <div data-ice="card"><h1>Intl</h1><p>Luxon uses the native Intl API to provide easy-to-use internationalization. A quick example:</p><pre><code class="lang-js"><code class="source-code prettyprint">DateTime.local().setLocale('el').toLocaleString(DateTime.DATE_FULL); //=> '24 Σεπτεμβρίου 2017'</code> </code></pre><h2>How locales work</h2><p>Luxon DateTimes can be configured using <a href="https://tools.ietf.org/html/rfc5646">BCP 47</a> locale strings specifying the language to use generating or interpreting strings. The native Intl API provides the actual internationalized strings; Luxon just wraps it with a nice layer of convenience and integrates the localization functionality into the rest of Luxon. The Mozilla MDN Intl docs have a <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation">good description</a> of how the <code>locale</code> argument. In Luxon, the methods are different but the semantics are the same, except in that Luxon allows you to specify a numbering system and output calendar independently of the locale string (i.e. Luxon does the string munging for you).</p><p>The rest of this document will concentrate on what Luxon does when provided with locale information.</p><h2>Setting locale</h2><p><code>locale</code> is a property of Luxon object, and it defaults to 'en-US'. Thus, locale is a sort of setting on the DateTime object, as opposed to an argument you provide the different methods that need internationalized.</p><p>You can generally set it at construction time:</p><pre><code class="lang-js"><code class="source-code prettyprint">var dt = DateTime.fromISO('2017-09-24', { locale: 'fr' }) dt.locale //=> 'fr'</code> </code></pre><p>In this case, the specified locale didn't change the how the parsing worked (there's nothing localized about it), but it did set the locale property in the resulting instance. For other factory methods, such as <code>fromString</code>, the locale argument <em>does</em> affect how the string is parsed. See further down for more.</p><p>You can change the locale of a DateTime instance (meaning, create a clone DateTime with a different locale) using <code>setLocale</code>:</p><pre><code class="lang-js"><code class="source-code prettyprint">DateTime.local().setLocale('fr').locale //=> 'fr'</code> </code></pre><p><code>setLocale</code> is just a convenience for <code>reconfigure</code>:</p><pre><code class="lang-js"><code class="source-code prettyprint">DateTime.local().reconfigure({ locale: 'fr' }).locale; //=> 'fr'</code> </code></pre><h2>Checking what you got</h2><p>The local environment may not support the exact locale you asked for. The native Intl API will try to find the best match. If you want to know what that match was, use <code>resolvedLocaleOpts</code>:</p><pre><code class="lang-js"><code class="source-code prettyprint">DateTime.fromObject({locale: 'fr-co'}).resolvedLocaleOpts(); //=> { locale: 'fr', // numberingSystem: 'latn', // outputCalendar: 'gregory' }</code> </code></pre><h2>Methods affected by the locale</h2><h3>Formatting</h3><p>The most important method affected by the locale setting is <code>toLocaleString</code>, which allows you to produce internationalized, human-readable strings.</p><pre><code class="lang-js"><code class="source-code prettyprint">dt.setLocale('fr').toLocaleString(DateTime.DATE_FULL) //=> '25 septembre 2017'</code> </code></pre><p>That's the normal way to do it: set the locale as property of the DateTime itself and let the <code>toLocaleString</code> inherit it. But you can specify the locale directly to <code>toLocaleString</code> too:</p><pre><code class="lang-js"><code class="source-code prettyprint">dt.toLocaleString( Object.assign({ locale: 'es' }, DateTime.DATE_FULL)) //=> '25 de septiembre de 2017'</code> </code></pre><p>Ad-hoc formatting also respects the locale:</p><pre><code class="lang-js"><code class="source-code prettyprint">dt.setLocale('fr').toFormat('MMMM dd, yyyy GG'); //=> 'septembre 25, 2017 après Jésus-Christ'</code> </code></pre><h3>Parsing</h3><p>You can <a href="./manual/parsing.md">parse</a> localized strings:</p><pre><code class="lang-js"><code class="source-code prettyprint">DateTime.fromString('septembre 25, 2017 après Jésus-Christ', 'MMMM dd, yyyy GG', {locale: 'fr'})</code> </code></pre><h3>Listing</h3><p>Some of the methods in the <a href="./manual/../docs/class/src/info.js~Info.html">Info</a> class let you list strings like months, weekdays, and eras, and they can be localized:</p><pre><code class="lang-js"><code class="source-code prettyprint">Info.months('long', { locale: 'fr' }) //=> [ 'janvier', 'février', ... Info.weekdays('long', { locale: 'fr' }) //=> [ 'lundi', 'mardi', ... Info.eras('long', { locale: 'fr' }) //=> [ 'avant Jésus-Christ', 'après Jésus-Christ' ]</code> </code></pre><h2>numberingSystem</h2><p>DateTimes also have a <code>numberingSystem</code> setting that lets you control what system of numerals is used in formatting. In general, you shouldn't override the numbering system provided by the locale. For example, no extra work is needed to get Arabic numbers to show up in Arabic-speaking locales:</p><pre><code class="lang-js"><code class="source-code prettyprint">var dt = DateTime.local().setLocale('ar') dt.resolvedLocaleOpts() //=> { locale: 'ar', // numberingSystem: 'arab', // outputCalendar: 'gregory' } dt.toLocaleString() //=> '٢٤‏/٩‏/٢٠١٧'</code> </code></pre><p>For this reason, Luxon defaults its own <code>numberingSystem</code> property to null, by which it means "let the Intl API decide". However, you can override it if you want. This example is admittedly ridiculous:</p><pre><code class="lang-js"><code class="source-code prettyprint">var dt = DateTime.local().reconfigure({ locale: 'it', numberingSystem: 'beng' }) dt.toLocaleString(DateTime.DATE_FULL) //=> '২৪ settembre ২০১৭'</code> </code></pre></div> <a data-ice="link" href="manual/usage/intl.html"></a> </div> </div> <div class="manual-card-wrap" data-ice="cards"> <h1 data-ice="label" class="manual-color manual-color-usage" data-section-count="■■■■■"><span data-ice="label-inner">Time zones and offsets</span></h1> <div class="manual-card"> <div data-ice="card"><h1>Time zones and offsets</h1><p>Luxon has support for time zones. This page explains how to use them.</p><h2>Don't worry!</h2><p>You <em>usually</em> don't need to worry about time zones. Your code runs on a computer with a particular time zone and everything will work consistently in that zone without you doing anything. It's when you want to do complicated stuff <em>across</em> zones that you have to think about it. Even then, here are some pointers to help you avoid situations where you have to think carefully about time zones:</p><ol> <li>Don't make servers think about <em>local</em> times. Configure them to use UTC and write your server's code to work in UTC. Times can often be thought of as a simple count of epoch milliseconds; what you would call that time (e.g. 9:30) in what zone doesn't (again, often) matter.</li> <li>Communicate times between systems in ISO 8601, like "2017-05-15T13:30:34Z" where possible (it doesn't matter if you use Z or some local offset; the point is that it precisely identifies the millisecond on the global timeline).</li> <li>Where possible, only think of time zones as a formatting concern; your application ideally never knows that the time it's working with is called "9:00" until it's being rendered to the user.</li> <li>Barring 3, do as much manipulation of the time (say, adding an hour to the current time) in the client code that's already running in the time zone where the results will matter.</li> </ol><p>All those things will make it less likely you ever need to work explicitly with time zones and may also save you plenty of other headaches. But those aren't possible for some applications; you might need to work with times in zones other than the one the program is running in, for any number of reasons. And that's where Luxon's time zone support comes in.</p><h2>Terminology</h2><p>Bear with me here. Time zones are pain in the ass. Luxon has lots of tools to deal with them, but there's no getting around the fact that they're complicated. The terminology for time zones and offsets isn't well-established. But let's try to impose some order:</p><ol> <li>An <strong>offset</strong> is a difference between the local time and the UTC time, such as +5 (hours) or -12:30. They may be expressed directly in minutes, or in hours, or in a combination of minutes and hours. Here we'll use hours.</li> <li>A <strong>time zone</strong> is a set of rules, associated with a geographical location, that determines the local offset from UTC at any given time. The best way to identify a zone is by its IANA string, such as "America/New_York". That zone says something to the effect of "The offset is -4, except between March and November, when it's -5".</li> <li>A <strong>fixed-offset time zone</strong> is any time zone that never changes offsets, such as UTC. Luxon supports fixed-offset zones directly; they're specified like UTC+7, which you can interpret as "always with an offset of +7".</li> <li>A <strong>named offset</strong> is a time zone-specific name for an offset, such as Eastern Daylight Time. It expresses both the zone (America's EST roughly implies America/New_York) and the current offset (EST means +4). They are also confusing in that they overspecify the offset (e.g. for any given time it is unnecessary to specify EST vs EDT; it's always whichever one is right). They are also ambiguous (BST is both British Summer Time and Bangladesh Standard Time), unstandardized, and internationalized (what would a Frenchman call the US's EST?). For all these reasons, you should avoid them when specifying times programmatically. Luxon only supports their use in formatting.</li> </ol><p>Some subtleties:</p><ol> <li>Multiple zones can have the same offset (think