Daty i czas: Klasa java.text.SimpleDateFormat (1)
Klasa java.text.SimpleDateFormat (1)
Klasa dziedzicząca po DateFormat. Obsługuje formatowanie i parsowanie dat z uwzględnieniem lokalizacji.
Klasa pozwala na tworzenie instancji klasy z użyciem własnego wzorca formatowania. Jednak dokumentacja zachęca do tworzenia instancji przy użyciu metod odziedziczonych: getTimeInstance, getDateInstance albo getDateTimeInstance, a następnie ustawienie wzorca formatowania przy użyciu metody applyPattern.
Tworzenie wzorca
Wzorzec jest łańcuchem znaków. Litery od A do Z i od a do z są interpretowane jako litery wzorca, chyba że są ujęte w pojedyncze cudzysłowy ‘a’. Wtedy nie są interpretowane lecz kopiowane. Wszystkie pozostałe znaki nie są interpretowane lecz są po prostu kopiowane.
Wykaz symboli wzorca
| Litera | Prezentowany składnik daty lub czasu | Typ | Przykład |
|---|---|---|---|
| G | era | tekst | AD, BC |
| y | rok | rok | 1996, 96 |
| Y | rok tygodniowy | rok | 2009, 09 |
| M | miesiąc w roku (zależny od kontekstu) | miesiąc | July, Jul, 07 |
| L | miesiąc w roku (standardowy) | miesiąc | July, Jul, 07 |
| w | tydzień w roku | liczba | 27 |
| W | tydzień w miesiącu | liczba | 2 |
| D | dzień roku | liczba | 189 |
| d | dzień miesiąca | iczba | 10 |
| F | dzień tygodnia w miesiącu | liczba | 2 |
| E | nazwa dnia tygodnia | tekst | Tuesday, Tue |
| u | numer dnia tygodnia (1=Monday,…,7=Sunday) | liczba | 1 |
| a | znacznik am/pm | tekst | AM, PM |
| H | godzina dnia (0-23) | numer | 1 |
| k | godzina dnia(1-24) | numer | 1-24 |
| K | godzina przedpołudniowa (am) (0-11) | liczba | 1 |
| h | godzina popołudniowa (pm)(1-12) | liczba | 11 |
| m | minuta w godzinie | liczba | 30 |
| s | sekunda w minucie | liczba | 55 |
| S | milisekunda | liczba | 978 |
| z | strefa czasowa | ogólna | Pacific Standard Time, PST, GMT-08:00 |
| Z | strefa czasowa | według RFC 8222 | -0800 |
| X | strefa czasowa | według ISO 8601 | -08, -0800, -08:00 |
Powtarzanie symboli wzorca
Symbole mogą być powtarzane, a liczba powtórzeń określa szczegóły prezentacji.
Tekst
Jeżeli litera wzorca powtarza się 4 razy lub więcej, używany jest format pełny, w innym przypadku używana jest skrócona forma, jeśli jest dostępna.
Liczba
Liczba liter wzorca określa minimalną liczbę cyfr. Do liczb zawierających mniej cyfr jest dodawana stosowna liczba zer wiodących. Przy parsowaniu liczba liter wzorca jest ignorowana, chyba że jest potrzebna do oddzielenia dwóch przyległych pól.
Rok
Jeśli używany jest kalendarz gregoriański to stosowane są następujące reguły:
- Przy formatowaniu, jeśli liczba liter wzorca równa się 2, rok jest obcinany do 2 cyfr. Inaczej litera wzorca oznacza zwykłą liczbę,
- przy parsowaniu – jeśli liczba liter wzorca jest większa od 2, rok jest interpretowany dokładnie, niezależnie od liczby cyfr
- Przy parsowaniu, jeśli użyto jednej lub dwu cyfr, rok jest uznany za względny w stosunku do pewnego stulecia.. Odniesieniem jest data utworzenia instancji klasy
SimpleDateFormat. Jeśli ta data to 1 stycznia 1997 to rok daty 01/11/12 będzie uznany za rok 2012. Obowiązuje zasada podkręcenia daty do 80 lat wstecz lub 20 lat naprzód w stosunku do daty utworzenia instancji klasy. Jeśli parsowany jest tylko string, a data zawiera 2 cyfry roku to przyjmowane jest stulecie domyślne. Wszystkie pozostałe liczby liter wzorca będą interpretowane dosłownie. Rok 3 albo 003 albo -3 będą interpretowane jako rok 3 n.e., rok 3 n.e, rok 4 p.n.e.
W przypadku innego kalendarza jeśli liczba liter wzorca wynosi 4 albo więcej to używana jest długa forma. W innym przypadku używane są specyficzne krótkie albo skrócone formy.
Jeśli użyto litery wzorca ‘Y’, a kalendarz nie umożliwia użycia roku tygodniowego, przyjmuje się, że użyto ‘y’.
Miesiąc
Jeśli liczba liter wzorca wynosi 3 lub więcej, miesiąc jest przedstawiany jako tekst, w przeciwnym przypadku jest przedstawiany jako liczba:
- litera M tworzy nazwy miesięcy zależne od kontekstu, na przykład wbudowane formy nazw.Jeśli obiekt klasy
DateFormatSymbolsbył podany jako parametr konstruktora obiektuSimpleDateFormatalbo wywołano metodęsetDateSymbols()z tym parametrem, to używane są nazwy miesięcy podane w obiekcieDateFormatSymbols. - Litera L oznacza standardowe, niekontekstowe nazwy miesięcy.
Ogólna strefa czasowa
Strefy czasowe – jeśli mają nazwy – są interpretowane jako tekst. Jeśli podane są jako offset od czasu GMT to używa się następującej składni:
- GMT znak godziny : minuty
- Znak oznacza ‘+’ albo ‘-‘
- Godziny podane są jako jedna albo jako dwie cyfry
- Minuty podane są jako dwie cyfry
- Cyfra oznacza jedną z cyfr 0 1 2 3 4 5 6 7 8 9
- Przykłady: GMT+1:00 , GMT+02:00, GMT-8:03, GMT-08:20
Strefa czasowa według RFC 822
Używana jest 4-cyfrowe oznakowanie strefy:
- Znak godziny minuty
- Znak oznacza ‘+’ albo ‘-‘
- Godzina podawana jest jako dwie cyfry od 00 do 23
- Cyfra oznacza jedną z cyfr 0 1 2 3 4 5 6 7 8 9
- Przykłady: +0100, +0200, -0803, -0820
Strefa czasowa według ISO 8601
Zostało omówione w rozdziale Norma ISO 8601:2004.
Jeśli przesunięcie od GMT wynosi 0, wstawiana jest litera ‘Z’.
Jeśli liczba liter wzorca strefy wynosi 1, frakcja godzin jest ignorowana
Przy parsowaniu ‘Z’ jest parsowane jako UTC. Ogólne strefy czasowe nie są akceptowane.
Uwagi
Formaty dat nie są synchronizowane. Dla każdego wątku powinna być utworzona oddzielna instancja. Jeśli wiele wątków ma współbieżnie dostęp do formatu, ten musi być synchronizowany zewnętrznie.
Przykłady z dokumentacji
| Date and Time Pattern | Result |
|---|---|
| "yyyy.MM.dd G ‘at’ HH:mm:ss z" | 2001.07.04 AD at 12:08:56 PDT |
| "EEE, MMM d, ”yy" | Wed, Jul 4, ’01 |
| "h:mm a" | 12:08 PM |
| "hh ‘o”clock’ a, zzzz" | 12 o’clock PM, Pacific Daylight Time |
| "K:mm a, z" | 0:08 PM, PDT |
| "yyyyy.MMMMM.dd GGG hh:mm aaa" | 02001.July.04 AD 12:08 PM |
| "EEE, d MMM yyyy HH:mm:ss Z" | Wed, 4 Jul 2001 12:08:56 -0700 |
| "yyMMddHHmmssZ" | 010704120856-0700 |
| "yyyy-MM-dd’T’HH:mm:ss.SSSZ" | 2001-07-04T12:08:56.235-0700 |
| "yyyy-MM-dd’T’HH:mm:ss.SSSXXX" | 2001-07-04T12:08:56.235-07:00 |
| "YYYY-‘W’ww-u" | 2001-W27-3 |