hunt.time.temporal.TemporalQuery source code

1 /*
2  * hunt-time: A time library for D programming language.
3  *
4  * Copyright (C) 2015-2018 HuntLabs
5  *
6  * Website: https://www.huntlabs.net/
7  *
8  * Licensed under the Apache-2.0 License.
9  *
10  */
11 
12 module hunt.time.temporal.TemporalQuery;
13 
14 import hunt.time.Exceptions;
15 import hunt.time.temporal.TemporalAccessor;
16 /**
17  * Strategy for querying a temporal object.
18  * !(p)
19  * Queries are a key tool for extracting information from temporal objects.
20  * They exist to externalize the process of querying, permitting different
21  * approaches, as per the strategy design pattern.
22  * Examples might be a query that checks if the date is the day before February 29th
23  * _in a leap year, or calculates the number of days to your next birthday.
24  * !(p)
25  * The {@link TemporalField} interface provides another mechanism for querying
26  * temporal objects. That interface is limited to returning a {@code long}.
27  * By contrast, queries can return any type.
28  * !(p)
29  * There are two equivalent ways of using a {@code TemporalQuery}.
30  * The first is to invoke the method on this interface directly.
31  * The second is to use {@link TemporalAccessor#query(TemporalQuery)}:
32  * !(pre)
33  *   // these two lines are equivalent, but the second approach is recommended
34  *   temporal = thisQuery.queryFrom(temporal);
35  *   temporal = temporal.query(thisQuery);
36  * </pre>
37  * It is recommended to use the second approach, {@code query(TemporalQuery)},
38  * as it is a lot clearer to read _in code.
39  * !(p)
40  * The most common implementations are method references, such as
41  * {@code LocalDate.from} and {@code ZoneId::from}.
42  * Additional common queries are provided as static methods _in {@link TemporalQueries}.
43  *
44  * @implSpec
45  * This interface places no restrictions on the mutability of implementations,
46  * however immutability is strongly recommended.
47  *
48  * @param !(R) the type returned from the query
49  *
50  * @since 1.8
51  */
52 // @FunctionalInterface
53 public interface TemporalQuery(R) {
54 
55     /**
56      * Queries the specified temporal object.
57      * !(p)
58      * This queries the specified temporal object to return an object using the logic
59      * encapsulated _in the implementing class.
60      * Examples might be a query that checks if the date is the day before February 29th
61      * _in a leap year, or calculates the number of days to your next birthday.
62      * !(p)
63      * There are two equivalent ways of using this method.
64      * The first is to invoke this method directly.
65      * The second is to use {@link TemporalAccessor#query(TemporalQuery)}:
66      * !(pre)
67      *   // these two lines are equivalent, but the second approach is recommended
68      *   temporal = thisQuery.queryFrom(temporal);
69      *   temporal = temporal.query(thisQuery);
70      * </pre>
71      * It is recommended to use the second approach, {@code query(TemporalQuery)},
72      * as it is a lot clearer to read _in code.
73      *
74      * @implSpec
75      * The implementation must take the input object and query it.
76      * The implementation defines the logic of the query and is responsible for
77      * documenting that logic.
78      * It may use any method on {@code TemporalAccessor} to determine the result.
79      * The input object must not be altered.
80      * !(p)
81      * The input temporal object may be _in a calendar system other than ISO.
82      * Implementations may choose to document compatibility with other calendar systems,
83      * or reject non-ISO temporal objects by {@link TemporalQueries#chronology() querying the chronology}.
84      * !(p)
85      * This method may be called from multiple threads _in parallel.
86      * It must be thread-safe when invoked.
87      *
88      * @param temporal  the temporal object to query, not null
89      * @return the queried value, may return null to indicate not found
90      * @throws DateTimeException if unable to query
91      * @throws ArithmeticException if numeric overflow occurs
92      */
93     R queryFrom(TemporalAccessor temporal);
94 
95 }