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)
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