Module dev.metaschema.core
Package dev.metaschema.core.metapath.item.atomic

Interface IDateTimeItem

All Superinterfaces:
IAnyAtomicItem, IAtomicValuedItem, ICalendarTemporalItem, ICollectionValue, IItem, ITemporalItem
All Known Subinterfaces:
IDateTimeWithTimeZoneItem
public interface IDateTimeItem extends ICalendarTemporalItem
An atomic Metapath item representing a date/time value in the Metapath system.

This interface provides functionality for handling date/time values with and without time zone information, supporting parsing, casting, and comparison operations. It works in conjunction with AmbiguousDateTime to properly handle time zone ambiguity.

  • Method Details

    • type

      @NonNull static IAtomicOrUnionType<IDateTimeItem> type()
      Get the type information for this item.
      Returns:
      the type information

    • getType

      default IAtomicOrUnionType<? extends IDateTimeItem> getType()
      Description copied from interface: IItem
      Get the type information for the item.
      Specified by:
      getType in interface IItem
      Returns:
      the item's type information

    • valueOf

      @NonNull static IDateTimeItem valueOf(@NonNull String value)
      Construct a new date/time item using the provided string value.
      Parameters:
      value - a string representing a date/time
      Returns:
      the new item

    • valueOf

      @NonNull static IDateTimeItem valueOf(@NonNull IDateItem date, @NonNull ITimeItem time)
      Get a date/time item based on the provided date and time item values.
      Parameters:
      date - the date portion of the date/time
      time - the time portion of the date/time
      Returns:
      the date/time item

    • valueOf

      @NonNull static IDateTimeItem valueOf(@NonNull ICalendarTemporalItem item)
      Get the provided item as a date/time item.
      Parameters:
      item - the item to convert to a date/time
      Returns:
      the provided value as a date/time

    • valueOf

      @NonNull static IDateTimeItem valueOf(@NonNull ZonedDateTime value, boolean hasTimeZone)
      Construct a new date/time item using the provided value.

      This method handles recording if an explicit timezone was provided using the hasTimeZone parameter. The AbstractAmbiguousTemporal.hasTimeZone() method can be called to determine if timezone information is present.

      Parameters:
      value - a date/time, without time zone information
      hasTimeZone - true if the date/time is intended to have an associated time zone or false otherwise
      Returns:
      the new item
      See Also:

    • valueOf

      @NonNull static IDateTimeItem valueOf(@NonNull LocalDateTime value)
      Construct a new date/time item using the provided local time value.

      The timezone is marked as ambiguous, meaning the AbstractAmbiguousTemporal.hasTimeZone() method will return a result of false.

      Parameters:
      value - the local time value to use
      Returns:
      the new item
      See Also:

    • valueOf

      @NonNull static IDateTimeItem valueOf(@NonNull AmbiguousDateTime value)
      Construct a new date/time item using the provided value.

      This method handles recording if an explicit timezone was provided using the AmbiguousDateTime. The AbstractAmbiguousTemporal.hasTimeZone() method can be called to determine if timezone information is present.

      Parameters:
      value - a date/time, without time zone information
      Returns:
      the new item
      See Also:

    • hasDate

      default boolean hasDate()
      Description copied from interface: ITemporalItem
      Determine if the temporal has date information.
      Specified by:
      hasDate in interface ITemporalItem
      Returns:
      true if the temporal item has date information or false otherwise

    • hasTime

      default boolean hasTime()
      Description copied from interface: ITemporalItem
      Determine if the temporal has time information.
      Specified by:
      hasTime in interface ITemporalItem
      Returns:
      true if the temporal item has time information or false otherwise

    • getYear

      default int getYear()
      Description copied from interface: ITemporalItem
      Get the year value of this temporal.
      Specified by:
      getYear in interface ITemporalItem
      Returns:
      the year value

    • getMonth

      default int getMonth()
      Description copied from interface: ITemporalItem
      Get the month value of this temporal.
      Specified by:
      getMonth in interface ITemporalItem
      Returns:
      the month value

    • getDay

      default int getDay()
      Description copied from interface: ITemporalItem
      Get the day value of this temporal.
      Specified by:
      getDay in interface ITemporalItem
      Returns:
      the day value

    • getHour

      default int getHour()
      Description copied from interface: ITemporalItem
      Get the hour value of this temporal.
      Specified by:
      getHour in interface ITemporalItem
      Returns:
      the hour value

    • getMinute

      default int getMinute()
      Description copied from interface: ITemporalItem
      Get the minute value of this temporal.
      Specified by:
      getMinute in interface ITemporalItem
      Returns:
      the minute value

    • getSecond

      default int getSecond()
      Description copied from interface: ITemporalItem
      Get the whole second value of this temporal.
      Specified by:
      getSecond in interface ITemporalItem
      Returns:
      the whole second value

    • getNano

      default int getNano()
      Description copied from interface: ITemporalItem
      Get the partial nano second value of this temporal.
      Specified by:
      getNano in interface ITemporalItem
      Returns:
      the partial nano second value

    • asLocalDateTime

      @NonNull default LocalDateTime asLocalDateTime()
      Get the date as a LocalDate.
      Returns:
      the date

    • asLocalDate

      @NonNull default LocalDate asLocalDate()
      Get the date as a LocalDate.
      Returns:
      the date

    • asLocalTime

      @NonNull default LocalTime asLocalTime()
      Get the date/time as a LocalTime.
      Returns:
      the time

    • asOffsetTime

      @NonNull default OffsetTime asOffsetTime()
      Get the date/time as an OffsetTime.
      Returns:
      the time

    • asDate

      @NonNull default IDateItem asDate()
      Get the date/time as a date item.
      Returns:
      the date portion of this date/time

    • asTime

      @NonNull default ITimeItem asTime()
      Get the date/time as a time item.
      Returns:
      the time portion of this date/time

    • normalize

      @NonNull default IDateTimeItem normalize(@NonNull DynamicContext dynamicContext)
      Get a date/time that has an explicit timezone.

      If this date/time has a timezone, then this timezone is used. Otherwise, the implicit timezone is used from the dynamic context to create a new date/time.

      Parameters:
      dynamicContext - the dynamic context used to get the implicit timezone
      Returns:
      the date/time with the timezone normalized using UTC-based timezone

    • asDateTimeZ

      default IDateTimeItem asDateTimeZ()
      Get this date/time in the UTC timezone.
      Returns:
      the date/time in UTC

    • replaceTimezone

      default IDateTimeItem replaceTimezone(@Nullable IDayTimeDurationItem offset)
      Adjusts an xs:dateTime value to a specific timezone, or to no timezone at all.

      This method does one of the following things based on the arguments.

      1. If the provided offset is null and the provided date/time value has a timezone, the timezone is maked absent.
      2. If the provided offset is null and the provided date/time value has an absent timezone, the date/time value is returned.
      3. If the provided offset is not null and the provided date/time value has an absent timezone, the date/time value is returned with the new timezone applied.
      4. Otherwise, the provided timezone is applied to the date/time value adjusting the time instant.

      Implements the XPath 3.1 fn:adjust-dateTime-to-timezone function.

      Specified by:
      replaceTimezone in interface ITemporalItem
      Parameters:
      offset - the timezone offset to use or null
      Returns:
      the adjusted date/time value
      Throws:
      DateTimeFunctionException - with code DateTimeFunctionException.INVALID_TIME_ZONE_VALUE_ERROR if the offset is < -PT14H or > PT14H

    • cast

      @NonNull static IDateTimeItem cast(@NonNull IAnyAtomicItem item)
      Cast the provided type to this item type.
      Parameters:
      item - the item to cast
      Returns:
      the original item if it is already this type, otherwise a new item cast to this type
      Throws:
      InvalidValueForCastFunctionException - if the provided item cannot be cast to this type

    • castAsType

      default IDateTimeItem castAsType(IAnyAtomicItem item)
      Description copied from interface: IAnyAtomicItem
      Cast the provided item to be the same type as this item.
      Specified by:
      castAsType in interface IAnyAtomicItem
      Parameters:
      item - the item to cast
      Returns:
      an atomic item of this type