} // public static string FormatTimeForShow
/// <summary>
/// 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.
/// </summary>
/// <param name="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.
/// </param>
/// <param name="pstrTimeZoneID">
/// Specify a valid time zone ID string. Please see the Remarks.
/// </param>
/// <param name="pfAbbreviateTZName">
/// <para>
/// 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.
/// </para>
/// <para>
/// You may also specify TZ_NAME_FULL to explicitly cause the full time
/// zone name to be returned.
/// </para>
/// <para>
/// If this argument is omitted, the full time zone name is returned, so
/// that this method is backwards compatible.
/// </para>
/// </param>
/// <returns>
/// 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.
/// </returns>
/// <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.
/// </remarks>
/// <see cref="GetSystemTimeZoneInfo"/>
public static string GetDisplayTimeZone (
DateTime pdtmTestDate ,
string pstrTimeZoneID ,
bool pfAbbreviateTZName = false )
{
if ( pdtmTestDate == DateTime.MinValue || pdtmTestDate == DateTime.MaxValue )
{ // Insufficient data available
return SpecialStrings.EMPTY_STRING;
} // TRUE (degenerate case) block, if ( pdtmTestDate == DateTime.MinValue || pdtmTestDate == DateTime.MaxValue || string.IsNullOrEmpty(pstrTimeZoneID) )
else
{
TimeZoneInfo tzinfo = GetSystemTimeZoneInfo ( pstrTimeZoneID );
if ( pfAbbreviateTZName )
{ // Use the new TimeZoneInfo extension methods to render abbreviated names.
return tzinfo.IsDaylightSavingTime ( pdtmTestDate ) ?
tzinfo.AbbreviateDaylightName ( ) :
tzinfo.AbbreviatedStandardName ( );
} // TRUE (Render abbreviated time zone names.) block, if ( pfAbbreviateTZName )
else
{ // Render the default time zone display names, which are spelled out. This is the legacy behavior.
return tzinfo.IsDaylightSavingTime ( pdtmTestDate ) ?
tzinfo.DaylightName :
tzinfo.StandardName;
} // TRUE (Render fully spelled out time zone names.) block, if ( pfAbbreviateTZName )
} // FALSE (desired outcome) block, if ( pdtmTestDate == DateTime.MinValue || pdtmTestDate == DateTime.MaxValue || string.IsNullOrEmpty(pstrTimeZoneID) )
} // public static string GetDisplayTimeZone