Semantic MediaWiki and related extensions
Public Member Functions | Public Attributes | Static Public Attributes | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
SMWTimeValue Class Reference
Inheritance diagram for SMWTimeValue:
Inheritance graph
[legend]
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=DITime::CM_GREGORIAN)
 
 getMonth ( $calendarmodel=DITime::CM_GREGORIAN, $default=1)
 
 getDay ( $calendarmodel=DITime::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)
 
 getTypeID ()
 
 setUserValue ( $value, $caption=false)
 
 setDataItem (SMWDataItem $dataItem)
 
 setDataValueServiceFactory (DataValueServiceFactory $dataValueServiceFactory)
 
 setProperty (DIProperty $property)
 
 getProperty ()
 
 setContextPage (SMWDIWikiPage $contextPage=null)
 
 getContextPage ()
 
 setCaption ( $caption)
 
 getCaption ()
 
 getPreferredCaption ()
 
 setOutputFormat ( $formatString)
 
 getOutputFormat ()
 
 addError ( $error)
 
 addErrorMsg ( $error, $type=Message::TEXT)
 
 getErrorText ()
 
 getErrors ()
 
 getErrorsByType ( $type=null)
 
 getRestrictionError ()
 
 clearErrors ()
 
 getQueryDescription ( $value)
 
 getDataItem ()
 
 __toString ()
 
 getShortWikiText ( $linker=null)
 
 getShortHTMLText ( $linker=null)
 
 getLongWikiText ( $linker=null)
 
 getLongHTMLText ( $linker=null)
 
 getWikiValue ()
 
 getShortText ( $outputFormat, $linker=null)
 
 getLongText ( $outputFormat, $linker=null)
 
 getInfolinkText ( $outputFormat, $linker=null)
 
 getInfolinks ()
 
 getHash ()
 
 isNumeric ()
 
 isValid ()
 
 canUse ()
 
 isRestricted ()
 
 addCallable ( $key, callable $callable)
 
 hasCallable ( $key)
 
 getCallable ( $key)
 
 clearCallable ( $key)
 
 copyOptions (Options $options=null)
 
 setOption ( $key, $value)
 
 getOption ( $key, $default=false)
 
 hasFeature ( $feature)
 
 isEnabledFeature ( $feature)
 
 checkConstraints ()
 

Public Attributes

const TYPE_ID = '_dat'
 
static const J1582 = 2299160.5
 
const MJD_EPOCH = 2400000.5
 
const PREHISTORY = -10000
 
- 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'
 
const OPT_DISABLE_SERVICELINKS = 'disable.servicelinks'
 
const OPT_COMPACT_INFOLINKS = 'compact.infolinks'
 

Static Public Attributes

static SMW_YM => [ 'y'
 
static SMW_MY => [ 'm'
 
static SMW_YDM => [ 'y'
 
static SMW_YMD => [ 'y'
 
static SMW_DMY => [ 'd'
 
static SMW_MDY => [ 'm'
 

Protected Member Functions

 parseUserValue ( $value)
 
 interpretDateComponents ( $datecomponents, &$date)
 
 setDateFromParsedValues ( $components)
 
 getCalendarModel ( $presetmodel, $year, $month, $day)
 
 loadDataItem (SMWDataItem $dataItem)
 
- Protected Member Functions inherited from SMWDataValue
 getOptions ()
 
 parseUserValue ( $value)
 
 loadDataItem (SMWDataItem $dataItem)
 
 getServiceLinkParams ()
 
 checkAllowedValues ()
 

Static Protected Member Functions

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
 
 $restrictionError = false
 
 $dataValueServiceFactory
 

Static Protected Attributes

static $m_formats
 

Additional Inherited Members

- Static Public Member Functions inherited from SMWDataValue
static prepareValue (&$value, &$comparator)
 

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 DITime.

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

◆ checkDateComponent()

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

◆ getCalendarModel()

SMWTimeValue::getCalendarModel (   $presetmodel,
  $year,
  $month,
  $day 
)
protected

Determine the calendar 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 DITime::CM_GREGORIAN or DITime::CM_JULIAN

◆ getDataItemForCalendarModel()

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 DITime::CM_GREGORIAN or DITime::CM_JULIAN
Returns
DITime

◆ getDay()

SMWTimeValue::getDay (   $calendarmodel = DITime::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 DITime::CM_GREGORIAN or DITime::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

◆ getISO8601Date()

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

◆ getLongHTMLText()

SMWTimeValue::getLongHTMLText (   $linker = null)

◆ getLongWikiText()

SMWTimeValue::getLongWikiText (   $linker = null)

◆ getMediaWikiDate()

SMWTimeValue::getMediaWikiDate ( )
See also
TimeValueFormatter::getMediaWikiDateFromDataItem
Returns
string

◆ getMonth()

SMWTimeValue::getMonth (   $calendarmodel = DITime::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 DITime::CM_GREGORIAN or DITime::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

◆ getShortHTMLText()

SMWTimeValue::getShortHTMLText (   $linker = null)

◆ getShortWikiText()

SMWTimeValue::getShortWikiText (   $linker = null)

◆ getTimeString()

SMWTimeValue::getTimeString (   $default = '00:00:00')
See also
TimeValueFormatter::getTimeStringFromDataItem
Returns

◆ getWikiValue()

SMWTimeValue::getWikiValue ( )
Todo:
The preferred caption may not be suitable as a wiki value (i.e. not parsable).
See also
SMWDataValue::getLongHTMLText

◆ getXMLSchemaDate()

SMWTimeValue::getXMLSchemaDate (   $mindefault = true)
Deprecated:
This method is now called getISO8601Date(). It will vanish before SMW 1.7.

◆ getYear()

SMWTimeValue::getYear (   $calendarmodel = DITime::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 DITime::CM_GREGORIAN or DITime::CM_JULIAN
Returns
mixed typically a number but possibly false

◆ interpretDateComponents()

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

◆ isNumeric()

SMWTimeValue::isNumeric ( )

◆ loadDataItem()

SMWTimeValue::loadDataItem ( SMWDataItem  $dataItem)
protected

◆ parseUserValue()

SMWTimeValue::parseUserValue (   $value)
protected
See also
DataValue::parseUserValue

◆ setDateFromParsedValues()

SMWTimeValue::setDateFromParsedValues (   $components)
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

◆ $m_formats

SMWTimeValue::$m_formats
staticprotected
Initial value:
= [
SMW_Y => [ 'y' ]

◆ J1582

const SMWTimeValue::J1582 = 2299160.5

Moment of switchover to Gregorian calendar.

◆ MJD_EPOCH

const SMWTimeValue::MJD_EPOCH = 2400000.5

Offset of Julian Days for Modified JD inputs.

◆ PREHISTORY

const SMWTimeValue::PREHISTORY = -10000

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

◆ TYPE_ID

const SMWTimeValue::TYPE_ID = '_dat'

DV identifier


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

About | General disclaimer | Privacy policy