Skip to content

Latest commit

 

History

History
119 lines (88 loc) · 4.82 KB

readme.md

File metadata and controls

119 lines (88 loc) · 4.82 KB
Raw

strtime

MIT License Build Status NPM version

The strtime package provides native JavaScript implementations of the strftime and strptime functions. It supports most of the combined features of Python, Ruby, and GNU C strftime and strptime functions. It's possible to write and parse calendar dates (e.g. %Y-%m-%d), week dates (e.g. %G-W%V-%u), and ordinal dates (e.g. %Y-%j).

Installation

You can add the strtime package to your project using a JavaScript package manager such as npm.

npm install --save strtime

Directives

You can read complete documentation regarding the directives which strtime supports (e.g. %Y, %b) and how they behave in directives.md.

Basic usage

The strftime function accepts Date objects, unix timestamps (as milliseconds since UTC epoch), moment datetime objects, luxon datetime objects, and dayjs datetime objects. The strptime function always outputs a Date object.

const strftime = require("strtime").strftime;
const strptime = require("strtime").strptime;

// Prints "2000-01-01T00:00:00.000Z"
console.log(strftime(new Date("2000-01-01"), "%Y-%m-%dT%H:%M:%S.%LZ"));

// Prints "2000-01-01T00:00:00.000Z"
const date = strptime("2000-01-01T00:00:00.000Z", "%Y-%m-%dT%H:%M:%S.%LZ");
console.log(date.toISOString());

Advanced usage

Timezone output with strftime

The strftime function defaults to writing a UTC timestamp. You can specify which timezone should be used by passing it as an argument. Timezones are accepted as numeric offsets or as abbreviations such as UTC or EDT or EEST. Offsets between and including -16 and +16 are interpreted as hour offsets. Other offset values are interpreted as minute offsets. You can also use the string local to use the local timezone.

// Prints "2000-01-01 12:00:00 GMT+0000"
console.log(strftime(new Date("2000-01-01T12:00:00Z"), "%Y-%m-%d %H:%M:%S GMT%z"));

// Prints "2000-01-01 14:00:00 GMT+0200"
console.log(strftime(new Date("2000-01-01T12:00:00Z"), "%Y-%m-%d %H:%M:%S GMT%z", +2));

// Prints "2000-01-01 08:00:00 GMT-0400"
console.log(strftime(new Date("2000-01-01T12:00:00Z"), "%Y-%m-%d %H:%M:%S GMT%z", "EDT"));

Timezone assumption with strptime

The strptime function assumes that a timestamp represents a UTC date if no timezone is specified in that timestamp. You can specify what timezone should be assumed for timestamps which do not contain an explicit timezone by passing it as an argument. The strptime function accepts timezones arguments in the same way that strftime does.

// Prints e.g. "2000-01-01T12:00:00.000Z"
const date = strptime("2000-01-01 12:00:00", "%Y-%m-%d %H:%M:%S");
console.log(date.toISOString());

// Prints "2000-01-01T10:00:00.000Z" due to the +2 hours offset
const date = strptime("2000-01-01 12:00:00", "%Y-%m-%d %H:%M:%S", +2);
console.log(date.toISOString());

Locale-dependent strings

The strftime and strptime functions default to English weekday names, month names, and ordinals. However, it is possible to specify different text by passing an options object.

The options object attributes which are recognized for this purpose are:

  • shortWeekdayNames: A list of abbreviated weekday names, e.g. "Sun", "Mon".
  • longWeekdayNames: A list of full weekday names, e.g. "Sunday", "Monday".
  • shortMonthNames: A list of abbreviated month names, e.g. "Jan", "Feb".
  • longMonthNames: A list of full month names, e.g. "January", "February".
  • eraNames: A list of era names, e.g. "CE", "BCE".
  • meridiemNames: A list of meridiem strings, e.g. "AM", "PM".
  • ordinalTransform: A function accepting a number and outputting an ordinal suffix, e.g. 1 => "st".
const monthNames = [
    "enero", "febrero", "marzo", "abril", "mayo", "junio",
    "julio", "agosto", "septiembre", "octubre", "noviembre", "diciembre"
];

// Prints "1 enero 2000"
console.log(strftime(new Date("2000-01-01"), "%-d %B %Y", +0, {
    longMonthNames: monthNames
}));