public interface TimeValue extends Value
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()
.
Modifier and Type | Field and Description |
---|---|
static String |
CM_GREGORIAN_PRO
IRI of the proleptic Gregorian calendar; often used to specify the
calendar model
|
static String |
CM_JULIAN_PRO
IRI of the proleptic Julian calendar; often used to specify the calendar
model
|
static byte |
PREC_100KY
Precision constant for dates that are precise to 100,000 years.
|
static byte |
PREC_100MY
Precision constant for dates that are precise to 100 million years.
|
static byte |
PREC_100Y
Precision constant for dates that are precise to 100 years.
|
static byte |
PREC_10KY
Precision constant for dates that are precise to 10,000 years.
|
static byte |
PREC_10MY
Precision constant for dates that are precise to 10 million years.
|
static byte |
PREC_1GY
Precision constant for dates that are precise to 10^9 years.
|
static byte |
PREC_1KY
Precision constant for dates that are precise to 1,000 years.
|
static byte |
PREC_1MY
Precision constant for dates that are precise to 1 million years.
|
static byte |
PREC_DAY
Precision constant for dates that are precise to the day.
|
static byte |
PREC_DECADE
Precision constant for dates that are precise to the decade.
|
static byte |
PREC_HOUR
Precision constant for dates that are precise to the hour.
|
static byte |
PREC_MINUTE
Precision constant for dates that are precise to the minute.
|
static byte |
PREC_MONTH
Precision constant for dates that are precise to the month.
|
static byte |
PREC_SECOND
Precision constant for dates that are precise to the second.
|
static byte |
PREC_YEAR
Precision constant for dates that are precise to the year.
|
Modifier and Type | Method and 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.
|
static final String CM_GREGORIAN_PRO
static final String CM_JULIAN_PRO
static final byte PREC_SECOND
static final byte PREC_MINUTE
static final byte PREC_HOUR
static final byte PREC_DAY
static final byte PREC_MONTH
static final byte PREC_YEAR
static final byte PREC_DECADE
static final byte PREC_100Y
static final byte PREC_1KY
static final byte PREC_10KY
static final byte PREC_100KY
static final byte PREC_1MY
static final byte PREC_10MY
static final byte PREC_100MY
static final byte PREC_1GY
long getYear()
byte getMonth()
byte getDay()
byte getHour()
byte getMinute()
byte getSecond()
String getPreferredCalendarModel()
CM_GREGORIAN_PRO
or
CM_JULIAN_PRO
.ItemIdValue getPreferredCalendarModelItemId()
ItemIdValue
of the preferred calendar model that should
be used to display this date (and that was presumably used when entering it).IllegalArgumentException
- if the calendar model is not a valid item IRIbyte getPrecision()
PREC_DAY
, ..., PREC_1GY
.int getTimezoneOffset()
int getBeforeTolerance()
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
getAfterTolerance()
int getAfterTolerance()
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).
getBeforeTolerance()
TimeValue toGregorian()
Copyright © 2014–2024 Wikidata Toolkit Developers. Generated from source code published under the Apache License 2.0. For more information, see the Wikidata Toolkit homepage