net.time4j.IsoUnit 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-2014 Meno Hochschild, 
 * -----------------------------------------------------------------------
 * This file (IsoUnit.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;

import net.time4j.engine.ChronoUnit;


/**
 * Represents a unit suitable for timestamps which are compositions of
 * date and time ({@code PlainTimestamp}). 
 *
 * @author  Meno Hochschild
 */
/*[deutsch]
 * Repräsentiert eine für aus Datum und Uhrzeit zusammengesetzte
 * ISO-konforme Zeitstempel ({@code PlainTimestamp}) geeignete Zeiteinheit. 
 *
 * @author  Meno Hochschild
 */
public interface IsoUnit
    extends ChronoUnit {

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

    /**
     * Gets the format symbol which is used to display this time unit
     * in canonical representations of timespans. 
     *
     * Canonical timespan formats follow ISO-8601. For example, the day
     * unit is represented by the symbol D. Note that the letters P and T
     * must not be used because these special characters are for structuring,
     * the display. In ISO-8601 following symbols are defined: 
     *
     * 
     *  Y - year
     *  M - month or minute
     *  W - week
     *  D - day
     *  H - hour
     *  S - second
     *  P - qualifies a timespan (period)
     *  T - separates date and time part
     * 
     *
     * If this method yields as special case a digit 1-9 then Time4J expects
     * a fractional display of preceding second unit S that is nanoseconds,
     * microseconds and milliseconds. Time4J will use the comma as decimal
     * separation char in the canonical display as recommended by ISO-8601
     * unless the system property "net.time4j.format.iso.decimal.dot"
     * is set to {@code true} (which causes the usage of a dot). 
     *
     * @return  char (ASCII-NULL if undefined)
     * @see     Duration#toString()
     */
    /*[deutsch]
     * Liefert das Formatsymbol, mit dem diese Instanz in kanonischen
     * Darstellungen von Zeitspannen repräsentiert wird. 
     *
     * Kanonische Zeitspannenformate folgen dem ISO-Standard. Zum Beispiel
     * wird der Tag durch den Buchstaben D repräsentiert. Zu beachten ist,
     * daß die Buchstaben P und T hier nicht verwendet werden dürfen,
     * da sie die Darstellung strukturieren. Im ISO-8601-Format gilt: 
     *
     * 
     *  Y - Jahr (engl.: year)
     *  M - Monat oder Minute (engl.: month or minute)
     *  W - Woche (engl.: week)
     *  D - Tag (engl.: day)
     *  H - Stunde (engl.: hour)
     *  S - Sekunde (engl.: second)
     *  P - Qualifiziert eine Zeitspanne (englisch: period)
     *  T - Trennt Datums- und Uhrzeitanteil
     * 
     *
     * Liefert die Methode als Sonderfall eine Ziffer 1-9, dann erwartet
     * Time4J eine fraktionale Anzeige der vorangehenden Sekundenzeiteinheit S,
     * also Nanos, Mikros und Millisekunden. Als Dezimaltrennzeichen wird in
     * der kanonischen Darstellung wie im ISO-8601-Standard empfohlen dann das
     * Komma verwendet, es sei denn, über das Setzen der System-Property
     * "net.time4j.format.iso.decimal.dot" auf den Wert {@code true}
     * wurde ein Punkt verlangt. 
     *
     * @return  char (ASCII-NULL wenn undefiniert)
     * @see     Duration#toString()
     */
    char getSymbol();

}