Date: Olson-timezone-support (real z, v, V) and options.timeZone (2/2)

Gruntfile.js

@@ -123,7 +123,13 @@ module.exports = function( grunt ) {
 				paths: {
 					cldr: "../external/cldrjs/dist/cldr",
 					"make-plural": "../external/make-plural/make-plural",
-					messageformat: "../external/messageformat/messageformat"
+					messageformat: "../external/messageformat/messageformat",
+					"zoned-date-time": "../node_modules/zoned-date-time/src/zoned-date-time"
+				},
+				shim: {
+					"zoned-date-time": {
+						exports: "ZonedDateTime"
+					}
 				},
 				skipSemiColonInsertion: true,
 				skipModuleInsertion: true,
@@ -246,6 +252,14 @@ module.exports = function( grunt ) {
 							"}());",
 							"/* jshint ignore:end */"
 						].join( "\n" ) );
+
+					// ZonedDateTime
+					} else if ( ( /zoned-date-time/ ).test( id ) ) {
+						contents = contents.replace(
+							"module.exports = ZonedDateTime;",
+							"return ZonedDateTime;"
+						);
+						contents = "var ZonedDateTime = (function() {\n" + contents + "}());";
 					}
 
 					// 1, and 2: Remove define() wrap.

README.md

@@ -146,7 +146,7 @@ information on its usage.
 |---|--:|--:|---|
 | globalize.js | 1.5KB | 1.0KB | [Core library](#core-module) |
 | globalize/currency.js | 2.6KB | 0.6KB | [Currency module](#currency-module) provides currency formatting and parsing |
-| globalize/date.js | 5.1KB | 3.8KB | [Date module](#date-module) provides date formatting and parsing |
+| globalize/date.js | 7.7KB | 5.0KB | [Date module](#date-module) provides date formatting and parsing |
 | globalize/message.js | 5.4KB | 0.7KB | [Message module](#message-module) provides ICU message format support |
 | globalize/number.js | 3.8KB | 2.1KB | [Number module](#number-module) provides number formatting and parsing |
 | globalize/plural.js | 2.3KB | 0.4KB | [Plural module](#plural-module) provides pluralization support |
@@ -169,12 +169,13 @@ version of a browser is 24.x, we support the 24.x and 23.x versions.
 
 ## Getting Started
 
-    npm install globalize cldr-data
+    npm install globalize cldr-data iana-tz-data
 
 ```js
 var Globalize = require( "globalize" );
 Globalize.load( require( "cldr-data" ).entireSupplemental() );
 Globalize.load( require( "cldr-data" ).entireMainFor( "en", "es" ) );
+Globalize.loadIANATimeZone( require( "iana-tz-data" ) );
 
 Globalize("en").formatDate(new Date());
 // > "11/27/2015"
@@ -183,9 +184,17 @@ Globalize("es").formatDate(new Date());
 // > "27/11/2015"
 ```
 
-Note `cldr-data` is an optional module, read [CLDR content](#2-cldr-content) section below for more information on how to get CLDR from different sources.
+Note `cldr-data` is an optional module, read [CLDR content](#2-cldr-content)
+section below for more information on how to get CLDR from different sources.
 
-Read the [Locales section](#locales) for more information about supported locales. For AMD, bower and other usage examples, see [Examples section](#examples).
+The [`iana-tz-data`](https://github.com/rxaviers/iana-tz-data) module is only
+needed when IANA time zones (via `options.timeZone`) are used with date
+functions. Read [IANA time zone data](#3-iana-time-zone-data) below for more
+information.
+
+Read the [Locales section](#locales) for more information about supported
+locales. For AMD, bower and other usage examples, see [Examples
+section](#examples).
 
 ### Installation
 
@@ -245,7 +254,7 @@ requirements. See table below.
 |---|---|
 | Core module | cldr/supplemental/likelySubtags.json |
 | Currency module | cldr/main/`locale`/currencies.json<br>cldr/supplemental/currencyData.json<br>+CLDR JSON files from number module<br>+CLDR JSON files from plural module for name style support |
-| Date module | cldr/main/`locale`/ca-gregorian.json<br>cldr/main/`locale`/timeZoneNames.json<br>cldr/supplemental/timeData.json<br>cldr/supplemental/weekData.json<br>+CLDR JSON files from number module |
+| Date module | cldr/main/`locale`/ca-gregorian.json<br>cldr/main/`locale`/timeZoneNames.json<br>cldr/supplemental/metaZones.json<br>cldr/supplemental/timeData.json<br>cldr/supplemental/weekData.json<br>+CLDR JSON files from number module |
 | Number module | cldr/main/`locale`/numbers.json<br>cldr/supplemental/numberingSystems.json |
 | Plural module | cldr/supplemental/plurals.json (for cardinals)<br>cldr/supplemental/ordinals.json (for ordinals) |
 | Relative time module | cldr/main/`locale`/dateFields.json<br>+CLDR JSON files from number and plural modules |
@@ -255,7 +264,25 @@ As an alternative to deducing this yourself, use this [online tool](http://johnn
 
 *(b) How am I supposed to get and load CLDR content?*
 
-Learn [how to get and load CLDR content...](doc/cldr.md).
+Learn [how to get and load CLDR content...](doc/cldr.md) and use
+[`Globalize.load()`](#core-module) to load it.
+
+#### 3. IANA time zone data
+
+The IANA time zone (tz) database, sometimes called the Olson database, is the
+standard data used by Unicode CLDR, ECMA-402, Linux, UNIX, Java, ICU, and
+others. It's used by Globalize to circumvent the JavaScript limitations with
+respect to manipulating date in time zones other than the user's environment.
+
+In short, feed Globalize on IANA time zone data if you need to format or parse
+dates in a specific time zone, independently of the user's environment, e.g.,
+`America/Los_Angeles`.
+
+It's important to note there's no official IANA time zone data in the JSON
+format. Therefore, [`iana-tz-data`](https://github.com/rxaviers/iana-tz-data)
+has been adopted for convenience.
+
+Learn more on [`Globalize.loadIANATimeZone()`](#date-module).
 
 ### Usage
 
@@ -422,6 +449,13 @@ Read more details about locale at [UTS#35 locale][].
 
 ### Date module
 
+- **`Globalize.loadIANATimeZone( ianaTzData )`**
+
+  This method allows you to load IANA time zone data to enable
+  `options.timeZone` feature on date formatters and parsers.
+
+  [Read more...](doc/api/date/load-iana-time-zone.md)
+
 - **`.dateFormatter( [options] )`**
 
   Return a function that formats a date according to the given `options`. The default formatting is
@@ -442,6 +476,12 @@ Read more details about locale at [UTS#35 locale][].
 
   .dateFormatter({ datetime: "medium" })( new Date() )
   // > "Nov 1, 2010, 5:55:00 PM"
+
+  .dateFormatter({ datetime: "full", timeZone: "America/New_York" })( new Date() );
+  // > "Monday, November 1, 2010 at 3:55:00 AM Eastern Daylight Time"
+
+  .dateFormatter({ datetime: "full", timeZone: "America/Los_Angeles" })( new Date() );
+  // > "Monday, November 1, 2010 at 12:55:00 AM Pacific Daylight Time"
   ```
 
   [Read more...](doc/api/date/date-formatter.md)

doc/api/date/date-formatter.md

@@ -54,6 +54,12 @@ A JSON object including one of the following.
 > [raw pattern (anything in the "Sym." column)](http://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table)
 > eg. `{ raw: "dd/mm" }`. Note this is NOT recommended for i18n in general.
 > Use `skeleton` instead.
+>
+> **timeZone**
+>
+> String based on the time zone names of the [IANA time zone
+> database](https://www.iana.org/time-zones), such as `"Asia/Shanghai"`, `"Asia/Kolkata"`,
+> `"America/New_York"`.
 
 **value**
 
@@ -63,15 +69,12 @@ Date instance to be formatted, eg. `new Date()`;
 
 Prior to using any date methods, you must load
 `cldr/main/{locale}/ca-gregorian.json`, `cldr/main/{locale}/timeZoneNames.json`,
-`cldr/supplemental/timeData.json`, `cldr/supplemental/weekData.json`, and the
-CLDR content required by the number module. Read [CLDR content][] if you need
-more information.
+`cldr/supplemental/metaZones.json`, `cldr/supplemental/timeData.json`,
+`cldr/supplemental/weekData.json`, and the CLDR content required by the number
+module. Read [CLDR content][] if you need more information.
 
 [CLDR content]: ../../../README.md#2-cldr-content
 
-You can use the static method `Globalize.dateFormatter()`, which uses the default
-locale.
-
 ```javascript
 var formatter;
 
@@ -183,6 +186,26 @@ hourMinuteSecondFormatter( date );
 // > "17:55:00"
 ```
 
+Using specific timeZones, i.e., using `options.timezone`. Note that prior to using
+it, you must load IANA time zone data.
+
+```js
+Globalize.loadIANATimeZone( require( "iana-tz-data" ) );
+```
+
+```js
+Globalize.locale( "en" );
+
+Globalize.dateFormatter({ datetime: "medium", timeZone: "America/Los_Angeles" })( new Date() );
+// > "Nov 1, 2010, 12:55:00 PM"
+
+Globalize.dateFormatter({ datetime: "medium", timeZone: "America/Sao_Paulo" })( new Date() )
+// > "Nov 1, 2010, 5:55:00 PM"
+
+Globalize.dateFormatter({ datetime: "full", timeZone: "Europe/Berlin" })( new Date() )
+// > "Monday, November 1, 2010 at 8:55:00 PM Central European Standard Time"
+```
+
 For improved performance on iterations, first create the formatter. Then, reuse
 it on each loop.
 

doc/api/date/load-iana-time-zone.md

@@ -0,0 +1,31 @@
+## Globalize.loadIANATimeZone( ianaTzData )
+
+This method allows you to load IANA time zone data to enable `options.timeZone`
+feature on date formatters and parsers.
+
+### Parameters
+
+**ianaTzData**
+
+A JSON object with zdumped IANA timezone data. Get the data via
+[`iana-tz-data`](https://github.com/rxaviers/iana-tz-data).
+
+### Example
+
+```javascript
+Globalize.loadIANATimeZone({
+  "zoneData": {
+    ...
+    "America": {
+      ...
+      "New_York": {
+        abbrs: [],
+        untils: [],
+        offsets: [],
+        isdsts: []
+      }
+      ...
+    }
+  }
+});
+```

examples/amd-bower/bower.json

@@ -2,7 +2,8 @@
   "name": "globalize-hello-world-amd-bower",
   "dependencies": {
     "cldr-data": "*",
-    "globalize": ">=1.3.0-a <2.0.0"
+    "globalize": ">=1.3.0-a <2.0.0",
+    "iana-tz-data": "*"
   },
   "devDependencies": {
     "requirejs": "2.1.14",

examples/amd-bower/index.html

@@ -21,6 +21,7 @@ <h2>Requirements</h2>
         <h2>Demo output</h2>
         <p>Now: <span id="date"></span></p>
         <p>Now: <span id="dateToParts"></span> (note the highlighted month, the markup was added using formatDateToParts)</p>
+        <p>Now (in America/Sao_Paulo): <span id="zonedDate"></span></p>
         <p>A number: <span id="number"></span></p>
         <p>A currency: <span id="currency"></span></p>
         <p>Plural form of <span id="plural-number"></span> is <span id="plural-form"></span></p>

examples/amd-bower/main.js

@@ -9,6 +9,9 @@ require.config({
 		// Unicode CLDR JSON data.
 		"cldr-data": "./bower_components/cldr-data",
 
+		// IANA time zone data.
+		"iana-tz-data": "../bower_components/iana-tz-data/iana-tz-data",
+
 		// require.js plugin we'll use to fetch CLDR JSON content.
 		json: "./bower_components/requirejs-plugins/src/json",
 
@@ -32,13 +35,16 @@ require([
 	"json!cldr-data/main/en/currencies.json",
 	"json!cldr-data/main/en/dateFields.json",
 	"json!cldr-data/main/en/numbers.json",
+	"json!cldr-data/main/en/timeZoneNames.json",
 	"json!cldr-data/main/en/units.json",
 	"json!cldr-data/supplemental/currencyData.json",
 	"json!cldr-data/supplemental/likelySubtags.json",
+	"json!cldr-data/supplemental/metaZones.json",
 	"json!cldr-data/supplemental/plurals.json",
 	"json!cldr-data/supplemental/timeData.json",
 	"json!cldr-data/supplemental/weekData.json",
 	"json!messages/en.json",
+	"json!iana-tz-data.json",
 
 	// Extend Globalize with Date and Number modules.
 	"globalize/currency",
@@ -48,8 +54,9 @@ require([
 	"globalize/plural",
 	"globalize/relative-time",
 	"globalize/unit"
-], function( Globalize, enGregorian, enCurrencies, enDateFields, enNumbers, enUnits, currencyData,
-	likelySubtags, pluralsData, timeData, weekData, messages ) {
+], function( Globalize, enGregorian, enCurrencies, enDateFields, enNumbers,
+	enTimeZoneNames, enUnits, currencyData, likelySubtags, metaZones,
+	pluralsData, timeData, weekData, messages, ianaTzData ) {
 
 	var en, like, number;
 
@@ -60,13 +67,16 @@ require([
 		enDateFields,
 		enGregorian,
 		enNumbers,
+		enTimeZoneNames,
 		enUnits,
 		likelySubtags,
+		metaZones,
 		pluralsData,
 		timeData,
 		weekData
 	);
 	Globalize.loadMessages( messages );
+	Globalize.loadIANATimeZone( ianaTzData );
 
 	// Instantiate "en".
 	en = Globalize( "en" );
@@ -76,6 +86,12 @@ require([
 		datetime: "medium"
 	});
 
+	// Use Globalize to format dates on specific time zone.
+	document.getElementById( "zonedDate" ).textContent = en.formatDate( new Date(), {
+		datetime: "full",
+		timeZone: "America/Sao_Paulo"
+	});
+
 	// Use Globalize to format dates to parts.
 	document.getElementById( "dateToParts" ).innerHTML = en.formatDateToParts( new Date(), {
 		datetime: "medium"

examples/app-npm-webpack/app/index.js

@@ -11,6 +11,12 @@ document.getElementById( "currency" ).textContent = currencyFormatter( 69900 );
 var dateFormatter = Globalize.dateFormatter({ datetime: "medium" });
 document.getElementById( "date" ).textContent = dateFormatter( new Date() );
 
+var dateWithTimeZoneFormatter = Globalize.dateFormatter({
+	datetime: "full",
+	timeZone: "America/Sao_Paulo"
+});
+document.getElementById( "date-time-zone" ).textContent = dateWithTimeZoneFormatter( new Date() );
+
 var _dateToPartsFormatter = Globalize.dateToPartsFormatter({ datetime: "medium" });
 var dateToPartsFormatter = function( value ) {
 	return _dateToPartsFormatter( value, {
@@ -37,6 +43,7 @@ document.getElementById( "intro-1" ).textContent = Globalize.formatMessage( "int
 document.getElementById( "number-label" ).textContent = Globalize.formatMessage( "number-label" );
 document.getElementById( "currency-label" ).textContent = Globalize.formatMessage( "currency-label" );
 document.getElementById( "date-label" ).textContent = Globalize.formatMessage( "date-label" );
+document.getElementById( "date-time-zone-label" ).textContent = Globalize.formatMessage( "date-time-zone-label" );
 document.getElementById( "date-to-parts-label" ).textContent = Globalize.formatMessage( "date-to-parts-label" );
 document.getElementById( "relative-time-label" ).textContent = Globalize.formatMessage( "relative-time-label" );
 document.getElementById( "unit-label" ).textContent = Globalize.formatMessage( "unit-label" );
@@ -60,6 +67,7 @@ document.getElementById( "demo" ).style.display = "block";
 setInterval(function() {
 	var elapsedTime = +( ( startTime - new Date() ) / 1000 ).toFixed( 0 );
 	document.getElementById( "date" ).textContent = dateFormatter( new Date() );
+	document.getElementById( "date-time-zone" ).textContent = dateWithTimeZoneFormatter( new Date() );
 	document.getElementById( "date-to-parts" ).innerHTML = dateToPartsFormatter( new Date() );
 	document.getElementById( "relative-time" ).textContent = relativeTimeFormatter( elapsedTime );
 	document.getElementById( "message-1" ).textContent = Globalize.formatMessage( "message-1", {

examples/app-npm-webpack/index-template.html

@@ -33,6 +33,10 @@ <h2>Requirements</h2>
 				<td><span id="date-label">Standalone Date</span></td>
 				<td>"<span id="date"></span>"</td>
 			</tr>
+			<tr>
+				<td><span id="date-time-zone-label">Standalone Date (in a specific IANA time zone, e.g., America/Sao_Paulo)</span></td>
+				<td>"<span id="date-time-zone"></span>"</td>
+			</tr>
 			<tr>
 				<td><span id="date-to-parts-label">Standalone Date (note the highlighted month, the markup was added using formatDateToParts)</span></td>
 				<td>"<span id="date-to-parts"></span>"</td>

examples/app-npm-webpack/messages/ar.json

@@ -4,6 +4,7 @@
 		"number-label": "رقم",
 		"currency-label": "عملة",
 		"date-label": "تاريخ",
+		"date-time-zone-label": "التاريخ (في منطقة زمنية محددة ل إيانا، على سبيل المثال، America/Sao_Paulo)",
 		"date-to-parts-label": "التاريخ (لاحظ الشهر القوي، تمت إضافة الترميز باستخدام formatDateToParts)",
 		"relative-time-label": "الوقت النسبي",
 		"unit-label": "وحدة القياس",

examples/app-npm-webpack/messages/de.json

@@ -4,6 +4,7 @@
 		"number-label": "Zahl",
 		"currency-label": "Währung",
 		"date-label": "Datum",
+		"date-time-zone-label": "Datum (in einer bestimmten IANA-Zeitzone, z. B. America/Sao_Paulo)",
 		"date-to-parts-label": "Datum (beachten Sie den hervorgehobenen Monat, das Markup wurde mit dateToPartsFormatter hinzugefügt)",
 		"relative-time-label": "Relative Zeit",
 		"unit-label": "Einheit",

examples/app-npm-webpack/messages/en.json

@@ -4,6 +4,7 @@
 		"number-label": "Number",
 		"currency-label": "Currency",
 		"date-label": "Date",
+		"date-time-zone-label": "Date (in a specific IANA time zone, e.g., America/Sao_Paulo)",
 		"date-to-parts-label": "Date (note the highlighted month, the markup was added using formatDateToParts)",
 		"relative-time-label": "Relative Time",
 		"unit-label": "Unit",

examples/app-npm-webpack/messages/es.json

@@ -4,6 +4,7 @@
 		"number-label": "Número",
 		"currency-label": "Moneda",
 		"date-label": "Fecha",
+		"date-time-zone-label": "Fecha (en una zona horaria IANA específica, por ejemplo, America/Sao_Paulo)",
 		"date-to-parts-label": "Fecha (note el mes destacado en negro, el marcador de html se agregó utilizando dateToPartsFormatter)",
 		"relative-time-label": "Tiempo Relativo",
 		"unit-label": "Unidad",

examples/app-npm-webpack/messages/pt.json

@@ -4,6 +4,7 @@
 		"number-label": "Número",
 		"currency-label": "Moeda",
 		"date-label": "Data",
+		"date-time-zone-label": "Data (em um fuso horário IANA específico, por exemplo, America/Sao_Paulo)",
 		"date-to-parts-label": "Data (note o mês em negrito, a marcação HTML foi adicionada usando formatDateToParts)",
 		"relative-time-label": "Tempo relativo",
 		"unit-label": "Unit",