Document Era related APIs

docs/moment/01-parsing/03-string-format.md

@@ -107,7 +107,6 @@ Note that the number of `S` characters provided is only relevant when parsing in
 In standard mode, `S`, `SS`, `SSS`, `SSSS` are all equivalent, and interpreted as fractions of a second.
 For example, `.12` is always 120 milliseconds, passing `SS` will not cause it to be interpreted as 12 milliseconds.
 
-
 `Z ZZ` were added in version **1.2.0**.
 
 `S SS SSS` were added in version **1.6.0**.
@@ -123,6 +122,23 @@ moment("2010-10-20 4:30",       "YYYY-MM-DD HH:mm");   // parsed as 4:30 local t
 moment("2010-10-20 4:30 +0000", "YYYY-MM-DD HH:mm Z"); // parsed as 4:30 UTC
 ```
 
+#### Era Year related tokens
+
+*Tokens are case-sensitive.*
+
+| Input     | Examples      | Description    |
+|-----------|---------------|----------------|
+| y .. yyyy | `5 +5 -500`   | Years          |
+| yo        | `5th 1st`     | Ordinal Years  |
+| N         | `AD`          | Abbr Era name  |
+| NN        | `AD`          | Short Era name |
+| NNN       | `Anno Domini` | Full Era name  |
+
+
+Era support was added in **2.25.0**. The tokens/API are still in flux.
+
+#### Notes and gotchas
+
 If the moment that results from the parsed input does not exist, `moment#isValid` will return false.
 
 ```js

docs/moment/04-displaying/01-format.md

@@ -171,6 +171,32 @@ moment('gibberish').format('YYYY MM DD');         // "Invalid date"
         <b>Note:</b> This complies with the ISO 8601 standard for dates past the year 9999
       </td>
     </tr>
+    <tr>
+      <td><b>Era Year</b></td>
+      <td>y</td>
+      <td>1 2 ... 2020 ... </td>
+    </tr>
+    <tr>
+      <td><b>Era</b></td>
+      <td>N</td>
+      <td> BC AD<br />
+        <b>Note:</b> Abbr era name
+      </td>
+    </tr>
+    <tr>
+      <td></td>
+      <td>NN</td>
+      <td> BC AD<br />
+        <b>Note:</b> Narrow era name
+      </td>
+    </tr>
+    <tr>
+      <td></td>
+      <td>NNN</td>
+      <td> Before Christ, Anno Domini <br />
+        <b>Note:</b> Full era name
+      </td>
+    </tr>
     <tr>
       <td><b>Week Year</b></td>
       <td>gg</td>
@@ -407,7 +433,7 @@ If you are more comfortable working with strftime instead of LDML-like parsing t
 
 Calling `moment#format` without a format will default to `moment.defaultFormat`. Out of the box, `moment.defaultFormat` is the ISO8601 format `YYYY-MM-DDTHH:mm:ssZ`.
 
-As of version **2.13.0**, when in UTC mode, the default format is governed by `moment.defaultFormatUtc` which is in the format `YYYY-MM-DDTHH:mm:ss[Z]`. This returns ``Z`` as the offset, instead of ``+00:00``. 
+As of version **2.13.0**, when in UTC mode, the default format is governed by `moment.defaultFormatUtc` which is in the format `YYYY-MM-DDTHH:mm:ss[Z]`. This returns ``Z`` as the offset, instead of ``+00:00``.
 
 In certain instances, a local timezone (such as `Atlantic/Reykjavik`) may have a zero offset, and will be considered to be UTC. In such cases, it may be useful to set `moment.defaultFormat` and `moment.defaultFormatUtc` to use the same formatting.
 

docs/moment/07-customization/17-eras.md

@@ -0,0 +1,46 @@
+---
+title: Eras
+version: 2.25.0
+signature: |
+  moment.updateLocale('en', {
+      eras: [{
+          since:  '0001-01-01',
+          until:  +Infinity,
+          offset: 1,
+          name:   'Anno Domini',
+          narrow: 'AD',
+          abbr:   'AD'
+      }, {
+          until:   -Infinity,
+          since:  '0000-12-31',
+          offset: 1,
+          name:   'Before Christ',
+          narrow: 'BC',
+          abbr:   'BC'
+      }],
+  });
+---
+
+Specify Eras for a particular locale. An era is a time interval with name and
+year numbering. Absolute year number (like 2020) can also be specified as 2020
+AD: the 2020th year of the era AD. Similarly the absolute year number -0500 can
+be described as 501 BC, the 501st year from the BC era.
+
+```javascript
+eras: [{
+    since:  '0001-01-01', // the start of the era
+    until:  +Infinity,    // the end of the era, can be +/-Infinity
+    offset: 1,            // added to year to (mostly) avoid 0 era years
+    name:   'Anno Domini',// full name of era
+    narrow: 'AD',         // narrow name of era
+    abbr:   'AD'          // abbreviated name of era
+}]
+```
+
+`since` and `until` govern the direction of the era. As in the case of `BC` it
+grows toward `-Infinity`, thus `since` > `until`. For eras that
+increment toward +Infinity `since` < `until`.
+
+Parsing/formatting of eras is accomplished with `yo`, `y*` and `N*` tokens.
+
+**Note**: The era-related APIs are subject to change.