モジュール java.base
パッケージ java.text

クラスSimpleDateFormat

java.lang.Object
java.text.Format
java.text.DateFormat
java.text.SimpleDateFormat
すべての実装されたインタフェース:
Serializable, Cloneable
public class SimpleDateFormat
extends DateFormat
SimpleDateFormatは、日付のフォーマットと解析を、ロケールを考慮して行うための具象クラスです。 フォーマット(日付→テキスト)、解析(テキスト→日付)および正規化を行うことができます。

SimpleDateFormatを使うと、日付時刻フォーマットのユーザー定義パターンを選択することによって、とりあえず使用を開始することができます。 しかし、できるだけ、DateFormatのgetTimeInstance、getDateInstance、またはgetDateTimeInstanceで日付時刻フォーマッタを作成するようにしてください。 これらのクラス・メソッドはいずれも、デフォルト・フォーマット・パターンで初期化された日付時刻フォーマッタを返すことができます。 フォーマット・パターンは、必要に応じて、applyPatternメソッドを使って修正することができます。 これらのメソッドの使い方については、DateFormatを参照してください。

日時パターン

日時フォーマットは日時パターン文字列で指定されます。 日時パターン文字列内では、引用符で囲まれていない'A' - 'Z'および'a' - 'z'は、日付または時間文字列のコンポーネントを表すパターン文字として解釈されます。 テキストは単一引用符(')で囲むことで解釈を回避できます。"''"は単一引用符を表します。 ほかのすべての文字は解釈されず、フォーマット中に出力文字列へ単純にコピーされるか、解析中に入力文字列に対して一致させられます。

次のパターン文字が定義されます(ほかの'A' - 'Z'および'a' - 'z'のすべての文字は予約済み)。

チャートはパターン文字、日付/時間コンポーネント、表示および例を示します。
文字 日付または時刻のコンポーネント 表示 例
G 紀元 Text AD
y 年 Year 1996; 96
Y 暦週の基準年 Year 2009; 09
M 年における月(状況依存) Month July; Jul; 07
L 年における月(スタンドアロン形式) Month July; Jul; 07
w 年における週 Number 27
W 月における週 Number 2
D 年における日 Number 189
d 月における日 Number 10
F 月における曜日 Number 2
E 曜日の名前 Text Tuesday; Tue
u 曜日の番号(1 =月曜、...、7 =日曜) Number 1
a 午前/午後 Text PM
H 一日における時(0 - 23) Number 0
k 一日における時(1 - 24) Number 24
K 午前/午後の時(0 - 11) Number 0
h 午前/午後の時(1 - 12) Number 12
m 分 Number 30
s 秒 Number 55
S ミリ秒 Number 978
z タイムゾーン 一般的なタイムゾーン Pacific Standard Time; PST; GMT-08:00
Z タイムゾーン RFC 822タイムゾーン -0800
X タイムゾーン ISO 8601タイムゾーン -08; -0800; -08:00
パターン文字は、その数で正確な表現が決まるため、通常繰り返されます。
  • テキスト: フォーマット時に、パターン文字の数が4以上の場合はフル形式を使用します。そうでない場合、短い形式または省略された形式があれば、それを使用します。 解析には、パターン文字の数値にかかわらず、どちらの形式も受け付けられます。
  • 数値: フォーマット時に、パターン文字の数は最小桁数です。これより短い数値は、この桁数までゼロ埋めされます。 解析には、2つの隣接するフィールドを区切る必要がないかぎり、パターン文字の数は無視されます。
  • 年:フォーマッタのCalendarがグレゴリオ暦の場合は、次に示すルールが適用されます。
    • パターン文字の数が2の場合、フォーマットには年が2桁に短縮されます。そうでない場合は、数値として解釈されます。
    • 解析には、パターン文字の数が2以上の場合、年は桁数にかかわらず文字どおりに解釈されます。 「MM/dd/yyyy」のパターンを用いると、「01/11/12」はA.D. 12年1月11日に解釈されます。
    • 短縮年パターン(「y」または「yy」)で解析するときは、SimpleDateFormatは特定の世紀に合わせて短縮年を解釈する必要があります。 この解釈は、SimpleDateFormatのインスタンスの生成前の80年以内から生成後の20年以内に日付を調整することによって行われます。 たとえば、「MM/dd/yy」のパターンと1997年1月1日に生成されたSimpleDateFormatのインスタンスを使うと、「01/11/12」という文字列は2012年1月11日と解釈され、「05/04/64」という文字列は1964年5月4日と解釈されます。 解析中は、Character.isDigit(char)で定義された2桁を含む文字列のみがデフォルトの世紀に解析されます。 1桁の文字列、3桁以上の文字列、あるいは数値以外を含む2桁の文字列(-1など)といったその他の数値文字列は、文字どおりに解釈されます。 つまり、同じパターンを用いて「01/02/3」または「01/02/003」を解析すると、A.D. 3年1月2日となります。 同様に、「01/02/-3」はB.C. 4年1月2日と解析されます。
    そうでない場合は、暦体系固有の形式が適用されます。 パターン文字の数が4以上の場合、フォーマットと解析の両方に、カレンダ固有の長い形式が使用されます。 そうでない場合は、カレンダ固有の短い形式または省略された形式が使用されます。

    暦週の基準年'Y'が指定され、カレンダが暦週の基準年をサポートしていない場合は、代わりにカレンダの年('y')が使用されます。     getCalendar().isWeekDateSupported()を呼び出すと、暦週の基準年のサポートをテストできます。
  • 月:パターン文字の数が3以上の場合、月はテキストとして解釈されます。そうでない場合は、数値として解釈されます。
    • 文字Mにより、埋込み形式の名前など、状況依存の月の名前が生成されます。 文字Mは、スタンドアロンのパターン、たとえば"MMMM"で使用される場合、スタンドアロン形式の月名を与え、それが他のフィールドを含むパターン(たとえば"d MMMM")で使用される場合、コンテキスト依存です。それは月の名前の書式形式を与える。 たとえば、ニア語の1月は、形式形式の"ジェネレーション"ですが、スタンドアロン形式の"gener"です。 この場合、"MMMM"は"gener"を生成し、"d MMMM"の月部分は"ジェネレーション"を生成します。 DateFormatSymbolsがコンストラクタSimpleDateFormat(String,DateFormatSymbols)またはメソッドsetDateFormatSymbols(DateFormatSymbols)を使用して明示的に設定されている場合、DateFormatSymbolsによって指定された月の名前が使用されます。
    • 文字Lによりスタンドアロン形式の月の名前が生成されます。

  • 一般的なタイムゾーン:タイムゾーンに名前がある場合、テキストとして解釈されます。 GMTオフセット値を表すタイムゾーンには、次の構文が使用されます。 
         GMTOffsetTimeZone:
             GMT Sign Hours : Minutes
     Sign: one of
             + -
     Hours:
             Digit
             Digit Digit
     Minutes:
             Digit Digit
     Digit: one of
             0 1 2 3 4 5 6 7 8 9
    時は0 - 23、分は00 - 59です。 フォーマットはロケールに依存せず、数字はUnicode標準のBasic Latinブロックの数字である必要があります。

    解析には、RFC 822タイムゾーンも受け入れられます。

  • RFC 822タイムゾーン:フォーマットには、RFC 822の4桁タイムゾーン形式が使用されます。 
         RFC822TimeZone:
             Sign TwoDigitHours Minutes
     TwoDigitHours:
             Digit Digit
    TwoDigitHoursは00 - 23です。 ほかの定義は一般的なタイムゾーンと同様です。

    解析には、一般的なタイムゾーンも受け入れられます。

  • ISO 8601タイムゾーン:以下のように、フォーマットと解析のフォーマットはどちらも、パターン文字の数で指定されます。 
         ISO8601TimeZone:
             OneLetterISO8601TimeZone
             TwoLetterISO8601TimeZone
             ThreeLetterISO8601TimeZone
     OneLetterISO8601TimeZone:
             Sign TwoDigitHours
             Z
     TwoLetterISO8601TimeZone:
             Sign TwoDigitHours Minutes
             Z
     ThreeLetterISO8601TimeZone:
             Sign TwoDigitHours : Minutes
             Z
    ほかの定義は一般的なタイムゾーンやRFC 822タイムゾーンと同様です。

    フォーマットでは、GMTからのオフセット値が0の場合に"Z"が生成されます。 パターン文字の数が1の場合は、1時間の端数は無視されます。 たとえば、パターンが"X"で、タイムゾーンが"GMT+05:30"の場合、"+05"が生成されます。

    解析では、UTCタイムゾーン指示子として"Z"が解析されます。 一般的なタイムゾーンは受け入れられません。

    パターン文字数が4以上の場合、 SimpleDateFormatを構築するかパターンを適用すると、IllegalArgumentExceptionがスローされます。

SimpleDateFormatはローカライズされた日時パターン文字列もサポートします。 この文字列では、前述したパターン文字はロケール依存のほかの文字パターンに置き換えられます。 SimpleDateFormatでは、パターン文字以外のテキストのローカリゼーションが処理されません。この処理はクラスのクライアント次第で決まります。

例

次の例に、U.S. ロケールで日時パターンがどのように解釈されるかを示します。 指定された日付と時刻はU.S. Pacific Timeタイムゾーンのローカル・タイム2001年7月4日12時8分56秒です。
U.S.ロケールで解釈された日時パターンの例
日時パターン 結果
"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

Synchronization

日付フォーマットは同期化されません。 スレッドごとに別のフォーマット・インスタンスを作成することをお薦めします。 複数のスレッドがフォーマットに並行してアクセスする場合は、外部的に同期化する必要があります。

導入されたバージョン:
1.1
関連項目:
Java Tutorial, Calendar, TimeZone, DateFormat, DateFormatSymbols, 直列化された形式

  • コンストラクタの詳細

    • SimpleDateFormat

      public SimpleDateFormat()
      デフォルトのFORMATロケールのデフォルト・パターンと日付フォーマット記号を使ってSimpleDateFormatを構築します。 ノート: このコンストラクタはすべてのロケールをサポートするわけではありません。 すべてをカバーするには、DateFormatクラスのファクトリ・メソッドを使用してください。

    • SimpleDateFormat

      public SimpleDateFormat​(String pattern)
      指定されたパターンとデフォルトのFORMATロケールのデフォルト日付フォーマット記号を使ってSimpleDateFormatを構築します。 ノート: このコンストラクタはすべてのロケールをサポートするわけではありません。 すべてをカバーするには、DateFormatクラスのファクトリ・メソッドを使用してください。

      これは、SimpleDateFormat(pattern, Locale.getDefault(Locale.Category.FORMAT))の呼び出しと同等です。

      パラメータ:
      pattern - 日付と時刻のフォーマットを記述するパターン
      例外:
      NullPointerException - 指定されたパターンがnullの場合
      IllegalArgumentException - 指定されたパターンが無効な場合
      関連項目:
      Locale.getDefault(java.util.Locale.Category)、Locale.Category.FORMAT

    • SimpleDateFormat

      public SimpleDateFormat​(String pattern, Locale locale)
      指定されたパターンと指定されたロケールのデフォルト日付フォーマット記号を使ってSimpleDateFormatを構築します。 ノート: このコンストラクタはすべてのロケールをサポートするわけではありません。 すべてをカバーするには、DateFormatクラスのファクトリ・メソッドを使用してください。
      パラメータ:
      pattern - 日付と時刻のフォーマットを記述するパターン
      locale - 日付フォーマット記号を使用するロケール
      例外:
      NullPointerException - 指定されたパターンまたはロケールがnullの場合
      IllegalArgumentException - 指定されたパターンが無効な場合

    • SimpleDateFormat

      public SimpleDateFormat​(String pattern, DateFormatSymbols formatSymbols)
      指定されたパターンと日付フォーマット記号を使ってSimpleDateFormatを構築します。
      パラメータ:
      pattern - 日付と時刻のフォーマットを記述するパターン
      formatSymbols - フォーマットに使用する日付フォーマット記号
      例外:
      NullPointerException - 指定されたパターンまたはformatSymbolsがnullの場合
      IllegalArgumentException - 指定されたパターンが無効な場合

  • メソッドの詳細

    • set2DigitYearStart

      public void set2DigitYearStart​(Date startDate)
      2桁年が属すると解釈される100年間をユーザーが指定する日付から始まるように設定します。
      パラメータ:
      startDate - 解析中、2桁年はstartDate - startDate+100 yearsの範囲に配置される。
      例外:
      NullPointerException - startDateがnullの場合。
      導入されたバージョン:
      1.2
      関連項目:
      get2DigitYearStart()

    • get2DigitYearStart

      public Date get2DigitYearStart()
      2桁年が属すると解釈される100年間の開始日付を返します。
      戻り値:
      2桁年が解析される100年間の始まり
      導入されたバージョン:
      1.2
      関連項目:
      set2DigitYearStart(java.util.Date)

    • format

      public StringBuffer format​(Date date, StringBuffer toAppendTo, FieldPosition pos)
      指定されたDateを日付/時間文字列にフォーマットし、指定されたStringBufferに結果を付加します。
      定義:
      format、クラス: DateFormat
      パラメータ:
      date - 日付/時間文字列にフォーマットする日付/時間値。
      toAppendTo - 新しい日付/時間テキストを付加する位置。
      pos - 返された文字列内のフィールドの位置を追跡します。 例えば、日時テキスト"1996.07.10 AD at 15:08:56 PDT"が与えられている場合、与えられたfieldPositionがDateFormat.YEAR_FIELDであれば、fieldPositionのbegin indexとend indexはそれぞれ0と4に設定されます。 同じ日付/時間フィールドがパターン内に複数回現れた場合、その日時フィールドが最初に出現するようにfieldPositionが設定されます。 たとえば、パターン"h a z (zzzz)"とフィールドDateFormat.TIMEZONE_FIELDを使用してDateを日付時間文字列"1 PM PDT (Pacific Daylight Time)"にフォーマットすると、fieldPositionのbeginインデックスとendインデックスは、タイムゾーン・パターン文字の最初のオカレンスに対してそれぞれ5と8に設定されます'z'。
      戻り値:
      フォーマットされた日付/時間文字列。
      例外:
      NullPointerException - いずれかのパラメータがnullの場合。

    • formatToCharacterIterator

      public AttributedCharacterIterator formatToCharacterIterator​(Object obj)
      Objectをフォーマットし、AttributedCharacterIteratorを生成します。 返されたAttributedCharacterIteratorを使用すると、結果のStringを構築できるとともに、結果のStringについての情報を判定できます。

      AttributedCharacterIteratorの各属性キーはDateFormat.Field型です。対応する属性値は属性キーと同一です。

      オーバーライド:
      formatToCharacterIterator、クラス: Format
      パラメータ:
      obj - フォーマットするオブジェクト
      戻り値:
      フォーマットされた値を説明するAttributedCharacterIterator。
      例外:
      NullPointerException - objがnullの場合。
      IllegalArgumentException - 指定されたオブジェクトをFormatでフォーマットできない場合、またはFormatのパターン文字列が無効な場合。
      導入されたバージョン:
      1.4

    • parse

      public Date parse​(String text, ParsePosition pos)
      文字列からテキストを解析してDateを生成します。

      メソッドはposによって指定されたインデックスを開始位置としてテキストの解析を試みます。 解析が完了すると、posのインデックスは、使用された最後の文字(解析では、文字列の最後までのすべての文字が使用されるとは限らない)のあとのインデックスに更新され、解析された日付が返されます。 更新されたposは、このメソッドの次の呼出しの開始点を示すのに使用できます。 エラーが発生した場合は、posのインデックスは変更されず、エラーが発生した文字のインデックスにposのエラー・インデックスが設定され、nullが返されます。

      この解析操作は、calendarを使用してDateを生成します。 calendarの日付時間フィールドはすべて解析前のclearedであり、日付時間フィールドのcalendarデフォルト値は、欠落している日付時間情報に使用されます。 たとえば、解析操作によって年の値が取得されない場合、解析されたDateの年の値は、GregorianCalendarを使って1970となります。 textに指定されたパターンやタイムゾーンによっては、 TimeZoneの値が上書きされる可能性があります。 さらに操作を行うには、setTimeZoneの呼出しによってすでに設定されている TimeZone値の復元が必要になることもあります。

      定義:
      parse、クラス: DateFormat
      パラメータ:
      text - 部分的に解析されるString。
      pos - 上記のインデックスおよびエラー・インデックス情報を持つParsePositionオブジェクト
      戻り値:
      文字列から解析されるDate。 エラーの場合はnullを返す。
      例外:
      NullPointerException - textまたはposがnullの場合。

    • toPattern

      public String toPattern()
      この日付フォーマットを記述するパターン文字列を返します。
      戻り値:
      この日付フォーマットを記述するパターン文字列。

    • toLocalizedPattern

      public String toLocalizedPattern()
      この日付フォーマットのローカライズされたパターン文字列を返します。
      戻り値:
      この日付フォーマットを記述するローカライズされたパターン文字列。

    • applyPattern

      public void applyPattern​(String pattern)
      指定されたパターン文字列を、この日付フォーマットに適用します。
      パラメータ:
      pattern - この日付フォーマットのための新しい日付と時刻のパターン
      例外:
      NullPointerException - 指定されたパターンがnullの場合
      IllegalArgumentException - 指定されたパターンが無効な場合

    • applyLocalizedPattern

      public void applyLocalizedPattern​(String pattern)
      指定されたローカライズされたパターン文字列を、この日付フォーマットに適用します。
      パラメータ:
      pattern - このフォーマットの新しい日付と時刻のフォーマット・パターンにマップするString
      例外:
      NullPointerException - 指定されたパターンがnullの場合
      IllegalArgumentException - 指定されたパターンが無効な場合

    • getDateFormatSymbols

      public DateFormatSymbols getDateFormatSymbols()
      この日付フォーマットの、日付と時刻のフォーマット記号のコピーを取得します。
      戻り値:
      この日付フォーマットの、日付と時刻のフォーマット記号
      関連項目:
      setDateFormatSymbols(java.text.DateFormatSymbols)

    • setDateFormatSymbols

      public void setDateFormatSymbols​(DateFormatSymbols newFormatSymbols)
      この日付フォーマットの、日付と時刻のフォーマット記号を設定します。
      パラメータ:
      newFormatSymbols - 新しい日付と時刻のフォーマット記号
      例外:
      NullPointerException - 指定されたnewFormatSymbolsがnullの場合
      関連項目:
      getDateFormatSymbols()

    • clone

      public Object clone()
      このSimpleDateFormatのコピーを作成します。 また、フォーマットの日付フォーマット記号を複製します。
      オーバーライド:
      clone、クラス: DateFormat
      戻り値:
      このSimpleDateFormatの複製
      関連項目:
      Cloneable

    • hashCode

      public int hashCode()
      このSimpleDateFormatオブジェクトのハッシュ・コード値を返します。
      オーバーライド:
      hashCode、クラス: DateFormat
      戻り値:
      このSimpleDateFormatオブジェクトのハッシュ・コード値。
      関連項目:
      Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

    • equals

      public boolean equals​(Object obj)
      指定されたオブジェクトとこのSimpleDateFormatが等しいかどうかを比較します。
      オーバーライド:
      equals、クラス: DateFormat
      パラメータ:
      obj - 比較対象の参照オブジェクト。
      戻り値:
      指定されたオブジェクトがこのSimpleDateFormatと等しい場合はtrue
      関連項目:
      Object.hashCode()、HashMap