[date_utils] Refactor functions, documentation

- Use the same names used in locale module (so dow instead of getDOW, month instead of getMonth, etc.)
- Add documentation

modules/date_utils.js

@@ -1,39 +1,65 @@
-/* Utility functions that use the 'locale' module so can produce text
-in the currently selected language. */
+// module "date_utils"
+//
+// Utility functions that use the "locale" module so can produce
+// date-related text in the currently selected language.
+//
+// Some functions have a "firstDayOfWeek" parameter.
+// Most used values are:
+// - 0/undefined --> Sunday
+// - 1           --> Monday
+// but you can start the week from any day if you need it.
+// 
+// Some functions have an "abbreviated" parameter.
+// It supports the following 3 values:
+// - 0/undefined --> get the full value, without abbreviation (eg.: "Monday", "January", etc.)
+// - 1           --> get the short value (eg.: "Mon", "Jan", etc.)
+// - 2           --> get only the first char (eg.: "M", "J", etc.)
+//
 
-/** Return the day of the week (0=Sunday)
-    short==0/undefined -> "Sunday"
-    short==1           -> "Sun"
-*/
-exports.getDOW = (dow, short) => require("locale").dow({getDay:()=>dow},short);
-
-/** Return the month (1=January)
-    short==0/undefined -> "January"
-    short==1           -> "Jan"
-*/
-exports.getMonth = (month, short) => require("locale").month({getMonth:()=>month-1},short);
-
-/** Return all 7 days of the week as an array ["Sunday","Monday",...].
-    short==0/undefined -> ["Sunday",...
-    short==1           -> ["Sun",...
-    short==2           -> ["S",...
-*/
-exports.getDOWs = (short) => {
-  var locale = require("locale");
-  var days = [];
-  for (var i=0;i<7;i++)
-    days.push(locale.dow({getDay:()=>i},short).slice(0,(short==2)?1:100));
-  return days;
+/**
+ * @param {int} i The index of the day of the week (0 = Sunday)
+ * @param {int} abbreviated
+ * @returns The localized name of the i-th day of the week
+ */
+exports.dow = (i, abbreviated) => {
+  var dow = require("locale").dow(new Date(((i || 0) + 3.5) * 86400000), abbreviated).slice(0, (abbreviated == 2) ? 1 : 100);
+  return abbreviated == 2 ? dow.toUpperCase() : dow;
 }
 
-/** Return all 12 months as an array ["January","February",...]
-    short==0/undefined -> ["January",...
-    short==1           -> ["Jan",...
-*/
-exports.getMonths = (short) => {
+/**
+ * @param {int} firstDayOfWeek 0/undefined -> Sunday,  
+ *                             1           -> Monday
+ * @param {int} abbreviated
+ * @returns All 7 days of the week (localized) as an array
+ */
+exports.dows = (firstDayOfWeek, abbreviated) => {
+  var dows = [];
   var locale = require("locale");
+  for (var i = 0; i < 7; i++) {
+    dows.push(exports.dow(i + (firstDayOfWeek || 0), abbreviated))
+  }
+  return abbreviated == 2 ? dows.map(dow => dow.toUpperCase()) : dows;
+};
+
+/**
+ * @param {int} i The index of the month (1 = January)
+ * @param {int} abbreviated
+ * @returns The localized name of the i-th month
+ */
+exports.month = (i, abbreviated) => {
+  var month = require("locale").month(new Date((i - 0.5) * 2628000000), abbreviated).slice(0, (abbreviated == 2) ? 1 : 100);
+  return abbreviated == 2 ? month.toUpperCase() : month;
+}
+
+/**
+ * @param {int} abbreviated
+ * @returns All 12 months (localized) as an array
+ */
+exports.months = (abbreviated) => {
   var months = [];
-  for (var i=0;i<12;i++)
-    months.push(locale.month({getMonth:()=>i},short));
-  return months;
-}
+  var locale = require("locale");
+  for (var i = 1; i <= 12; i++) {
+    months.push(locale.month(new Date((i - 0.5) * 2628000000), abbreviated).slice(0, (abbreviated == 2) ? 1 : 100));
+  }
+  return abbreviated == 2 ? months.map(month => month.toUpperCase()) : months;
+};