^Status|Draft|
^Todo|Proof read|

====== Date Helper ======
The Date helper assists in formating dates and times allowing for addition and conversion between different formats.

===== Methods =====

==== unix2dos() ====
'unix2dos' converts UNIX time into DOS time.

The one arguments is:
  * [int] UNIX timestamp

**Example:**
<code php>
// Please note that the print() statements are for display purposes only
$time = mktime(0, 0, 0, 31, 10, 1987);
print ($time);
$time = date::unix2dos($time);
print ($time);
</code>

It will result in HTML as:
<code html>
616046400
317325312
</code>

==== dos2unix() ====
'dos2unix' converts DOS time into UNIX time.

The one arguments is:
  * [int] DOS timestamp

**Example:**
<code php>
// Please note that the print() statements are for display purposes only
$time = 317325312;
print ($time);
$time = date::dos2unix($time);
print ($time);
</code>

It will result in HTML as:
<code html>
317325312
616046400
</code>

==== offset() ====
'offset' calculates the seconds between two timezones.

The two arguments are:
  * [int] remote timezone
  * [mixed] use local time? -- default is TRUE -- else enter your own 

**Example:**
<code php>
// Please note that the print() statements are for display purposes only
// This example was executed in the EST timezone
print (date::offset('CST').'<br />');
print (date::offset('CST', 'MST').'<br />');
print (date::offset('UTC', 'GMT').'<br />');
</code>

It will result in HTML as:
<code html>
-3600
3600
0
</code>

==== seconds() ====
'seconds' creates an array of numbers based on your input.

The three arguments are:
  * [int] step (count by) -- default = 1
  * [int] start number -- default = 0
  * [int] end number -- default = 60

**Example:**
<code php>
// Please note that the print() statements are for display purposes only
print Kohana::debug(date::seconds());
print Kohana::debug(date::seconds(2,1,7));
print Kohana::debug(date::seconds(100,200,400));
</code>

It will result in HTML as:
<code html>
Array
(
    [0] => 0
    [1] => 1
    [2] => 2
    [3] => 3
    [4] => 4
    [5] => 5
    [6] => 6
    [7] => 7
    [8] => 8
    [9] => 9
    [10] => 10
    [11] => 11
    [12] => 12
    [13] => 13
    [14] => 14
    [15] => 15
    [16] => 16
    [17] => 17
    [18] => 18
    [19] => 19
    [20] => 20
    [21] => 21
    [22] => 22
    [23] => 23
    [24] => 24
    [25] => 25
    [26] => 26
    [27] => 27
    [28] => 28
    [29] => 29
    [30] => 30
    [31] => 31
    [32] => 32
    [33] => 33
    [34] => 34
    [35] => 35
    [36] => 36
    [37] => 37
    [38] => 38
    [39] => 39
    [40] => 40
    [41] => 41
    [42] => 42
    [43] => 43
    [44] => 44
    [45] => 45
    [46] => 46
    [47] => 47
    [48] => 48
    [49] => 49
    [50] => 50
    [51] => 51
    [52] => 52
    [53] => 53
    [54] => 54
    [55] => 55
    [56] => 56
    [57] => 57
    [58] => 58
    [59] => 59
)

Array
(
    [1] => 1
    [3] => 3
    [5] => 5
)

Array
(
    [200] => 200
    [300] => 300
)
</code>

==== minutes() ====
Please see [[date#seconds]].

==== hours() ====
'hours' counts the number of hours there are left in a day or from a specific start point.

The three arguments are:
  * [int] step (count by) -- default = 1
  * [boolean] 24-hour time? -- default = FALSE
  * [int] start hour -- default = 1

**Example:**
<code php>
// Please note that the print() statements are for display purposes only
// This example ran at 6:10PM EST
print Kohana::debug(date::hours());
print Kohana::debug(date::hours(1, TRUE, 9));
print Kohana::debug(date::hours(1, TRUE, 22));
print Kohana::debug(date::hours(1, TRUE, date('g'))); // 24-hour format of an hour without leading zeros
</code>

It will result in HTML as:
<code html>
Array
(
    [1] => 1
    [2] => 2
    [3] => 3
    [4] => 4
    [5] => 5
    [6] => 6
    [7] => 7
    [8] => 8
    [9] => 9
    [10] => 10
    [11] => 11
    [12] => 12
)

Array
(
    [9] => 9
    [10] => 10
    [11] => 11
    [12] => 12
    [13] => 13
    [14] => 14
    [15] => 15
    [16] => 16
    [17] => 17
    [18] => 18
    [19] => 19
    [20] => 20
    [21] => 21
    [22] => 22
    [23] => 23
)

Array
(
    [22] => 22
    [23] => 23
)

Array
(
    [18] => 18
    [19] => 19
    [20] => 20
    [21] => 21
    [22] => 22
    [23] => 23
)
</code>

==== ampm() ====
'ampm' calculates whether the supplied integer makes the hour AM or PM.

The one argument is:
  * [int] hour to calculate

**Example:**
<code php>
// Please note that the print() statements are for display only
// This example ran at 5:45PM EST
print Kohana::debug(date::ampm(1));
print Kohana::debug(date::ampm(13));
print Kohana::debug(date::ampm(date('G'))); // 24-hour format of an hour without leading zeros
</code>

It will result in HTML as:
<code html>
AM
PM
PM
</code>


==== days() ====
'days' counts the number of days there are in a specific month of a specific year.

The two arguments are:
  * [int] month (1-12)
  * [int] year -- default: current year

**Example:**
<code php>
// Please note that the print() statement is for display purposes only
print Kohana::debug(date::days(5,2007));
</code>

It will result in HTML as:
<code html>
Array
(
    [1] => 1
    [2] => 2
    [3] => 3
    [4] => 4
    [5] => 5
    [6] => 6
    [7] => 7
    [8] => 8
    [9] => 9
    [10] => 10
    [11] => 11
    [12] => 12
    [13] => 13
    [14] => 14
    [15] => 15
    [16] => 16
    [17] => 17
    [18] => 18
    [19] => 19
    [20] => 20
    [21] => 21
    [22] => 22
    [23] => 23
    [24] => 24
    [25] => 25
    [26] => 26
    [27] => 27
    [28] => 28
    [29] => 29
    [30] => 30
    [31] => 31
)
</code>

==== months() ====
'months' returns an mirrored array with the month-numbers of the year.

**Example:**
<code php>
// Please note that the print() statement is for display purposes only
print Kohana::debug(date::months());
</code>

It will result in HTML as:
<code html>
Array
(
    [1] => 1
    [2] => 2
    [3] => 3
    [4] => 4
    [5] => 5
    [6] => 6
    [7] => 7
    [8] => 8
    [9] => 9
    [10] => 10
    [11] => 11
    [12] => 12
)
</code>


==== years() ====
'years' returns an array with the years between the specified years.

The two arguments are:
  * [int] start year-- default = current year - 5
  * [int] end year -- default = current year + 5 

**Example:**
<code php>
// Please note that the print() statements are for display purposes only
// This example ran in 2007
print Kohana::debug(date::years());
print Kohana::debug(date::years(1998,2002));
</code>

It will result in HTML as:
<code html>
Array
(
    [2002] => 2002
    [2003] => 2003
    [2004] => 2004
    [2005] => 2005
    [2006] => 2006
    [2007] => 2007
    [2008] => 2008
    [2009] => 2009
    [2010] => 2010
    [2011] => 2011
    [2012] => 2012
)

Array
(
    [1998] => 1998
    [1999] => 1999
    [2000] => 2000
    [2001] => 2001
    [2002] => 2002
)
</code>



==== timespan() ====
'timespan' returns the time between two timestamps in a human readable format.

The arguments are:
  * [int] timestamp 1 
  * [int] timestamp 2 -- default: current timestamp
  * [string] format -- default: 'years,months,weeks,days,hours,minutes,seconds'

**Example:**
<code php>
// Please note that the print() statements are for display purposes only
// This example ran in 2007
$timestamp = time() - (60*60*24*7*31*3); // timestamp of 651 days ago
$timestamp2 = time() - (60*60*24*7*50); // timestamp of 350 days ago
print Kohana::debug(date::timespan($timestamp));
print Kohana::debug(date::timespan($timestamp, time(), 'years,days'));
print Kohana::debug(date::timespan($timestamp, $timestamp2));
print 'minutes: '.Kohana::debug(date::timespan($timestamp, time(), 'minutes'));
</code>

It will result in HTML as:
<code html>
Array
(
    [years] => 1
    [months] => 9
    [weeks] => 2
    [days] => 2
    [hours] => 0
    [minutes] => 0
    [seconds] => 0
)

Array
(
    [years] => 1
    [days] => 286
)

Array
(
    [years] => 0
    [months] => 10
    [weeks] => 0
    [days] => 1
    [hours] => 0
    [minutes] => 0
    [seconds] => 0
)

minutes: 

937440
</code>

==== adjust() ====
'adjust' converts an hour integer into 24-hour format from a non-24-hour format. 

The two arguments are:
  * [int] hour in non-24-hour format
  * [string] AM or PM

**Example:**
<code php>
// Please note that the print() statements are for display only
print Kohana::debug(date::adjust(11, 'PM'));

</code>

It will result in HTML as:
<code html>
23
</code>