01: /*
02: * Copyright 2001-2005 Stephen Colebourne
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License");
05: * you may not use this file except in compliance with the License.
06: * You may obtain a copy of the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
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,
61: int position, Locale locale);
62:
63: }
|