`DateTime` format

In VB.NET we format dates and times with a string pattern. This changes how days, months and years are displayed. Many format strings are supported by .NET.

Formatting DateTime as a string is straightforward. Often we use format patterns like "HH." But methods like ToShortDateString are also useful.

Example

First we get the current time through DateTime.Now. When you execute these code examples, the current DateTime will be different on your computer.

Here A format string beginning with MMM (for the month) is used. Look at how the pattern matches up to the output of the program.

Module Module1
    Sub Main()
        ' Use current time.
        ' ... Use a format.
        ' ... Write to console.
        Dim time As DateTime = DateTime.Now
        Dim format As String = "MMM ddd d HH:mm yyyy"
        Console.WriteLine(time.ToString(format))
    End Sub
End Module
Jun Wed 22 08:07 2022MMM     Three-letter month.
ddd     Three-letter day of the week.
d       Day of the month.
HH      Two-digit hours on 24-hour scale.
mm      Two-digit minutes.
yyyy    Four-digit year.

Pattern

It is possible to change the pattern used in the format string in many ways. To explore this, we try to shorten the output by changing the MMM to a single M.

Note The pattern matches up to the output of the program. The description of the formatting string is shown in tabular format.

Module Module1
    Sub Main()
        ' Use current time.
        ' ... Use a format.
        ' ... Write to console.
        Dim time As DateTime = DateTime.Now
        Dim format As String = "M d HH:mm yy"
        Console.WriteLine(time.ToString(format))
    End Sub
End Module
5 18 16:46 10M       One-digit month number.
d       One-digit day of the month.
HH      Two-digit hours on 24-hour scale.
mm      Two-digit minutes.
yy      Two-digit year.

One-character formats

Here we use single-character format strings. For this feature, you pass a one-character string to the ToString function.

Note This encodes a specific formatting style. Sometimes it might be worth memorizing the ones you like the most.

However Searching for a formatting string table on the Internet is much easier and requires less effort.

Module Module1
    Sub Main()
        ' Acquire current time and then try format strings.
        Dim now As DateTime = DateTime.Now
        Console.WriteLine(now.ToString("d"))
        Console.WriteLine(now.ToString("D"))
        Console.WriteLine(now.ToString("f"))
        Console.WriteLine(now.ToString("F"))
        Console.WriteLine(now.ToString("g"))
        Console.WriteLine(now.ToString("G"))
        Console.WriteLine(now.ToString("m"))
        Console.WriteLine(now.ToString("M"))
        Console.WriteLine(now.ToString("o"))
        Console.WriteLine(now.ToString("O"))
        Console.WriteLine(now.ToString("s"))
        Console.WriteLine(now.ToString("t"))
        Console.WriteLine(now.ToString("T"))
        Console.WriteLine(now.ToString("u"))
        Console.WriteLine(now.ToString("U"))
        Console.WriteLine(now.ToString("y"))
        Console.WriteLine(now.ToString("Y"))
    End Sub
End Module5/18/2010
Tuesday, May 18, 2010
Tuesday, May 18, 2010 4:47 PM
Tuesday, May 18, 2010 4:47:55 PM
5/18/2010 4:47 PM
5/18/2010 4:47:55 PM
May 18
May 18
2010-05-18T16:47:55.9620000-06:00
2010-05-18T16:47:55.9620000-06:00
2010-05-18T16:47:55
4:47 PM
4:47:55 PM
2010-05-18 16:47:55Z
Tuesday, May 18, 2010 10:47:55 PM
May, 2010
May, 2010

Helper functions

These functions, available on DateTime, allow us to format strings. For rapid application development, these are ideal because they are easy to remember and guess.

Note The methods with the word Long in them produce considerably more verbose output.

Module Module1
    Sub Main()
        ' Use string helper functions.
        Dim now As DateTime = DateTime.Now
        Console.WriteLine(now.ToLongDateString())
        Console.WriteLine(now.ToLongTimeString())
        Console.WriteLine(now.ToShortDateString())
        Console.WriteLine(now.ToShortTimeString())
        Console.WriteLine(now.ToString())
    End Sub
End ModuleTuesday, May 18, 2010
4:49:57 PM
5/18/2010
4:49 PM
5/18/2010 4:49:57 PM

`Short` day strings

The .NET Framework gives us the ability to print the representation of a day in short form. The three-letter form returns the day name and truncates it.

Here In this example, we use a loop construct that iterates through seven days and prints out the short form string for each of them.

Module Module1
    Sub Main()
        ' Current time.
        Dim now As DateTime = DateTime.Now

        ' Print out all the days.
        For index As Integer = 0 To 6
            Console.WriteLine(now.ToString("ddd"))
            now = now.AddDays(1)
        Next
    End Sub
End ModuleTue
Wed
Thu
Fri
Sat
Sun
Mon

Long day strings

You can also print out the long day strings using the format string dddd. For more textual output, the longer day string might be preferred.

Here In this example, we loop over seven consecutive days and print out the long day strings.

Module Module1
    Sub Main()
        Dim now As DateTime = DateTime.Now
        For index As Integer = 0 To 6
            Console.WriteLine(now.ToString("dddd"))
            now = now.AddDays(1)
        Next
    End Sub
End ModuleTuesday
Wednesday
Thursday
Friday
Saturday
Sunday
Monday

AM, PM

When you are using a 12-hour based time system, you will typically want to display AM or PM to indicate whether it is morning or evening.

Next This example prints out AM and PM for two times that are twelve hours apart.

Detail Are you a morning person, or a night person? This program will help you figure this out.

Module Module1
    Sub Main()
        Dim now As DateTime = DateTime.Now
        For index As Integer = 0 To 1
            Console.WriteLine(now.ToString("tt "))
            now = now.AddHours(12)
        Next
    End Sub
End ModulePM
AM

Year

The year part of the format string is also important. Typically, you will want a two or four digit year, but a one-digit year is also possible with a single y.

Here Let's look at some output in an example program that tests yy and yyyy. We see two-digit and four-digit years.

Module Module1
    Sub Main()
        ' Use the best y patterns.
        Dim now As DateTime = DateTime.Now
        Console.WriteLine(now.ToString("yy"))
        Console.WriteLine(now.ToString("yyyy"))
    End Sub
End Module10
2010

Empty formats

When we use a Nothing, empty, or missing format string, the default ToString implementation is used. It is easiest to just omit the argument when no special format is needed.

Module Module1

    Sub Main()
        Dim testDate As DateTime = New Date(2019, 1, 1)
        Dim nothingString As String = Nothing
        ' Test the ToString Function.
        Console.WriteLine("NOTHING: {0}", testDate.ToString(nothingString))
        Console.WriteLine("EMPTY:   {0}", testDate.ToString(""))
        Console.WriteLine("MISSING: {0}", testDate.ToString())

    End Sub

End ModuleNOTHING: 1/1/2019 12:00:00 AM
EMPTY:   1/1/2019 12:00:00 AM
MISSING: 1/1/2019 12:00:00 AM

`FormatException`

Be careful to use a valid format string with DateTime. Some patterns, like the asterisk, will cause a FormatException—lower and uppercase letters should be used instead.

Module Module1
    Sub Main()
        Dim testDate As DateTime = New Date(2000, 1, 1)
        Dim result As String = testDate.ToString("*")
    End Sub
End ModuleUnhandled Exception: System.FormatException: Input string was not in a correct format.
   at System.DateTimeFormat.GetRealFormat...

Correctly using format strings on DateTime is possible. DateTime has many convenience functions, different format character styles and display options.

DateTime requires no custom code on our part. This makes programs easier to maintain and read. The DateTime formatting mechanism can handle most common cases.

DateTime format