Semantic MediaWiki and related extensions
Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
SMWTimeValue Class Reference
Collaboration diagram for SMWTimeValue:
Collaboration graph
[legend]

Public Member Functions

 getShortWikiText ($linker=null)
 
 getShortHTMLText ($linker=null)
 
 getLongWikiText ($linker=null)
 
 getLongHTMLText ($linker=null)
 
 getWikiValue ()
 
 isNumeric ()
 
 getYear ($calendarmodel=SMWDITime::CM_GREGORIAN)
 
 getMonth ($calendarmodel=SMWDITime::CM_GREGORIAN, $default=1)
 
 getDay ($calendarmodel=SMWDITime::CM_GREGORIAN, $default=1)
 
 getTimeString ($default= '00:00:00')
 
 getXMLSchemaDate ($mindefault=true)
 
 getISO8601Date ($mindefault=true)
 
 getMediaWikiDate ()
 
 getDataItemForCalendarModel ($calendarmodel)
 
- Public Member Functions inherited from SMWDataValue
 __construct ($typeid)
 
 setUserValue ($value, $caption=false)
 
 setDataItem (SMWDataItem $dataItem)
 
 setDataValueServiceFactory ($dataValueServiceFactory)
 
 setProperty (SMWDIProperty $property)
 
 getProperty ()
 
 setContextPage (SMWDIWikiPage $contextPage=null)
 
 getContextPage ()
 
 setOptions (Options $options=null)
 
 setOption ($key, $value)
 
 getOption ($key)
 
 isEnabledFeature ($feature)
 
 setCaption ($caption)
 
 getCaption ()
 
 getPreferredCaption ()
 
 setOutputFormat ($formatString)
 
 getOutputFormat ()
 
 addError ($error)
 
 addErrorMsg ($parameters, $type=null)
 
 clearErrors ()
 
 getQueryDescription ($value)
 
 getDataItem ()
 
 __toString ()
 
 getShortWikiText ($linked=null)
 
 getShortHTMLText ($linker=null)
 
 getLongWikiText ($linked=null)
 
 getLongHTMLText ($linker=null)
 
 getShortText ($outputformat, $linker=null)
 
 getLongText ($outputformat, $linker=null)
 
 getInfolinkText ($outputformat, $linker=null)
 
 getWikiValue ()
 
 getTypeID ()
 
 getInfolinks ()
 
 getHash ()
 
 isNumeric ()
 
 isValid ()
 
 canUse ()
 
 getExtraneousFunctionFor ($name, array $parameters=array())
 
 getErrorText ()
 
 getErrors ()
 

Static Public Member Functions

static parseTimeString ($string, &$hours, &$minutes, &$seconds, &$timeoffset)
 
- Static Public Member Functions inherited from SMWDataValue
static prepareValue (&$value, &$comparator)
 

Public Attributes

const TYPE_ID = '_dat'
 
const J1582 = 2299160.5
 Moment of switchover to Gregorian calendar. More...
 
const MJD_EPOCH = 2400000.5
 Offset of Julian Days for Modified JD inputs. More...
 
const PREHISTORY = -10000
 The year before which we do not accept anything but year numbers and largely discourage calendar models. More...
 
- Public Attributes inherited from SMWDataValue
const OPT_USER_LANGUAGE = 'user.language'
 
const OPT_CONTENT_LANGUAGE = 'content.language'
 
const OPT_QUERY_CONTEXT = 'query.context'
 
const OPT_QUERY_COMP_CONTEXT = 'query.comparator.context'
 
const OPT_DISABLE_INFOLINKS = 'disable.infolinks'
 

Protected Member Functions

 parseUserValue ($value)
 
 parseDateString ($string, &$datecomponents, &$calendarmodel, &$era, &$hours, &$minutes, &$seconds, &$microseconds, &$timeoffset, &$timezone)
 
 interpretDateComponents ($datecomponents, &$date)
 
 setDateFromParsedValues ($datecomponents, $calendarmodel, $era, $hours, $minutes, $seconds, $microseconds, $timeoffset, $timezone)
 
 getCalendarModel ($presetmodel, $year, $month, $day)
 
 loadDataItem (SMWDataItem $dataItem)
 
- Protected Member Functions inherited from SMWDataValue
 parseUserValue ($value)
 
 loadDataItem (SMWDataItem $dataItem)
 
 getServiceLinkParams ()
 
 checkAllowedValues ()
 
 getOptions ()
 

Static Protected Member Functions

static parseMilTimeString ($string, &$hours, &$minutes, &$seconds)
 
static checkDateComponent ($component, &$numvalue)
 

Protected Attributes

 $m_dataitem_greg = null
 
 $m_dataitem_jul = null
 
 $m_wikivalue
 
- Protected Attributes inherited from SMWDataValue
 $m_dataitem
 
 $m_property = null
 
 $m_contextPage = null
 
 $m_caption
 
 $m_typeid
 
 $m_outformat = false
 
 $dataValueServiceFactory
 

Static Protected Attributes

static $m_months = array( 'January', 'February', 'March', 'April' , 'May' , 'June' , 'July' , 'August' , 'September' , 'October' , 'November' , 'December' )
 
static $m_monthsshort = array( 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' )
 
static $m_formats = array( SMW_Y => array( 'y' ), SMW_YM => array( 'y', 'm' ), SMW_MY => array( 'm', 'y' ), SMW_YDM => array( 'y', 'd', 'm' ), SMW_YMD => array( 'y', 'm', 'd' ), SMW_DMY => array( 'd', 'm', 'y' ), SMW_MDY => array( 'm', 'd', 'y' ) )
 

Detailed Description

This datavalue captures values of dates and times, in many formats, throughout history and pre-history. The implementation can handle dates across 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.

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 with defaults (usually using the earliest possible time, i.e. interpreting "2008" as "Jan 1 2008 00:00:00"). The information on what was unspecified is kept internally for improving behavior e.g. for outputs (defaults are not printed when querying for a value). This largely uses the precision handling of SMWDITime.

Date formats

Dates can be given in many formats, using numbers, month names, and abbreviated month names. The preferred interpretation of ambiguous dates ("1 2 2008" or even "1 2 3 BC") is controlled by the language file, as is the local naming of months. English month names are always supported.

Dates can be given in Gregorian or Julian calendar, set by the token "Jl" or "Gr" in the input. If neither is set, a default is chosen: inputs after October 15, 1582 (the time when the Gregorian calendar was first inaugurated in some parts of the world) are considered Gr, earlier inputs are considered Jl. In addition to Jl and Gr, we support "OS" (Old Style English dates that refer to the use of Julian calendar with a displaced change of year on March 24), JD (direct numerical input in Julian Day notation), and MJD (direct numerical input in Modified Julian Day notation as used in aviation and space flight).

The class does not support the input of negative year numbers but uses the markers "BC"/"BCE" and "AD"/"CE" instead. There is no year 0 in Gregorian or Julian calendars, but the class graciously considers this input to mean year 1 BC(E).

For prehisoric dates before 9999 BC(E) only year numbers are allowed (nothing else makes much sense). At this time, the years of Julian and Gregorian calendar still overlap significantly, so the transition to a purely solar annotation of prehistoric years is smooth. Technically, the class will consider prehistoric dates as Gregorian but very ancient times may be interpreted as desired (probably with reference to a physical notion of time that is not dependent on revolutions of earth around the sun).

Time formats

Times can be in formats like "23:12:45" and "12:30" possibly with additional modifiers "am" or "pm". Timezones are supported: the class knows many international timezone monikers (e.g. CET or GMT) and also allows time offsets directly after a time (e.g. "10:30-3:30" or "14:45:23+2"). Such offsets always refer to UTC. Timezones are only used on input and are not stored as part of the value.

Time offsets take leap years into account, e.g. the date "Feb 28 2004 23:00+2:00" is equivalent to "29 February 2004 01:00:00", while "Feb 28 1900 23:00+2:00" is equivalent to "1 March 1900 01:00:00".

Military time format is supported. This consists of 4 or 6 numeric digits followed by a one-letter timezone code (e.g. 1240Z is equivalent to 12:40 UTC).

I18N

Currently, neither keywords like "BCE", "Jl", or "pm", nor timezone monikers are internationalized. Timezone monikers may not require this, other than possibly for Cyrillic (added when needed). Month names are fully internationalized, but English names and abbreviations will also work in all languages. The class also supports ordinal day-of-month annotations like "st" and "rd", again only for English.

I18N includes the preferred order of dates, e.g. to interpret "5 6 2010".

Todo:

Theparsing process can encounter many kinds of well-defined problems but uses only one error message. More detailed reporting should be done.

Try to reuse more of MediaWiki's records, e.g. to obtain month names or to format dates. The problem is that MW is based on SIO timestamps that don't extend to very ancient or future dates, and that MW uses PHP functions that are bound to UNIX time.

Author
Markus Krötzsch
Fabian Howahl
Terry A. Hurlbut

Member Function Documentation

static SMWTimeValue::checkDateComponent (   $component,
$numvalue 
)
staticprotected

Check which roles a string component might play in a date, and set the call-by-ref parameter to the proper numerical representation. The component string has already been normalized to be either a plain number, a month name, or a plain number with "d" pre-pended. The result is a bit vector to indicate the possible interpretations.

Parameters
$componentstring
$numvalueinteger representing the components value
Returns
integer that encodes a three-digit bit vector
SMWTimeValue::getCalendarModel (   $presetmodel,
  $year,
  $month,
  $day 
)
protected

Determine the calender model under which an input should be interpreted based on the given input data.

Parameters
$presetmodelmixed string related to a user input calendar model (OS, Jl, Gr) or false
$yearinteger of the given year (adjusted for BC(E), i.e. possibly negative)
$monthmixed integer of the month or false
$daymixed integer of the day or false
Returns
integer either SMWDITime::CM_GREGORIAN or SMWDITime::CM_JULIAN
SMWTimeValue::getDataItemForCalendarModel (   $calendarmodel)

Get the current data in the specified calendar model. Conversion is not done for prehistoric dates (where it might lead to precision errors and produce results that are not meaningful). In this case, null might be returned if no data in the specified format is available.

Parameters
$calendarmodelinteger one of SMWDITime::CM_GREGORIAN or SMWDITime::CM_JULIAN
Returns
SMWDITime
SMWTimeValue::getDay (   $calendarmodel = SMWDITime::CM_GREGORIAN,
  $default = 1 
)

Return the day number in the given calendar model, or false if this number is not available (typically when attempting to get prehistoric Julian calendar dates).

Parameters
$calendarmodelinteger either SMWDITime::CM_GREGORIAN or SMWDITime::CM_JULIAN
$defaultvalue to return if day is not set at our level of precision
Returns
mixed typically a number but possibly anything given as $default
SMWTimeValue::getISO8601Date (   $mindefault = true)
See also
TimeValueFormatter::getISO8601DateFromDataItem
Parameters
$mindefaultboolean determining whether values below the precision of our input should be completed with minimal or maximal conceivable values
Returns
string
SMWTimeValue::getLongHTMLText (   $linker = null)
SMWTimeValue::getLongWikiText (   $linker = null)
SMWTimeValue::getMediaWikiDate ( )
See also
TimeValueFormatter::getMediaWikiDateFromDataItem
Returns
string
SMWTimeValue::getMonth (   $calendarmodel = SMWDITime::CM_GREGORIAN,
  $default = 1 
)

Return the month number in the given calendar model, or false if this number is not available (typically when attempting to get prehistoric Julian calendar dates).

Parameters
$calendarmodelinteger either SMWDITime::CM_GREGORIAN or SMWDITime::CM_JULIAN
$defaultvalue to return if month is not set at our level of precision
Returns
mixed typically a number but possibly anything given as $default
SMWTimeValue::getShortHTMLText (   $linker = null)
SMWTimeValue::getShortWikiText (   $linker = null)
SMWTimeValue::getTimeString (   $default = '00:00:00')
See also
TimeValueFormatter::getTimeStringFromDataItem
Returns
SMWTimeValue::getWikiValue ( )
Todo:
The preferred caption may not be suitable as a wiki value (i.e. not parsable).
See also
SMWDataValue::getLongHTMLText
SMWTimeValue::getXMLSchemaDate (   $mindefault = true)
Deprecated:
This method is now called getISO8601Date(). It will vanish before SMW 1.7.
SMWTimeValue::getYear (   $calendarmodel = SMWDITime::CM_GREGORIAN)

Return the year number in the given calendar model, or false if this number is not available (typically when attempting to get prehistoric Julian calendar dates). As everywhere in this class, there is no year 0.

Parameters
$calendarmodelinteger either SMWDITime::CM_GREGORIAN or SMWDITime::CM_JULIAN
Returns
mixed typically a number but possibly false
SMWTimeValue::interpretDateComponents (   $datecomponents,
$date 
)
protected

Validate and interpret the date components as retrieved when parsing a user input. The method takes care of guessing how a list of values such as "10 12 13" is to be interpreted using the current language settings. The result is stored in the call-by-ref parameter $date that uses keys 'y', 'm', 'd' and contains the respective numbers as values, or false if not specified. If errors occur, error messages are added to the objects list of errors, and false is returned. Otherwise, true is returned.

Parameters
$datecomponentsarray of strings that might belong to the specification of a date
$datearray set to result
Returns
boolean stating if successful
SMWTimeValue::isNumeric ( )
SMWTimeValue::loadDataItem ( SMWDataItem  $dataItem)
protected
SMWTimeValue::parseDateString (   $string,
$datecomponents,
$calendarmodel,
$era,
$hours,
$minutes,
$seconds,
$microseconds,
$timeoffset,
$timezone 
)
protected

Parse the given string to check if it a date/time value. The function sets the provided call-by-ref values to the respective values. If errors are encountered, they are added to the objects error list and false is returned. Otherwise, true is returned.

Parameters
$stringstring input time representation, e.g. "12 May 2007 13:45:23-3:30"
$datecomponentsarray of strings that might belong to the specification of a date
$calendarmodeslstring if model was set in input, otherwise false
$erastring '+' or '-' if provided, otherwise false
$hoursinteger set to a value between 0 and 24
$minutesinteger set to a value between 0 and 59
$secondsinteger set to a value between 0 and 59, or false if not given
$timeoffsetdouble set to a value for time offset (e.g. 3.5), or false if not given
Returns
boolean stating if the parsing succeeded
Todo:
This method in principle allows date parsing to be internationalized further. Should be done.
static SMWTimeValue::parseMilTimeString (   $string,
$hours,
$minutes,
$seconds 
)
staticprotected

Parse the given string to check if it encodes a "military time". If successful, the function sets the provided call-by-ref values to the respective numbers and returns true. Otherwise, it returns false and does not set any values.

Parameters
$stringstring input time representation, e.g. "134523"
$hoursinteger between 0 and 24
$minutesinteger between 0 and 59
$secondsinteger between 0 and 59, or false if not given
Returns
boolean stating if the parsing succeeded
static SMWTimeValue::parseTimeString (   $string,
$hours,
$minutes,
$seconds,
$timeoffset 
)
static

Parse the given string to check if it encodes an international time. If successful, the function sets the provided call-by-ref values to the respective numbers and returns true. Otherwise, it returns false and does not set any values.

Note
This method is only temporarily public for enabling SMWCompatibilityHelpers. Do not use it directly in your code.
Parameters
$stringstring input time representation, e.g. "13:45:23-3:30"
$hoursinteger between 0 and 24
$minutesinteger between 0 and 59
$secondsinteger between 0 and 59, or false if not given
$timeoffsetdouble for time offset (e.g. 3.5), or false if not given
Returns
boolean stating if the parsing succeeded
SMWTimeValue::parseUserValue (   $value)
protected
SMWTimeValue::setDateFromParsedValues (   $datecomponents,
  $calendarmodel,
  $era,
  $hours,
  $minutes,
  $seconds,
  $microseconds,
  $timeoffset,
  $timezone 
)
protected

Initialise data from the provided intermediate results after parsing, assuming that a conventional date notation is used. If errors occur, error messages are added to the objects list of errors, and false is returned. Otherwise, true is returned.

Parameters
$datecomponentsarray of strings that might belong to the specification of a date
$calendarmodeslstring if model was set in input, otherwise false
$erastring '+' or '-' if provided, otherwise false
$hoursinteger value between 0 and 24
$minutesinteger value between 0 and 59
$secondsinteger value between 0 and 59, or false if not given
$timeoffsetdouble value for time offset (e.g. 3.5), or false if not given
Returns
boolean stating if successful

Member Data Documentation

SMWTimeValue::$m_dataitem_greg = null
protected
SMWTimeValue::$m_dataitem_jul = null
protected
SMWTimeValue::$m_formats = array( SMW_Y => array( 'y' ), SMW_YM => array( 'y', 'm' ), SMW_MY => array( 'm', 'y' ), SMW_YDM => array( 'y', 'd', 'm' ), SMW_YMD => array( 'y', 'm', 'd' ), SMW_DMY => array( 'd', 'm', 'y' ), SMW_MDY => array( 'm', 'd', 'y' ) )
staticprotected
SMWTimeValue::$m_months = array( 'January', 'February', 'March', 'April' , 'May' , 'June' , 'July' , 'August' , 'September' , 'October' , 'November' , 'December' )
staticprotected
SMWTimeValue::$m_monthsshort = array( 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' )
staticprotected
SMWTimeValue::$m_wikivalue
protected
const SMWTimeValue::J1582 = 2299160.5

Moment of switchover to Gregorian calendar.

const SMWTimeValue::MJD_EPOCH = 2400000.5

Offset of Julian Days for Modified JD inputs.

const SMWTimeValue::PREHISTORY = -10000

The year before which we do not accept anything but year numbers and largely discourage calendar models.

const SMWTimeValue::TYPE_ID = '_dat'

DV identifier


The documentation for this class was generated from the following file: