View Javadoc

1   /*
2    *  Copyright 2001-2005 Stephen Colebourne
3    *
4    *  Licensed under the Apache License, Version 2.0 (the "License");
5    *  you may not use this file except in compliance with the License.
6    *  You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *  Unless required by applicable law or agreed to in writing, software
11   *  distributed under the License is distributed on an "AS IS" BASIS,
12   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *  See the License for the specific language governing permissions and
14   *  limitations under the License.
15   */
16  package org.joda.time.format;
17  
18  import java.util.Locale;
19  
20  import org.joda.time.ReadWritablePeriod;
21  
22  /**
23   * Internal interface for parsing textual representations of time periods.
24   * <p>
25   * Application users will rarely use this class directly. Instead, you
26   * will use one of the factory classes to create a {@link PeriodFormatter}.
27   * <p>
28   * The factory classes are:<br />
29   * - {@link PeriodFormatterBuilder}<br />
30   * - {@link PeriodFormat}<br />
31   * - {@link ISOPeriodFormat}<br />
32   *
33   * @author Brian S O'Neill
34   * @author Stephen Colebourne
35   * @since 1.0
36   * @see PeriodFormatter
37   * @see PeriodFormatterBuilder
38   * @see PeriodFormat
39   */
40  public interface PeriodParser {
41  
42      /**
43       * Parses a period from the given text, at the given position, saving the
44       * result into the fields of the given ReadWritablePeriod. If the parse
45       * succeeds, the return value is the new text position. Note that the parse
46       * may succeed without fully reading the text.
47       * <p>
48       * If it fails, the return value is negative, but the period may still be
49       * modified. To determine the position where the parse failed, apply the
50       * one's complement operator (~) on the return value.
51       *
52       * @param period  a period that will be modified
53       * @param periodStr  text to parse
54       * @param position position to start parsing from
55       * @param locale  the locale to use for parsing
56       * @return new position, if negative, parse failed. Apply complement
57       * operator (~) to get position of failure
58       * @throws IllegalArgumentException if any field is out of range
59       */
60      int parseInto(ReadWritablePeriod period, String periodStr, int position, Locale locale);
61  
62  }