【C#入門】DateTimeOffset.AddYears()メソッドの使い方を徹底解説

C#のDateTimeOffset.AddYears()メソッドは、現在のDateTimeOffsetインスタンスが表す日時に、指定した年数を加算した新しいDateTimeOffset値を返すメソッドです。元のインスタンスの値は変更されず、計算結果が新しいオブジェクトとして返される点に注意してください。

構文

AddYears()メソッドの構文は以下のとおりです。

public DateTimeOffset AddYears (int val);

引数valには、加算する年数を整数で指定します。負の値を指定すると、年数を減算（過去にさかのぼる）ことができます。

主な特徴

• 戻り値は新しいDateTimeOffsetインスタンス（元の値は不変）
• うるう年の2月29日に対して加算した場合、結果が存在しない日は2月28日に調整される
• 結果がDateTimeOffset.MinValue〜DateTimeOffset.MaxValueの範囲外になる場合、ArgumentOutOfRangeExceptionがスローされる

サンプル1：年数を加算する

まずは、AddYears()メソッドを使って年数を加算する基本的な例を見てみましょう。

using System;

public class Demo {
   public static void Main() {
      DateTimeOffset dateTimeOffset = new DateTimeOffset(2019, 06, 09, 8, 20, 10, new TimeSpan(-5, 0, 0));
      Console.WriteLine("DateTimeOffset（年数追加前）= {0}", dateTimeOffset);
      DateTimeOffset res = dateTimeOffset.AddYears(5);
      Console.WriteLine("DateTimeOffset（年数追加後）= {0}", res);
   }
}

実行結果

上記のコードを実行すると、以下のような出力が得られます。

DateTimeOffset（年数追加前）= 6/9/2019 8:20:10 AM -05:00
DateTimeOffset（年数追加後）= 6/9/2024 8:20:10 AM -05:00

この例では、2019年6月9日の日時に対してAddYears(5)を呼び出しているため、5年後の「2024年6月9日」が取得できています。オフセット（-05:00）や時刻部分はそのまま維持されていることも確認できます。

サンプル2：年数を減算する

次に、負の値を指定して年数を減算する例を見てみましょう。

using System;

public class Demo {
   public static void Main() {
      DateTimeOffset dateTimeOffset = new DateTimeOffset(2019, 06, 09, 8, 20, 10, new TimeSpan(-5, 0, 0));
      Console.WriteLine("DateTimeOffset（年数減算前）= {0}", dateTimeOffset);
      DateTimeOffset res = dateTimeOffset.AddYears(-3);
      Console.WriteLine("DateTimeOffset（年数減算後）= {0}", res);
   }
}

実行結果

上記のコードを実行すると、以下のような出力が得られます。

DateTimeOffset（年数減算前）= 6/9/2019 8:20:10 AM -05:00
DateTimeOffset（年数減算後）= 6/9/2016 8:20:10 AM -05:00

負の値「-3」を渡すことで、3年前の「2016年6月9日」の日時が正しく計算されています。

まとめ

DateTimeOffset.AddYears()メソッドを使えば、オフセット情報を保持したまま日時に年数を簡単に加算・減算できます。ポイントは以下の3つです。

• 正の値で未来へ、負の値で過去へ移動できる
• 元のインスタンスは変更されず、新しいインスタンスが返る（イミュータブルな設計）
• 有効範囲外の日時になるとArgumentOutOfRangeExceptionが発生するため、極端な年数の指定には注意が必要

同様のメソッドとして、月を加算するAddMonths()、日を加算するAddDays()なども用意されているので、用途に応じて使い分けるとよいでしょう。