DateTime Parsing

The library supports parsing dates and times from strings using configurable style flags.

DateTime Formatter

The DotNetDateTimeFormatter class supports parsing dates from strings:

import { DotNetDateTimeFormatter, DotNetLocaleSettings } from '@pbkware/dot-net-date-number-formatting';

const formatter = new DotNetDateTimeFormatter();
formatter.localeSettings = DotNetLocaleSettings.createInvariant();
formatter.trySetFormat('yyyy-MM-dd');

const result = formatter.tryFromString('2024-07-05');
if (result.isOk()) {
  console.log(result.value);  // Date object: Fri Jul 05 2024 00:00:00
} else {
  console.error(result.error);
}
Copy

DateTime Style Flags

Control which date/time formats are allowed during parsing using DotNetDateTimeStyleFlags:

Available Flags

Flag	Description
allowLeadingWhite	Permit leading whitespace
allowTrailingWhite	Permit trailing whitespace
allowInnerWhite	Permit whitespace within date/time string
noCurrentDateDefault	Do not use current date for missing components
adjustToUniversal	Adjust date/time to UTC (not implemented)
assumeLocal	Assume local time zone if not specified (not implemented)
assumeUniversal	Assume UTC time zone if not specified (not implemented)
roundTripKind	Preserve DateTimeKind when parsing (not implemented)

Custom Style Combinations

import { DotNetDateTimeFormatter, DotNetDateTimeStyleFlags, DotNetLocaleSettings } from '@pbkware/dot-net-date-number-formatting';

const formatter = new DotNetDateTimeFormatter();
formatter.localeSettings = DotNetLocaleSettings.createInvariant();
formatter.trySetFormat('yyyy-MM-dd');

// Configure allowed styles using bitwise OR
formatter.styles = 
  DotNetDateTimeStyleFlags.allowLeadingWhite |
  DotNetDateTimeStyleFlags.allowTrailingWhite;

// These will parse successfully
let result = formatter.tryFromString('  2024-07-05  ');
console.log(result.value);  // Date object

result = formatter.tryFromString('2024-07-05');
console.log(result.value);  // Date object

// Without allowInnerWhite, this would fail with extra spaces
formatter.styles = 
  DotNetDateTimeStyleFlags.allowLeadingWhite |
  DotNetDateTimeStyleFlags.allowTrailingWhite |
  DotNetDateTimeStyleFlags.allowInnerWhite;
Copy

Predefined Style Sets

Use DotNetDateTimeStyles for common parsing scenarios:

DotNetDateTimeStyles.none

No special styles - strict parsing only:

import { DotNetDateTimeStyles } from '@pbkware/dot-net-date-number-formatting';

formatter.styles = DotNetDateTimeStyles.none;

// Only exact matches work
formatter.trySetFormat('yyyy-MM-dd');
formatter.tryFromString('2024-07-05');    // OK
formatter.tryFromString('  2024-07-05'); // Error
Copy

DotNetDateTimeStyles.allowWhiteSpaces

Allow whitespace in date/time strings:

formatter.styles = DotNetDateTimeStyles.allowWhiteSpaces;

// Includes: allowLeadingWhite, allowTrailingWhite, allowInnerWhite
formatter.trySetFormat('yyyy-MM-dd');
formatter.tryFromString('  2024-07-05  ');  // OK
formatter.tryFromString('2024-07-05');       // OK
Copy

Individual Style Flags

You can also use individual flags directly from DotNetDateTimeStyles:

// Allow only leading whitespace
formatter.styles = DotNetDateTimeStyles.allowLeadingWhite;

// Allow only trailing whitespace
formatter.styles = DotNetDateTimeStyles.allowTrailingWhite;

// Allow inner whitespace
formatter.styles = DotNetDateTimeStyles.allowInnerWhite;
Copy

Parsing with Standard Format Strings

When using standard format strings, the parser uses JavaScript's built-in Date constructor:

import { DotNetDateTimeFormatter, DotNetDateTimeStyles } from '@pbkware/dot-net-date-number-formatting';

const formatter = new DotNetDateTimeFormatter();
formatter.styles = DotNetDateTimeStyles.allowWhiteSpaces;

// Standard format strings use JavaScript's Date parsing
formatter.trySetFormat('s');  // Sortable format
const result = formatter.tryFromString('2024-07-05T14:30:45');
console.log(result.value);  // Date object
Copy

Parsing with Custom Format Strings

Custom format strings allow precise parsing of specific date/time patterns:

Date Parsing Examples

import { DotNetDateTimeFormatter, DotNetDateTimeStyles, DotNetLocaleSettings } from '@pbkware/dot-net-date-number-formatting';

const formatter = new DotNetDateTimeFormatter();
formatter.localeSettings = DotNetLocaleSettings.createInvariant();
formatter.styles = DotNetDateTimeStyles.allowWhiteSpaces;

// ISO 8601 date
formatter.trySetFormat('yyyy-MM-dd');
let result = formatter.tryFromString('2024-07-05');
console.log(result.value);  // Fri Jul 05 2024 00:00:00

// US date format
formatter.trySetFormat('MM/dd/yyyy');
result = formatter.tryFromString('07/05/2024');
console.log(result.value);  // Fri Jul 05 2024 00:00:00

// European date format
formatter.trySetFormat('dd.MM.yyyy');
result = formatter.tryFromString('05.07.2024');
console.log(result.value);  // Fri Jul 05 2024 00:00:00

// Two-digit year (assumes 1900-1999 for 50-99, 2000-2049 for 00-49)
formatter.trySetFormat('MM/dd/yy');
result = formatter.tryFromString('07/05/24');
console.log(result.value);  // Fri Jul 05 2024 00:00:00

result = formatter.tryFromString('07/05/99');
console.log(result.value);  // Mon Jul 05 1999 00:00:00
Copy

Time Parsing Examples

// 24-hour time
formatter.trySetFormat('HH:mm:ss');
let result = formatter.tryFromString('14:30:45');
console.log(result.value);  // Date with time 14:30:45

// 12-hour time with AM/PM
formatter.trySetFormat('hh:mm:ss tt');
result = formatter.tryFromString('02:30:45 PM');
console.log(result.value);  // Date with time 14:30:45

// Time with fractional seconds
formatter.trySetFormat('HH:mm:ss.fff');
result = formatter.tryFromString('14:30:45.123');
console.log(result.value);  // Date with time 14:30:45.123
Copy

DateTime Parsing Examples

// ISO 8601 datetime
formatter.trySetFormat('yyyy-MM-dd HH:mm:ss');
let result = formatter.tryFromString('2024-07-05 14:30:45');
console.log(result.value);  // Fri Jul 05 2024 14:30:45

// US datetime format
formatter.trySetFormat('MM/dd/yyyy hh:mm:ss tt');
result = formatter.tryFromString('07/05/2024 02:30:45 PM');
console.log(result.value);  // Fri Jul 05 2024 14:30:45

// Filename-safe format
formatter.trySetFormat('yyyy-MM-dd_HHmmss');
result = formatter.tryFromString('2024-07-05_143045');
console.log(result.value);  // Fri Jul 05 2024 14:30:45
Copy

Month and Day Names

The parser can match month and day names:

// Full month names
formatter.trySetFormat('MMMM d, yyyy');
let result = formatter.tryFromString('July 5, 2024');
console.log(result.value);  // Fri Jul 05 2024 00:00:00

// Abbreviated month names
formatter.trySetFormat('MMM d, yyyy');
result = formatter.tryFromString('Jul 5, 2024');
console.log(result.value);  // Fri Jul 05 2024 00:00:00

// Day names (ignored during parsing but must match)
formatter.trySetFormat('dddd, MMMM d, yyyy');
result = formatter.tryFromString('Friday, July 5, 2024');
console.log(result.value);  // Fri Jul 05 2024 00:00:00

// Short day names
formatter.trySetFormat('ddd, MMM d, yyyy');
result = formatter.tryFromString('Fri, Jul 5, 2024');
console.log(result.value);  // Fri Jul 05 2024 00:00:00
Copy

Literal Text in Format Strings

Use quotes or backslashes to include literal text:

// Using single quotes
formatter.trySetFormat("'Date:' yyyy-MM-dd");
let result = formatter.tryFromString('Date: 2024-07-05');
console.log(result.value);  // Fri Jul 05 2024 00:00:00

// Using double quotes
formatter.trySetFormat('"Time:" HH:mm');
result = formatter.tryFromString('Time: 14:30');
console.log(result.value);  // Date with time 14:30:00

// Using backslash escape
formatter.trySetFormat('yyyy\\-MM\\-dd');
result = formatter.tryFromString('2024-MM-dd');
console.log(result.value);  // Fri Jul 05 2024 00:00:00 (note: only literal characters match)
Copy

Examples

Flexible DateTime Parsing

import { DotNetDateTimeFormatter, DotNetDateTimeStyleFlags, DotNetLocaleSettings } from '@pbkware/dot-net-date-number-formatting';

const formatter = new DotNetDateTimeFormatter();
formatter.localeSettings = DotNetLocaleSettings.createInvariant();

// Configure flexible parsing
formatter.styles = 
  DotNetDateTimeStyleFlags.allowLeadingWhite |
  DotNetDateTimeStyleFlags.allowTrailingWhite;

formatter.trySetFormat('yyyy-MM-dd HH:mm:ss');

const inputs = [
  '2024-07-05 14:30:45',
  '  2024-07-05 14:30:45',
  '2024-07-05 14:30:45  ',
  '  2024-07-05 14:30:45  '
];

for (const input of inputs) {
  const result = formatter.tryFromString(input);
  if (result.isOk()) {
    console.log(`Parsed: ${result.value}`);
  } else {
    console.error(`Failed to parse: ${input}`);
  }
}
Copy

Parsing Multiple DateTime Formats

import { DotNetDateTimeFormatter, DotNetDateTimeStyles, DotNetLocaleSettings } from '@pbkware/dot-net-date-number-formatting';

const formatter = new DotNetDateTimeFormatter();
formatter.localeSettings = DotNetLocaleSettings.createInvariant();
formatter.styles = DotNetDateTimeStyles.allowWhiteSpaces;

function tryParseDate(input: string): Date | null {
  const formats = [
    'yyyy-MM-dd',
    'MM/dd/yyyy',
    'dd.MM.yyyy',
    'yyyy-MM-dd HH:mm:ss',
    'MM/dd/yyyy hh:mm:ss tt',
    'MMMM d, yyyy',
  ];

  for (const format of formats) {
    formatter.trySetFormat(format);
    const result = formatter.tryFromString(input);
    if (result.isOk()) {
      return result.value;
    }
  }

  return null;
}

console.log(tryParseDate('2024-07-05'));           // Fri Jul 05 2024 00:00:00
console.log(tryParseDate('07/05/2024'));           // Fri Jul 05 2024 00:00:00
console.log(tryParseDate('July 5, 2024'));         // Fri Jul 05 2024 00:00:00
console.log(tryParseDate('2024-07-05 14:30:45'));  // Fri Jul 05 2024 14:30:45
Copy

Error Handling

import { DotNetDateTimeFormatter, DotNetDateTimeStyles, DotNetLocaleSettings } from '@pbkware/dot-net-date-number-formatting';

const formatter = new DotNetDateTimeFormatter();
formatter.localeSettings = DotNetLocaleSettings.createInvariant();
formatter.styles = DotNetDateTimeStyles.none;  // Strict parsing
formatter.trySetFormat('yyyy-MM-dd');

// Invalid format - has leading whitespace
let result = formatter.tryFromString('  2024-07-05');
if (result.isErr()) {
  console.error(result.error);  // "DateTime string does not match all Format specifiers"
}

// Invalid date
result = formatter.tryFromString('2024-13-45');  // Invalid month and day
if (result.isErr()) {
  console.error(result.error);  // "Year, Month or Day is invalid"
}

// Format mismatch
result = formatter.tryFromString('07/05/2024');  // US format but expects ISO
if (result.isErr()) {
  console.error(result.error);  // "DateTime string does not match all Format specifiers"
}
Copy

Locale-Specific Parsing

Date and time separators from locale settings are used during parsing:

import { DotNetDateTimeFormatter, DotNetDateTimeStyles, DotNetLocaleSettings } from '@pbkware/dot-net-date-number-formatting';

const formatter = new DotNetDateTimeFormatter();
formatter.styles = DotNetDateTimeStyles.allowWhiteSpaces;

// US English (slash separator)
formatter.localeSettings = DotNetLocaleSettings.create('en-US');
formatter.trySetFormat('MM/dd/yyyy');
let result = formatter.tryFromString('07/05/2024');
console.log(result.value);  // Fri Jul 05 2024 00:00:00

// German (dot separator)
formatter.localeSettings = DotNetLocaleSettings.create('de-DE');
formatter.trySetFormat('dd.MM.yyyy');
result = formatter.tryFromString('05.07.2024');
console.log(result.value);  // Fri Jul 05 2024 00:00:00
Copy

Limitations

Some features from .NET are not fully implemented:

• Time zone parsing is not fully implemented (adjustToUniversal, assumeLocal, assumeUniversal flags are not implemented)
• The roundTripKind flag is not implemented
• Era formatting (Japanese, Taiwanese, Korean calendars) is not supported
• Some culture-specific calendar systems are not supported
• The noCurrentDateDefault flag is defined but has limited effect