Package org.wikidata.wdtk.datamodel.interfaces

Interface TimeValue

All Superinterfaces:
Value
All Known Implementing Classes:
TimeValueImpl
public interface TimeValue extends Value
Time values represent points and intervals in time, and additional information about their format. Information includes a specific time point, information about its precision, and the preferred calendar model and timezone (for display). Moreover, time values can describe some uncertainty regarding the exact position in time. This is achieved by tolerance values that specify how much before or after the given time point an event might have occurred.

Time points cannot describe durations (which are quantities), recurring events ("1st of May"), or time spans ( "He reigned from 1697 to 1706, i.e., during every moment of that time span" ). Intervals expressed by times always encode uncertainty ("He died in the year 546 BCE, i.e., in some moment within that interval").

The main time point of the value generally refers to the proleptic Gregorian calendar. However, if dates are imprecise (like "Jan 1512" or even "1200") then one cannot convert this reliably and Wikidata will just keep the value as entered.

"Y0K issue": Neither the Gregorian nor the Julian calendar assume a year 0, i.e., the year 1 BCE was followed by 1 CE in these calendars. See http://en.wikipedia.org/wiki/Year_zero. Wikibase internally uses the year 0. This is the same as ISO-8601, where 1 BCE is represented as "0000". However, note that XML Schema dates (1.0 and 2.0) do not have a year 0, so in their case 1BCE is represented as "-1". Understanding the difference is relevant for computing leap years, for computing temporal intervals, and for exporting data.

Timezone information is to be given in the form of a positive or negative offset with respect to UTC, measured in minutes. This information specifies the timezone that the time should be displayed in when shown to a user. The recorded time point is in UTC, so timezone can be ignored for comparing values. See getTimezoneOffset().

Author:
Markus Kroetzsch

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    CM_GREGORIAN_PRO
    IRI of the proleptic Gregorian calendar; often used to specify the calendar model
    static final String
    CM_JULIAN_PRO
    IRI of the proleptic Julian calendar; often used to specify the calendar model
    static final byte
    PREC_100KY
    Precision constant for dates that are precise to 100,000 years.
    static final byte
    PREC_100MY
    Precision constant for dates that are precise to 100 million years.
    static final byte
    PREC_100Y
    Precision constant for dates that are precise to 100 years.
    static final byte
    PREC_10KY
    Precision constant for dates that are precise to 10,000 years.
    static final byte
    PREC_10MY
    Precision constant for dates that are precise to 10 million years.
    static final byte
    PREC_1GY
    Precision constant for dates that are precise to 10^9 years.
    static final byte
    PREC_1KY
    Precision constant for dates that are precise to 1,000 years.
    static final byte
    PREC_1MY
    Precision constant for dates that are precise to 1 million years.
    static final byte
    PREC_DAY
    Precision constant for dates that are precise to the day.
    static final byte
    PREC_DECADE
    Precision constant for dates that are precise to the decade.
    static final byte
    PREC_HOUR
    Precision constant for dates that are precise to the hour.
    static final byte
    PREC_MINUTE
    Precision constant for dates that are precise to the minute.
    static final byte
    PREC_MONTH
    Precision constant for dates that are precise to the month.
    static final byte
    PREC_SECOND
    Precision constant for dates that are precise to the second.
    static final byte
    PREC_YEAR
    Precision constant for dates that are precise to the year.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    getAfterTolerance()
    Get a tolerance value that specifies how much later in time the value could at most be, measured as a multiple of precision.
    int
    getBeforeTolerance()
    Get a tolerance value that specifies how much earlier in time the value could at most be, measured as a multiple of precision.
    byte
    getDay()
    Get the day stored for this date.
    byte
    getHour()
    Get the hour stored for this date.
    byte
    getMinute()
    Get the minute stored for this date.
    byte
    getMonth()
    Get the month stored for this date.
    byte
    getPrecision()
    Get the precision hint of this date.
    String
    getPreferredCalendarModel()
    Get the IRI of the preferred calendar model that should be used to display this date (and that was presumably used when entering it).
    ItemIdValue
    getPreferredCalendarModelItemId()
    Get the ItemIdValue of the preferred calendar model that should be used to display this date (and that was presumably used when entering it).
    byte
    getSecond()
    Get the seconds stored for this date.
    int
    getTimezoneOffset()
    Get the offset in minutes from UTC that should be applied when displaying this time to users.
    long
    getYear()
    Get the year stored for this date.
    TimeValue
    toGregorian()
    Convert the value to the Gregorian calendar, if possible.

    Methods inherited from interface org.wikidata.wdtk.datamodel.interfaces.Value

    accept

  • Field Details

    • CM_GREGORIAN_PRO

      static final String CM_GREGORIAN_PRO
      IRI of the proleptic Gregorian calendar; often used to specify the calendar model
      See Also:

    • CM_JULIAN_PRO

      static final String CM_JULIAN_PRO
      IRI of the proleptic Julian calendar; often used to specify the calendar model
      See Also:

    • PREC_SECOND

      static final byte PREC_SECOND
      Precision constant for dates that are precise to the second.
      See Also:

    • PREC_MINUTE

      static final byte PREC_MINUTE
      Precision constant for dates that are precise to the minute.
      See Also:

    • PREC_HOUR

      static final byte PREC_HOUR
      Precision constant for dates that are precise to the hour.
      See Also:

    • PREC_DAY

      static final byte PREC_DAY
      Precision constant for dates that are precise to the day.
      See Also:

    • PREC_MONTH

      static final byte PREC_MONTH
      Precision constant for dates that are precise to the month.
      See Also:

    • PREC_YEAR

      static final byte PREC_YEAR
      Precision constant for dates that are precise to the year.
      See Also:

    • PREC_DECADE

      static final byte PREC_DECADE
      Precision constant for dates that are precise to the decade.
      See Also:

    • PREC_100Y

      static final byte PREC_100Y
      Precision constant for dates that are precise to 100 years.
      See Also:

    • PREC_1KY

      static final byte PREC_1KY
      Precision constant for dates that are precise to 1,000 years.
      See Also:

    • PREC_10KY

      static final byte PREC_10KY
      Precision constant for dates that are precise to 10,000 years.
      See Also:

    • PREC_100KY

      static final byte PREC_100KY
      Precision constant for dates that are precise to 100,000 years.
      See Also:

    • PREC_1MY

      static final byte PREC_1MY
      Precision constant for dates that are precise to 1 million years.
      See Also:

    • PREC_10MY

      static final byte PREC_10MY
      Precision constant for dates that are precise to 10 million years.
      See Also:

    • PREC_100MY

      static final byte PREC_100MY
      Precision constant for dates that are precise to 100 million years.
      See Also:

    • PREC_1GY

      static final byte PREC_1GY
      Precision constant for dates that are precise to 10^9 years.
      See Also:

  • Method Details

    • getYear

      long getYear()
      Get the year stored for this date. Years in Wikibase can be 0; see "Y0K" issue in the interface documentation.
      Returns:
      year number

    • getMonth

      byte getMonth()
      Get the month stored for this date. It will be a number from 1 to 12.
      Returns:
      month number

    • getDay

      byte getDay()
      Get the day stored for this date. It will be a number from 1 to 31.
      Returns:
      day number

    • getHour

      byte getHour()
      Get the hour stored for this date. It will be a number from 0 to 23.
      Returns:
      hour number

    • getMinute

      byte getMinute()
      Get the minute stored for this date. It will be a number from 0 to 59.
      Returns:
      minute number

    • getSecond

      byte getSecond()
      Get the seconds stored for this date. The value will be between 0 and 60 (inclusive) to account for leap seconds. Implementations are not expected to validate leap seconds but they should provide consistent ordering: the time 23:59:60 is always before 00:00:00 on the next day.
      Returns:
      second number

    • getPreferredCalendarModel

      String getPreferredCalendarModel()
      Get the IRI of the preferred calendar model that should be used to display this date (and that was presumably used when entering it). This is usually CM_GREGORIAN_PRO or CM_JULIAN_PRO.
      Returns:
      IRI of the preferred calendar model

    • getPreferredCalendarModelItemId

      ItemIdValue getPreferredCalendarModelItemId()
      Get the ItemIdValue of the preferred calendar model that should be used to display this date (and that was presumably used when entering it).
      Throws:
      IllegalArgumentException - if the calendar model is not a valid item IRI

    • getPrecision

      byte getPrecision()
      Get the precision hint of this date. The return value will be in the range of PREC_DAY, ..., PREC_1GY.
      Returns:
      precision hint for this date

    • getTimezoneOffset

      int getTimezoneOffset()
      Get the offset in minutes from UTC that should be applied when displaying this time to users. The recorded time point is always in UTC, so the timezone can be ignored for comparing values. The offset should be added to the given time to obtain the intended local value. For example, an offset of +60 and a time of 10:45:00 should be displayed as 11:45:00 to the user (ideally with some indication of the shift; time zone abbreviations like "CET" could be used when matching the given offset, but the offset might also have values that do not correspond to any current or modern time zone). Therefore positive offsets are used for timezones that to the east of the prime meridian.
      Returns:
      minute number (positive or negative)

    • getBeforeTolerance

      int getBeforeTolerance()
      Get a tolerance value that specifies how much earlier in time the value could at most be, measured as a multiple of precision. The value is a non-negative integer.

      For example, for the date 2007-05-12T10:45:00 with precision PREC_MONTH, a before-tolerance value of 3 means that the earliest possible time of this event could have been 2007-02-12T10:45:00. This information about the uncertainty of time points can be taken into account in query answering, but simplified implementations can also ignore it and work with the given (exact) time point instead. If not set specifically by the user, the before-tolerance value should be 0, i.e., the given time point marks the earliest possible time.

      This boundary is inclusive. For example, a date 2014-02-17T00:00:00 with precision PREC_DAY and before-tolerance value 1 specifies a time that between 2014-02-17T00:00:00

      Returns:
      a non-negative integer tolerance measured in terms of precision
      See Also:

    • getAfterTolerance

      int getAfterTolerance()
      Get a tolerance value that specifies how much later in time the value could at most be, measured as a multiple of precision. The value is a positive integer.

      For example, for the date 2007-05-12T10:45:00 with precision PREC_MONTH, an after-tolerance value of 2 means that the latest possible time of this event could have been strictly before 2007-07-12T10:45:00. This information about the uncertainty of time points can be taken into account in query answering, but simplified implementations can also ignore it and work with the given (exact) time point instead. If not set specifically by the user, the after-tolerance value should be 1, i.e., the interval of uncertainty is exactly the length given by precision. However, because most (if not all) other known implementations of the data model got this detail wrong and use 0 instead, we are also using 0 as a default value. This issue is tracked at https://phabricator.wikimedia.org/T194869.

      The boundary is exclusive. For example, a date 2013-02-01T00:00:00 with precision PREC_MONTH and after-tolerance value 1 and before-tolerance value of 0 specifies a time "sometime in February 2013", but it excludes any time in March 2013. The after-tolerance must not be 0 (which would make no sense if the bound is exclusive, and which is not needed since precision up to a single second can be specified anyway).

      Returns:
      a non-zero, positive integer tolerance measured in terms of precision
      See Also:

    • toGregorian

      TimeValue toGregorian()
      Convert the value to the Gregorian calendar, if possible. This conversion can fail if not enough information is available (for example, we need at least day precision to convert from Julian to Gregorian).
      Returns:
      a TimeValue that uses the Gregorian calendar, or null if the conversion failed.