DateTime in C#

Introduction

 

These days DateTime is very important to everyone. A proverb says that,  “Time and Tide wait for none”. In most of the software projects we deal with DateTime object, so in this article we will discuss about DateTime object in C#. Here is the agenda of DateTime object:

• What is DateTime
• DateTime Constructor, Field, Methods and Properties
• Operators in DateTime
• DateTime Formatting
• Managing Nullable DateTime
• Parse to DateTime object from String
• Working with Calendars
• Working with TimeZone
• DateTime with different Culture
• Starting with DateTimeOffSet
• TimeSpan features

Note: The aim of this article is to provide the overall idea of DateTime object and how we can work with different cultures, timezones, formatting etc. This article provides so many features of DateTime object which are collected from various sources.

What is DateTime

 

DateTime is a structure of value Type like int, double etc. It is available in System namespace and present in mscorlib.dll assembly. It implements interfaces like IComparable, IFormattable, IConvertible, ISerializable, IComparable, IEquatable. 

public struct DateTime : IComparable, IFormattable, IConvertible, ISerializable, IComparable<DateTime>, IEquatable<DateTime>
{
     // Contains methods and properties
}

DateTime helps developer to find out more information about Date and Time like Get month, day, year, week day. It also helps to find date difference, add number of days to a date, etc.

 

DateTime Constructor

 

It initializes a new instance of DateTime object. At the time of object creation we need to pass required parameters like year, month, day, etc. It contains around 11 overload methods. More details available here.

// 2015 is year, 12 is month, 25 is day
DateTime date1 = new DateTime(2015, 12, 25);
Console.WriteLine(date1.ToString()); // 12/25/2015 12:00:00 AM

// 2015 - year, 12 - month, 25 – day, 10 – hour, 30 – minute, 50 - second
DateTime date2 = new DateTime(2012, 12, 25, 10, 30, 50);
Console.WriteLine(date1.ToString());// 12/25/2015 10:30:00 AM }

DateTime Fields

 

DateTime object contains two static read-only fields called as MaxValue and Minvalue.

 

MinValue – It provides smallest possible value of DateTime. 

// Define an uninitialized date.
Console.Write(DateTime.MinValue); // 1/1/0001 12:00:00 AM

MaxValue – It provides smallest possible value of DateTime. 

// Define an uninitialized date.
Console.Write(DateTime.MaxValue); // 12/31/9999 11:59:59 PM

DateTime Methods

 

DateTime contains a variety of methods which help to manipulate DateTime Object. It helps to add number of days, hour, minute, seconds to a date, date difference, parsing from string to datetime object, get universal time and many more. More on DateTime Methods, visit here

 

Here are a couple of DateTime Methods: 

// Creating TimeSpan object of one month(as 30 days)
System.TimeSpan duration = new System.TimeSpan(30, 0, 0, 0);
System.DateTime newDate1 = DateTime.Now.Add(duration);
System.Console.WriteLine(newDate1); // 1/19/2016 11:47:52 AM

// Adding days to a date
DateTime today = DateTime.Now; // 12/20/2015 11:48:09 AM
DateTime newDate2 = today.AddDays(30); // Adding one month(as 30 days)
Console.WriteLine(newDate2); // 1/19/2016 11:48:09 AM

// Parsing
string dateString = "Wed Dec 30, 2015";
DateTime dateTime12 = DateTime.Parse(dateString); // 12/30/2015 12:00:00 AM

// Date Difference
System.DateTime date1 = new System.DateTime(2015, 3, 10, 2, 15, 10);
System.DateTime date2 = new System.DateTime(2015, 7, 15, 6, 30, 20);
System.DateTime date3 = new System.DateTime(2015, 12, 28, 10, 45, 30);

// diff1 gets 127 days, 04 hours, 15 minutes and 10 seconds.
System.TimeSpan diff1 = date2.Subtract(date1); // 127.04:15:10
// date4 gets 8/23/2015 6:30:20 AM
System.DateTime date4 = date3.Subtract(diff1);
// diff2 gets 166 days 4 hours, 15 minutes and 10 seconds.
System.TimeSpan diff2 = date3 - date2; //166.04:15:10
// date5 gets 3/10/2015 2:15:10 AM
System.DateTime date5 = date2 - diff1;

// Universal Time
DateTime dateObj = new DateTime(2015, 12, 20, 10, 20, 30);
Console.WriteLine("mans" + dateObj.ToUniversalTime()); // 12/20/2015 4:50:30 AM

DateTime Properties

 

It contains properties like Day, Month, Year, Hour, Minute, Second, DayOfWeek and others in a DateTime object.

DateTime myDate = new DateTime(2015, 12, 25, 10, 30, 45);
int year = myDate.Year; // 2015
int month = myDate.Month; //12
int day = myDate.Day; // 25
int hour = myDate.Hour; // 10
int minute = myDate.Minute; // 30
int second = myDate.Second; // 45
int weekDay = (int)myDate.DayOfWeek; // 5 due to Friday

DayOfWeek

 

It specifies day of the week like Sunday, Monday etc. It is an enum which starts from Sunday to Saturday. If you cast the weekofday value to integer then it starts from Zero (0) for Sunday to Six (6) for Saturday.

DateTime dt = new DateTime(2015, 12, 25);
bool isEqual = dt.DayOfWeek == DayOfWeek.Thursday); // False
bool isEqual = dt.DayOfWeek == DayOfWeek.Friday); // True

DateTimeKind

 

It specifies whether a DateTime object is Unspecified, Utc or Local time. It is enum type with values: Unspecified(0), Utc(1), Local(2).

DateTime saveNow = DateTime.Now;
DateTime saveUtcNow = DateTime.UtcNow;

DateTime myDate = DateTime.SpecifyKind(saveUtcNow, DateTimeKind.Utc); // 12/20/2015 12:17:18 PM
DateTime myDate2 = DateTime.SpecifyKind(saveNow, DateTimeKind.Local); // 12/20/2015 5:47:17 PM

Console.WriteLine("Kind: " + myDate.Kind); // Utc
Console.WriteLine("Kind: " + myDate2.Kind); // Local

More on DateTime properties visit here.

 

DateTime Operators

 

DateTime object facilitates to perform addition, subtraction, equality, greater than using operators like “+”, “-”, “==” etc. Here are couples of examples:

// It is 10th December 2015
System.DateTime dtObject = new System.DateTime(2015, 12, 10); // 12/10/2015 12:00:00 AM
// TimeSpan object with 15 days, 10 hours, 5 minutes and 1 second.
System.TimeSpan timeSpan = new System.TimeSpan(15, 10, 5, 1);
System.DateTime addResult = dtObject + timeSpan; // 12/25/2015 10:05:01 AM
System.DateTime substarctResult = dtObject - timeSpan; // 11/24/2015 1:54:59 PM

DateTime dec25 = new DateTime(2015, 12, 25);
DateTime dec15 = new DateTime(2015, 12, 15);

// areEqual gets false.
bool areEqual = dec25 == dec15;
DateTime newDate = new DateTime(2015, 12, 25);
// areEqual gets true.
areEqual = dec25 == newDate

More on operators, please visit here

 

DateTime Formatting

 

Different users need different kinds of  format date. For instance some users need date like "mm/dd/yyyy", some need "dd-mm-yyyy". Let's say current Date Time is "12/8/2015 3:15:19 PM" and as per specifier you will get below output.

DateTime tempDate = new DateTime(2015, 12, 08); // creating date object with 8th December 2015
Console.WriteLine(tempDate.ToString("MMMM dd, yyyy")); //December 08, 2105.

Below specifiers will help you to get the date in different formats.

 

Specifier	Description	Output
d	Short Date	12/8/2015
D	Long Date	Tuesday, December 08, 2015
t	Short Time	3:15 PM
T	Long Time	3:15:19 PM
f	Full date and time	Tuesday, December 08, 2015 3:15 PM
F	Full date and time (long)	Tuesday, December 08, 2015 3:15:19 PM
g	Default date and time	12/8/2015 15:15
G	Default date and time (long)	12/8/2015 15:15
M	Day / Month	8-Dec
r	RFC1123 date	Tue, 08 Dec 2015 15:15:19 GMT
s	Sortable date/time	2015-12-08T15:15:19
u	Universal time, local timezone	2015-12-08 15:15:19Z
Y	Month / Year	December, 2015
dd	Day	8
ddd	Short Day Name	Tue
dddd	Full Day Name	Tuesday
hh	2 digit hour	3
HH	2 digit hour (24 hour)	15
mm	2 digit minute	15
MM	Month	12
MMM	Short Month name	Dec
MMMM	Month name	December
ss	seconds	19
fff	milliseconds	120
FFF	milliseconds without trailing zero	12
tt	AM/PM	PM
yy	2 digit year	15
yyyy	4 digit year	2015
:	Hours, minutes, seconds separator, e.g. {0:hh:mm:ss}	9:08:59
/	Year, month , day separator, e.g. {0:dd/MM/yyyy}	8/4/2007

 

Handling Nullable DateTime

 

DateTime is a Value Type like int, double etc. so there is no way to assign a null value. When a type can be assigned null it is called nullable, that means the type has no value. All Reference Types are nullable by default, e.g. String, and all ValueTypes are not, e.g. Int32. The Nullable<T> structure is using a value type as a nullable type.

 

By default DateTime is not nullable because it is a Value Type, using the nullable operator introduced in C#, you can achieve this using a question mark (?) after the type or using the generic style Nullable.

Nullable <DateTime> nullDateTime;
DateTime? nullDateTime = null;

Parse string to DateTime object

 

Sometimes we do parsing from string to DateTime object to perform operations like date difference, weekday, month name etc. For instance, there is a string value (“12/10/2015”) and our requirement is to find out weekday (Sunday or Monday and so on) of date. In this scenario we need to convert string value to DateTime object and then use WeekDay property(obj.WeekDay) to find out weekday. We can accomplish the same by built-in methods like Convert.ToDateTime(), DateTime.Parse(),DateTime.ParseExact(), DateTime.TryParse(), DateTime.TryParseExact(). Here are a few examples of how to parse a string to DateTime object:

CultureInfo culture = new CultureInfo("en-US");

DateTime dateTimeObj = Convert.ToDateTime("10/22/2015 12:10:15 PM", culture);
DateTime dateTimeObj = DateTime.Parse("10/22/2015 12:10:15 PM");
DateTime dateTimeObj = DateTime.ParseExact("10-22-2015", "MM-dd-yyyy", provider); // 10/22/2015 12:00:00 AM

DateTime dateTimeObj; // 10-22-2015 12:00:00 AM
bool isSuccess = DateTime.TryParse("10-22-2015", out dateTimeObj); // True

DateTime dateTimeObj; // 10/22/2015 12:00:00 AM
CultureInfo provider = CultureInfo.InvariantCulture;
bool isSuccess = DateTime.TryParseExact("10-22-2015", "MM-dd-yyyy", provider, DateTimeStyles.None, out dateTimeObj); // True

Now a question arises in your mind, that is, why do we have so many methods for parsing? The reason is every method is for a different purpose. Use TryParse() when you want to be able to attempt a parse and handle invalid data immediately (instead of throwing the exception), and ParseExact() when the format you are expecting is not a standard format, or when you want to limit to one particular standard format for efficiency. If you're sure the string is a valid DateTime, and you know the format, you could also consider the DateTime.ParseExact() or DateTime.TryParseExact() methods.

 

More on this visit here.

 

Working with Calendars

  

Although DateTime object stores Date and Time information but it also depends on Calendar. Calendar class is an abstract class which is present in System.Globalization namespace. There are different types of Calendar available in .Net framework. These are ChineseLunisolarCalendar, GregorianCalendar, HebrewCalendar, HijriCalendar, JapaneseCalendar, JapaneseLunisolarCalendar, JulianCalendar, KoreanCalendar, KoreanLunisolarCalendar, PersianCalendar, TaiwanCalendar, TaiwanLunisolarCalendar, ThaiBuddhistCalendar, UmAlQuraCalendar.

 

Calendar can be used in two ways:

• Using CultureInfo object
• Using Calendar object. It is for Calendars that are independent of culture: ChineseLunisolarCalendar, JapaneseLunisolarCalendar, JulianCalendar, KoreanLunisolarCalendar,PersianCalendar and TaiwanLunisolarCalendar. 

You can know your current Calendar information using following code:

CultureInfo currentCulture = Thread.CurrentThread.CurrentCulture;
Calendar cl = currentCulture.Calendar; // System.Globalization.GregorianCalendar
string temip = cl.ToString().Replace("System.Globalization.", "");

// 4th Jan 2016 - current date
Calendar calendar = new HijriCalendar();
DateTime dt10 = new DateTime(2016, 01, 04, calendar);// Uses month 13!
Console.WriteLine("HijriCalendar year: " + dt10.Year); // 2141
Console.WriteLine("HijriCalendar month: " + dt10.Month); // 9
Console.WriteLine("HijriCalendar total date: " + dt10.ToString("d")); // 9

// Converting one Calendar value to another - Option1
var calendar1 = new HijriCalendar();
var hijriYear = calendar1.GetYear(DateTime.Now); // 1437
var hijriMonth = calendar1.GetMonth(DateTime.Now); // 3
var hijriDay = calendar1.GetDayOfMonth(DateTime.Now); // 24

//- Option2
DateTime utc = DateTime.Now;
var ci = CultureInfo.CreateSpecificCulture("ar-SA");
string s = utc.ToString(ci); // 24/03/37 08:15:03 ?
A calendar divides into multiple eras. In .Net framework it supports only one era except JapaneseCalendar (supports multiple).

Calendar cal = new JapaneseCalendar();
foreach (int era in cal.Eras) {
DateTime date2 = cal.ToDateTime(year, month, day, 0, 0, 0, 0, era);

Console.WriteLine("{0}/{1}/{2} era {3} in Japanese Calendar -> {4:d} in Gregorian",
cal.GetMonth(date2), cal.GetDayOfMonth(date2),
cal.GetYear(date2), cal.GetEra(date2), date2);

Working with TimeZone object

 

TimeZoneInfo class represents world time like Indian Standard Time (IST), US Eastern Standard Time, Tokyo Standard Time etc. It is present in System namespace. It recognizes Local Time Zone and converts times between Coordinated Universal Time (UTC) and local time. It helps to get time in Time Zone (Indis or Japan or USA), converts time between two Time Zone(Australia time zone to India Standard time) and serializes a Date Time.

 

It is a sealed class and you can’t create an instance of this class. You need to call static members and methods. Static methods like CreateCustomTimeZone(), FindSystemTimeZoneById(), FromSerializedString(), GetSystemTimeZonesand properties like Utc and Local. Here area couple examples:

//If you want to convert it back from UTC:
DateTime now = DateTime.UtcNow;
DateTime tempD = TimeZone.CurrentTimeZone.ToLocalTime(now);
// Get current TimeZone
string current = TimeZone.CurrentTimeZone.StandardName;

// Get All Time Zones
foreach (TimeZoneInfo z in TimeZoneInfo.GetSystemTimeZones())
{
    Console.WriteLine(z.Id);
}

//If you want to convert any date from your time-zone to UTC do this:
DateTime tempD1 = TimeZone.CurrentTimeZone.ToUniversalTime(DateTime.Now);

// Get Tokyo Standard Time zone from Local time Zone(India)
TimeZoneInfo tzObject = TimeZoneInfo.FindSystemTimeZoneById("Tokyo Standard Time");
DateTime tstTime = TimeZoneInfo.ConvertTime(DateTime.Now, TimeZoneInfo.Local, tzObject);
Console.WriteLine("1. Time in {0} zone: {1}", tzObject.IsDaylightSavingTime(tstTime) ?
tzObject.DaylightName : tzObject.StandardName, tstTime);

// Converting Austrlia Standard Time to Indian Standrd Time
TimeZoneInfo tzObject1 = TimeZoneInfo.FindSystemTimeZoneById("AUS Central Standard Time");
DateTime tstTime2 = TimeZoneInfo.ConvertTime(DateTime.Now, TimeZoneInfo.Local, tzObject1);
Console.WriteLine("2. Time in {0} zone: {1}", tzObject1.IsDaylightSavingTime(tstTime2) ?
tzObject1.DaylightName : tzObject1.StandardName, tstTime2);

// Converting value to UTC time zone to make comfortale with TimeZone
DateTime ut1 = TimeZoneInfo.ConvertTimeToUtc(tstTime2, tzObject1);

TimeZoneInfo tzObject2 = TimeZoneInfo.FindSystemTimeZoneById("India Standard Time");
DateTime tstTime3 = TimeZoneInfo.ConvertTime(ut1, TimeZoneInfo.Utc, tzObject2);
Console.WriteLine("3. Time in {0} zone: {1}", tzObject2.IsDaylightSavingTime(tstTime3) ?
tzObject2.DaylightName : tzObject2.StandardName, tstTime3);

DateTime with Different Culture

 

.Net uses CultureInfo class for providing information about specific culture. The information is writing system, date, number, string, and calendar. It is present in System.Globalization namespace.

// Current culture name
string currentCulture = Thread.CurrentThread.CurrentCulture.DisplayName;

DateTime currentTime = DateTime.Now; //"1/9/2016 10:22:45 AM"
//// Getting DateTime based on culture.
string dateInUSA = currentTime.ToString("D", new CultureInfo("en-US")); // USA - Saturday, January 09, 2016
string dateInHindi = currentTime.ToString("D", new CultureInfo("hi-IN")); // Hindi - 09 ????? 2016
string dateInJapan = currentTime.ToString("D", new CultureInfo("ja-JP")); // Japan - 2016?1?9?
string dateInFrench = currentTime.ToString("D", new CultureInfo("fr-FR")); // French - samedi 9 janvier 2016

string dateInOriya = currentTime.ToString("D", new CultureInfo("or")); // Oriya - 09 ???????? 2016
// Convert Hindi Date to French Date
DateTime originalResult = new DateTime(2016, 01, 09);
// Converting Hindi Date to DateTime object
bool success = DateTime.TryParse(dateInHindi, new System.Globalization.CultureInfo("hi-IN"),
System.Globalization.DateTimeStyles.None, out originalResult);

// Next convert current date to French date
string frenchTDate = originalResult.ToString("D", new CultureInfo("fr-FR")); // French - samedi 9 janvier 2016

// To get DatePattern from Culture
CultureInfo fr = new CultureInfo("fr-FR");
string shortUsDateFormatString = fr.DateTimeFormat.LongDatePattern;
string shortUsTimeFormatString = fr.DateTimeFormat.ShortTimePattern;

// To get all installed culture in .Net version
foreach (CultureInfo ci in CultureInfo.GetCultures(CultureTypes. AllCultures))
{
    Console.WriteLine(ci.Name + ", " + ci.EnglishName);
}

What is DateTimeOffset?

 

It is a structure type like DateTime. It is introduced in .Net framework 3.5 and present in System namespace. It is mostly relative to Universal Coordinated Time (UTC).

 

DateTimeOffset is Date + Time + Offset. It provides precise information because it contains offset from Date and Time is taken. DateTimeOffset provides same properties as DateTime structure like Day, Month, Year, Hour, Minute, Second etc. However DateTimeOffset has some new properties:

• DateTime
  Gets the DateTime portion of the value without regard to the offset.
  
  
• LocalDateTime
  Returns a DateTime representing the value in respect to the local time zone.
  
  
• Offset
  Returns the time offset from UTC.
  
  
• UtcDateTime
  Returns a DateTime representing the value in respect to UTC time. 

Follow example, we declare date variable of DateTimeOffset type and assign current DateTime to it. You will get a result like: 1/9/2016 2:27:00 PM +05:30. Here “1/9/2016 2:27:00 PM” is datetime and “+05:30” (5 hours 30 minutes) is your Offset value. Means if you add offset value to date time (1/9/2016 2:27:00 PM) you will get UTC time. It provides a better way to work with different times from different time zones.

// Original time: 1/9/2016 2:27:00 PM
DateTimeOffset date = DateTimeOffset.Now; // 1/9/2016 2:27:00 PM +05:30

// You can get Offset value using Offset property
DateTimeOffset dateTimeObj = DateTime.Now;
dateTimeObj.Offset.Hours // 5
dateTimeObj.Offset.Minutes //30
dateTimeObj.Offset.Seconds // 0

// Get only DateTime from DateTimeOffset
dateTimeObj.DateTime // 1/9/2016 2:27:00 PM

// Get Utc time from DateTime Offset
dateTimeObj.UtcDateTime.ToString() // 1/9/2016 7:57:00 PM

// Get Utc from local time
DateTime utcTimeObj = DateTimeOffset.Parse(DateTime.Now.ToString()).UtcDateTime;

// Another way to get Utc from local time
DateTime utcTimeObj = DateTime.Now.ToUniversalTime();

// Get local time from Utc time
DateTime localVersion = DateTime.UtcNow.ToLocalTime();

// Another way to get local(India) time from Utc time
localVersion = TimeZoneInfo.ConvertTimeFromUtc(DateTime.UtcNow, TimeZoneInfo.FindSystemTimeZoneById("India Standard Time"));

DateTime is a more powerful structure for manipulating datetime but it is less portable when working with times from different time zones. The DateTimeOffset is much more portable in that it preserves the offset from UTC. So choose as per your requirement.

 

Working with TimeSpan

 

It is a structure type which is present in System namespace. It represents time interval and can be expressed as days, hours, minutes, and seconds. It helps to fetch days, hour, minutes and seconds between two dates.

 

You can create instance of TimeSpan object. It contains 4 parameterized constructors which take days, hours, minutes, seconds, and milliseconds as parameter. Here is the example:

TimeSpan ts = new TimeSpan(10, 40, 20); // 10 - hour, 40 - minute, 20 - second
TimeSpan ts1 = new TimeSpan(1, 2, 5, 10); // 1 - day, 2 - hour, 5 - minute, 10 – seconds

// You can add TimeSpan with DateTime object as well as TimeSpan object.
TimeSpan ts = new TimeSpan(10, 40, 20); // 10 - hour, 40 - minute, 20 - second
TimeSpan ts1 = new TimeSpan(1, 2, 5, 10); // 1 - day, 2 - hour, 5 - minute, 10 – seconds

DateTime tt = DateTime.Now + ts; // Addition with DateTime
ts.Add(ts1); // Addition with TimeSpan Object

A single tick represents one hundred nanoseconds or one ten-millionth of a second. There are 10,000 ticks in a millisecond, or 10 million ticks in a second.

TimeSpan ts3 = new TimeSpan(10000000);
double secondFromTs = ts3.TotalSeconds; // 1 second
Console.WriteLine(secondFromTs);

Below is the example of how to get the exact date difference between them using TimeSpan: 

// Define two dates.
DateTime date1 = new DateTime(2016, 1, 10, 11, 20, 30);
DateTime date2 = new DateTime(2016, 2, 20, 12, 25, 35);

// Calculate the interval between the two dates.
TimeSpan interval = date2 - date1;

// Display individual properties of the resulting TimeSpan object.
Console.WriteLine("No of Days:", interval.Days); // 41
Console.WriteLine("Total No of Days:", interval.TotalDays); // 41.0451
Console.WriteLine("No of Hours:", interval.Hours); //1
Console.WriteLine("Total No of Hours:", interval.TotalHours); // 985.084
Console.WriteLine("No of Minutes:", interval.Minutes); // 5
Console.WriteLine("Total No of Minutes:", interval.TotalMinutes); // 59105.833
Console.WriteLine("No of Seconds:", interval.Seconds); // 5
Console.WriteLine("Total No of Seconds:", interval.TotalSeconds); // 3546305.0
Console.WriteLine("No of Milliseconds:", interval.Milliseconds); // 0
Console.WriteLine("Total No of Milliseconds:", interval.TotalMilliseconds); // 3546305000
Console.WriteLine("Ticks:", interval.Ticks); // 354630500000000

Here you will get one doubt as to the difference between Hours and TotalHours. Hours property represents difference between two dates hours value (12-11). However TotalHours represents total number of hours difference between two dates. First it calculates days between two and then multiplies 24 hours into it.

 

Conclusion 

 

In this article we discussed about DateTime object in C#. It also contains how to work with different cultures, timezones, formmatting, date differences and others. Hope it will help you often.

 

References 

https://msdn.microsoft.com/en-us/library/system.datetime(v=vs.110).aspx