Package Chronos

This document is written in ISO-Latin-1 with Unix-Lineendings. Tabulator uses 4 spaces.
I don't like it if code is cramed with comments. In my oppinion the code itself should be as readable as possible (no short variable names, no abbreviated function names). But of course that doesn't make documentation obsolete, that's why this document exists.

The package chronos consists of the classes datetime, difference, timespan, location and chronos which are intended to let you easily deal with everything related to time & date. It allows you to deal with:

• different languages (userinput & output)
• different timezones (conversion & handling)
• daylight saving times (handling)
• different startdays for week
• comparison of dates/times/datetimes/differences
• addition of dates with differences or differences
• subtraction of dates with differences or differences
• some special "goto" methods (to quickly get n. week of the year or month, the n. day of the year, week or month, ...)
• output dates/times/datetimes/differences in many useful ways (e.g. humand readably, unixtime, mysql-formatted, ...)
• deal with some special interests (pull out zodiac, age etc. from dates immediatly)
• Since it only rarely uses the unix libraries it is not restricted to it's limits (eg. only from 1970-2038)
• Retrieving fractions of dates/times/datetimes/differences (e.g. how many months are in that difference, the howmaniest day of the year is it, ...)

What this library does not do for you:

• it is not (yet) aware of leapseconds
• it assumes all dates are gregorian, it doesn't deal in a special way with dates before introduction of the gregorian calendar*
• it is not aware of all daylight saving time exceptions around the world and time

*See NOTES, different behaviour is difficult

Be aware that this class is a pre 1.0 release and I probably will change some of the interfaces and functions What I'm still unhappy with is:

• creation of difference (I want to drop the $from and automatically detect how to create it)
• creation of chronos (is timezone really more important then language?)
• handling of locations (for local usage we don't need to carry the whole file around and read it every time, that's waste of resources)
• format of strings-files
• implementation of DST could change some behaviours (think about adding 1 month to a datetime which then shifts from non-DST to DST and vice-versa - what happens to the time?)
• implementation of leapseconds, which could change some behaviours of adding-/subtracting-methods
• reorganizing code in a way that advanced functions like sun-calculations are only loaded if needed (the class is 90K at the moment and I think most users will only use functions that would need 30K, so 60K that we could load optionally)
• implementation of non-ISO-8601 for week of year (the ISO way to do it can be very unhandy since it is sometimes ambivalent)

Dates:

• ISO 8601 weeknumber

Times:

• DIN 5034 sunrise/sunset algorithm

Locations:

• ISO 6709 sign-degrees-minutes-seconds format (longitude/latitude)
• ISO 3166 two-letter country codes
  http://de.wikipedia.org/wiki/ISO_3166_Kodierliste
  http://de.wikipedia.org/wiki/ISO_3166
  http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/index.html

Timezones:

• http://www.timezoneconverter.com/cgi-bin/tzref.tzc
• http://www.timeanddate.com/worldclock/converter.html

• year can range from 1 to 9999
• month can range from 1 to 12, where 1 is normally January
• week can range from 1 to 53
• weekday can range from 1 to 7, where 1 is normally starting day of week (per default 'Monday').
• day can range from 1 to 31
  You can change that by changing the $starts-property in Chronos
  For language files, 1 always refers to Monday, 2 to Tuesday and so on
• per default a year starts with 1.1.
• datetimes are not consistent in addition/subtraction

  Example: 31.3. +1month = ?
  My Solution:
  	31.3. +1month	= 31.4.(overflow) => 1.5.
  Now, whats 1.5. -1month?
  My Solution:
  	1.5. -1month	= 1.4.
  Problem: 31.3. +1month-1month != 31.3.
  			

  If you have a *usable* solution to this problem, let me know
• If you use those classes, please notify me.
• If you make changes you're not only asked but even forced by the license
• Please help me to improve this class. If you see an error in the docs
  (I'm not a native english-speaker), let me know.
• I'm very interested in other language files.
• I'm too interested in information how to correctly include
  handling of DST all over the world.
• if a datepart is supplied we fill in gaps with current date (e.g. month and day are supplied we complement year with current year)
  Be aware that for the latter you have to regard the different dates of
  introduction (russia, europa and some europian countries differ in the date
  of adoption)

• all dates treated as gregorian even before 15. october 1582 (and the leap from 4. oct 1582 to 15. is not implemented)
• leapseconds are ignored
• DST implementation incomplete
• not yet safe to change start-property

• difference::create_fromString()
• location::get_timezoneName($format=false)
• location::get_offset()
• location::get_isDST() [will probably be moved to chronos anyway]
• timespan::count_weeks()
• chronos::convert_toDatetime()
• integrate error handling (especially for creation of datetimes from strings)
• integrate DST
• make it more consistent
• improve subtractDatetime in a way that if possible the difference is positive or negative numbers only
• enable procedural usage of methods where it makes sense
• today_moon_phase(string $date)
• find other algorithms for sunrise/sunset/twilight (DIN 5034 e.g., at the moment it seems we use NREL SOLPOS)
• check timezones
• convert var $lookups into a chronos::lookup() method which can be used procedurally (allows some other functions to be used procedurally too)
• datetime::create_fromString()
• chronos::include_exists()

method datetime()

// timezone will be local timezone, language is 'en'
$now            = new datetime("current");
// another variant of the sample above
$now            = new datetime(time());
// language will be 'de' (default for Europe/Zurich)
$date           = new datetime("2005-12-31", "Europe/Zurich");
// you can create time-only objects as well
$time           = new datetime("13:45:21", "Europe/Zurich");
// this pattern will be recognized because german-strings are loaded
$datetime       = new datetime("31.12.2005 13:45", , "Europe/Zurich", "de");
// you can create from an array
$datetime       = new datetime(array('day' => 31, 'month' => 12, 'year' => 2005, 'hour' => 13, 'minute' => 45), "Europe/Zurich");

method create_fromString()

$result	= $datetime->create_fromString('1/1/2005 13.45', false);

method create_fromUnixtime()

$result	= $datetime->create_fromUnixtime(1108500000);

method create_fromMySQL()

$result	= $datetime->create_fromMySQL('2005-01-20 12:00:00');
$result	= $datetime->create_fromMySQL('20050120120000'); // the same as above

method create_fromCurrent()

$result	= $datetime->create_fromCurrent();

method create_fromArray()

// sets datetime to '2005-01-20 12:59:02'
$result         = create_fromArray(array('year' => 2005, 'month' => 1, 'day' => 20, 'hour' => 12, 'minute' => 59, 'second' => 2);
// sets datetime to 'current year-01-20 12:00:00'
$result         = create_fromArray(array('month' => 1, 'day' => 20, 'hour' => 12);

method set_micro()

$result	= $datetime->set_micro(456);

method set_milli()

$result	= $datetime->set_milli(123);

method set_second()

$result	= $datetime->set_second(52);

method set_minute()

$result	= $datetime->set_minute(45);

method set_hour()

$result	= $datetime->set_hour(13);

method set_day()

$result	= $datetime->set_day(21);

method set_dayOfYear()

$result	= $datetime->set_dayOfYear(121);

method set_month()

$result	= $datetime->set_month(1);

method set_year()

$result	= $datetime->set_year($year);

method setTo_nthDayOfWeek()

// set date to monday
$result	= $datetime->setTo_nthDayOfWeek(0);

method setTo_nthDayOfMonth()

// set date to last day of the month
$result	= $datetime->setTo_nthDayOfMonth(-1);

method setTo_nthDayOfYear()

// set date to last day of the year
$result	= $datetime->setTo_nthDayOfYear(-1);

method setTo_nthWeekOfYear()

// set the date to the same weekday as it is at the moment but in the first week of the year
$result	= $datetime->setTo_nthWeekOfYear(1, false);
// set the date to monday of the first week of the year
$result	= $datetime->setTo_nthWeekOfYear(1, 0);

method setTo_sunrise()

// Set the time to the time of the sunrise
$result	= $datetime->setTo_sunrise();

method setTo_sunset()

$result	= $datetime->setTo_sunset($location);

method setTo_morningTwilight()

$result	= $datetime->setTo_morningTwilight($location);

method setTo_eveningTwilight()

$result	= $datetime->setTo_eveningTwilight($location);

method do_add()

$result	= $datetime->do_add($differenceOrArray);

method do_addSeconds()

$result	= $datetime->do_addSeconds($seconds);

method do_addMinutes()

$result	= $datetime->do_addMinutes($minutes);

method do_addHours()

$result	= $datetime->do_addHours($hours);

method do_addDays()

$result	= $datetime->do_addDays($days);

method do_addMonths()

$result	= $datetime->do_addMonths($months, $cutOverflow);

method do_addYears()

$result	= $datetime->do_addYears($years);

method do_subtractDatetime()

$result	= $datetime->do_subtractDatetime($subtrahend);

method do_subtract()

$result	= $datetime->do_subtract($differenceDatetimeOrArray);

method do_subtractSeconds()

$result	= $datetime->do_subtractSeconds($seconds);

method do_subtractMinutes()

$result	= $datetime->do_subtractMinutes($minutes);

method do_subtractHours()

$result	= $datetime->do_subtractHours($hours);

method do_subtractDays()

$result	= $datetime->do_subtractDays($days);

method do_subtractMonths()

$result	= $datetime->do_subtractMonths($months, $cutOverflow);

method do_subtractYears()

$result	= $datetime->do_subtractYears($years);

method get_nthDayOfWeek()

$result	= $datetime->get_nthDayOfWeek($n);

method get_nthDayOfMonth()

$result	= $datetime->get_nthDayOfMonth($n);

method get_nthDayOfYear()

$result	= $datetime->get_nthDayOfYear($n);

method get_nthWeekOfYear()

$result	= $datetime->get_nthWeekOfYear($n, $weekday);

method get_dayOfWeek()

$result	= $datetime->get_dayOfWeek($format);

method get_dayOfMonth()

$result	= $datetime->get_dayOfMonth($format);

method get_dayOfYear()

$result	= $datetime->get_dayOfYear($format);

method get_daysOfMonth()

$result	= $datetime->get_daysOfMonth($month, $year);

method get_weeksOfYear()

$result	= $datetime->get_weeksOfYear($year);

method get_monthFromYearday()

$result	= $datetime->get_monthFromYearday($day, $year);

method get_monthDayFromYearday()

$result	= $datetime->get_monthDayFromYearday($day, $year);

method get_date()

$result	= $datetime->get_date();

method get_time()

$result	= $datetime->get_time();

method get_datetime()

$result	= $datetime->get_datetime();

method get_year()

$result	= $datetime->get_year($digits, $asInt);

method get_month()

$result	= $datetime->get_month($format);

method get_day()

$result	= $datetime->get_day($format);

method get_hour()

$result	= $datetime->get_hour($format, $mode);

method get_minute()

$result	= $datetime->get_minute($format);

method get_second()

$result	= $datetime->get_second($format);

method get_milli()

$result	= $datetime->get_milli($format);

method get_micro()

$result	= $datetime->get_micro($format);

method get_week()

$result	= $datetime->get_week($format);

method get_zodiac()

$result	= $datetime->get_zodiac();

method get_age()

$result	= $datetime->get_age();

method as_array()

$result	= $datetime->as_array();

method as_unixtime()

$result	= $datetime->as_unixtime();

method as_mysqlDate()

$result	= $datetime->as_mysqlDate();

method as_mysqlTime()

$result	= $datetime->as_mysqlTime($asInteger);

method as_mysqlDatetime()

$result	= $datetime->as_mysqlDatetime($asInteger);

method as_string()

$datetime	= new datetime();
echo $datetime->as_string("%m/%d/%Y %H.%M");
--> 11/21/2005 13.45
echo $datetime->as_string("%B %{B|lc} %{monthname|uc|3}");
--> November november NOV

method difference()

$result	= $difference->difference($from, $difference, $timezone, $language);

method create_fromString()

// this method is currently non-functional

method create_fromPart()

$result	= $difference->create_fromPart($amount, $part);

method create_fromDatetimes()

$result	= $difference->create_fromDatetimes($datetime1, $datetime2);

method create_fromArray()

$result	= $difference->create_fromArray($array);

method create_fromExact()

$result	= $difference->create_fromExact($seconds, $months);

method do_add()

$result	= $difference->do_add($differenceDatetimeOrArray);

method do_subtract()

$result	= $difference->do_subtract($differenceOrArray);

method get_seconds()

$result	= $difference->get_seconds($part);

method get_minutes()

$result	= $difference->get_minutes($part);

method get_hours()

$result	= $difference->get_hours($part);

method get_days()

$result	= $difference->get_days($part);

method get_weeks()

$result	= $difference->get_weeks($part);

method get_months()

$result	= $difference->get_months($part);

method get_years()

$result	= $difference->get_years($part);

method as_array()

$result	= $difference->as_array($part);

method as_string()

$result	= $difference->as_string($pattern);

method timespan()

$result	= $timespan->timespan($start, $end, $language, $timezone);

method count_weekdayOccurrences()

$result	= $timespan->count_weekdayOccurrences($day);

method count_monthOccurrences()

$result	= $timespan->count_monthOccurrences($month);

method count_weeks()

$result	= $timespan->count_weeks($mode);

method location()

$result	= $location->location($location);

method set_location()

$result	= $location->set_location($location);

method set_pseudoLocation()

$result	= $location->set_pseudoLocation($data);

method set_language()

$result	= $location->set_language($lang);

method do_readData()

$result	= $location->do_readData($file);

method is_validID()

$result	= $location->is_validID($timezoneID);

method get_language()

$result	= $location->get_language();

method get_utc()

$result	= $location->get_utc();

method get_timezoneName()

$result	= $location->get_timezoneName($format);

method get_countryAlpha2()

$result	= $location->get_countryAlpha2();

method get_countryAlpha3()

$result	= $location->get_countryAlpha3();

method get_numeric()

$result	= $location->get_numeric();

method get_timezoneID()

$result	= $location->get_timezoneID();

method get_rawOffset()

$result	= $location->get_rawOffset();

method get_offset()

$result	= $location->get_offset($atDatetime);

method get_latitude()

$result	= $location->get_latitude($format);

method get_longitude()

$result	= $location->get_longitude($format);

method get_isDST()

$result	= $location->get_isDST($atDatetime);

method get_DSTrule()

$result	= $location->get_DSTrule();

method chronos()

$result	= $chronos->chronos($timezoneID, $language);

method load_stringsFile()

$result	= $chronos->load_stringsFile($lang);

method unset_dateTimeAndDifference()

$result	= $chronos->unset_dateTimeAndDifference();

method unset_time()

$result	= $chronos->unset_time();

method unset_date()

$result	= $chronos->unset_date();

method unset_difference()

$result	= $chronos->unset_difference();

method unset_differenceDate()

$result	= $chronos->unset_differenceDate();

method set_defaults()

$result	= $chronos->set_defaults($timezone);

method set_is()

$result	= $chronos->set_is($date, $time, $difference);

method set_timezone()

$result	= $chronos->set_timezone($timezoneID);

method set_language()

$result	= $chronos->set_language($language);

method do_convertTimezone()

$result	= $chronos->do_convertTimezone($newTimezoneID);

method is_chronos()

$result	= $chronos->is_chronos($object, $class);

method is_time()

$result	= $chronos->is_time($exclusive, $object);

method is_date()

$result	= $chronos->is_date($exclusive, $object);

method is_datetime()

$result	= $chronos->is_datetime($object);

method is_dateOrTime()

$result	= $chronos->is_dateOrTime($object);

method is_difference()

$result	= $chronos->is_difference($object);

method is_leapyear()

$result	= $chronos->is_leapyear($year);

method is_dst()

$result	= $chronos->is_dst();

method is_equal()

$result	= $chronos->is_equal($to);

method is_biggerOrEqual()

$result	= $chronos->is_biggerOrEqual($than);

method is_bigger()

$result	= $chronos->is_bigger($than);

method is_smallerOrEqual()

$result	= $chronos->is_smallerOrEqual($than);

method is_smaller()

$result	= $chronos->is_smaller($than);

method get_utc()

$result	= $chronos->get_utc($timezone);

method get_timezone()

$result	= $chronos->get_timezone($format);

method get_string()

$result	= $chronos->get_string($block, $string);

method get_comparison()

$result	= $chronos->get_comparison($with);

method get_cmp()

$result	= $chronos->get_cmp($with);

method get_withoutOverflow()

$result	= $chronos->get_withoutOverflow($array);

method get_differenceTo()

$result	= $chronos->get_differenceTo($to, $absolute);

method get_stringPart()

$result	= $chronos->get_stringPart($part);

method get_timeserverStamp()

$result	= $chronos->get_timeserverStamp($server, $port);

method get_appliedModificators()

$result	= $chronos->get_appliedModificators($value, $modifiers);

method get_sunCalculation()

$result	= $chronos->get_sunCalculation($location, $what, $timezone);

method include_exists()

$result	= $chronos->include_exists($filename);

method convert_toDifference()

$result	= $chronos->convert_toDifference($ignoreDate);

method convert_toTime()

$result	= $chronos->convert_toTime();

method convert_toDate()

$result	= $chronos->convert_toDate();

method convert_toDatetime()

$result	= $chronos->convert_toDatetime($getMissingFrom, $value);