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

Interface ITimeItem

All Superinterfaces:
IAnyAtomicItem, IAtomicValuedItem, ICollectionValue, IItem, ITemporalItem
All Known Subinterfaces:
ITimeWithTimeZoneItem
public interface ITimeItem extends ITemporalItem
An atomic Metapath item representing a time value in the Metapath system.

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

  • Method Details

    • type

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

    • getType

      default IAtomicOrUnionType<? extends ITimeItem> 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 ITimeItem valueOf(@NonNull String value)
      Construct a new date/time item using the provided string value.
      Parameters:
      value - a string representing a time
      Returns:
      the new item

    • valueOf

      @NonNull static ITimeItem valueOf(@NonNull OffsetTime value, boolean hasTimeZone)
      Construct a new 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 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 ITimeItem valueOf(@NonNull AmbiguousTime value)
      Construct a new time item using the provided value.

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

      Parameters:
      value - a 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

    • hasTimezone

      boolean hasTimezone()
      Description copied from interface: ITemporalItem
      Determine if the temporal item has a timezone.
      Specified by:
      hasTimezone in interface ITemporalItem
      Returns:
      true if the temporal item has a timezone 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

    • getZoneOffset

      @Nullable default ZoneOffset getZoneOffset()
      Description copied from interface: ITemporalItem
      Get the timezone offset for this temporal.
      Specified by:
      getZoneOffset in interface ITemporalItem
      Returns:
      the timezone offset if specified or null if the timezone is not known
      See Also:

    • asOffsetTime

      @NonNull OffsetTime asOffsetTime()
      Get the underlying time value.
      Returns:
      the time value

    • replaceTimezone

      default ITimeItem 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 ITimeItem 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 ITimeItem 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

    • asLocalTime

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