countdown.js / readme.html

Full commit
<!DOCTYPE html>
<html class="no-js">
	<meta charset="UTF-8">

	<link href="test/styles.css" rel="stylesheet" type="text/css" />

<h1><a href="/">Countdown.js</a></h1>
<div style="float:right"><a href="" class="twitter-share-button" data-url="" data-text="Countdown.js: A simple JavaScript API for producing an accurate, intuitive description of the timespan between dates" data-count="none"></a></div>

<p>A simple JavaScript API for producing an accurate, intuitive description of the timespan between two Date instances.</p>

<hr />

<h2>Algorithm background</h2>

<p>While seemingly a trivial problem, the human descriptions for a span of time tend to be fuzzier than a computer naturally computes.
More specifically, months are an inherently messed up unit of time.
For instance, when a human says "in 1 month" how long do they mean? Banks often interpret this as <em>thirty days</em> but that is only correct one third of the time.
People casually talk about a month being <em>four weeks long</em> but there is only one month in a year which is four weeks long and it is only that long three quarters of the time.
Even intuitively defining these terms can be problematic. For instance, what is the date one month after January 31st, 2001?
JavaScript will happily call this March 3rd, 2001. Humans will typically debate either February 28th, 2001 or March 1st, 2001. There isn't a "right" answer, per se.</p>

<p><em>Countdown.js</em> emphasizes producing intuitively correct description of timespans which are consistent as time goes on.
To do this, <em>Countdown.js</em> uses the concept of "today's date next month" to mean "a month from now".
As the days go by, <em>Countdown.js</em> produces consecutively increasing or decreasing counts without inconsistent jumps.
The range of accuracy is only limited by the underlying system clock.</p>

<p><em>Countdown.js</em> approaches finding the difference between two times like an elementary school subtraction problem.
Each unit acts like a base-10 place where any overflow is carried to the next highest unit, and any underflow is borrowed from the next highest unit.
In base-10 subtraction, every column is worth 10 times the previous column. It is a little more complex since the conversions between the units of time are not the same and months are an inconsistent number of days.
In the final step of the algorithm, <em>Countdown.js</em> prunes the set of time units down to only those requested, forcing larger units down to smaller.</p>

<hr />

<h2>The API</h2>

<p>A simple but flexible API is the goal of <em>Countdown.js</em>. There is one global function with a set of static constants:</p>

<pre><code>var timespan = countdown(start|callback, end|callback, units, max);</code></pre>

<p>The parameters are a starting Date, ending Date, an optional set of units, and an optional maximum number of units. If units is left off, it defaults to <code>countdown.DEFAULTS</code>.</p>

<pre><code>countdown.ALL =
	countdown.MILLENNIA |
	countdown.CENTURIES |
	countdown.DECADES |
	countdown.YEARS |
	countdown.MONTHS |
	countdown.WEEKS |
	countdown.DAYS |
	countdown.HOURS |
	countdown.MINUTES |
	countdown.SECONDS |

countdown.DEFAULTS =
	countdown.YEARS |
	countdown.MONTHS |
	countdown.DAYS |
	countdown.HOURS |
	countdown.MINUTES |

<p>This allows a very minimal call to accept the defaults and get the time since/until a single date. For example:</p>

<pre><code>countdown( new Date(2000, 0, 1) ).toString();</code></pre>

<p>This will produce a human readable description like:</p>

<pre><code>11 years, 8 months, 4 days, 10 hours, 12 minutes, and 43 seconds</code></pre>

<h3>The <code>start</code> / <code>end</code> arguments</h3>

<p>The parameters <code>start</code> and <code>end</code> can be one of several values:</p>

	<li><code>null</code> which indicates "now".</li>
	<li>a JavaScript <code>Date</code> object.</li>
	<li>a number specifying the number of milliseconds since midnight Jan 1, 1970 UTC (i.e., the "UNIX epoch").</li>
	<li>a callback function accepting one timespan argument.</li>

<p>If <code>start</code> and <code>end</code> are both specified, then repeated calls to <code>countdown(...)</code> will always return the same result.
If one date argument is left <code>null</code> while the other is provided, then repeated calls will count up if the provided date is in the past, and it will count down if the provided date is in the future.
For example,</p>

<pre><code>var daysSinceLastWorkplaceAccident = countdown(507314280000, null, countdown.DAYS);</code></pre>

<p>If a callback function is supplied, then an interval timer will be started with a frequency based upon the smallest unit (e.g., if <code>countdown.SECONDS</code> is the smallest unit, the callback will be invoked once per second). Rather than returning a Timespan object, the timer's ID will be returned to allow canceling by passing into <code>window.clearInterval(id)</code>. For example, to show a timer since the page first loaded:</p>

<pre><code>var timerId =
    new Date(),
    function(ts) {
      document.getElementById('pageTimer').innerHTML = ts.toHTML("strong");

// later on this timer may be stopped

<h3>The <code>units</code> argument</h3>

<p>The static units constants can be combined using <a href="">standard bitwise operators</a>. For example, to explicitly include "months or days" use bitwise-OR:</p>

<pre><code>countdown.MONTHS | countdown.DAYS</code></pre>

<p>To explicitly exclude units like "not weeks and not milliseconds" combine bitwise-NOT and bitwise-AND:</p>

<pre><code>~countdown.WEEKS &amp; ~countdown.MILLISECONDS</code></pre>

<p><a href="'s_laws">Equivalently</a>, to specify everything but "not weeks or milliseconds" wrap bitwise-NOT around bitwise-OR:</p>

<pre><code>~(countdown.WEEKS | countdown.MILLISECONDS)</code></pre>

<h3>The <code>max</code> argument</h3>

<div id="v2.3.0-max" class="breaking-change">
<h4>Breaking change in v2.3.0!</h4>
<p>The <code>max</code> argument used to be specified in <code>timespan.toString(&hellip;)</code> and <code>timespan.toHTML(&hellip;)</code>. v2.3.0 moves it to <code>countdown(&hellip;)</code>, which improves efficiency as well as enabling fractional units (<a href="#v2.3.0-digits">see below</a>).</p>

The final optional argument specifies a maximum number of unit labels to display. This allows specifying which units are interesting but only displaying the `max` most significant units.

<pre><code>countdown(start, end, units).toString() => "5 years, 1 month, 19 days, 12 hours, and 17 minutes"</code></pre>

<p>Specifying <code>max</code> as <code>2</code> ensures that only the two most significant units are displayed <strong>(note the rounding of months)</strong>:</p>

<pre><code>countdown(start, end, units, 2).toString() => "5 years, and 2 months"</code></pre>

<p>Negative or zero values of <code>max</code> are ignored.</code>

<h3>Timespan result</h3>

<p>The return value is a Timespan object which always contains the following fields:</p>

	<li><code>Date start</code>: the starting date object used for the calculation</li>
	<li><code>Date end</code>: the ending date object used for the calculation</li>
	<li><code>Number units</code>: the units specified</li>
	<li><code>Number value</code>: total milliseconds difference (i.e., <code>end</code> - <code>start</code>). If <code>end &lt; start</code> then <code>value</code> will be negative.</li>

<p>Typically the <code>end</code> occurs after <code>start</code>, but if the arguments were reversed, the only difference is <code>Timespan.value</code> will be negative. The sign of <code>value</code> can be used to determine if the event occurs in the future or in the past. </p>

<p>The following time unit fields are only present if their corresponding units were requested:</p>

	<li><code>Number millennia</code></li>
	<li><code>Number centuries</code></li>
	<li><code>Number decades</code></li>
	<li><code>Number years</code></li>
	<li><code>Number months</code></li>
	<li><code>Number days</code></li>
	<li><code>Number hours</code></li>
	<li><code>Number minutes</code></li>
	<li><code>Number seconds</code></li>
	<li><code>Number milliseconds</code></li>

<p>Finally, Timespan has two formatting methods each with some optional parameters:</p>


<li><code>String toString(digits)</code>: formats the Timespan object as an English sentence. The optional <code>digits</code> argument allows fractional values on the smallest unit. e.g., using the same input:

<pre><code>ts.toString() => "5 years, and 2 months"
ts.toString(2) => "5 years, and 1.65 months"</code></pre></li>

<li><code>String toHTML(tagName, digits)</code>: formats the Timespan object as an English sentence, with the specified HTML tag wrapped around each unit. If no tag name is provided, "<code>span</code>" is used. Again, the optional <code>digits</code> argument allows fractional values on the smallest unit. e.g., using the same input:

<pre><code>ts.toHTML("em") => "&lt;em&gt;5 years&lt;/em&gt;, &lt;em&gt;1 month&lt;/em&gt;, &lt;em&gt;19 days&lt;/em&gt;, &lt;em&gt;12 hours&lt;/em&gt;, and &lt;em&gt;17 minutes&lt;/em&gt;"
ts.toHTML("em", 3) => "&lt;em&gt;5 years&lt;/em&gt;, &lt;em&gt;1 month&lt;/em&gt;, &lt;em&gt;19 days&lt;/em&gt;, &lt;em&gt;12 hours&lt;/em&gt;, and &lt;em&gt;17.193 minutes&lt;/em&gt;"</code></pre></li>


<p>Digits must be between <code>0</code> and <code>20</code>, inclusive. Negative values of <code>digits</code> are ignored.</p>

<p>If <code>start</code> and <code>end</code> are exactly the same or the difference is below the requested granularity of units, then <code>toString()</code> and <code>toHTML()</code> will simply return an empty string.</p>

<div id="v2.3.0-digits" class="breaking-change">
<h4>Breaking change in v2.3.0!</h4>
<p>Previously, the <code>max</code> number of unit labels used to be defined when formatting. Now it is specified with the units themselves (<a href="#v2.3.0-max">see above</a>).</p>

<p>With the calculations of fractional units in v2.3.0, the smallest displayed unit now properly rounds. Previously, the equivalent of <code>"1.99 years"</code> would be truncated to <code>"1 year"</code>, as of v2.3.0 it will display as <code>"2 years"</code>.</p>
<p>Typically, this is the intended interpretation but there are a few circumstances where people expect the truncated behavior. For example, people often talk about their age as the lowest possible interpretation. e.g., they claim "39-years-old" right up until the morning of their 40th birthday (some people do even for years after!). In these cases, after calling <code>countdown(&hellip;)</code>, you might want to set <code>ts.years = Math.floor(ts.years)</code> before calling <code>ts.toString(0)</code>. The vain might want you to set <code>ts.years = Math.min(ts.years, 39)</code>!</p>


<p>Distributed under the terms of <a href="">The MIT license</a>.</p>

	<div style="float:left"><a href="" class="twitter-share-button" data-url="" data-text="Countdown.js: A simple JavaScript API for producing an accurate, intuitive description of the timespan between dates"></a></div>
	Copyright &copy; 2006-2012 <a href="">Stephen M. McKamey</a>
<script src="/ga.js" type="text/javascript" defer></script>
<script src="" type="text/javascript" defer="defer"></script>