001    /*
002     *  Copyright 2001-2005 Stephen Colebourne
003     *
004     *  Licensed under the Apache License, Version 2.0 (the "License");
005     *  you may not use this file except in compliance with the License.
006     *  You may obtain a copy of the License at
007     *
008     *      http://www.apache.org/licenses/LICENSE-2.0
009     *
010     *  Unless required by applicable law or agreed to in writing, software
011     *  distributed under the License is distributed on an "AS IS" BASIS,
012     *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     *  See the License for the specific language governing permissions and
014     *  limitations under the License.
015     */
016    package org.joda.time.format;
017    
018    import java.util.Locale;
019    
020    import org.joda.time.ReadWritablePeriod;
021    
022    /**
023     * Internal interface for parsing textual representations of time periods.
024     * <p>
025     * Application users will rarely use this class directly. Instead, you
026     * will use one of the factory classes to create a {@link PeriodFormatter}.
027     * <p>
028     * The factory classes are:<br />
029     * - {@link PeriodFormatterBuilder}<br />
030     * - {@link PeriodFormat}<br />
031     * - {@link ISOPeriodFormat}<br />
032     *
033     * @author Brian S O'Neill
034     * @author Stephen Colebourne
035     * @since 1.0
036     * @see PeriodFormatter
037     * @see PeriodFormatterBuilder
038     * @see PeriodFormat
039     */
040    public interface PeriodParser {
041    
042        /**
043         * Parses a period from the given text, at the given position, saving the
044         * result into the fields of the given ReadWritablePeriod. If the parse
045         * succeeds, the return value is the new text position. Note that the parse
046         * may succeed without fully reading the text.
047         * <p>
048         * If it fails, the return value is negative, but the period may still be
049         * modified. To determine the position where the parse failed, apply the
050         * one's complement operator (~) on the return value.
051         *
052         * @param period  a period that will be modified
053         * @param periodStr  text to parse
054         * @param position position to start parsing from
055         * @param locale  the locale to use for parsing
056         * @return new position, if negative, parse failed. Apply complement
057         * operator (~) to get position of failure
058         * @throws IllegalArgumentException if any field is out of range
059         */
060        int parseInto(ReadWritablePeriod period, String periodStr, int position, Locale locale);
061    
062    }