This documentation is archived and is not being maintained.

Calendar Class

Represents time in divisions, such as weeks, months, and years.

Namespace:  System.Globalization
Assembly:  mscorlib (in mscorlib.dll)

<SerializableAttribute> _
<ComVisibleAttribute(True)> _
Public MustInherit Class Calendar _
	Implements ICloneable
Dim instance As Calendar

A calendar divides time into units, such as weeks, months, and years. The number, length, and start of the divisions vary in each calendar.

Any moment in time can be represented as a set of numeric values using a particular calendar. For example, a vernal equinox occurred at (1999, 3, 20, 8, 46, 0, 0.0) in the Gregorian calendar, that is, March 20, 1999 C.E. at 8:46:00:0.0. An implementation of Calendar can map any date in the range of a specific calendar to a similar set of numeric values, and DateTime can map such sets of numeric values to a textual representation using information from Calendar and DateTimeFormatInfo. The textual representation can be culture-sensitive, for example, "8:46 AM March 20th 1999 AD" for the en-US culture, or culture-insensitive, for example, "1999-03-20T08:46:00" in ISO 8601 format.

A Calendar implementation can define one or more eras. The Calendar class identifies the eras as enumerated integers, where the current era (CurrentEra) has the value 0.

To make up for the difference between the calendar year and the actual time that the earth rotates around the sun or the actual time that the moon rotates around the earth, a leap year has a different number of days from a standard calendar year. Each Calendar implementation defines leap years differently.

For consistency, the first unit in each interval (the first month, for example) is assigned the value 1.

The System.Globalization namespace includes the following Calendar implementations:

The following code example demonstrates the members of the Calendar class.

Imports System
Imports System.Globalization

Public Class SamplesCalendar   

   Public Shared Sub Main()

      ' Sets a DateTime to April 3, 2002 of the Gregorian calendar. 
      Dim myDT As New DateTime(2002, 4, 3, New GregorianCalendar())

      ' Uses the default calendar of the InvariantCulture. 
      Dim myCal As Calendar = CultureInfo.InvariantCulture.Calendar

      ' Displays the values of the DateTime.
      Console.WriteLine("April 3, 2002 of the Gregorian calendar:")
      DisplayValues(myCal, myDT)

      ' Adds 5 to every component of the DateTime.
      myDT = myCal.AddYears(myDT, 5)
      myDT = myCal.AddMonths(myDT, 5)
      myDT = myCal.AddWeeks(myDT, 5)
      myDT = myCal.AddDays(myDT, 5)
      myDT = myCal.AddHours(myDT, 5)
      myDT = myCal.AddMinutes(myDT, 5)
      myDT = myCal.AddSeconds(myDT, 5)
      myDT = myCal.AddMilliseconds(myDT, 5)

      ' Displays the values of the DateTime.
      Console.WriteLine("After adding 5 to each component of the DateTime:")
      DisplayValues(myCal, myDT)

   End Sub 'Main

   Public Shared Sub DisplayValues(myCal As Calendar, myDT As DateTime)
      Console.WriteLine("   Era:          {0}", myCal.GetEra(myDT))
      Console.WriteLine("   Year:         {0}", myCal.GetYear(myDT))
      Console.WriteLine("   Month:        {0}", myCal.GetMonth(myDT))
      Console.WriteLine("   DayOfYear:    {0}", myCal.GetDayOfYear(myDT))
      Console.WriteLine("   DayOfMonth:   {0}", myCal.GetDayOfMonth(myDT))
      Console.WriteLine("   DayOfWeek:    {0}", myCal.GetDayOfWeek(myDT))
      Console.WriteLine("   Hour:         {0}", myCal.GetHour(myDT))
      Console.WriteLine("   Minute:       {0}", myCal.GetMinute(myDT))
      Console.WriteLine("   Second:       {0}", myCal.GetSecond(myDT))
      Console.WriteLine("   Milliseconds: {0}", myCal.GetMilliseconds(myDT))
   End Sub 'DisplayValues

End Class 'SamplesCalendar 

'This code produces the following output. 

'April 3, 2002 of the Gregorian calendar: 

'   Era:          1 

'   Year:         2002 

'   Month:        4 

'   DayOfYear:    93 

'   DayOfMonth:   3 

'   DayOfWeek:    Wednesday 

'   Hour:         0 

'   Minute:       0 

'   Second:       0 

'   Milliseconds: 0 

'After adding 5 to each component of the DateTime: 

'   Era:          1 

'   Year:         2007 

'   Month:        10 

'   DayOfYear:    286 

'   DayOfMonth:   13 

'   DayOfWeek:    Saturday 

'   Hour:         5 

'   Minute:       5 

'   Second:       5 

'   Milliseconds: 5

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 3.5, 2.0, 1.0

XNA Framework

Supported in: 3.0, 2.0, 1.0