この記事の英語版を表示するには、[英語] のチェック ボックスをオンにしてください。また、テキストにマウス ポインターを合わせると、ポップアップ ウィンドウに英語のテキストを表示することもできます。
翻訳
英語

DateTimeOffset オブジェクトのインスタンス化

 

DateTimeOffset 構造体は DateTimeOffset 新しい値を作成する方法を示します。 大部分の方法は、新しい DateTime 値のインスタンス化に利用できるメソッドに直接対応しています。このメソッドには拡張が施されており、世界協定時刻 (UTC: Coordinated Universal Time) からの日付と時刻の値のオフセットを指定できます。 具体的には、次の方法を使用して DateTimeOffset 値をインスタンス化できます。

  • 日付リテラルと時刻リテラルを使用する。

  • DateTimeOffset コンストラクターを呼び出す。

  • 値を DateTimeOffset 値に暗黙に変換する。

  • 日付と時刻の文字列形式を解析する。

このトピックでは、これらの方法を使用して新しい DateTimeOffset 値をインスタンス化する方法を詳述し、コード例を示します。

DateTime 値をインスタンス化する最も一般的な方法は、日付と時刻を、ハードコーディングされたリテラル値としてインスタンス化することです (言語がサポートしている場合)。 たとえば、次の Visual Basic コードは、値が 2008 年 1 月 1 日午前 10 時を示す DateTime オブジェクトを作成します。

Dim literalDate1 As Date = #05/01/2008 8:06:32 AM#
Console.WriteLine(literalDate1.ToString() )
' Displays:
'              5/1/2008 8:06:32 AM

DateTime リテラルをサポートする言語を使用する場合は、日付リテラルと時刻リテラルを使用して DateTimeOffset 値を初期化することもできます。 たとえば、次の Visual Basic コードは、DateTimeOffset オブジェクトを作成します。

Dim literalDate As DateTimeOffset = #05/01/2008 8:06:32 AM#
Console.WriteLine(literalDate.ToString() )
' Displays:
'              5/1/2008 8:06:32 AM -07:00

ファイルの出力を見てわかるように、この方法で作成した DateTimeOffset 値には、ローカル タイム ゾーンのオフセットが割り当てられます。 これは、文字リテラルを使用して割り当てられた DateTimeOffset 値は、コードが別のコンピューターで実行されると、単一の時点の時刻を指すものではないことを意味しています。

DateTimeOffset 型は、6 つのコンストラクターを定義します。 そのうちの 4 つは、DateTime コンストラクターに直接対応し、UTC からの日付と時刻のオフセットを定義する型 TimeSpan の追加のパラメーターを提供します。 これにより、日付と時刻に関する各コンポーネントの値に基づいて、DateTimeOffset 値を定義できます。 たとえば、次のコードでは 4 つのコンストラクターを使用して、7/1/2008 12:05 AM +01:00 という同一の値を持つ DateTimeOffset オブジェクトをインスタンス化します。

DateTimeOffset dateAndTime;

// Instantiate date and time using years, months, days, 
// hours, minutes, and seconds
dateAndTime = new DateTimeOffset(2008, 5, 1, 8, 6, 32, 
                                 new TimeSpan(1, 0, 0));
Console.WriteLine(dateAndTime);
// Instantiate date and time using years, months, days,
// hours, minutes, seconds, and milliseconds
dateAndTime = new DateTimeOffset(2008, 5, 1, 8, 6, 32, 545, 
                                 new TimeSpan(1, 0, 0));
Console.WriteLine("{0} {1}", dateAndTime.ToString("G"), 
                             dateAndTime.ToString("zzz"));

// Instantiate date and time using Persian calendar with years,
// months, days, hours, minutes, seconds, and milliseconds
dateAndTime = new DateTimeOffset(1387, 2, 12, 8, 6, 32, 545, 
                                 new PersianCalendar(), 
                                 new TimeSpan(1, 0, 0));
// Note that the console output displays the date in the Gregorian
// calendar, not the Persian calendar. 
Console.WriteLine("{0} {1}", dateAndTime.ToString("G"), 
                             dateAndTime.ToString("zzz"));

// Instantiate date and time using number of ticks
// 05/01/2008 8:06:32 AM is 633,452,259,920,000,000 ticks
dateAndTime = new DateTimeOffset(633452259920000000, new TimeSpan(1, 0, 0));  
Console.WriteLine(dateAndTime);
// The example displays the following output to the console:
//       5/1/2008 8:06:32 AM +01:00
//       5/1/2008 8:06:32 AM +01:00
//       5/1/2008 8:06:32 AM +01:00
//       5/1/2008 8:06:32 AM +01:00

コンストラクターに対する引数の 1 つである、PersianCalendar オブジェクトを使用してインスタンス化した DateTimeOffset オブジェクトの値は、コンソールにはペルシャ暦ではなくグレゴリオ暦として表示されることに注意してください。 ペルシャ暦を使用した日付を出力するには、トピック「PersianCalendar」にある例を参照してください。

残りの 2 つのコンストラクターは、DateTime 値から DateTimeOffset オブジェクトを作成します。 このうちの 1 つのコンストラクターには、1 つのパラメーターがあります。このパラメーターを使用して、DateTime 値を DateTimeOffset 値に変換します。 結果として得られる DateTimeOffset 値のオフセットは、コンストラクターの単一のパラメーターの Kind プロパティに依存します。 その値が DateTimeKind.Utc である場合、オフセットは TimeSpan.Zero と等しい値に設定されます。 それ以外の場合は、オフセットはローカル タイム ゾーンの値と等しい値に設定されます。 次に、このコンストラクターを使用して、UTC およびローカル タイム ゾーンを表す DateTimeOffset オブジェクトをインスタンス化する例を示します。

// Declare date; Kind property is DateTimeKind.Unspecified
DateTime sourceDate = new DateTime(2008, 5, 1, 8, 30, 0);
DateTimeOffset targetTime;

// Instantiate a DateTimeOffset value from a UTC time 
DateTime utcTime = DateTime.SpecifyKind(sourceDate, DateTimeKind.Utc);
targetTime = new DateTimeOffset(utcTime);
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM +00:00
// Because the Kind property is DateTimeKind.Utc, 
// the offset is TimeSpan.Zero.

// Instantiate a DateTimeOffset value from a UTC time with a zero offset
targetTime = new DateTimeOffset(utcTime, TimeSpan.Zero);
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM +00:00
// Because the Kind property is DateTimeKind.Utc, 
// the call to the constructor succeeds

// Instantiate a DateTimeOffset value from a UTC time with a negative offset
try
{
   targetTime = new DateTimeOffset(utcTime, new TimeSpan(-2, 0, 0));
   Console.WriteLine(targetTime);
}
catch (ArgumentException)
{
   Console.WriteLine("Attempt to create DateTimeOffset value from {0} failed.", 
                      targetTime);
}   
// Throws exception and displays the following to the console:
//   Attempt to create DateTimeOffset value from 5/1/2008 8:30:00 AM +00:00 failed.

// Instantiate a DateTimeOffset value from a local time
DateTime localTime = DateTime.SpecifyKind(sourceDate, DateTimeKind.Local);
targetTime = new DateTimeOffset(localTime);
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM -07:00
// Because the Kind property is DateTimeKind.Local, 
// the offset is that of the local time zone.

// Instantiate a DateTimeOffset value from an unspecified time
targetTime = new DateTimeOffset(sourceDate);
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM -07:00
// Because the Kind property is DateTimeKind.Unspecified, 
// the offset is that of the local time zone.
System_CAPS_noteメモ

単一の DateTime パラメーターを持つ DateTimeOffset コンストラクターのオーバーロードを呼び出すことは、DateTime 値の DateTimeOffset 値への暗黙の変換を実行することと同じです。

残りの 2 つのコンストラクターのうち、もう 1 つのコンストラクターは、DateTime 値から DateTimeOffset オブジェクトを作成します。この値には、変換する値である DateTime と、UTC からの日付と時刻のオフセットを表す TimeSpan の 2 つのパラメーターがあります。 このオフセット値は、コンストラクターの最初のパラメーターの Kind プロパティに対応する必要があります。対応していないと、ArgumentException がスローされます。 最初のパラメーターの Kind プロパティが DateTimeKind.Utc である場合、2 番目のパラメーターの値は TimeSpan.Zero であることが必要です。 最初のパラメーターの Kind プロパティが DateTimeKind.Local である場合、2 番目のパラメーターの値はローカル システムのタイム ゾーンのオフセットであることが必要です。 最初のパラメーターの Kind プロパティが DateTimeKind.Unspecified である場合、どのようなオフセットでも有効になります。 次のコードは、このコンストラクターを呼び出して DateTimeDateTimeOffset 値に変換する例を示したものです。

DateTime sourceDate = new DateTime(2008, 5, 1, 8, 30, 0);
DateTimeOffset targetTime;

// Instantiate a DateTimeOffset value from a UTC time with a zero offset.
DateTime utcTime = DateTime.SpecifyKind(sourceDate, DateTimeKind.Utc);
targetTime = new DateTimeOffset(utcTime, TimeSpan.Zero);
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM +00:00
// Because the Kind property is DateTimeKind.Utc,  
// the call to the constructor succeeds

// Instantiate a DateTimeOffset value from a UTC time with a non-zero offset.
try
{
   targetTime = new DateTimeOffset(utcTime, new TimeSpan(-2, 0, 0));
   Console.WriteLine(targetTime);
}
catch (ArgumentException)
{
   Console.WriteLine("Attempt to create DateTimeOffset value from {0} failed.", 
                      utcTime);
}   
// Throws exception and displays the following to the console:
//   Attempt to create DateTimeOffset value from 5/1/2008 8:30:00 AM failed.

// Instantiate a DateTimeOffset value from a local time with 
// the offset of the local time zone
DateTime localTime = DateTime.SpecifyKind(sourceDate, DateTimeKind.Local);
targetTime = new DateTimeOffset(localTime, 
                                TimeZoneInfo.Local.GetUtcOffset(localTime));
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM -07:00
// Because the Kind property is DateTimeKind.Local and the offset matches
// that of the local time zone, the call to the constructor succeeds.

// Instantiate a DateTimeOffset value from a local time with a zero offset.
try
{
   targetTime = new DateTimeOffset(localTime, TimeSpan.Zero);
   Console.WriteLine(targetTime);
}
catch (ArgumentException)
{
   Console.WriteLine("Attempt to create DateTimeOffset value from {0} failed.", 
                      localTime);
}   
// Throws exception and displays the following to the console:
//   Attempt to create DateTimeOffset value from 5/1/2008 8:30:00 AM failed.

// Instantiate a DateTimeOffset value with an arbitary time zone. 
string timeZoneName = "Central Standard Time";
TimeSpan offset = TimeZoneInfo.FindSystemTimeZoneById(timeZoneName). 
                         GetUtcOffset(sourceDate); 
targetTime = new DateTimeOffset(sourceDate, offset);
Console.WriteLine(targetTime);
// Displays 5/1/2008 8:30:00 AM -05:00

DateTimeOffset 型は、DateTime 値から DateTimeOffset 値への暗黙の型変換をサポートします。暗黙の型変換とは、明示的なキャスト (C# の場合) や明示的な変換 (Visual Basic の場合) を要求せず、かつ情報を失わずに、ある型を別の型に変換することを言います。 次に、コード例を示します。

DateTimeOffset targetTime;

// The Kind property of sourceDate is DateTimeKind.Unspecified
DateTime sourceDate = new DateTime(2008, 5, 1, 8, 30, 0);
targetTime = sourceDate;
Console.WriteLine(targetTime);   
// Displays 5/1/2008 8:30:00 AM -07:00

// define a UTC time (Kind property is DateTimeKind.Utc)
DateTime utcTime = DateTime.SpecifyKind(sourceDate, DateTimeKind.Utc);
targetTime = utcTime;
Console.WriteLine(targetTime);   
// Displays 5/1/2008 8:30:00 AM +00:00

// Define a local time (Kind property is DateTimeKind.Local)
DateTime localTime = DateTime.SpecifyKind(sourceDate, DateTimeKind.Local);
targetTime = localTime;
Console.WriteLine(targetTime);      
// Displays 5/1/2008 8:30:00 AM -07:00

結果として得られる DateTimeOffset 値のオフセットは、DateTime.Kind プロパティの値に依存します。 その値が DateTimeKind.Utc である場合、オフセットは TimeSpan.Zero と等しい値に設定されます。 値が DateTimeKind.Local または DateTimeKind.Unspecified である場合、オフセットはローカル タイム ゾーンの値と等しい値に設定されます。

DateTimeOffset 型は、日付と時刻の文字列形式を DateTimeOffset 値に変換する 4 つのメソッドをサポートしています。

  • Parse メソッド。日付と時刻の文字列形式を DateTimeOffset 値に変換します。変換に失敗した場合には例外をスローします。

  • TryParse メソッド。日付と時刻の文字列形式を DateTimeOffset 値に変換します。変換に失敗した場合には false を返します。

  • ParseExact メソッド。指定の形式での日付と時刻の文字列形式を DateTimeOffset 値に変換します。 変換に失敗した場合には例外をスローします。

  • TryParseExact メソッド。指定の形式での日付と時刻の文字列形式を DateTimeOffset 値に変換します。 変換に失敗した場合には false を返します。

次に、これらの 4 つの文字列変換メソッドを個別に呼び出して、DateTimeOffset 値をインスタンス化する例を示します。

string timeString; 
DateTimeOffset targetTime;

timeString = "05/01/2008 8:30 AM +01:00";
try
{
   targetTime = DateTimeOffset.Parse(timeString);
   Console.WriteLine(targetTime);
}
catch (FormatException)
{
   Console.WriteLine("Unable to parse {0}.", timeString);   
}   

timeString = "05/01/2008 8:30 AM";
if (DateTimeOffset.TryParse(timeString, out targetTime))
   Console.WriteLine(targetTime);
else
   Console.WriteLine("Unable to parse {0}.", timeString);   

timeString = "Thursday, 01 May 2008 08:30";
try
{
   targetTime = DateTimeOffset.ParseExact(timeString, "f", 
                CultureInfo.InvariantCulture);
   Console.WriteLine(targetTime);
}
catch (FormatException)
{
   Console.WriteLine("Unable to parse {0}.", timeString);   
}   

timeString = "Thursday, 01 May 2008 08:30 +02:00";
string formatString; 
formatString = CultureInfo.InvariantCulture.DateTimeFormat.LongDatePattern +
                " " +
                CultureInfo.InvariantCulture.DateTimeFormat.ShortTimePattern +
                " zzz"; 
if (DateTimeOffset.TryParseExact(timeString, 
                                formatString, 
                                CultureInfo.InvariantCulture, 
                                DateTimeStyles.AllowLeadingWhite, 
                                out targetTime))
   Console.WriteLine(targetTime);
else
   Console.WriteLine("Unable to parse {0}.", timeString);
// The example displays the following output to the console:
//    5/1/2008 8:30:00 AM +01:00
//    5/1/2008 8:30:00 AM -07:00
//    5/1/2008 8:30:00 AM -07:00
//    5/1/2008 8:30:00 AM +02:00
表示: