Revision: 43779 Author: mkroetzsch Date: 2008-11-20 22:09:57 +0000 (Thu, 20 Nov 2008)
Log Message: ----------- Documentation of major features, various fixes, especially in output of BC years Modified Paths: -------------- trunk/extensions/SemanticMediaWiki/includes/SMW_DV_Time.php Modified: trunk/extensions/SemanticMediaWiki/includes/SMW_DV_Time.php =================================================================== --- trunk/extensions/SemanticMediaWiki/includes/SMW_DV_Time.php 2008-11-20 21:10:27 UTC (rev 43778) +++ trunk/extensions/SemanticMediaWiki/includes/SMW_DV_Time.php 2008-11-20 22:09:57 UTC (rev 43779) @@ -5,17 +5,39 @@ */ /** - * This datavalue captures values of dates and times. - * The implementation uses a format similiar to Julian Day Number to represent time values. - * Times internally are stored as XSD-conformant strings, see - * http://www.w3.org/TR/xmlschema-2/#dateTime + * This datavalue captures values of dates and times. All dates and times refer to + * the "local time" of the server (or the wiki). A wiki may define what timezone this + * refers to by common conventions. For export, times are given without timezone + * information. However, time offsets to that local time are supported (see below). * - * This implementation might change in the future. For maximum - * compatibility, use no relative dates ("... + 10 days"), - * no dates referring to current time ("next Tuesday"), no - * weekdays in your values, and use ":" between hours, minutes, - * and seconds (i.e. no "1230" as 12:30). + * It is able to handle dates accross history with full precision for storing, and + * substantial precision for sorting and querying. The range of supported past dates + * should encompass the Beginning of Time according to most of today's theories. The + * range of supported future dates is limited more strictly, but it does also allow + * year numbers in the order of 10^9. * + * Years before common era (aka BC) can be denoted using "BC" in a date. The internal + * nummeric date model supports the year 0, and considers it to be the same as "1 BC". + * The year "0 BC" is accepted to refer to the same year, but its use is discouraged. + * According to this convention, e.g., the year "-100" is the same as "101 BC". This + * convention agrees with ISO 6801 and the remarks in XML Schema Datatypes 2nd Edition, + * (the latter uses a different convention that disallows year 0, but it explicitly + * endorses the ISO convention and announces the future use of this in XML). + * Note that the implementation currently does not support the specification of negative + * year numbers as input; negative numbers are only used internally. + * + * The implementation notices and stores whether parts of a date/time have been + * omitted (as in "2008" or "May 2007"). For all exporting and sorting purposes, + * incomplete dates are completed wiht defaults (usually using the earliest possible + * time, i.e. interpreting "2008" as "Jan 1 2008 00:00:00"). But the information + * on what was unspecified is kept internally for improving behaviour e.g. for + * outputs (defaults are not printed when querying for a value). Functions are + * provided to access the individual time components (getYear, getMonth, getDay, + * getTimeString), and those can also be used to find out what was unspecified. + * + * Time offests are supported (e.g. "1 1 2008 12:00-2:00"). As explained above, those + * refer to the local time. + * * @author Fabian Howahl * @author Markus Krötzsch * @ingroup SMWDataValues @@ -29,10 +51,9 @@ protected $m_month = false; //Gregorian month, remains false if unspecified protected $m_year = false; //Gregorian year, remains false if unspecified protected $m_time = false; //time, remains false if unspecified - protected $m_jdn = ''; //numerical time representation similiar to Julian Day Number + protected $m_jdn = ''; //numerical time representation similiar to Julian Day Number, for ancient times, a more compressed number is used (preserving ordering but not distance of time points) protected $m_timeoffset; //contains offset (e.g. timezone) protected $m_timeannotation; //contains am or pm - protected $m_yearbc; //true if year is BC // The following are constant (array-valued constants are not supported, hence the decalration as variable): protected $m_months = array("January", "February", "March", "April" , "May" , "June" , "Juli" , "August" , "September" , "October" , "November" , "December"); protected $m_monthsshort = array("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"); @@ -63,9 +84,10 @@ } //browse string for special abbreviations referring to year like AD, BC + $is_yearbc = false; if(preg_match("/[ABab][DCdc]/u", $filteredvalue, $match)){ - if(!strcasecmp($match[0],'bc')){ - $this->m_yearbc = true; + if ( strtoupper($match[0]) == 'BC' ) { + $is_yearbc = true; } $regexp = "/(\040|T){0,1}".str_replace("+", "\+", $match[0])."(\040){0,1}/u"; //delete ad/bc value and preceding and following chars $filteredvalue = preg_replace($regexp,'', $filteredvalue); //value without ad/bc @@ -158,8 +180,10 @@ return true; } - if ($this->m_yearbc) { - $this->m_year = -$this->m_year; + if ($is_yearbc) { + if ($this->m_year > 0) { // see class documentation on BC, "year 0", and ISO conformance ... + $this->m_year = -($this->m_year-1); + } } //handle offset @@ -349,7 +373,20 @@ global $smwgContLang; if ($this->m_printvalue === false) { //MediaWiki date function is not applicable any more (no support for BC Dates) - $this->m_printvalue = $this->m_day . " " . $smwgContLang->getMonthLabel($this->m_month) . " " . $this->m_year . " " . $this->m_time; + if ($this->m_year > 0) { + $this->m_printvalue = $this->m_year; + } else { + $this->m_printvalue = -($this->m_year-1) . ' BC'; + } + if ($this->m_month) { + $this->m_printvalue = $smwgContLang->getMonthLabel($this->m_month) . " " . $this->m_printvalue; + } + if ($this->m_day) { + $this->m_printvalue = $this->m_day . " " . $this->m_printvalue; + } + if ($this->m_time) { + $this->m_printvalue .= " " . $this->m_time; + } } } @@ -376,22 +413,22 @@ //otherwise XXXX is the number of years BC and YYYY represents the elapsed days of the year as fraction of 1 protected function createJDN(){ $this->m_jdn = 0; + if (!$this->isValid()) return; if($this->m_year >= -4713){ - $a = intval((14-$this->getMonth())/12); - $y = $this->m_year + 4800 - $a; - $m = $this->getMonth() + 12 * $a - 3; + $a = intval((14-$this->getMonth())/12); + $y = $this->m_year + 4800 - $a; + $m = $this->getMonth() + 12 * $a - 3; - if($this->m_time != false) {//just calculate fraction if time is set - list ($hours, $minutes, $seconds) = explode(':',$this->getTimeString(),3); - $time = ($hours/24) + ($minutes / (60*24)) + ($seconds / (3600*24)); - $this->m_jdn += $time; + if($this->m_time != false) {//just calculate fraction if time is set + list ($hours, $minutes, $seconds) = explode(':',$this->getTimeString(),3); + $time = ($hours/24) + ($minutes / (60*24)) + ($seconds / (3600*24)); + $this->m_jdn += $time; } - $this->m_jdn += $this->getDay() + intval((153*$m+2)/5) + 365*$y + intval($y/4) - intval($y/100) + intval($y/400) - 32045; } - else{ - $time = 1 - (($this->getMonth() / 12) + ($this->getDay() / 365)); - $this->m_jdn = $this->m_year - $time; + else { + $time = 1 - (($this->getMonth() / 12) + ($this->getDay() / 365)); + $this->m_jdn = $this->m_year - $time; } } _______________________________________________ MediaWiki-CVS mailing list MediaWiki-CVS@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-cvs