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 }