dafo

General Date Format

Description

To format date in PHP or MySQL style.

Table of Contents

• DISCLAIMER
• Get Started
• API
  • dafo/mysql
  • dafo/php
  • dafo.parse
  • dafo.toSeconds
  • Others
• Why dafo
• About
• References
• CHANGE LOG
• Homepage

DISCLAIMER

I understand that date and datetime is really important and sensitive. However, there are too many details to be dealt with in this package. So, there is NO guarantee that the outputs of dafo will conform to what described in this document.

If anything unexpected found, please create an issue to let me and others know.

Get Started

dafo offers different ways to format a date. And you may choose the style which you are familiar with.

MySQL Style

const DATE_FORMAT = require('dafo/mysql');

// Use customised format mask.
DATE_FORMAT(new Date, '%Y-%M-%d');
// e.g. RETURN 2018-1-1

// Use predefined format mask.
DATE_FORMAT(new Date, DATE_FORMAT.USA);

See MySQL Reference Manual Date and Time Functions, DATE_FORMAT for details, and GET_FORMAT for available predefined formats.

PHP Style

const date_format = require('dafo/php');

date_format(new Date, 'Y-n-j');
// e.g. RETURN 2018-1-1

See PHP Manual > Date/Time Functions for details.

API

dafo/mysql

const date_format = require('dafo/mysql');

• string date_format(Date date, string format)
• const string date_format.DATE.*
• const string date_format.DATETIME.*
• const string date_format.TIME.*

Special characters prefixed with % will be recognized and transformed into corresponding date text. Characters prefixed with % but unrecognizable will be preserved wite the leading % trimmed.

Follow the next table for frequently used format characters which supported by dafo/mysql:

| Catergory | Example | Ch | Meaning | | :--------- | :---------------- | :----- | :------------------------------------------ | | Day | Sun..Sat | %a | weekday short name | | Day | 1st,2nd..31st | %D | day of the month (ordinal number) | | Day | 01..31 | %d | day of the month | | Day | 1..31 | %e | day of the month | | Day | 001..366 | %j | day of the year | | Day | Sunday..Saturday | %W | weekday name | | Day | 0..6 | %w | weekday number (0=Sunday..6=Saturday) | | Week | 00..53 | %U | week number of year (mode 0) | | Week | 00..53 | %u | week number of year (mode 1) | | Week | 01..53 | %V | week number of year (mode 2) | | Week | 01..53 | %v | week number of year (mode 3) | | Month | Jan..Dec | %b | month short name | | Month | 1..12 | %c | month number | | Month | January..December | %M | month name | | Month | 01..12 | %m | month number | | Year | 1999 | %X | week-numbering year (mode 2) | | Year | 1999 | %x | week-numbering year (mode 3) | | Year | 2000 | %Y | year | | Year | 00 | %y | year | | Time | 000000..999999 | %f | micro-seconds | | Time | 00..23 | %H | hours (24-hour) | | Time | 01..12 | %h | hours (12-hour) | | Time | 01..12 | %I | hours (12-hour) | | Time | 00..59 | %i | minutes | | Time | 0..23 | %k | hours (24-hour) | | Time | 1..12 | %l | hours (12-hour) | | Time | AM, PM | %p | Ante meridiem / Post meridiem | | Time | 11:59:59 AM | %r | time (12-hour) | | Time | 00..59 | %S | seconds | | Time | 00..59 | %s | seconds | | Time | 23:59:59 | %T | time (24-hour) |

ATTENTION: Most, but NOT ALL format characters used in MySQL function DATE_FORMAT() are supported by dafo/mysql.

dafo/php

const date_format = require('dafo/php');

• string date_format(Date date, string format)

As what date() in PHP does, dafo/php will recognize special single characters in format string and transform them into corresponding date text. Unlike dafo/mysql, there are no leading escapers before these special characters and those not recognized will be preserved.

Escape Character
If you want to keep the format character from being replaced, prefix it with an escape character anti-slash \, e.g.

date_format(new Date(2000, 0, 1), '\\Y Y');
// RETURN 'Y 2000'

// Because '\' is also the default escaper in JavaScript string, 
// you should input double anti-slash characters '\\' in string literal 
// to create a real '\' in the format.

Follow the next table for frequently used format characters which supported by dafo/php:

| Catergory | Example | Ch | Meaning | | :--------- | :---------------- | :---- | :------------------------------------------ | | Day | 01..31 | d | day of the month | | Day | Mon..Sun | D | weekday short name | | Day | 1..31 | j | day of the month | | Day | Sunday..Saturday | l | weekday name | | Day | 1..7 | N | weekday number | | Day | st,nd..st | S | day of the month (ordinal suffix) |1 | Day | 0..6 | w | weekday number | | Day | 0..365 | z | day of the year | | Week | 01..53 | W | week number of year | | Month | January..December | F | month name | | Month | 01..12 | m | month number | | Month | Jan..Dec | M | month short name | | Month | 1..12 | n | month number | | Month | 28..31 | t | days in the month | | Year | 0,1 | L | if it is a leap year | | Year | 1999, 2000 | o | week-numbering year | | Year | 0100, 1899, 2050 | Y | year A.D. | | Year | 00, 99, 50 | y | year A.D. | | Time | am, pm | a | Ante meridiem / Post meridiem | | Time | AM, PM | A | Ante meridiem / Post meridiem | | Time | 1..12 | g | 12 hour | | Time | 0..23 | G | 24 hour | | Time | 01..12 | h | 12 hour | | Time | 00..23 | H | 24 hour | | Time | 00..59 | i | minutes | | Time | 00..59 | s | seconds | | Time | 000000..999999 | u | micro-seconds | | Time | 000...999 | v | milli-seconds | | TimeZone | +0800 | O | offset from GMT (in hours and minutes) | | TimeZone | +08:00 | P | offset from GMT (in hours and minutes) | | TimeZone | 28800 | Z | offset from GMT (in seconds) |

ATTENTION: Most, but NOT ALL format characters used in PHP function date() are supported by dafo/php.

dafo.parse

const dafo = require('dafo');

// Get a Date object.
let date = dafo.parse('2019.04.01', 'Y.m.d');

• Date dafo.parse(string date, string format)

Argument format describes what and how makes up date string. Acceptable placeholders include:
( Other characters are regarded as normal text. )

| Catergory | Example | Ch | Meaning | | :--------- | :---------------- | :---- | :------------------------------------------ | | Day | 01..31 | d | day of the month | | Month | 01..12 | m | month number | | Year | 0100, 1899, 2050 | Y | year A.D. | | Time | 00..23 | H | 24 hour | | Time | 00..59 | i | minutes | | Time | 00..59 | s | seconds |

dafo.toSeconds

const dafo = require('dafo');
let secondCount = dafo.toSeconds('1d2h');

• Date dafo.toSeconds(string age)

Argument age is an expression used to describe age, generally that of HTTP cache.

| Unit | Meaning | | :---- | :------------------------------------------ | | s | second(s) | | m | minute(s) | | h | hour(s) | | d | day(s) | | M | month(es) | | Y | year(s) |

Others

• number dafo.getDayOfYear(Date date)
  Get the day of the current year.
  Jan 1st is always 1, and Dec 31st may be 365 (not leap year) or 366 (leap year).

• number dafo.getMonthDays(Date date)
  Get days of the current month.

• number dafo.getWeekOfYear(Date date, number mode)
  Get the week number of year.
  Read section Week Mode for details about the mode argument.

• { Date first, Date last } dafo.getWeekRange({ number year, number week, number mode })
  Get the week range.
  Read section Week Mode for details about the mode argument.

• { year, week } dafo.getYearWeek(Date date, number mode)
  Get the week number of year, and the corresponding year.
  In some mode, the first few days in a year may be belonging to the last week of last year.
  Read section Week Mode for details about the mode argument.

• boolean dafo.isLeapYear(Date date)
  Return true if the year of date is leap. Otherwise return false.

• Date dafo.parse(string date, string format)

Week Mode

The definition of mode argument in functions dafo.getWeekOfYear() and dafo.getYearWeek() is borrowed from MySQL function WEEK(). The next table is cited from MySQL Manual and explains the difference between modes:

| Mode | 1st weekday | Range | Week 1 is the first week ... | Follows | | :--- | :---------- | :---- | :---------------------------- | :------ | | 0 | Sunday | 0-53 | with a Sunday in this year | | 1 | Monday | 0-53 | with 4 or more days this year | | 2 | Sunday | 1-53 | with a Sunday in this year | | 3 | Monday | 1-53 | with 4 or more days this year | ISO 8601 | | 4 | Sunday | 0-53 | with 4 or more days this year | | 5 | Monday | 0-53 | with a Monday in this year | | 6 | Sunday | 1-53 | with 4 or more days this year | | 7 | Monday | 1-53 | with a Monday in this year |

Why dafo

There have been lots of packages helping to format date or datetime. Generally, a format string is required to indicate what kind of date string you want, e.g. YY in moment means 2 digit year. The formats used in those packages are similiar, but more or less different from each other. It is really confusing! For those who are familiar with syntax used in date() in PHP or DATE_FORMAT() in MySQL, it is wasting time to learn another one.

I am tired of inventing something new but useless. What uou will not meet with in dafo is NOT a new general format, but something you have been familiar with.

About

References

• MySQL 5.7 Reference Manual > Date and Time Functions
• PHP Manual > Date/Time Functions
• Date and time format - ISO 8601 or WIKIPEDIA: ISO 8601