worldtime

Convert to and from various worldtime formats. Get manipulated time values.

worldtime

(c)Bumblehead, 2013 MIT-license

worldtime provides methods for manipulating international dates, converting dates to and from unicode format.

worldtime uses the official Unicode ldml-JSON files for formatting and parsing international dates and times. Use json-locale to get these files and to optimise them.

worldtime extends simpletime. no libraries are required. just simpletime, worldtime and unicode JSON files.

because worldtime extends simpletime, constructed worldtime objects will have the same methods and properties that are defined on simpletime objects.

what's good about this script:

  • format and unformat international time using unicode forms
  • create and use YMDArr objects to simplify time manipulation
  • it may be used in a browser or node.js ecmascipt environment

Install:

worldtime may be downloaded directly or installed through npm.

  • npm
$ npm install worldtime
  • Direct Download
$ git clone https://github.com/iambumblehead/worldtime.git

Test:

to run tests, use npm test from a shell.

$ npm test

GET STARTED:

  1. Construct a WorldTime Object

construct a worldtime object and begin using it.

pass a unicode json object as first parameter to worldtime methods.

var WorldTime = require('../worldtime');
var es_CLObj = require('./locale/es_CL.json');    
var d = WorldTime.extractFormattedDate(es_CLObj, '05-04-2013', 'medium');
console.log(d); // (date) Fri Apr 05 2013 21:23:41 GMT-0700 (PDT) 
var f = WorldTime.getFormattedTime(es_CLObjd, 'medium');
console.log(f); // 05-04-2013 

METHODS:

  • getCalendarObj ( uObj, calendarType )
    returns a calendar object from the unicode file.

    the following calendars are defined by the unicode files and are valid calendarTypes:

    "buddhist",
    "chinese",
    "coptic",
    "dangi",
    "ethiopic",
    "ethiopicAmeteAlem",
    "gregorian",
    "hebrew",
    "indian",
    "islamic",
    "islamicCivil",
    "japanese",
    "persian",
    "roc"

  • getCalendarUnit ( uObj, unitType )

    returns a calendar unit object from the unicode file.

    the following units are defined by the unicode files and are valid unitTypes:

    "months",
    "days",
    "quarters",
    "eras",
    "dateFormats",
    "timeFormats",
    "dateTimeFormats",
    "fields"

  • getMonthNameFormatObj ( uObj, monthType )

    returns an object of month names for the given month type

    by default, months are provided by the gregorian calendar object

    the following month types are defined by the unicode files and are valid monthTypes:

    "abbreviated",
    "narrow",
    "wide"

    var result = WorldTime.getMonthNameFormatObj(es_CLObj, 'abbreviated');
    console.log(result);
    // { 
    //   "1": "ene", 
    //   "2": "feb", 
    //   "3": "mar", 
    //   "4": "abr", 
    //   "5": "may", 
    //   "6": "jun", 
    //   "7": "jul", 
    //   "8": "ago", 
    //   "9": "sep", 
    //   "10": "oct", 
    //   "11": "nov", 
    //   "12": "dic" 
    // } 
  • getNumericMonthNameAbbrev ( uObj, monthNum )

    returns a month name of the abbreviated month type for the given monthNum

    var result = WorldTime.getNumericMonthNameAbbrev(es_CLObj, '1');
    console.log(result);
    // ene 
  • getNumericMonthNameWide ( uObj, monthNum )

    returns a month name of the wide month type for the given monthNum

    var result = WorldTime.getNumericMonthNameWide(es_CLObj, '1');
    console.log(result);
    // enero 
  • getDayNameFormatObj ( uObj, dayType )

    returns an object of day names for the given day type

    by default, months are provided by the gregorian calendar object

    the following day types are defined by the unicode files:

    "abbreviated",
    "narrow",
    "wide"

    var result = WorldTime.getDayNameFormatObj(es_CLObj, 'abbreviated');
    console.log(result);
    // { 
    //   "sun": "dom", 
    //   "mon": "lun", 
    //   "tue": "mar", 
    //   "wed": "mié", 
    //   "thu": "jue", 
    //   "fri": "vie", 
    //   "sat": "sáb" 
    // } 
  • getStrDayNameAbbrev ( uObj, dayStr )

    returns a day name of the abbreviated day type for the given dayStr

    var result = WorldTime.getStrDayNameAbbrev(es_CLObj, 'mon');
    console.log(result);
    // lun 
  • getStrDayNameWide ( uObj, dayStr )

    returns a day name of the wide day type for the given dayStr

    var result = WorldTime.getStrDayNameWide(es_CLObj, 'mon');
    console.log(result);
    // lunes 
  • getDateMonthNameAbbrev ( uObj, dayStr )

    returns a day name of the wide day type for the given dayStr

    // Fri Apr 05 2013 21:23:41 GMT-0700 (PDT) 
    var date = new Date(1365222221485);  
    var result = WorldTime.getDateMonthNameAbbrev(es_CLObj, date);
    console.log(result);
    // abr 
  • getDateMonthNameWide ( uObj, dayStr )

    returns a day name of the wide day type for the given dayStr

    // Fri Apr 05 2013 21:23:41 GMT-0700 (PDT) 
    var date = new Date(1365222221485);  
    var result = WorldTime.getDateMonthNameWide(es_CLObj, date);
    console.log(result);
    // abril 
  • getDateFormat ( uObj, formatType )

    returns a date format of the given formatType ( full, long, medium, short ). If no formatType is given, the default format of the locale is returned.

    var result = WorldTime.getDateFormat(es_CLObj, 'short');
    console.log(result);
    // dd-MM-yy 
  • getTimeFormat ( uObj, formatType )

    returns a time format of the given formatType ( full, long, medium, short ). If no formatType is given, the default format of the locale is returned.

    var result = WorldTime.getTimeFormat(es_CLObj, 'short');
    console.log(result);
    // H:mm 
  • getFormattedDate ( uObj, dateObj , formatType )

    returns a formatted date of the given dateObj and formatType ( full, long, medium, short ). If no formatType is given, the default format of the locale is returned.

    // Fri Apr 05 2013 21:23:41 GMT-0700 (PDT) 
    var date = new Date(1365222221485);     
    var result = WorldTime.getFormattedDate(es_CLObj, date, 'short');
    console.log(result);
    // 05-04-13 
  • getFormattedTime ( uObj, dateObj , formatType )

    returns a formatted date of the given dateObj and formatType ( full, long, medium, short ). If no formatType is given, the default format of the locale is returned.

    // Fri Apr 05 2013 21:23:41 GMT-0700 (PDT) 
    var date = new Date(1365222221485);     
    var result = WorldTime.getFormattedTime(es_CLObj, date, 'short');
    console.log(result);
    // 21:23 
  • extractFormattedDate ( uObj, dateStr , formatType )

    returns a date of the given formattted dateStr and formatType ( full, long, medium, short ). If no formatType is given, the default format of the locale is returned.

    // Fri Apr 05 2013 21:23:41 GMT-0700 (PDT) 
    var date = '05-04-13';
    var result = WorldTime.extractFormattedDate(es_CLObj, date, 'short');
    console.log(result);
    // Fri Apr 05 13 23:13:55 GMT-0700 (PDT) 
  • getBaseMonthsArr ( uObj, formatType )

    returns an array of months for the given formatType ( abbreviated, narrow, wide ).

    var result = WorldTime.getBaseMonthsArr(es_CLObj, 'abbreviated');
    console.log(result);
    // [ 
    //   'feb', 
    //   'mar', 
    //   'abr', 
    //   'may', 
    //   'jun', 
    //   'jul', 
    //   'ago', 
    //   'sep', 
    //   'oct', 
    //   'nov', 
    //   'dic' 
    // ] 
  • getBaseDaysArr ( uObj, formatType )

    returns an array of months for the given formatType ( abbreviated, narrow, wide ).

    var result = WorldTime.getBaseDaysArr(es_CLObj, 'abbreviated');
    console.log(result);
    // [ 
    //   'dom', 
    //   'lun', 
    //   'mar', 
    //   'mié', 
    //   'jue', 
    //   'vie', 
    //   'sáb' 
    // ] 

Contributions:

Contributions are welcome.

I initially wrote worldtime while I was building an international software application on a job. I have changed jobs and I'm no longer testing or developing this script for a production environment. If you find issues please report them or send a fix.


License:

(The MIT License)

Copyright (c) 2013 Bumblehead chris@bumblehead.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.