Time Formatting and Parsing

/**
 * Creates a time formatter function using the default locale
 * @param specifier - Format string with % directives
 * @returns Function that formats Date objects to strings
 */
function timeFormat(specifier: string): (date: Date) => string;

import { timeFormat } from "d3-time-format";

const formatMonth = timeFormat("%B");
const formatDay = timeFormat("%A");
const formatDateTime = timeFormat("%B %d, %Y at %I:%M %p");

const date = new Date(2014, 4, 1); // Thu May 01 2014

formatMonth(date); // "May"
formatDay(date); // "Thursday"
formatDateTime(date); // "May 01, 2014 at 12:00 AM"

/**
 * Creates a time parser function using the default locale
 * @param specifier - Format string with % directives matching expected input
 * @returns Function that parses date strings to Date objects or null
 */
function timeParse(specifier: string): (dateString: string) => Date | null;

import { timeParse } from "d3-time-format";

const parseMonth = timeParse("%B %d, %Y");
const parseDateTime = timeParse("%Y-%m-%dT%H:%M:%S");

parseMonth("June 30, 2015"); // Date object for June 30, 2015
parseDateTime("2015-06-30T19:15:28"); // Date object for that exact time
parseDateTime("invalid"); // null

/**
 * Creates a UTC time formatter function using the default locale
 * @param specifier - Format string with % directives
 * @returns Function that formats Date objects to UTC strings
 */
function utcFormat(specifier: string): (date: Date) => string;

import { utcFormat } from "d3-time-format";

const formatUTC = utcFormat("%Y-%m-%d %H:%M:%S");
const formatISOStyle = utcFormat("%Y-%m-%dT%H:%M:%SZ");

const date = new Date(2015, 5, 30, 12, 30, 0);
formatUTC(date); // "2015-06-30 19:30:00" (if local timezone is UTC-7)
formatISOStyle(date); // "2015-06-30T19:30:00Z"

/**
 * Creates a UTC time parser function using the default locale
 * @param specifier - Format string with % directives matching expected input
 * @returns Function that parses UTC date strings to Date objects or null
 */
function utcParse(specifier: string): (dateString: string) => Date | null;

import { utcParse } from "d3-time-format";

const parseUTC = utcParse("%Y-%m-%dT%H:%M:%SZ");
const parseCustomUTC = utcParse("%B %d, %Y at %H:%M UTC");

parseUTC("2015-06-30T19:15:28Z"); // Date object interpreted as UTC
parseCustomUTC("June 30, 2015 at 19:15 UTC"); // Date object interpreted as UTC
parseUTC("invalid format"); // null

// Date components
%d  // Zero-padded day of month [01,31]
%e  // Space-padded day of month [ 1,31]
%j  // Day of the year [001,366] 
%m  // Month as decimal [01,12]
%y  // Year without century [00,99]
%Y  // Year with century (e.g., 1999)

// Week-based
%u  // Monday-based weekday [1,7] (ISO 8601)
%w  // Sunday-based weekday [0,6]
%U  // Sunday-based week of year [00,53]
%W  // Monday-based week of year [00,53]
%V  // ISO 8601 week of year [01,53]
%g  // ISO 8601 week-based year without century [00,99]
%G  // ISO 8601 week-based year with century

// Quarter
%q  // Quarter of the year [1,4]

// Time components
%H  // Hour (24-hour) [00,23]
%I  // Hour (12-hour) [01,12]
%M  // Minutes [00,59]
%S  // Seconds [00,61]
%L  // Milliseconds [000,999]
%f  // Microseconds [000000,999999]

// Time zones
%Z  // Time zone offset (-0700, -07:00, -07, or Z)

// Unix timestamps
%Q  // Milliseconds since UNIX epoch
%s  // Seconds since UNIX epoch

// Weekdays (affected by locale)
%a  // Abbreviated weekday name (Sun, Mon, ...)
%A  // Full weekday name (Sunday, Monday, ...)

// Months (affected by locale)
%b  // Abbreviated month name (Jan, Feb, ...)
%B  // Full month name (January, February, ...)

// Periods (affected by locale)
%p  // AM or PM equivalent

// Composite formats (affected by locale)
%c  // Complete date and time (equivalent to %x, %X)
%x  // Locale date format (%-m/%-d/%Y in US)
%X  // Locale time format (%-I:%M:%S %p in US)

// Literal
%%  // Literal percent sign

// Modifier characters (placed after % and before directive)
%0d  // Zero-padding (default): "01", "02", ...
%_d  // Space-padding: " 1", " 2", ...
%-d  // No padding: "1", "2", ...

// Example usage
timeFormat("%0d")  // "01" (default zero-padding)
timeFormat("%_d")  // " 1" (space-padding)
timeFormat("%-d")  // "1" (no padding)

const parseStrict = timeParse("%Y-%m-%dT%H:%M:%SZ");
parseStrict("2011-07-01T19:15:28Z"); // ✓ Success
parseStrict("2011-07-01T19:15:28");  // ✗ null (missing Z)
parseStrict("2011-07-01 19:15:28");  // ✗ null (space instead of T)
parseStrict("2011-07-01");           // ✗ null (incomplete)

function flexibleParse(dateString) {
  const formats = [
    timeParse("%Y-%m-%dT%H:%M:%SZ"),
    timeParse("%Y-%m-%d %H:%M:%S"),
    timeParse("%Y-%m-%d"),
    timeParse("%m/%d/%Y")
  ];
  
  for (const parse of formats) {
    const result = parse(dateString);
    if (result) return result;
  }
  return null;
}

const format = timeFormat("%Y-%m-%d");
format(new Date(2015, 5, 30)); // Date object
format(1435622400000);          // Timestamp number
format("2015-06-30");           // Date-parseable string