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 }