1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package dev.metaschema.core.metapath.item.atomic;
7   
8   import java.time.Duration;
9   import java.time.ZoneOffset;
10  
11  import dev.metaschema.core.metapath.function.DateTimeFunctionException;
12  import dev.metaschema.core.util.ObjectUtils;
13  import edu.umd.cs.findbugs.annotations.NonNull;
14  import edu.umd.cs.findbugs.annotations.Nullable;
15  
16  /**
17   * An atomic Metapath item containing a temporal data value.
18   */
19  public interface ITemporalItem extends IAnyAtomicItem {
20    /**
21     * Get the year value of this temporal.
22     *
23     * @return the year value
24     */
25    int getYear();
26  
27    /**
28     * Get the month value of this temporal.
29     *
30     * @return the month value
31     */
32    int getMonth();
33  
34    /**
35     * Get the day value of this temporal.
36     *
37     * @return the day value
38     */
39    int getDay();
40  
41    /**
42     * Get the hour value of this temporal.
43     *
44     * @return the hour value
45     */
46    int getHour();
47  
48    /**
49     * Get the minute value of this temporal.
50     *
51     * @return the minute value
52     */
53    int getMinute();
54  
55    /**
56     * Get the whole second value of this temporal.
57     *
58     * @return the whole second value
59     */
60    int getSecond();
61  
62    /**
63     * Get the partial nano second value of this temporal.
64     *
65     * @return the partial nano second value
66     */
67    int getNano();
68  
69    /**
70     * Get the timezone offset for this temporal.
71     *
72     * @return the timezone offset if specified or {@code null} if the timezone is
73     *         not known
74     * @see ITemporalItem#hasTimezone()
75     */
76    @Nullable
77    ZoneOffset getZoneOffset();
78  
79    /**
80     * Get the timezone offset as a day/time duration for this temporal.
81     *
82     * @return the timezone offset if specified or {@code null} if the timezone is
83     *         not known
84     * @see ITemporalItem#hasTimezone()
85     */
86    @Nullable
87    default IDayTimeDurationItem getOffset() {
88      ZoneOffset offset = getZoneOffset();
89      return offset == null
90          ? null
91          : IDayTimeDurationItem.valueOf(ObjectUtils.notNull(Duration.ofSeconds(offset.getTotalSeconds())));
92    }
93  
94    /**
95     * Determine if the temporal item has a timezone.
96     *
97     * @return {@code true} if the temporal item has a timezone or {@code false}
98     *         otherwise
99     */
100   boolean hasTimezone();
101 
102   /**
103    * Determine if the temporal has date information.
104    *
105    * @return {@code true} if the temporal item has date information or
106    *         {@code false} otherwise
107    */
108   boolean hasDate();
109 
110   /**
111    * Determine if the temporal has time information.
112    *
113    * @return {@code true} if the temporal item has time information or
114    *         {@code false} otherwise
115    */
116   boolean hasTime();
117 
118   /**
119    * Adjusts a temporal item value to a specific timezone, or to no timezone at
120    * all.
121    *
122    * @param offset
123    *          the timezone offset to use or {@code null}
124    * @return the adjusted temporal value
125    * @throws DateTimeFunctionException
126    *           with code
127    *           {@link DateTimeFunctionException#INVALID_TIME_ZONE_VALUE_ERROR} if
128    *           the offset is < -PT14H or > PT14H
129    */
130   @NonNull
131   ITemporalItem replaceTimezone(@Nullable IDayTimeDurationItem offset);
132 }