Class TimeDisplayFormatter

Use instances of this class to return dates and times, uniformly formatted by rules set by way of its properties.

This class is sealed, and cannot be inherited.

Inheritance

System.Object

TimeDisplayFormatter

Namespace: WizardWrx.Core

Assembly: WizardWrx.Core.dll

Syntax

public sealed class TimeDisplayFormatter : object

Constructors

TimeDisplayFormatter()

The default constructor initializes an instance that follows the default preferences built into the class. Hence, methods called on objects created by it are guaranteed to yield a usable string unless the DateTime value supplied to the method is, itself, invalid.

Declaration

public TimeDisplayFormatter()

Remarks

Rather than attempt to create the numerous constructors that would be required to cover every possible combination of properties, there is just one constructor. All properties are read-write. Use them to change the operating parameters.

If you always use the same combination of settings, you can wrap your own class around an instance of this one.

Properties

CalendarDateFormat

Set this property to override the default formatting of calendar dates, which is governed by the active CultureInfo settings, which are, themselves, governed by the active Regional Settings of the operating system.

Declaration

public TimeDisplayFormatter.DateFieldOrder CalendarDateFormat { get; set; }

Property Value

Type	Description
TimeDisplayFormatter.DateFieldOrder

HoursFormat

Set the display format for hours. See the HoursFormatType enumeration for more details.

When the value is DateFieldOrder.CultureInfoShortDate, the HoursFormat and TimePrecision properties are ignored.

The default format is Military, and the value must be a member of the HoursFormatType enumeration. If an invalid value is specified, a System.ArgumentOutOfRangeException exception is thrown, and the property value is unchanged.

When the value of this property is CultureInfoShortTime, the TimePrecision property is ignored.

Declaration

public TimeDisplayFormatter.HoursFormatType HoursFormat { get; set; }

Property Value

Type	Description
TimeDisplayFormatter.HoursFormatType

MachineTimeZone

This static property provides convenience access to the CurrentTimeZone property maintained in a static TimeZone instance for its own use.

Declaration

public static TimeZone MachineTimeZone { get; }

Property Value

Type	Description
TimeZone

ShowAmPmAsUC

Set this property to TRUE to have the AM and PM tokens displayed in upper case.

Unless the HoursFormat property is HoursFormatType.Civilian, this property is ignored.

Declaration

public bool ShowAmPmAsUC { get; set; }

Property Value

Type	Description
System.Boolean

ShowTimeZone

Set this property to TRUE to have the local time zone displayed with the time. By default, the time zone is omitted.

This property is applied independently of the HoursFormatType and Precision properties.

Declaration

public bool ShowTimeZone { get; set; }

Property Value

Type	Description
System.Boolean

ShowWeekday

Set this property to TRUE to have the local weekday name displayed with the time. By default, the weekday name is omitted.

This property is applied independently of the HoursFormatType and Precision properties.

Declaration

public bool ShowWeekday { get; set; }

Property Value

Type	Description
System.Boolean

TimePrecision

This property governs the precision used for time displays. The class default is HMST.

When the value of the HoursFormat property is CultureInfoShortTime, the value of this property is ignored.

For additional information, see the TimePrecisionType enumeration.

Declaration

public TimeDisplayFormatter.TimePrecisionType TimePrecision { get; set; }

Property Value

Type	Description
TimeDisplayFormatter.TimePrecisionType

Methods

FormatCurrentTime()

Format the current time.

Declaration

public string FormatCurrentTime()

Returns

Type	Description
System.String	The current time, formatted as dictated by the current settings of the properties of the class instance.

FormatThisTime(DateTime)

Format the specified time.

Declaration

public string FormatThisTime(DateTime pdtmThisTime)

Parameters

Type	Name	Description
DateTime	pdtmThisTime	The DateTime instance to format.

Returns

Type	Description
System.String	The input time, formatted as dictated by the current settings of the properties of the class instance.

GetTimeZoneForTime(DateTime)

Return the time zone name that corresponds to a local time.

Declaration

public static string GetTimeZoneForTime(DateTime pdtmTheTime)

Parameters

Type	Name	Description
DateTime	pdtmTheTime	Specify the System.DateTime for which the correct time zone string is required.

Returns

Type	Description
System.String	If the DateTimeKind of argument pdtmTheTime is Local, the return value is a string representation of the spelled out time zone name. Otherwise, an ArgumentException is thrown.

PrepareLocalAndUTCTimes(DateTime, DateTime)

Given a pair of DateTime structures, return them in a standardized format.

Declaration

public static string PrepareLocalAndUTCTimes(DateTime dtmTimeLocal, DateTime dtmTimeUtc)

Parameters

Type	Name	Description
DateTime	dtmTimeLocal	Specify the local time to include in the standardized message.
DateTime	dtmTimeUtc	Specify the UTC time to include in the standardized message.

Returns

Type	Description
System.String	The returned string is of the format {0} ({1} UTC), where {0} is replaced with the local time, while {1} is replaced with the corresponding UTC time.

Examples

2017/03/27 18:18:58 (2017/03/27 23:18:58 UTC)

See Also

DisplayFormats

SysDateFormatters