Build from latest source.

dist/nifty-tou.d.ts

@@ -12,6 +12,100 @@
  */
 declare function cconcat(s1?: string, s2?: string): string;
 
+/**
+ * An enumeration of supported chronological fields of the Gregorian calendar.
+ * @public
+ */
+export declare enum ChronoField {
+    /** The month of year, from January (1) to December (12). */
+    MONTH_OF_YEAR = 1,
+    /** The day of the week, from Monday (1) to Sunday (7). */
+    DAY_OF_WEEK = 2
+}
+
+/**
+ * Class to parse locale-specific chronological field names of the Gregorian calendar.
+ * @public
+ */
+export declare class ChronoFieldParser {
+    #private;
+    /**
+     * Get a parser for a given locale.
+     *
+     * This method will instantiate and cache parsers, returning cached instances
+     * if already avaialble.
+     *
+     * @param locale - the locale of the parser to get
+     * @returns the parser
+     */
+    static forLocale(locale: string): ChronoFieldParser;
+    /**
+     * Constructor.
+     *
+     * @param locale - the desired locale
+     */
+    constructor(locale: string);
+    /**
+     * Get the locale.
+     */
+    get locale(): string;
+    /**
+     * Parse a field value.
+     *
+     * @param field - the field to treat `val` as
+     * @param value - the field value to parse
+     * @returns the associated field value, or undefined if not found
+     */
+    parse(field: ChronoField, value: string): ChronoFieldValue;
+    /**
+     * Parse a chronological field range string.
+     *
+     * A "range string" is a string formatted like `VALUE - VALUE`. Whitespace
+     * is ignored, and the `- VALUE` portion can be omitted for a singleton
+     * range. For example, in the `en-US` locale, `Jan-Dec` would be parsed as
+     * `[1..12]`.
+     *
+     * @example
+     * Here are some basic examples:
+     *
+     * ```ts
+     * const p = ChronoFieldParser.forLocale('en-US');
+     * p.parseRange(ChronoField.MONTH_OF_YEAR, 'Jan-Dec'); // [1..12]
+     * p.parseRange(ChronoField.MONTH_OF_YEAR, '4-6');     // [4..6]
+     * p.parseRange(ChronoField.DAY_OF_WEEK, 'Wednesday'); // [3..3]
+     * ```
+     *
+     * @param field - the field to parse the range values as
+     * @param value - the range string to parse
+     * @returns the parsed range, or `undefined` if not parsable as a range
+     */
+    parseRange(field: ChronoField, value: string): IntRange;
+}
+
+/**
+ * A chronological field value.
+ * @public
+ */
+export declare class ChronoFieldValue {
+    #private;
+    /**
+     * Constructor.
+     *
+     * @param field - the chronological field
+     * @param names - the value names, from longest to shortest
+     * @param value - the value
+     */
+    constructor(field: ChronoField, names: string[], value: number);
+    /** Get the field. */
+    get field(): ChronoField;
+    /** Get the full name. */
+    get name(): string;
+    /** Get the short name. */
+    get shortName(): string;
+    /** Get the value. */
+    get value(): number;
+}
+
 /**
  * An immutable number range with min/max values.
  * @public
@@ -30,6 +124,15 @@ export declare class IntRange {
      * Create a range.
      */
     static rangeOf(min: number, max: number): IntRange;
+    /**
+     * Parse a range array into an `IntRange`.
+     *
+     * @param value - the range array to parse; can have 1 or 2 elements; all elements must have number values
+     * @param bounds - the optional bounds (inclusive) to enforce; if the parsed range
+     * @returns the parsed range, or `undefined` if a range could not be parsed or extends
+     *          beyond the given `bounds` then `undefined` will be returned
+     */
+    static parseRange(array: string[], bounds?: IntRange): IntRange;
     /**
      * Get the minimum value.
      */
@@ -132,6 +235,38 @@ export declare class IntRange {
     static description(full: IntRange, r: IntRange): string;
 }
 
+/**
+ * A locale-specific number parser.
+ *
+ * Adapted from Mike Bostock's https://observablehq.com/\@mbostock/localized-number-parsing
+ * @public
+ */
+export declare class NumberParser {
+    #private;
+    /**
+     * Constructor.
+     *
+     * @param locale - the desired locale
+     */
+    constructor(locale: string);
+    /** Get the locale. */
+    get locale(): string;
+    /**
+     * Normalize a locale-specific number string.
+     *
+     * @param s - the number string to parse in this instance's locale
+     * @returns the number string normalized into a JavaScript number string
+     */
+    norm(s: string): string;
+    /**
+     * Parse a locale-specific number string.
+     *
+     * @param s - the number string to parse in this instance's locale
+     * @returns the parsed number, or `undefined`
+     */
+    parse(s: string): number;
+}
+
 /**
  * Verify that a variable is undefined or of a given type.
  *
@@ -166,6 +301,18 @@ declare function prefix(prefix?: string, s?: string): string;
  */
 declare function required<T>(arg: T, name: string, type?: new (...args: any[]) => any): T;
 
+/**
+ * Split a string based on a range delimiter pattern.
+ *
+ * A range delimited string has the pattern `VALUE - VALUE`, where whitespace
+ * at the start, around the `-` delimiter, and at the end is not significant.
+ *
+ * @param range - the range string to split into components, whitespace trimmed
+ * @returns the split range, of length 1 or 2, or `undefined` if `range` is undefined
+ * @public
+ */
+declare function splitRange(range: string): string[];
+
 /**
  * An identifiable tariff rate.
  *
@@ -284,7 +431,8 @@ declare namespace Utils {
         cconcat,
         optional,
         prefix,
-        required
+        required,
+        splitRange
     }
 }
 export { Utils }

docs/md/nifty-tou.chronofield.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [nifty-tou](./nifty-tou.md) &gt; [ChronoField](./nifty-tou.chronofield.md)
+
+## ChronoField enum
+
+An enumeration of supported chronological fields of the Gregorian calendar.
+
+**Signature:**
+
+```typescript
+export declare enum ChronoField 
+```
+
+## Enumeration Members
+
+|  Member | Value | Description |
+|  --- | --- | --- |
+|  DAY\_OF\_WEEK | <code>2</code> | The day of the week, from Monday (1) to Sunday (7). |
+|  MONTH\_OF\_YEAR | <code>1</code> | The month of year, from January (1) to December (12). |
+

docs/md/nifty-tou.chronofieldparser._constructor_.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [nifty-tou](./nifty-tou.md) &gt; [ChronoFieldParser](./nifty-tou.chronofieldparser.md) &gt; [(constructor)](./nifty-tou.chronofieldparser._constructor_.md)
+
+## ChronoFieldParser.(constructor)
+
+Constructor.
+
+**Signature:**
+
+```typescript
+constructor(locale: string);
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  locale | string | the desired locale |
+

docs/md/nifty-tou.chronofieldparser.forlocale.md

@@ -0,0 +1,28 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [nifty-tou](./nifty-tou.md) &gt; [ChronoFieldParser](./nifty-tou.chronofieldparser.md) &gt; [forLocale](./nifty-tou.chronofieldparser.forlocale.md)
+
+## ChronoFieldParser.forLocale() method
+
+Get a parser for a given locale.
+
+This method will instantiate and cache parsers, returning cached instances if already avaialble.
+
+**Signature:**
+
+```typescript
+static forLocale(locale: string): ChronoFieldParser;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  locale | string | the locale of the parser to get |
+
+**Returns:**
+
+[ChronoFieldParser](./nifty-tou.chronofieldparser.md)
+
+the parser
+

docs/md/nifty-tou.chronofieldparser.locale.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [nifty-tou](./nifty-tou.md) &gt; [ChronoFieldParser](./nifty-tou.chronofieldparser.md) &gt; [locale](./nifty-tou.chronofieldparser.locale.md)
+
+## ChronoFieldParser.locale property
+
+Get the locale.
+
+**Signature:**
+
+```typescript
+get locale(): string;
+```

docs/md/nifty-tou.chronofieldparser.md

@@ -0,0 +1,34 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [nifty-tou](./nifty-tou.md) &gt; [ChronoFieldParser](./nifty-tou.chronofieldparser.md)
+
+## ChronoFieldParser class
+
+Class to parse locale-specific chronological field names of the Gregorian calendar.
+
+**Signature:**
+
+```typescript
+export declare class ChronoFieldParser 
+```
+
+## Constructors
+
+|  Constructor | Modifiers | Description |
+|  --- | --- | --- |
+|  [(constructor)(locale)](./nifty-tou.chronofieldparser._constructor_.md) |  | Constructor. |
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [locale](./nifty-tou.chronofieldparser.locale.md) | <code>readonly</code> | string | Get the locale. |
+
+## Methods
+
+|  Method | Modifiers | Description |
+|  --- | --- | --- |
+|  [forLocale(locale)](./nifty-tou.chronofieldparser.forlocale.md) | <code>static</code> | <p>Get a parser for a given locale.</p><p>This method will instantiate and cache parsers, returning cached instances if already avaialble.</p> |
+|  [parse(field, value)](./nifty-tou.chronofieldparser.parse.md) |  | Parse a field value. |
+|  [parseRange(field, value)](./nifty-tou.chronofieldparser.parserange.md) |  | <p>Parse a chronological field range string.</p><p>A "range string" is a string formatted like <code>VALUE - VALUE</code>. Whitespace is ignored, and the <code>- VALUE</code> portion can be omitted for a singleton range. For example, in the <code>en-US</code> locale, <code>Jan-Dec</code> would be parsed as <code>[1..12]</code>.</p> |
+

docs/md/nifty-tou.chronofieldparser.parse.md

@@ -0,0 +1,27 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [nifty-tou](./nifty-tou.md) &gt; [ChronoFieldParser](./nifty-tou.chronofieldparser.md) &gt; [parse](./nifty-tou.chronofieldparser.parse.md)
+
+## ChronoFieldParser.parse() method
+
+Parse a field value.
+
+**Signature:**
+
+```typescript
+parse(field: ChronoField, value: string): ChronoFieldValue;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  field | [ChronoField](./nifty-tou.chronofield.md) | the field to treat <code>val</code> as |
+|  value | string | the field value to parse |
+
+**Returns:**
+
+[ChronoFieldValue](./nifty-tou.chronofieldvalue.md)
+
+the associated field value, or undefined if not found
+

docs/md/nifty-tou.chronofieldparser.parserange.md

@@ -0,0 +1,40 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [nifty-tou](./nifty-tou.md) &gt; [ChronoFieldParser](./nifty-tou.chronofieldparser.md) &gt; [parseRange](./nifty-tou.chronofieldparser.parserange.md)
+
+## ChronoFieldParser.parseRange() method
+
+Parse a chronological field range string.
+
+A "range string" is a string formatted like `VALUE - VALUE`<!-- -->. Whitespace is ignored, and the `- VALUE` portion can be omitted for a singleton range. For example, in the `en-US` locale, `Jan-Dec` would be parsed as `[1..12]`<!-- -->.
+
+**Signature:**
+
+```typescript
+parseRange(field: ChronoField, value: string): IntRange;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  field | [ChronoField](./nifty-tou.chronofield.md) | the field to parse the range values as |
+|  value | string | the range string to parse |
+
+**Returns:**
+
+[IntRange](./nifty-tou.intrange.md)
+
+the parsed range, or `undefined` if not parsable as a range
+
+## Example
+
+Here are some basic examples:
+
+```ts
+const p = ChronoFieldParser.forLocale('en-US');
+p.parseRange(ChronoField.MONTH_OF_YEAR, 'Jan-Dec'); // [1..12]
+p.parseRange(ChronoField.MONTH_OF_YEAR, '4-6');     // [4..6]
+p.parseRange(ChronoField.DAY_OF_WEEK, 'Wednesday'); // [3..3]
+```
+

docs/md/nifty-tou.chronofieldvalue._constructor_.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [nifty-tou](./nifty-tou.md) &gt; [ChronoFieldValue](./nifty-tou.chronofieldvalue.md) &gt; [(constructor)](./nifty-tou.chronofieldvalue._constructor_.md)
+
+## ChronoFieldValue.(constructor)
+
+Constructor.
+
+**Signature:**
+
+```typescript
+constructor(field: ChronoField, names: string[], value: number);
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  field | [ChronoField](./nifty-tou.chronofield.md) | the chronological field |
+|  names | string\[\] | the value names, from longest to shortest |
+|  value | number | the value |
+