Added time2words tool

olliebennett · Nov 23, 2012 · 5b0b95f · 5b0b95f
1 parent 9b4f19e
commit 5b0b95f
Show file tree

Hide file tree

Showing 4 changed files with 215 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -25,3 +25,19 @@ See individual `tools4text-num2words-<language_code>.js` files for language-spec
 
 *   `fr` French
 *   `cn` Chinese
+
+## time2words()
+
+Converts a time to words, in the specified language.
+
+Accepts a String representation of a time, in "HH:MM" format, and returns
+
+JavaScript `Date` objects are also accepted, and handled automatically.
+
+### Example Usage:
+
+    time2words("en", "23:45"); // "quarter to midnight" (English)
+
+### Implemented languages:
+
+* `en` English
diff --git a/time2words/time2words.html b/time2words/time2words.html
@@ -0,0 +1,67 @@
+<!DOCTYPE html>
+<html>
+
+    <head>
+        <meta charset="utf-8">
+        <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
+        <title>tools4text - time2words</title>
+        <meta name="viewport" content="width=device-width">
+        <script src="tools4text-time2words.js"></script>
+        <script src="../num2words/tools4text-num2words-en.js"></script>
+        <script src="tools4text-time2words-en.js"></script>
+    </head>
+
+    <body>
+
+        <h1>tools4text time2words Test Script</h1>
+
+        <p>Edit the `lang` variable defined in this html file to test other languages.</p>
+
+        <table>
+            <thead>
+                <tr>
+                    <th>Number</th>
+                    <th>Word</th>
+                </tr>
+            </thead>
+            <tbody>
+
+<script>
+
+    /********************************************
+     *  Change the following "lang" definition  *
+     *  to test different languages.            *
+     ********************************************/
+
+    var lang = "en";
+
+    function test(time) {
+
+        document.getElementById('numberwords-tbody')
+
+        document.write("<tr>");
+        document.write("<td>" + time + "</td>");
+        document.write("<td>'" + tools4text.time2words(lang, time) + "'</td>");
+        document.write("</tr>");
+    }
+
+    test(new Date());
+
+    var hour, minute;
+    for (hour = 0; hour < 24; hour += 1) {
+        for (minute = 0; minute < 60; minute += 1) {
+            test((hour < 10 ? "0" : "") + hour + ":" + (minute < 10 ? "0" : "") + minute);
+        }
+    }
+
+    test("oops"); // word
+    test("1"); // number as string
+    test(3.14159); // non-integer
+    test("0x5B"); // other number representations, such as hexadecimal
+
+</script>
+
+            </tbody>
+        </table>
+    </body>
+</html>
diff --git a/time2words/tools4text-time2words-en.js b/time2words/tools4text-time2words-en.js
@@ -0,0 +1,91 @@
+/*
+ * Convert Time to Words
+ *
+ * See README.md for usage instructions.
+ * https://github.com/olliebennett/tools4text
+ *
+ * Language: English (UK)
+ *
+ * Language Notes:
+ * - There are often various ways of reading times.
+ * - This script uses the most verbose possible.
+ * - "00:00" = Midnight, and "12:00" = Midday / Noon
+ * - If minute is divisible by 5, omit the word "minutes"
+ *   (this is purely an aesthetic preference)
+ *
+ * TODO:
+ * - Implement memoization to save time when calling num2words.
+ * 
+ */
+
+var tools4text = tools4text || {};
+tools4text.time2words_en = function (time) {
+
+    "use strict";
+
+    // Configuration
+    var lang = {},
+        hour,
+        hour_int,
+        hour_word,
+        hour_word_next,
+        min,
+        min_int,
+        time_parts;
+
+    lang.midnight = "midnight";
+    lang.midday = "midday";
+
+    // Assume "String" object is provided
+    time_parts = time.split(":");
+    hour = time_parts[0];
+    hour_int = parseInt(hour, 10);
+    min = time_parts[1];
+    min_int = parseInt(min, 10);
+
+    // Normalize for 24 hour clock
+    hour_word = tools4text.num2words_en(hour_int % 12);
+    hour_word_next = tools4text.num2words_en((hour_int + 1) % 12);
+
+    // Handle special cases (midday + midnight)
+    if (hour_int === 0) {
+        hour_word = lang.midnight;
+    } else if (hour_int === 11) {
+        hour_word_next = lang.midday;
+    } else if (hour_int === 12) {
+        hour_word = lang.midday;
+    } else if (hour_int === 23) {
+        hour_word_next = lang.midnight;
+    }
+
+    // o'clock
+    if (min_int === 0) {
+        if (hour_int === 0 || hour_int === 12) {
+            return hour_word;
+        }
+        return hour_word + " o'clock";
+    }
+    // X past ...
+    if (min_int <= 30) {
+        if (min_int === 15) {
+            return "quarter past " + hour_word;
+        }
+        if (min_int === 30) {
+            return "half past " + hour_word;
+        }
+        if (min_int % 5) {
+            return tools4text.num2words_en(min_int) + " " + (min_int === 1 ? "minute" : "minutes") + " past " + hour_word;
+        }
+        return tools4text.num2words_en(min_int) + " past " + hour_word;
+    }
+    // X to ...
+    if (min_int > 30) {
+        if (min_int === 45) {
+            return "quarter to " + hour_word_next;
+        }
+        if (min_int % 5) {
+            return tools4text.num2words_en(60 - min_int) + " " + ((60 - min_int) === 1 ? "minute" : "minutes") + " to " + hour_word_next;
+        }
+        return tools4text.num2words_en(60 - min_int) + " " + ((60 - min_int) === 1 ? "minute" : "minutes") + " to " + hour_word_next;
+    }
+};
diff --git a/time2words/tools4text-time2words.js b/time2words/tools4text-time2words.js
@@ -0,0 +1,41 @@
+/*
+ * Convert Time to Words
+ *
+ * See README.md for usage instructions.
+ * https://github.com/olliebennett/tools4text
+ *
+ */
+
+var tools4text = tools4text || {};
+tools4text.time2words = function (language_code, time) {
+
+    "use strict";
+
+    // Validate language code
+    if (tools4text['time2words_' + language_code] === undefined) {
+        return "Error: Language '" + language_code + "' is not supported.";
+    }
+
+    // Check whether a "Date" object is provided (and convert to String)
+    if (Object.prototype.toString.call(time) === '[object Date]') {
+        time = ((time.getHours() < 10 ? '0' : '') + time.getHours()) +
+            ":" +
+            ((time.getMinutes() < 10 ? '0' : '') + time.getMinutes());
+    }
+
+    // Check for bad param type
+    if (typeof time !== 'string') {
+        return "Error: Invalid 'time' parameter type (" + typeof time + ").";
+    }
+
+    // Validate input time format
+    // TODO - regex to check HH:MM format instead?
+    // Input hour + minute must lie in valid range.
+    if (time.split && time.split(":").length !== 2) {
+        return "Error: Supplied time '" + time + "' is not in valid (HH:MM) format.";
+    }
+
+    // Call language-specific function
+    return tools4text['time2words_' + language_code](time);
+
+};