net.time4j.format.TextElement Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of time4j-core Show documentation
There is a newer version: 4.38
/*
 * -----------------------------------------------------------------------
 * Copyright © 2013-2015 Meno Hochschild, 
 * -----------------------------------------------------------------------
 * This file (TextElement.java) is part of project Time4J.
 *
 * Time4J is free software: You can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published
 * by the Free Software Foundation, either version 2.1 of the License, or
 * (at your option) any later version.
 *
 * Time4J is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with Time4J. If not, see .
 * -----------------------------------------------------------------------
 */

package net.time4j.format;

import net.time4j.engine.AttributeQuery;
import net.time4j.engine.ChronoDisplay;
import net.time4j.engine.ChronoElement;
import net.time4j.engine.ChronoException;

import java.io.IOException;
import java.text.ParsePosition;


/**
 * A chronological element which can be formatted as text or can be parsed
 * from a text. 
 *
 * @param    generic type of element values
 * @author  Meno Hochschild
 */
/*[deutsch]
 * Repräsentiert ein chronologisches Element, das als Text dargestellt
 * und interpretiert werden kann. 
 *
 * @param    generic type of element values
 * @author  Meno Hochschild
 */
public interface TextElement
    extends ChronoElement {

    //~ Methoden ----------------------------------------------------------

    /**
     * Converts the element value in given context to a formatted text. 
     *
     * Implementation note: The concrete element value is obtainable by the
     * expression {@link ChronoDisplay#get(ChronoElement) context.get(this)}.
     * 
     *
     * @param   context     time context with the value of this element
     * @param   buffer      format buffer any text output will be sent to
     * @param   attributes  query for control attributes
     * @throws  IOException if writing to buffer fails
     * @throws  ChronoException if there is no suitable element rule for evaluating the value
     */
    /*[deutsch]
     * Wandelt dieses im angegebenen Zeitwertkontext enthaltene Element zu
     * einem Text um. 
     *
     * Implementierungshinweis: Der konkrete Elementwert ist durch den
     * Ausdruck {@link ChronoDisplay#get(ChronoElement) context.get(this)}
     * gegeben. 
     *
     * @param   context     time context with the value of this element
     * @param   buffer      format buffer any text output will be sent to
     * @param   attributes  query for control attributes
     * @throws  IOException if writing to buffer fails
     * @throws  ChronoException if there is no suitable element rule for evaluating the value
     */
    void print(
        ChronoDisplay context,
        Appendable buffer,
        AttributeQuery attributes
    ) throws IOException, ChronoException;

    /**
     * Interpretes the given text as element value. 
     *
     * Implementation note: Any implementation will start first at the
     * position {@link ParsePosition#getIndex() status.getIndex()} and
     * either set the new position after successful parsing or return
     * {@code null} in case of error. 
     *
     * @param   text        text to be parsed
     * @param   status      current parsing position
     * @param   attributes  query for control attributes
     * @return  parsed element value or {@code null} if parsing
     *          was not successful
     */
    /*[deutsch]
     * Interpretiert den angegebenen Text ab einer bestimmten Position
     * als Elementwert. 
     *
     * Implementierungshinweis: Eine Implementierung wird den Text
     * erst ab der angegebenen Position {@link ParsePosition#getIndex()
     * status.getIndex()} auswerten und nach erfolgreicher Interpretierung
     * den Index neu setzen oder im Fehlerfall {@code null} zurückgeben.
     * 
     *
     * @param   text        text to be parsed
     * @param   status      current parsing position
     * @param   attributes  query for control attributes
     * @return  parsed element value or {@code null} if parsing
     *          was not successful
     */
    V parse(
        CharSequence text,
        ParsePosition status,
        AttributeQuery attributes
    );

}