Java Date and Time API¶

• 目次
• Java Date and Time API
  • はじめに
  • 使い方メモ
    • ローカルタイムのみを扱う場合
      • LocalDate
      • 2つの日付の間の長さ
    • 各国で使用する時刻を扱う場合
      • 時差とタイムゾーン
      • タイムゾーンを扱うZoneIdクラス
      • 時差を扱うZoneOffsetクラス
      • OffsetDateTimeクラス
      • ZonedDateTimeクラス
      • 2つの日時の間の長さ
    • UTCとのオフセットで時刻を扱う場合
    • Instantクラス
      • 使用例
  • APIの実装
    • Instant
      • Instant.now
    • LocalTime
      • LocalTime.now

はじめに¶

Java Date and Times APIは、Java SE 8から標準化された日時に関する新しいAPIです。それまでのjava.util.Dateクラスおよびjava.util.Calendarクラスを刷新することが目的です。

使い方メモ¶

ローカルタイムのみを扱う場合¶

時差や、サマータイム制などを考慮しなくてもいい場合は、LocalDate、LocalTime、またはLocalDateTimeを使って日付、時刻を扱うことができます。

LocalDate¶

時分秒は含まず日付（年月日）を表現します。誕生日とか記念日、開催日などで時分秒を問わない情報を表現するのに有用です。

生成¶

LocalDate today = LocalDate.now(); // プログラムを実行した日
LocalDate theDay = LocalDate.of(2016, 1, 6); // 2016年1月6日
LocalDate theOtherDay = LocalDate.of(2015, Month.DECEMBER, 25); // 2015年12月25日、月をenum型で指定

LocalDateはイミュータブルオブジェクトとして設計されています。一度インスタンスを生成したらその値を変えることができません。

年、月、日の値の取り出し¶

int year = today.getYear();              // 年の値の取り出し
int monthValue = today.getMonthValue();  // 月の値の取り出し
int day = today.getDayOfMonth();         // 日の値の取り出し
Month month = today.getMonth();  // enum型で月を取り出し

2つの日付の間の長さ¶

期間¶

年、月、日単位である時刻と別な時刻との間の長さを表すPeriodを使います。

Period period = Period.between(theOtherDay, theDay);
int days = period.getDays();

時間¶

ある時刻（時分秒）と、別な時刻との間の長さをChronoUnitで表現します。
長さを時間単位で表現する場合は、ChronoUnit.HOURS を使います。

LocalDateTime now = LocalDateTime.now();
LocalDateTime closing = LocalDateTime.of(2016, 1, 9, 23, 59);

long hours = ChronoUnit.HOURS.between(now, closing);

各国で使用する時刻を扱う場合¶

時刻は、たいてい国ごと、あるいは地域ごとにそれぞれの標準時を定めています。日本であれば、日本標準時がそれにあたります。
UTC（協定世界時）と地方時との時差（オフセット）や、夏時間などの考慮が含まれるタイムゾーンを用いて地域ごとの標準時を扱います。

• UTCからの時差のみで扱うOffsetDateTime、OffsetTimeクラス
• タイムゾーンを扱うZonedDateTimeクラス

時差とタイムゾーン¶

• 時差とタイムゾーンを扱うZoneIdクラス
• 時差を扱うZoneOffset

タイムゾーンを扱うZoneIdクラス¶

tz databaseで扱う地域名/地名でタイムゾーンを表します。
日本標準時のタイムゾーンは、地域名/地名に "Asia/Tokyo"を指定してZonedDateTimeインスタンスを生成します。

var tokyo = ZoneId.of("Asia/Tokyo");
var time = ZonedDateTime.of(2023, 9, 18, 17, 45, 0, tokyo); // 年月日時分秒、ナノ秒とタイムゾーンを指定

日本時間ではサマータイムが今はないので、時差のみを扱うZoneOffsetと大きな差異はありませんが、夏時間を採用している欧米などの時刻を扱うときは、このZoneIdが必要になります。

地域名/地名の指定以外に、3文字のタイムゾーンコード（例：JST、BST、PST）を指定する方法もあります。
var tokyo = ZoneId.of("JST", ZoneId.SHORT_IDS);

時差を扱うZoneOffsetクラス¶

UTCからの時差のみを扱います。
var tokyo = ZoneOffset.of("+09:00");

UTCそのものを指定する、ZoneOffset.UTCもあります。

OffsetDateTimeクラス¶

時差を扱う日付時刻クラスです。

ZonedDateTimeクラス¶

2つの日時の間の長さ¶

UTCとのオフセットで時刻を扱う場合¶

UTCとの時刻差を考慮した時刻を扱う場合に、OffsetDateTime、OffsetTimeクラスが使えます。

Instantクラス¶

時刻系の上の単一点を表現します。
エポック（1970-01-01T00:00:00Z）を起点とする経過秒数と、ナノ秒を保持します。UTC時刻とほぼ同じとなります。

使用例¶

• 今の瞬間の Instant 生成
  Instant.now()
• テキスト文字から Instant 生成
  Instant.parse("2023-09-17T09:00:00Z")
• LocalDateTimeから Instant 生成
  LocalDateTimeはUTCに対するオフセット情報を持たないので、変換メソッドにゾーンオフセットを追加指定します。
  

  var now = LocalDateTime.now();
  var instant = now.toInstant(ZoneOffset.of("+09:00"));
  

APIの実装¶

Instant¶

Instant.now¶

Instant.now()
  Cloclk.systemUTC()
    new SystemClock(ZoneOffset.UTC)    
    SystemClock#instant()
      SystemClock#millis()
        System.currentTimeMillis()  *1
      Instant.ofEpochMillis(*1)
        Math.floorDiv  *2
        Math.floorMod  *3
        Instant#create(*2, *3)
          new Instant(*2, *3)

LocalTime¶

LocalTime.now¶

LocalTime.now()
  Clock.systemDefaultZone()
    ZoneId.systemDefault()
      TimeZone.getDefault()
        TimeZone.getDefaultRf()
        Timezone#clone()
      TimeZone#toZoneId()
        ZoneId.of(*, ZoneId.SHORT_IDS)
    new SystemClock(*)
  LocalTime.now(*)
    Clock.system(*)
      new SystemClock(*)
    LocalTime.now(*)
      Clock#instant()
      Clock#getZone()
      getRules()
      getOffset(*)
      Math.floorMod
      ofNanoOfDay()