Class SysDateFormatters

This class implements my stalwart date formatter, ReformatSysDateP6C, which I created initially as a Windows Interface Language (WIL, a. k. a. WinBatch) library function, Reformat_Date_YmdHms_P6C, in October 2001, although its roots go back much further in my WIL script development.

Since static classes are implicitly sealed, this class cannot be inherited.

Inheritance

System.Object

SysDateFormatters

Namespace: WizardWrx

Assembly: WizardWrx.Core.dll

Syntax

public static class SysDateFormatters : object

Fields

RFD_DD_MM_YYYY

Apply the following format to a date: DD/MM/YYYY

This is the standard format used in most of the English speaking world, by all military organizations of which I am aware, Europeans, and others who take their lead from any of the above groups.

Only the date is returned, all four digits of the year are included, and the month and day have leading zeros if either is less than 10.

Declaration

public const string RFD_DD_MM_YYYY = null

Field Value

Type	Description
System.String

RFD_HH_MM

Apply the following format to a time: hh:mm

The returned string represents the hours on a 24 hour clock.

At present, 12 hour (AM/PM) representation is unsupported.

This is a standard format used in most of the English speaking world, by all military organizations of which I am aware, Europeans, and others who take their lead from any of the above groups.

Only the time is returned, and the hour and minute have leading zeros if either is less than 10.

Declaration

public const string RFD_HH_MM = null

Field Value

Type	Description
System.String

RFD_HH_MM_SS

Apply the following format to a time: hh:mm:ss

The returned string represents the hours on a 24 hour clock.

At present, 12 hour (AM/PM) representation is unsupported.

This is a standard format used in most of the English speaking world, by all military organizations of which I am aware, Europeans, and others who take their lead from any of the above groups.

Only the time is returned, and the hour, minute, and second have leading zeros if any of them is less than 10.

Declaration

public const string RFD_HH_MM_SS = null

Field Value

Type	Description
System.String

RFD_HH_MM_SS_TTT

Apply the following format to a time: hh:mm:ss.ttt

The returned string represents the hours on a 24 hour clock.

At present, 12 hour (AM/PM) representation is unsupported.

The final token, ttt, is the milliseconds portion of the time, which is reported with leading zeros.

This is an extension of a standard format used in most of the English speaking world, by all military organizations of which I am aware, Europeans, and others who take their lead from any of the above groups.

Only the time is returned, and the hour, minute, and second have leading zeros if any of them is less than 10.

Declaration

public const string RFD_HH_MM_SS_TTT = null

Field Value

Type	Description
System.String

RFD_MM_DD_YY

Apply the following format to a date: MM/DD/YY

This is the standard short format used in the USA.

Only the date is returned, including only the year of century, and the month and day have leading zeros if either is less than 10.

Declaration

public const string RFD_MM_DD_YY = null

Field Value

Type	Description
System.String

RFD_MM_DD_YYYY

Apply the following format to a date: MM/DD/YYYY

This is the standard format used in the USA.

Only the date is returned, all four digits of the year are included, and the month and day have leading zeros if either is less than 10.

Declaration

public const string RFD_MM_DD_YYYY = null

Field Value

Type	Description
System.String

RFD_WW_DD_MM_YYYY

Apply the following format to a date: WW DD/MM/YYYY

The first token, WW, represents enough of the three letter weekday name abbreviation, which is derived from the regional settings in the Windows Control Panel, to uniquely identify the weekday. The returned string conforms to the settings in the UICulture of the calling thread.

This is the standard format used in most of the English speaking world, by all military organizations of which I am aware, Europeans, and others who take their lead from any of the above groups.

Only the date is returned, all four digits of the year are included, and the month and day have leading zeros if either is less than 10.

Declaration

public const string RFD_WW_DD_MM_YYYY = null

Field Value

Type	Description
System.String

RFD_WW_MM_DD_YYYY

Apply the following format to a date: WW DD/MM/YYYY

The first token, WW, represents enough of the three letter weekday name abbreviation, which is derived from the regional settings in the Windows Control Panel, to uniquely identify the weekday. The returned string conforms to the settings in the UICulture of the calling thread.

This is the standard format used in the USA.

Only the date is returned, all four digits of the year are included, and the month and day have leading zeros if either is less than 10.

Declaration

public const string RFD_WW_MM_DD_YYYY = null

Field Value

Type	Description
System.String

RFD_WWW_DD_MM_YYYY

Apply the following format to a date: WWW DD/MM/YYYY

The first token, WWW, represents the three letter abbreviation of the weekday name, which is derived from the regional settings in the Windows Control Panel. The returned string conforms to the settings in the UICulture of the calling thread.

This is the standard format used in most of the English speaking world, by all military organizations of which I am aware, Europeans, and others who take their lead from any of the above groups.

Only the date is returned, all four digits of the year are included, and the month and day have leading zeros if either is less than 10.

Declaration

public const string RFD_WWW_DD_MM_YYYY = null

Field Value

Type	Description
System.String

RFD_WWW_MM_DD_YYYY

Apply the following format to a date: WWW DD/MM/YYYY

The first token, WWW, represents the three letter abbreviation of the weekday name, which is derived from the regional settings in the Windows Control Panel. The returned string conforms to the settings in the UICulture of the calling thread.

This is the standard format used in the USA.

Only the date is returned, all four digits of the year are included, and the month and day have leading zeros if either is less than 10.

Declaration

public const string RFD_WWW_MM_DD_YYYY = null

Field Value

Type	Description
System.String

RFD_WWWW_DD_MM_YYYY

Apply the following format to a date: WWWW DD/MM/YYYY

The first token, WWWW, represents full name of the weekday, which is derived from the regional settings in the Windows Control Panel. The returned string conforms to the settings in the UICulture of the calling thread.

This is the standard format used in most of the English speaking world, by all military organizations of which I am aware, Europeans, and others who take their lead from any of the above groups.

Only the date is returned, all four digits of the year are included, and the month and day have leading zeros if either is less than 10.

Declaration

public const string RFD_WWWW_DD_MM_YYYY = null

Field Value

Type	Description
System.String

RFD_WWWW_MM_DD_YYYY

Apply the following format to a date: WWWW DD/MM/YYYY

The first token, WWWW, represents full name of the weekday, which is derived from the regional settings in the Windows Control Panel. The returned string conforms to the settings in the UICulture of the calling thread.

This is the standard format used in the USA.

Only the date is returned, all four digits of the year are included, and the month and day have leading zeros if either is less than 10.

Declaration

public const string RFD_WWWW_MM_DD_YYYY = null

Field Value

Type	Description
System.String

RFD_YYYY_MM_DD

Apply the following format to a date: YYYY/MM/DD

With respect to the date only, this format confirms to the ISO 8601 standard for time representation.

Only the date is returned, all four digits of the year are included, and the month and day have leading zeros if either is less than 10.

Declaration

public const string RFD_YYYY_MM_DD = null

Field Value

Type	Description
System.String

RFD_YYYY_MM_DD_HH_MM_SS

Apply the following format to a date and time: YYYY/MM/DD hh:mm:ss

The returned string represents the hours on a 24 hour clock.

At present, 12 hour (AM/PM) representation is unsupported.

This format conforms fully to the ISO 8601 standard for time representation.

The month, day, hour, minute, and second have leading zeros if any of them is less than 10.

Declaration

public const string RFD_YYYY_MM_DD_HH_MM_SS = null

Field Value

Type	Description
System.String

RFD_YYYY_MM_DD_HH_MM_SS_TTT

Apply the following format to a date and time: YYYY/MM/DD hh:mm:ss.ttt

The returned string represents the hours on a 24 hour clock.

At present, 12 hour (AM/PM) representation is unsupported.

This format conforms fully to the ISO 8601 standard for time representation.

The final token, ttt, is the milliseconds portion of the time, which is reported with leading zeros.

The month, day, hour, minute, and second have leading zeros if any of them is less than 10.

Declaration

public const string RFD_YYYY_MM_DD_HH_MM_SS_TTT = null

Field Value

Type	Description
System.String

RFDHHMMSS

Apply the following format to a date and time: hhmmss

The returned string represents the hours on a 24 hour clock.

At present, 12 hour (AM/PM) representation is unsupported.

This format conforms fully to the ISO 8601 standard for time representation.

The hour, minute, and second have leading zeros if any of them is less than 10.

Declaration

public const string RFDHHMMSS = null

Field Value

Type	Description
System.String

RFDYYYYMMDD

Apply the following format to a date and time: YYYYMMDD

The returned string represents the hours on a 24 hour clock.

At present, 12 hour (AM/PM) representation is unsupported.

This format conforms fully to the ISO 8601 standard for time representation.

The month and day have leading zeros if either is less than 10.

Declaration

public const string RFDYYYYMMDD = null

Field Value

Type	Description
System.String

RFDYYYYMMDD_HHMMSS

Apply the following format to a date and time: YYYYMMDD_hhmmss

The returned string represents the hours on a 24 hour clock.

At present, 12 hour (AM/PM) representation is unsupported.

This format conforms fully to the ISO 8601 standard for time representation.

The month, day, hour, minute, and second have leading zeros if any of them is less than 10.

Declaration

public const string RFDYYYYMMDD_HHMMSS = null

Field Value

Type	Description
System.String

RSD_TOKENS

The strings in this array are the substitution tokens supported by the date formatters in this class.

Declaration

public static readonly string[] RSD_TOKENS

Field Value

Type	Description
System.String[]

STANDARD_DISPLAY_DATE_FORMAT

I use this with my SysDateFormatters class to format a date (sans time) so that it prints as YYYY/MM/DD.

IMPORTANT: This string specifically targets the methods in the SysDateFormatters class. SysDateFormatters strings are incompatible with ToString.

Declaration

public const string STANDARD_DISPLAY_DATE_FORMAT = null

Field Value

Type	Description
System.String

Examples

2014/09/04

STANDARD_DISPLAY_DATE_TIME_FORMAT

I use this with my SysDateFormatters class to format a date and time so that it prints as YYYY/MM/DD HH:MM:SS.

IMPORTANT: This string specifically targets the methods in the SysDateFormatters class. SysDateFormatters strings are incompatible with ToString.

Declaration

public const string STANDARD_DISPLAY_DATE_TIME_FORMAT = null

Field Value

Type	Description
System.String

Examples

2014/09/04 16:17:30

STANDARD_DISPLAY_TIME_FORMAT

I use this with my SysDateFormatters class to format a time (sans date) so that it prints as HH:MM:SS.

IMPORTANT: This string specifically targets the methods in the SysDateFormatters class. SysDateFormatters strings are incompatible with ToString.

Declaration

public const string STANDARD_DISPLAY_TIME_FORMAT = null

Field Value

Type	Description
System.String

Examples

16:17:30

TZ_NAME_ABBR

Declaration

public const bool TZ_NAME_ABBR = null

Field Value

Type	Description
System.Boolean

TZ_NAME_FULL

Specify this constant as the pfAbbreviateTZName argument value to method GetDisplayTimeZone to explicitly elicit the default (legacy) behavior of returning the system-defined (spelled out) time zone name.

Declaration

public const bool TZ_NAME_FULL = null

Field Value

Type	Description
System.Boolean

Methods

FormatDateForShow(DateTime)

Use my standard format string for displaying date stamps in reports, to format a DateTime structure.

Declaration

public static string FormatDateForShow(DateTime pdtmTestDate)

Parameters

Type	Name	Description
DateTime	pdtmTestDate	Specify the populated DateTime to be formatted. Since only the date goes into the format, the time component MAY be uninitialized.

Returns

Type	Description
System.String	The return value is a string representation of the date and time, rendered according to constant STANDARD_DISPLAY_TIME_FORMAT.

FormatDateTimeForShow(DateTime)

Use my standard format string for displaying date/time stamps in reports, to format a DateTime structure.

Declaration

public static string FormatDateTimeForShow(DateTime pdtmTestDate)

Parameters

Type	Name	Description
DateTime	pdtmTestDate	Specify the populated DateTime to be formatted. Since the date and time go into the output string, the entire structure must be initialized.

Returns

Type	Description
System.String	The return value is a string representation of the date and time, rendered according to constant STANDARD_DISPLAY_DATE_TIME_FORMAT.

FormatTimeForShow(DateTime)

Use my standard format string for displaying time stamps in reports, to format a DateTime structure.

Declaration

public static string FormatTimeForShow(DateTime pdtmTestDate)

Parameters

Type	Name	Description
DateTime	pdtmTestDate	Specify the populated DateTime to be formatted. Since only the time goes into the format, the date component MAY be uninitialized.

Returns

Type	Description
System.String	The return value is a string representation of the date and time, rendered according to constant STANDARD_DISPLAY_TIME_FORMAT.

GetDisplayTimeZone(DateTime, String, Boolean)

Given a DateTime and a system time zone ID string, return the appropriate text to display, depending on whether the specified time is standard or Daylight Saving Time.

Declaration

public static string GetDisplayTimeZone(DateTime pdtmTestDate, string pstrTimeZoneID, bool pfAbbreviateTZName = false)

Parameters

Type	Name	Description
DateTime	pdtmTestDate	Specify the Syatem.DateTime for which the appropriate time zone string is required. Both DateTime.MinValue and DateTime.MaxValue are invalid; specifying either elicits the empty string.
System.String	pstrTimeZoneID	Specify a valid time zone ID string. Please see the Remarks.
System.Boolean	pfAbbreviateTZName	Specify TZ_NAME_ABBR (Boolean True) to cause the method to return the abbreviated time zone name that it constructs from the full (spelled out) name that is the system default. You may also specify TZ_NAME_FULL to explicitly cause the full time zone name to be returned. If this argument is omitted, the full time zone name is returned, so that this method is backwards compatible.

Returns

Type	Description
System.String	If the function succeeds, the return value is the appropriate string to display for the given time. Otherwise, the empty string is returned or one of several exceptions is thrown, the most likely of which is a TimeZoneNotFoundException, which is thrown when the specified time zone ID string is invalid.

Remarks

if in doubt, use TimeZoneInfo.GetSystemTimeZones to enumerate the time zones installed on the local machine. Invalid time zone strings always give rise to one of a number of exceptions, all of which are fully described in the documentation of a companion function, GetSystemTimeZoneInfo which this routine uses to get the time zone information that it needs.

GetSystemTimeZoneInfo(String)

Given a system time zone ID string, return the corresponding TimeZoneInfo object if the specified time zone is defined on the local system.

Declaration

public static TimeZoneInfo GetSystemTimeZoneInfo(string pstrTimeZoneID)

Parameters

Type	Name	Description
System.String	pstrTimeZoneID	Specify a valid time zone ID string. There are two special IDs, LocalTime and UTC, both of which are accessible through static properties on the TimeZoneInfo class. Although you could use the ID properties with this method, the most efficient way to handle these special cases is by reference to the Local property for LocalTime and the UTC property for UTC time. (This method could take the same shortcut, but I decided that it wasn't worth the extra code and testing.

Returns

Type	Description
TimeZoneInfo	If the function succeeds, the return value is a TimeZoneInfo object, populated from the Windows Registry. Otherwise, one of the exceptions listed and described below is thrown.

Remarks

if in doubt, use TimeZoneInfo.GetSystemTimeZones to enumerate the time zones installed on the local machine.

ReformatNow(String)

This method has a nearly exact analogue in the constellations of WIL User Defined Functions that gave rise to its immediate predecessor, a like named function implemented in straight C, with a little help from the Windows National Language Subsystem, which underlies the CultureInfo class.

Declaration

public static string ReformatNow(string pstrFormat)

Parameters

Type	Name	Description
System.String	pstrFormat	This System.String is a combination of tokens and literal text that governs the formatting of the date.

Returns

Type	Description
System.String	The return value is a string containing the current date and time, formatted according to the rules spelled out in format string pstrFormat.

ReformatSysDate(DateTime, String)

ReformatSysDate is the core function of the constellation of routines that grew from the original WIL script. Substitution tokens drive construction of a formatted date string.

Declaration

public static string ReformatSysDate(DateTime pdtmToFormat, string pstrFormat)

Parameters

Type	Name	Description
DateTime	pdtmToFormat	This System.DateTime is the time to be formatted.
System.String	pstrFormat	This System.String is a combination of tokens and literal text that governs the formatting of the date.

Returns

Type	Description
System.String	The return value is a string containing the date and/or time in argument pdtmToFormat, formatted according to the rules spelled out in format string pstrFormat.

ReformatUtcNow(String)

In the original constellation of WinBatch functions and their C descendants, this function took the form of an optional argument to ReformatNow. I think I prefer this way.

Declaration

public static string ReformatUtcNow(string pstrFormat)

Parameters

Type	Name	Description
System.String	pstrFormat	This System.String is a combination of tokens and literal text that governs the formatting of the date.

Returns

Type	Description
System.String	The return value is a string containing the current UTC time, formatted according to the rules spelled out in format string pstrFormat.

See Also

DisplayFormats

TimeDisplayFormatter