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    /**
019     * Internal interface for parsing textual representations of datetimes.
020     * <p>
021     * Application users will rarely use this class directly. Instead, you
022     * will use one of the factory classes to create a {@link DateTimeFormatter}.
023     * <p>
024     * The factory classes are:<br />
025     * - {@link DateTimeFormatterBuilder}<br />
026     * - {@link DateTimeFormat}<br />
027     * - {@link ISODateTimeFormat}<br />
028     *
029     * @author Brian S O'Neill
030     * @see DateTimeFormatter
031     * @see DateTimeFormatterBuilder
032     * @see DateTimeFormat
033     * @since 1.0
034     */
035    public interface DateTimeParser {
036    
037        /**
038         * Returns the expected maximum number of characters consumed.
039         * The actual amount should rarely exceed this estimate.
040         * 
041         * @return the estimated length
042         */
043        int estimateParsedLength();
044    
045        /**
046         * Parse an element from the given text, saving any fields into the given
047         * DateTimeParserBucket. If the parse succeeds, the return value is the new
048         * text position. Note that the parse may succeed without fully reading the
049         * text.
050         * <p>
051         * If it fails, the return value is negative. To determine the position
052         * where the parse failed, apply the one's complement operator (~) on the
053         * return value.
054         *
055         * @param bucket  field are saved into this, not null
056         * @param text  the text to parse, not null
057         * @param position  position to start parsing from
058         * @return new position, negative value means parse failed -
059         *  apply complement operator (~) to get position of failure
060         * @throws IllegalArgumentException if any field is out of range
061         */
062        int parseInto(DateTimeParserBucket bucket, String text, int position);
063    
064    }