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 */
016package org.joda.time.format;
017
018import java.util.Locale;
019
020import 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 */
040public 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}