dafo

    0.1.1 • Public • Published

    dafo

    General Date Format

    total downloads of dafo dafo's License latest version of dafo build status of github.com/YounGoat/ecmascript.dafo

    Description

    To format date in PHP or MySQL style.

    Table of Contents

    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

    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

    Install

    npm i dafo

    DownloadsWeekly Downloads

    25

    Version

    0.1.1

    License

    none

    Unpacked Size

    55.4 kB

    Total Files

    24

    Last publish

    Collaborators

    • youngoat
    • youngoat.elite