You are reading a single comment by @allObjects and its replies. Click here to read the full conversation.
  • Formatting pattern characters:

    // yMNdHhmsSxXDZ are date and time pattern chars, escape-able with ^ (default).

    • - ```M```: **Month**... "M" single or two digits, "MM" two digits with leading 0 for months 1..9. "MMM".."MMM..M" is the same as "NNN" and "NNN..N". See ```N```.
      - ```N```: **Name of month**... "N" as defined in prototype defaults ```mons``` string (```"JanFebMar..."``` or ```"January__February_March____..."```) with fix length of ```monLen``` (```3``` or ```9```, respectively), the length of longest month name. String is extracted with **mons.substr(month * monLen, monLen)**. "N..N" will take a substring of length equal to the number of "N"s. (Note that the underscores stand for blanks.)
      - ```d```: **day**... "d" single or two digits, "dd" two digits with leading 0 for days 1..9.
      - ```H```: **Hours in 24H format**... "H" single or two digits, "HH" two digits with leading 0 for hours 0..9.
      - ```h```: **hours in 12h format**... "h" single or two digits, "hh" two digits with leading 0 for hours 0..9. To display related *am* or *pm* and *AM* or *PM* see ```x``` and ```X```.
      - ```m```: **minutes**... "m" single or two digits, "mm" two digits with leading 0 for minutes 0..9.
      - ```s```: **seconds**... "s" single or two digits, "ss" two digits with leading 0 for secconds 0..9.
      - ```S```: **milliSeconds**... "S" single, two, or three digits, "SSS" three digits with two and one leading **0**(s) for seconds **1..9** and **10..99**, respectively.
      - ```x```: **am** and **pm** (lowercase)... "x" always puts **am** or **pm** in the output. See also ```X``` (uppercase) and ```h``` (lowercase).
      - ```X```: **AM** and **PM** (uppercase)... "X" always puts **AM** or **PM** in the output. See also ```x``` (lowercase) and ```h``` (lowercase).
      - ```D```: **Day name**... "D" as defined in prototype defaults ```days``` string (```"MonTueWed..."``` or ```"Monday___Tuesday__Wednesday..."``` with fix length of ```dayLen``` (```3``` or ```9```, respectively), the length of longest week day name. String is extracted with ***days.substr(day * dayLen, dayLen)***. "D..D" will take a substring of the length equal to the number of "D"s. (Note that the underscores stand for blanks.)
      - ```Z```: **Time zone**... "Z" as defined in prototype defaults ```zone``` string. "Z..Z" will take a substring of the length equal to the number of "Z"s.
      - ```any other character```... **as is**, for example: ```"in yyyy"``` for "in 1999" 
      - ```^```: **escape character**... "^" as defined in prototype defaults ```esc``` string (```"^"```). The escape character enables the use of date and time pattern characters **as is**; for example: ```"T^he ti^me i^s now: h:mm X"``` for "The time is now: 3:45 PM". 
      
      Formatting pattern examples:
      
      1. ```M/d/y``` ---> **2/29/1956 or 2/29/56**, depending on prototype defaults ```year: "yyyyy"``` or ```"yy"```
      2. ```yyyy/MM/dd``` ---> **1956/02/29**, date as sortable string
      3. ```D, N d, y``` ---> **Wednesday, February 29, 1956** (with prototype defaults ```days: "Sunday___Monday___Tuesday__Wednesday...­", dayLen: 9``` and equally for ```mons: "January__Feburary_...", monLen: 9```).  
      4. ```DDD, NNN d, y``` ---> **Wed, Feb 29, 1956**  (with prototype defaults ```days: "Sunday___Monday___Tuesday__Wednesday...­", dayLen: 9```; or ```"SunMonTueWed..."``` and ```3```;  and analog for ```mons``` and ```monLen```).
      5. ```DDD, NNN d, y``` ---> **Wed, Feb 29, 1956**  (with prototype defaults ```days: "SunMonTueWed...", dayLen: 3``` and ```mons: "JanFebMar...", monLen: 3```).
      6. ```D, N d, y``` ---> **Wed, Feb 29, 1956** (with prototype defaults ```days: "SunMonTueWed...", dayLen: 3``` and ```mons: "JanFebMar...", monLen: 3```).
      7. ```DD, NNNNNN d, yy``` ---> **We, Feb 29, 56** (with prototype defaults ```days: "SunMonTueWed...", dayLen: 3``` and ```mons: "JanFebMar...", monLen: 3```).
      8. ```Begin: yyyy-mm-dd_HH:mm:ss.SSS``` ---> **Begin: 1956-02-29_00:00:00.000**
      9. ```En^d: yyyy-mm-dd_HH:mm:ss.SSS``` ---> **End: 1956-02-29_23:59:59.999**
      
      ***Usage Notes:***
      
      1. Consecutive same date and time pattern characters define the length (as reasonable)
      2. Characters in the template other than date and time pattern characters are just pushed to the output
      3. To use pattern characters as plain template characters, they have to be ***escaped*** with **"^**" as defined in prototype defaults ```esc```.
      4. Prototype defaults can be updated with a defaults object that includes the property names and values to update. A mixin / merge into the existing properties allows the selective / partial update.
      5. Prototype defaults are shared and a change affects all formatters... with one exception see next item).
      6. Common to all usages is pulling the module or placing the code in-line and assigning result to a variable, for example ```var DF = ....;"``` (DateFormatter class, hence uppercase). ```var DF = require("DateFormatter");```` when code placed as module in local sandbox modules folder.
      7. The usual or regular form of usage is creating a formatter with optionally passing the template / pattern: ```var df = new DF();```.  If no template or pattern is passed, the prototype default is taken and stored in the formatter instance.  Therefore, a once created formatter holds the template / pattern that was actual at the time of formatter creation. To use the formatter, its methods ```df.format()```, ```df.getDefaults()``` and ```df.updateDefaults()``` are invoked. ```.format()``` accepts ***none***, ***one*** and ***two parameter*** parameters: *first is date*, and *second is pattern*. For *missing* or falsy (**undefined*, *null*, *0*, "", false) parameters the respective default is taken: *now* for *date*, and *prototpe.defaults.pattern* for *pattern*. To show, for example, now in ***non-default*** pattern, invocation is with ***null and non-default pattern***: ```.format(null,"yyyy-MM-dd")``` shows something like 2016-05-07.
      8. A shorter form of usage is invocation of formatter class (function name) methods ```DF.format()```, ```DF.getDefaults()``` and ```DF.updateDefaults()```. Parameter handling is the same as for regular usage. 
      9. The shortest - bit messy - version is the use of the constructor function (class definition function) ```DF(...)```. This version requires always two parameters - both ***date*** and ***pattern*** - to be supplied, of which one or both can be specified as "**false**" (undefined, null, 0, "", false) to force use of respective default. For example - shortest form: ```DF(0,0)``` - returns now in the format as defined in the prototype defaults property "**pattern**".
      
      Common to below usage examples is this snippet:
      
      

    // assuming now/today is: Wed, May 17, 2016, 1:45:59 PM, 704 milliseconds
    // assuming module's defaults = {pattern:"M/d/y",year:"yyyy",zone:"ESP"}­
    function log(v) { console.log(v); }
    var myDate = new Date(1955,1,29,13,45,59,123); // 1955-02-29_13:45:59.123
    var DF = require("DateFormatter"); // hold on to module as class and function

    
    ***Examples related to Usage Note 7. (with snippet a runnable sequence):***
    
    

    var DF = require("DateFormatter"); // hold on to module as class (and function)
    var df = new DF(); // create instance using class' default formatting pattern
    log(df.pattern); // M/d/y - logs instance's default formatting pattern
    log(df.format()); // 5/17/2016 - logs now in instance's default pattern
    log(df.format(myDate)); // 2/29/1955 - logs myDate in instance's default pattern
    log(df.format(null,"d.M.y")); // 17.5.2016 - logs now in specified format
    log(df.format(myDate,"d.M.y")); // 29.2.1955 - logs myDate in specified pattern
    df.pattern = "d.M.y"; // change instance's formatting pattern
    log(df.pattern); // d.M.y - logs instance's default formatting pattern
    df.updateDefaults({pattern:"yyyy-MM-dd",­ year:"yy", Z:"PSD"}); // update shared defaults, but not the default formatting pattern of existing instances.
    var df2 = new DF(); // create 2nd df picks up new default formatting pattern
    log(df.pattern); // d.M.y - instance's default pattern - still the 'old' one
    log(df.format()); // 17.5.16 - now in instance's still 'old' default, but...
    log(df.format(myDate)); // 29.2.55 - ...in inst.'s default but y from new defaults
    log(df.format(null,"d.M.yyyy")); // 17.5.2016 - logs now in specified format
    log(df.format(myDate,"d.M.y")); // 29.2.55 - myDate as spec'd, y as new defaults
    log(df.format(null,"d.M.yyyy")); // 17.5.2016 - logs now in specified format
    log(df.format(myDate,"dd.MM.yyyy")); // 29.02.1955 - myDate in spec'd pattern
    log(df2.format()); // 2016-05-17 - logs now in instance's default pattern
    log(df2.format(y-m-d)); // 16-5-17 - now in inst.'s default but y from defaults
    log(df2.format(null,"M/d/yyyy")); // 5/17/2016 - logs now in specified format

    
    ***Examples related to Usage Note 8. (with snippet a runnable sequence):***
    
    

    var DF = require("DateFormatter"); // hold on to module as class (and function)
    log(DF.getDefaults().pattern); // M/d/y - logs default formatting pattern
    log(DF.format()); // 5/17/2016 - logs now in shared default pattern
    log(DF.format(myDate)); // 2/29/1955 - logs myDate in shared default pattern
    log(DF.format(null,"d.M.y")); // 17.5.2016 - logs now in specified format
    log(DF.format(myDate,"d.M.y")); // 29.2.1955 - logs myDate in specified pattern
    DF.getDefaults().pattern = "d.M.y"; // change shared default pattern, BUT IT IS NOT the recommended way
    log(DF.getDefaults().pattern); // d.M.y - logs shared default formatting pattern
    DF.updateDefaults({pattern:"yyyy-MM-dd",­ year:"yy", Z:"PSD"}); // update shared defaults the RECOMMENDED way
    log(DF.getDefaults().pattern); // yyyy-MM-dd - shared default pattern
    log(DF.format()); // 2016-05-17 - logs now in shared default pattern
    log(DF.format(myDate)); // 1955-02-29 - myDate in shared default pattern
    log(DF.format(null,"d.M.yyyy")); // 17.5.2016 - logs now in specified pattern
    log(DF.format(myDate,"d.M.y")); // 29.2.55 - myDate in spec'd, y from new defaults
    log(DF.format(null,"d.M.yyyy")); // 17.5.2016 - logs now in specified pattern
    log(DF.format(myDate,"dd.MM.yyyy")); // 29.02.1955 - logs myDate in spec'd pattern

    
    ***Examples related to Usage Note 9. (with snippet a runnable sequence):***
    
    

    var fD = require("DateFormatter"); // hold on to module as formatDate() function
    log(fD.getDefaults().pattern); // M/d/y - logs default formatting pattern
    log(fD(0,0)); // 5/17/2016 - logs now in default pattern
    log(fD(myDate,null)); // 2/29/1955 - logs myDate in shared default pattern
    log(fD(null,"d.M.y")); // 17.5.2016 - logs now in specified format
    log(fD(myDate,"d.M.y")); // 29.2.1955 - logs myDate in specified pattern
    fD.getDefaults().pattern = "d.M.y"; // change shared default pattern, BUT IT IS NOT the recommended way
    log(fD.getDefaults().pattern); // d.M.y - logs shared default formatting pattern
    fD.updateDefaults({pattern:"yyyy-MM-dd",­ year:"yy", Z:"PSD"}); // update shared defaults the RECOMMENDED way
    log(fD.getDefaults().pattern); // yyyy-MM-dd - shared default pattern
    log(fD(false,undefined)); // 2016-05-17 - logs now in shared default pattern
    log(fD(myDate,0)); // 1955-02-29 - myDate in shared default pattern
    log(fD(null,"d.M.yyyy")); // 17.5.2016 - logs now in specified pattern
    log(fD(myDate,"d.M.y")); // 29.2.55 - myDate in spec'd, y from new defaults
    log(fD(null,"d.M.yyyy")); // 17.5.2016 - logs now in specified pattern
    log(fD(myDate,"dd.MM.yyyy")); // 29.02.1955 - logs myDate in spec'd pattern
    ```

    At a later time, I may put this up as a module. Until then, it still needs some hardening.

    Closing comments in next post...

About

Avatar for allObjects @allObjects started