Format

Return the formatted date string in the given format. The result may vary by locale.

• Characters wrapped between two single quotes (') are escaped.
• Two single quotes in a row, whether inside or outside a quoted sequence, represent a real single quote.

Common Patterns

Notes

1. "Formatting" units (e.g. formatting quarter) in the default en-US locale are the same as "stand-alone" units, but are different in some languages. "Formatting" units are declined according to the rules of the language in the context of a date. "Stand-alone" units are always nominative singular.

2. Any sequence of the identical letters is a pattern, unless it is escaped by the single quote characters. If the sequence is longer than listed in table, the output will be the same as default pattern for this unit, usually the longest one (e.g. EEEE for weekdays).

3. Some patterns could be unlimited length (such as yyyyyyyy). The output will be padded with zeros to match the length of the pattern.

4. QQQQQ and qqqqq could be not strictly numerical in some locales. These tokens represent the shortest form of the quarter.

5. The main difference between y and u patterns are B.C. years. Also yy always returns the last two digits of a year, while uu pads single digit years to 2 characters and returns other years unchanged. The same difference is true for local and ISO week-numbering years (Y and R).

6. Specific non-location timezones are currently unavailable, so these tokens fall back to GMT timezones.

7. These patterns are not in the Unicode Technical Standard #35 and are datezone extensions: i, I, R, t, T, o, P, p.

8. YY and YYYY tokens represent week-numbering years but are often confused with years. Use with care.

9. D and DD tokens represent days of the year but are often confused with days of the month. Use with care.

Examples

import { format } from "datezone";

// Basic usage
const formattedBasic = format(1392076800000, "yyyy-MM-dd", {
	timeZone: "America/New_York",
});
console.log(formattedBasic); // '2014-02-10'

// Escaping text
const formattedEscaped = format(1404322800000, "h 'o''clock'", {
	timeZone: "America/New_York",
});
console.log(formattedEscaped); // "1 o'clock"

// Localized output
const formattedLocalized = format(1392076800000, "PPPP", {
	locale: "en-US",
	timeZone: null,
});
console.log(formattedLocalized); // 'Tuesday, February 11th, 2014'

Another example:

import { format, type TimeZone } from "datezone";

// Current timestamp
const now = Date.now();

// Example timezone
const timeZone: TimeZone = "America/New_York";

// Format examples
console.log("Basic formatting:");
console.log(format(now, "yyyy-MM-dd", { timeZone }));
console.log(format(now, "MMM dd, yyyy", { timeZone }));
console.log(format(now, "h:mm a", { timeZone }));
console.log(format(now, "EEEE, MMMM do, yyyy", { timeZone }));

// With different locales
console.log("\nWith different locales:");
console.log(format(now, "MMMM dd, yyyy", { locale: "en-US", timeZone }));
console.log(format(now, "dd MMMM yyyy", { locale: "es-ES", timeZone }));

// Complex formatting
console.log("\nComplex format:");
console.log(format(now, "yyyy-MM-dd'T'HH:mm:ss.SSSxxx", { timeZone }));