Click to Rate and Give Feedback
MSDN
MSDN Library
.NET Development
.NET Framework 3.5
System Namespace
DateTime Structure
DateTime Methods
ToString Method
 ToString Method (String)
This page is specific to
Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:
.NET Framework Class Library
DateTime..::.ToString Method (String)

Updated: November 2007

Converts the value of the current DateTime object to its equivalent string representation using the specified format.

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

Visual Basic (Declaration)
Public Function ToString ( _
    format As String _
) As String
Visual Basic (Usage)
Dim instance As DateTime
Dim format As String
Dim returnValue As String

returnValue = instance.ToString(format)
C#
public string ToString(
    string format
)
Visual C++
public:
String^ ToString(
    String^ format
)
J#
public String ToString(
    String format
)
JScript
public function ToString(
    format : String
) : String

Parameters

format
Type: System..::.String

A DateTime format string.

Return Value

Type: System..::.String

A string representation of value of the current DateTime object as specified by format.

ExceptionCondition
FormatException

The length of format is 1, and it is not one of the format specifier characters defined for DateTimeFormatInfo.

-or-

format does not contain a valid custom format pattern.

The format parameter should contain either a single format specifier character (see Standard Date and Time Format Strings) or a custom format pattern (see Custom Date and Time Format Strings) that defines the format of the returned string. If format is nullNothingnullptra null reference (Nothing in Visual Basic) or an empty string, the general format specifier, 'G', is used.

This method uses formatting information derived from the current culture. For more information, see CurrentCulture.

The following example uses each of the standard date and time format strings and a selection of custom date and time format strings to display the string representation of a DateTime value. The thread current culture for the example is en-US.

Visual Basic
Module DateToStringExample
   Public Sub Main()
      Dim dateValue As Date = #6/15/2008 9:15:07PM#
      ' Create an array of standard format strings.
      Dim standardFmts() As String = {"d", "D", "f", "F", "g", "G", _
                                      "m", "o", "R", "s", "t", "T", _
                                      "u", "U", "y"}
      ' Output date and time using each standard format string.
      For Each standardFmt As String In standardFmts
         Console.WriteLine("{0}: {1}", standardFmt, _
                           dateValue.ToString(standardFmt))
      Next
      Console.WriteLine()

      ' Create an array of some custom format strings.
      Dim customFmts() As String = {"h:mm:ss.ff t", "d MMM yyyy", "HH:mm:ss.f", _
                                    "dd MMM HH:mm:ss", "\Mon\t\h\: M", "HH:mm:ss.ffffzzz" }
      ' Output date and time using each custom format string.
      For Each customFmt As String In customFmts
         Console.WriteLine("'{0}': {1}", customFmt, _
                           dateValue.ToString(customFmt))
      Next
   End Sub
End Module
' This example displays the following output to the console:
'       d: 6/15/2008
'       D: Sunday, June 15, 2008
'       f: Sunday, June 15, 2008 9:15 PM
'       F: Sunday, June 15, 2008 9:15:07 PM
'       g: 6/15/2008 9:15 PM
'       G: 6/15/2008 9:15:07 PM
'       m: June 15
'       o: 2008-06-15T21:15:07.0000000
'       R: Sun, 15 Jun 2008 21:15:07 GMT
'       s: 2008-06-15T21:15:07
'       t: 9:15 PM
'       T: 9:15:07 PM
'       u: 2008-06-15 21:15:07Z
'       U: Monday, June 16, 2008 4:15:07 AM
'       y: June, 2008
'       
'       'h:mm:ss.ff t': 9:15:07.00 P
'       'd MMM yyyy': 15 Jun 2008
'       'HH:mm:ss.f': 21:15:07.0
'       'dd MMM HH:mm:ss': 15 Jun 21:15:07
'       '\Mon\t\h\: M': Month: 6
'       'HH:mm:ss.ffffzzz': 21:15:07.0000-07:00

C#
using System;

public class DateToStringExample
{
   public static void Main()
   {
      DateTime dateValue = new DateTime(2008, 6, 15, 21, 15, 07);
      // Create an array of standard format strings.
      string[] standardFmts = {"d", "D", "f", "F", "g", "G", "m", "o", 
                               "R", "s", "t", "T", "u", "U", "y"};
      // Output date and time using each standard format string.
      foreach (string standardFmt in standardFmts)
         Console.WriteLine("{0}: {1}", standardFmt, 
                           dateValue.ToString(standardFmt));
      Console.WriteLine();

      // Create an array of some custom format strings.
      string[] customFmts = {"h:mm:ss.ff t", "d MMM yyyy", "HH:mm:ss.f", 
                             "dd MMM HH:mm:ss", @"\Mon\t\h\: M", "HH:mm:ss.ffffzzz" };
      // Output date and time using each custom format string.
      foreach (string customFmt in customFmts)
         Console.WriteLine("'{0}': {1}", customFmt,
                           dateValue.ToString(customFmt));
   }
}
// This example displays the following output to the console:
//       d: 6/15/2008
//       D: Sunday, June 15, 2008
//       f: Sunday, June 15, 2008 9:15 PM
//       F: Sunday, June 15, 2008 9:15:07 PM
//       g: 6/15/2008 9:15 PM
//       G: 6/15/2008 9:15:07 PM
//       m: June 15
//       o: 2008-06-15T21:15:07.0000000
//       R: Sun, 15 Jun 2008 21:15:07 GMT
//       s: 2008-06-15T21:15:07
//       t: 9:15 PM
//       T: 9:15:07 PM
//       u: 2008-06-15 21:15:07Z
//       U: Monday, June 16, 2008 4:15:07 AM
//       y: June, 2008
//       
//       'h:mm:ss.ff t': 9:15:07.00 P
//       'd MMM yyyy': 15 Jun 2008
//       'HH:mm:ss.f': 21:15:07.0
//       'dd MMM HH:mm:ss': 15 Jun 21:15:07
//       '\Mon\t\h\: M': Month: 6
//       'HH:mm:ss.ffffzzz': 21:15:07.0000-07:00

Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, 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

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: 2.0, 1.0
Tags What's this?: Add a tag
Community Content   What is Community Content?
Add new content RSS  Annotations
Can throw ArgumentOutOfRangeException when using the JapaneseCalender      David M. Kean - MSFT   |   Edit   |  
This method throws an ArgumentOutOfRangeException when using the JapaneseCalendar to format a date that occurs before September 8th, 1868.

The following method attempts to call DateTime.ToString(IFormatProvider) on a DateTime instance with the value September 7th, 1868.

[C#]

using System;
using System.Globalization;

namespace Samples
{
class Program
{
static void Main(string[] args)
{
CultureInfo culture = new CultureInfo("ja-JP");
culture.DateTimeFormat.Calendar = new JapaneseCalendar();

DateTime date = new DateTime(1868, 9, 7);


try
{
date.ToString(culture);
}
catch (ArgumentOutOfRangeException ex)
{
Console.WriteLine(ex.Message);
}
}
}
}

The above outputs the following:

Specified time is not supported in this calendar. It should be between 09/08/186
8 00:00:00 (Gregorian date) and 12/31/9999 23:59:59 (Gregorian date), inclusive.


Parameter name: time


This can also occur without explicitly specifying the JapaneseCalendar when the current user's calender is set to the Wareki calendar in Regional and Language Options. To set the calendar to this, do the following in Windows Vista and Windows Server 2003:

  1. Choose Start -> Control Panel -> Regional and Language Options
  2. From the Current format drop down, choose Japanese (Japan)
  3. Click Customize this format and select the Date tab
  4. Under Calendar type, choose 和暦
  5. Click OK and then OK again

The following method attempts to call DateTime.ToString() on a DateTime instance with the value September 7th, 1868. This code sample expects the above steps to have been done.

[C#]

using System;
using System.Globalization;

namespace Samples
{
class Program
{
static void Main(string[] args)
{
DateTime date = new DateTime(1868, 9, 7);


try
{
date.ToString();
}
catch (ArgumentOutOfRangeException ex)
{
Console.WriteLine(ex.Message);
}
}
}
}

The above outputs the following:

Specified time is not supported in this calendar. It should be between 09/08/186
8 00:00:00 (Gregorian date) and 12/31/9999 23:59:59 (Gregorian date), inclusive.


Parameter name: time
Tags What's this?: Add a tag
Flag as ContentBug
Processing
© 2008 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker