001/*
002 * Licensed under the Apache License, Version 2.0 (the "License");
003 * you may not use this file except in compliance with the License.
004 * You may obtain a copy of the License at
005 *
006 *     http://www.apache.org/licenses/LICENSE-2.0
007 *
008 * Unless required by applicable law or agreed to in writing, software
009 * distributed under the License is distributed on an "AS IS" BASIS,
010 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011 * See the License for the specific language governing permissions and
012 * limitations under the License.
013 */
014package org.gbif.common.parsers.date;
015
016import org.gbif.common.parsers.core.Parsable;
017import org.gbif.common.parsers.core.ParseResult;
018
019import java.time.temporal.TemporalAccessor;
020
021import javax.annotation.Nullable;
022
023/**
024 * Main interface for date/time parsing based.
025 */
026public interface TemporalParser extends Parsable<TemporalAccessor> {
027
028  /**
029   * Parse a date represented as a single String into a TemporalAccessor.
030   *
031   * @param input
032   * @return result, never null
033   */
034  @Override
035  ParseResult<TemporalAccessor> parse(String input);
036
037  /**
038   * Parse a String date <em>restricted to the <code>ordering</code> provided</em>.
039   *
040   * Set a general date ordering for the parsing.  For example, DMY will support both 14.08.2020 and
041   * 14/08/2020, but <em>not</em> 2020-08-14 or 08/14/2020.
042   *
043   * NOTE, this behaviour <strong>differs</strong> from {@link #parse(String, DateComponentOrdering[])}.
044   *
045   * @param ordering required date ordering.
046   * @return result, never null
047   */
048  ParseResult<TemporalAccessor> parse(String input, @Nullable DateComponentOrdering ordering);
049
050  /**
051   * Parse a String date to a TemporalAccessor, attempting unambiguous formats and the
052   * <code>orderings</code> provided.
053   *
054   * The date 2020-08-14 will always parse.  An <code>ordering</code> of DMY_FORMATS will also
055   * support 14.08.2020, 14/08/2020 and 14/08/2020 14:11:00, but not 08/14/2020.
056   *
057   * NOTE, this behaviour <strong>differs</strong> from {@link #parse(String, DateComponentOrdering)}.
058   *
059   * @param orderings required general date orderings
060   * @return result, never null
061   */
062  ParseResult<TemporalAccessor> parse(String input, @Nullable DateComponentOrdering[] orderings);
063
064  /**
065   * Parse year, month, day strings as a TemporalAccessor.
066   *
067   * @param year numerical value of a year
068   * @param month value of the mont depending on the implementation, numerical value of a
069   *              month (starting at 1 for January) or possibly text.
070   * @param day numerical value of a day
071   * @return result, never null
072   */
073  ParseResult<TemporalAccessor> parse(@Nullable String year, @Nullable String month, @Nullable String day);
074
075  /**
076   * Parse year, month, day integers as a TemporalAccessor.
077   *
078   * @param year numerical value of a year
079   * @param month numerical value of a month (starting at 1 for January)
080   * @param day numerical value of a day
081   * @return result, never null
082   */
083  ParseResult<TemporalAccessor> parse(@Nullable Integer year, @Nullable Integer month, @Nullable Integer day);
084
085  /**
086   * Parse year, dayOfYear strings as a TemporalAccessor.
087   *
088   * @param year numerical value of a year
089   * @param dayOfYear numerical value of a day of the year
090   * @return result, never null
091   */
092  ParseResult<TemporalAccessor> parse(@Nullable String year, @Nullable String dayOfYear);
093
094  /**
095   * Parse year, dayOfYear integers as a TemporalAccessor.
096   *
097   * @param year numerical value of a year
098   * @param dayOfYear numerical value of a day of the year
099   * @return result, never null
100   */
101  ParseResult<TemporalAccessor> parse(@Nullable Integer year, @Nullable Integer dayOfYear);
102}