//******************************************************************************************************//  DateTimeExtensions.cs - Gbtc////  Copyright © 2012, Grid Protection Alliance.  All Rights Reserved.////  Licensed to the Grid Protection Alliance (GPA) under one or more contributor license agreements. See//  the NOTICE file distributed with this work for additional information regarding copyright ownership.//  The GPA licenses this file to you under the MIT License (MIT), the "License"; you may//  not use this file except in compliance with the License. You may obtain a copy of the License at:////      http://www.opensource.org/licenses/MIT////  Unless agreed to in writing, the subject software distributed under the License is distributed on an//  "AS-IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. Refer to the//  License for the specific language governing permissions and limitations.////  Code Modification History://  ----------------------------------------------------------------------------------------------------//  02/23/2003 - J. Ritchie Carroll//       Generated original version of source code.//  12/21/2005 - J. Ritchie Carroll//       Migrated 2.0 version of source code from 1.1 source (GSF.Shared.DateTime).//  08/31/2007 - Darrell Zuercher//       Edited code comments.//  09/08/2008 - J. Ritchie Carroll//       Converted to C# extensions.//  02/16/2009 - Josh L. Patterson//       Edited Code Comments.//  09/14/2009 - Stephen C. Wills//       Added new header and license agreement.//  01/06/2010 - Andrew K. Hill//       Modified the following methods per unit testing://       LocalTimeTo(DateTime, string)//       LocalTimeTo(DateTime, TimeZoneInfo)//       UniversalTimeTo(DateTime, string)//       UniversalTimeTo(DateTime, TimeZoneInfo)//       TimeZoneToTimeZone(DateTime, string, string)//       TimeZoneToTimeZone(DateTime, TimeZoneInfo, TimeZoneInfo)//  12/14/2012 - Starlynn Danyelle Gilliam//       Modified Header.////****************************************************************************************************** using System;using System.Globalization; namespace GSF{    /// <summary>    /// Defines extension functions related to Date/Time manipulation.    /// </summary>    public static class DateTimeExtensions    {        /// <summary>Determines if the specified UTC time is valid, by comparing it to the system clock.</summary>        /// <param name="utcTime">UTC time to test for validity.</param>        /// <param name="lagTime">The allowed lag time, in seconds, before assuming time is too old to be valid.</param>        /// <param name="leadTime">The allowed lead time, in seconds, before assuming time is too advanced to be        /// valid.</param>        /// <returns>True, if time is within the specified range.</returns>        /// <remarks>        /// <para>Time is considered valid if it exists within the specified lag time/lead time range of current        /// time.</para>        /// <para>Note that lag time and lead time must be greater than zero, but can be set to sub-second        /// intervals.</para>        /// </remarks>        /// <exception cref="ArgumentOutOfRangeException">LagTime and LeadTime must be greater than zero, but can        /// be less than one.</exception>        public static bool UtcTimeIsValid(this DateTime utcTime, double lagTime, double leadTime)        {            return ((Ticks)utcTime).UtcTimeIsValid(lagTime, leadTime);        }         /// <summary>Determines if the specified local time is valid, by comparing it to the system clock.</summary>        /// <param name="localTime">Time to test for validity.</param>        /// <param name="lagTime">The allowed lag time, in seconds, before assuming time is too old to be valid.</param>        /// <param name="leadTime">The allowed lead time, in seconds, before assuming time is too advanced to be        /// valid.</param>        /// <returns>True, if time is within the specified range.</returns>        /// <remarks>        /// <para>Time is considered valid if it exists within the specified lag time/lead time range of current        /// time.</para>        /// <para>Note that lag time and lead time must be greater than zero, but can be set to sub-second        /// intervals.</para>        /// </remarks>        /// <exception cref="ArgumentOutOfRangeException">LagTime and LeadTime must be greater than zero, but can        /// be less than one.</exception>        public static bool LocalTimeIsValid(this DateTime localTime, double lagTime, double leadTime)        {            return ((Ticks)localTime).LocalTimeIsValid(lagTime, leadTime);        }         /// <summary>Determines if time is valid, by comparing it to the specified current time.</summary>        /// <param name="testTime">Time to test for validity.</param>        /// <param name="currentTime">Specified current time (e.g., could be Date.Now or Date.UtcNow).</param>        /// <param name="lagTime">The allowed lag time, in seconds, before assuming time is too old to be valid.</param>        /// <param name="leadTime">The allowed lead time, in seconds, before assuming time is too advanced to be        /// valid.</param>        /// <returns>True, if time is within the specified range.</returns>        /// <remarks>        /// <para>Time is considered valid if it exists within the specified lag time/lead time range of current        /// time.</para>        /// <para>Note that lag time and lead time must be greater than zero, but can be set to sub-second        /// intervals.</para>        /// </remarks>        /// <exception cref="ArgumentOutOfRangeException">LagTime and LeadTime must be greater than zero, but can        /// be less than one.</exception>        public static bool TimeIsValid(this DateTime testTime, DateTime currentTime, double lagTime, double leadTime)        {            return ((Ticks)testTime).TimeIsValid(currentTime, lagTime, leadTime);        }          /// <summary>Gets the distance, in <see cref="Ticks"/>, beyond the top of the <paramref name="timestamp"/> second.</summary>        /// <param name="timestamp">Timestamp to evaluate.</param>        /// <returns>Timestamp's tick distance from the top of the second.</returns>        public static Ticks DistanceBeyondSecond(this DateTime timestamp)        {            return ((Ticks)timestamp).DistanceBeyondSecond();        }         /// <summary>Creates a baselined timestamp which begins at the specified time interval.</summary>        /// <param name="timestamp">Timestamp to baseline.</param>        /// <param name="interval">        /// <see cref="BaselineTimeInterval"/> to which <paramref name="timestamp"/> should be baselined.        /// </param>        /// <returns>        /// A new <see cref="DateTime"/> value that represents a baselined timestamp that begins at the        /// specified <see cref="BaselineTimeInterval"/>.        /// </returns>        /// <remarks>        /// Baselining to the <see cref="BaselineTimeInterval.Second"/> would return the <see cref="DateTime"/>        /// value starting at zero milliseconds.<br/>        /// Baselining to the <see cref="BaselineTimeInterval.Minute"/> would return the <see cref="DateTime"/>        /// value starting at zero seconds and milliseconds.<br/>        /// Baselining to the <see cref="BaselineTimeInterval.Hour"/> would return the <see cref="DateTime"/>        /// value starting at zero minutes, seconds and milliseconds.<br/>        /// Baselining to the <see cref="BaselineTimeInterval.Day"/> would return the <see cref="DateTime"/>        /// value starting at zero hours, minutes, seconds and milliseconds.<br/>        /// Baselining to the <see cref="BaselineTimeInterval.Month"/> would return the <see cref="DateTime"/>        /// value starting at day one, zero hours, minutes, seconds and milliseconds.<br/>        /// Baselining to the <see cref="BaselineTimeInterval.Year"/> would return the <see cref="DateTime"/>        /// value starting at month one, day one, zero hours, minutes, seconds and milliseconds.        /// </remarks>        public static DateTime BaselinedTimestamp(this DateTime timestamp, BaselineTimeInterval interval)        {            return ((Ticks)timestamp).BaselinedTimestamp(interval);        }         /// <summary>Converts given local time to Eastern time.</summary>        /// <param name="timestamp">Timestamp in local time to be converted to Eastern time.</param>        /// <returns>        /// <para>Timestamp in Eastern time.</para>        /// </returns>        public static DateTime LocalTimeToEasternTime(this DateTime timestamp)        {            return TimeZoneInfo.ConvertTime(timestamp, TimeZoneInfo.Local, USTimeZones.Eastern);        }         /// <summary>Converts given local time to Central time.</summary>        /// <param name="timestamp">Timestamp in local time to be converted to Central time.</param>        /// <returns>        /// <para>Timestamp in Central time.</para>        /// </returns>        public static DateTime LocalTimeToCentralTime(this DateTime timestamp)        {            return TimeZoneInfo.ConvertTime(timestamp, TimeZoneInfo.Local, USTimeZones.Central);        }         /// <summary>Converts given local time to Mountain time.</summary>        /// <param name="timestamp">Timestamp in local time to be converted to Mountain time.</param>        /// <returns>        /// <para>Timestamp in Mountain time.</para>        /// </returns>        public static DateTime LocalTimeToMountainTime(this DateTime timestamp)        {            return TimeZoneInfo.ConvertTime(timestamp, TimeZoneInfo.Local, USTimeZones.Mountain);        }         /// <summary>Converts given local time to Pacific time.</summary>        /// <param name="timestamp">Timestamp in local time to be converted to Pacific time.</param>        /// <returns>        /// <para>Timestamp in Pacific time.</para>        /// </returns>        public static DateTime LocalTimeToPacificTime(this DateTime timestamp)        {            return TimeZoneInfo.ConvertTime(timestamp, TimeZoneInfo.Local, USTimeZones.Pacific);        }         /// <summary>Converts given local time to Universally Coordinated Time (a.k.a., Greenwich Meridian Time).</summary>        /// <remarks>This function is only provided for the sake of completeness. All it does is call the        /// "ToUniversalTime" property on the given timestamp.</remarks>        /// <param name="timestamp">Timestamp in local time to be converted to Universal time.</param>        /// <returns>        /// <para>Timestamp in UniversalTime (a.k.a., GMT).</para>        /// </returns>        public static DateTime LocalTimeToUniversalTime(this DateTime timestamp)        {            return timestamp.ToUniversalTime();        }         /// <summary>Converts given local time to time in specified time zone.</summary>        /// <param name="timestamp">Timestamp in local time to be converted to time in specified time zone.</param>        /// <param name="destinationTimeZoneStandardName">Standard name of desired end time zone for given        /// timestamp.</param>        /// <returns>        /// <para>Timestamp in specified time zone.</para>        /// </returns>        public static DateTime LocalTimeTo(this DateTime timestamp, string destinationTimeZoneStandardName)        {            if ((object)destinationTimeZoneStandardName == null)                throw new ArgumentNullException("destinationTimeZoneStandardName");             return TimeZoneInfo.ConvertTime(timestamp, TimeZoneInfo.Local, TimeZoneInfo.FindSystemTimeZoneById(destinationTimeZoneStandardName));        }         /// <summary>Converts given local time to time in specified time zone.</summary>        /// <param name="timestamp">Timestamp in local time to be converted to time in specified time zone.</param>        /// <param name="destinationTimeZone">Desired end time zone for given timestamp.</param>        /// <returns>        /// <para>Timestamp in specified time zone.</para>        /// </returns>        public static DateTime LocalTimeTo(this DateTime timestamp, TimeZoneInfo destinationTimeZone)        {            if ((object)destinationTimeZone == null)                throw new ArgumentNullException("destinationTimeZone");             return TimeZoneInfo.ConvertTime(timestamp, TimeZoneInfo.Local, destinationTimeZone);        }         /// <summary>        /// Converts the specified Universally Coordinated Time timestamp to Eastern time timestamp.        /// </summary>        /// <param name="universalTimestamp">The Universally Coordinated Time timestamp that is to be converted.</param>        /// <returns>The timestamp in Eastern time.</returns>        public static DateTime UniversalTimeToEasternTime(this DateTime universalTimestamp)        {            return TimeZoneInfo.ConvertTime(universalTimestamp, TimeZoneInfo.Utc, USTimeZones.Eastern);        }         /// <summary>        /// Converts the specified Universally Coordinated Time timestamp to Central time timestamp.        /// </summary>        /// <param name="universalTimestamp">The Universally Coordinated Time timestamp that is to be converted.</param>        /// <returns>The timestamp in Central time.</returns>        public static DateTime UniversalTimeToCentralTime(this DateTime universalTimestamp)        {            return TimeZoneInfo.ConvertTime(universalTimestamp, TimeZoneInfo.Utc, USTimeZones.Central);        }         /// <summary>        /// Converts the specified Universally Coordinated Time timestamp to Mountain time timestamp.        /// </summary>        /// <param name="universalTimestamp">The Universally Coordinated Time timestamp that is to be converted.</param>        /// <returns>The timestamp in Mountain time.</returns>        public static DateTime UniversalTimeToMountainTime(this DateTime universalTimestamp)        {            return TimeZoneInfo.ConvertTime(universalTimestamp, TimeZoneInfo.Utc, USTimeZones.Mountain);        }         /// <summary>        /// Converts the specified Universally Coordinated Time timestamp to Pacific time timestamp.        /// </summary>        /// <param name="universalTimestamp">The Universally Coordinated Time timestamp that is to be converted.</param>        /// <returns>The timestamp in Pacific time.</returns>        public static DateTime UniversalTimeToPacificTime(this DateTime universalTimestamp)        {            return TimeZoneInfo.ConvertTime(universalTimestamp, TimeZoneInfo.Utc, USTimeZones.Pacific);        }         /// <summary>        /// Converts the specified Universally Coordinated Time timestamp to timestamp in specified time zone.        /// </summary>        /// <param name="universalTimestamp">The Universally Coordinated Time timestamp that is to be converted.</param>        /// <param name="destinationTimeZoneStandardName">The time zone standard name to which the Universally        /// Coordinated Time timestamp is to be converted to.</param>        /// <returns>The timestamp in the specified time zone.</returns>        public static DateTime UniversalTimeTo(this DateTime universalTimestamp, string destinationTimeZoneStandardName)        {            if ((object)destinationTimeZoneStandardName == null)                throw new ArgumentNullException("destinationTimeZoneStandardName");             return TimeZoneInfo.ConvertTime(universalTimestamp, TimeZoneInfo.Utc, TimeZoneInfo.FindSystemTimeZoneById(destinationTimeZoneStandardName));        }         /// <summary>        /// Converts the specified Universally Coordinated Time timestamp to timestamp in specified time zone.        /// </summary>        /// <param name="universalTimestamp">The Universally Coordinated Time timestamp that is to be converted.</param>        /// <param name="destinationTimeZone">The time zone to which the Universally Coordinated Time timestamp        /// is to be converted to.</param>        /// <returns>The timestamp in the specified time zone.</returns>        public static DateTime UniversalTimeTo(this DateTime universalTimestamp, TimeZoneInfo destinationTimeZone)        {            if ((object)destinationTimeZone == null)                throw new ArgumentNullException("destinationTimeZone");             return TimeZoneInfo.ConvertTime(universalTimestamp, TimeZoneInfo.Utc, destinationTimeZone);        }         /// <summary>Converts given timestamp from one time zone to another using standard names for time zones.</summary>        /// <param name="timestamp">Timestamp in source time zone to be converted to time in destination time zone.</param>        /// <param name="sourceTimeZoneStandardName">Standard name of time zone for given source timestamp.</param>        /// <param name="destinationTimeZoneStandardName">Standard name of desired end time zone for given source        /// timestamp.</param>        /// <returns>        /// <para>Timestamp in destination time zone.</para>        /// </returns>        public static DateTime TimeZoneToTimeZone(this DateTime timestamp, string sourceTimeZoneStandardName, string destinationTimeZoneStandardName)        {            if ((object)sourceTimeZoneStandardName == null)                throw new ArgumentNullException("sourceTimeZoneStandardName");             if ((object)destinationTimeZoneStandardName == null)                throw new ArgumentNullException("destinationTimeZoneStandardName");             return TimeZoneInfo.ConvertTime(timestamp, TimeZoneInfo.FindSystemTimeZoneById(sourceTimeZoneStandardName), TimeZoneInfo.FindSystemTimeZoneById(destinationTimeZoneStandardName));        }         /// <summary>Converts given timestamp from one time zone to another.</summary>        /// <param name="timestamp">Timestamp in source time zone to be converted to time in destination time        /// zone.</param>        /// <param name="sourceTimeZone">Time zone for given source timestamp.</param>        /// <param name="destinationTimeZone">Desired end time zone for given source timestamp.</param>        /// <returns>        /// <para>Timestamp in destination time zone.</para>        /// </returns>        public static DateTime TimeZoneToTimeZone(this DateTime timestamp, TimeZoneInfo sourceTimeZone, TimeZoneInfo destinationTimeZone)        {            if ((object)sourceTimeZone == null)                throw new ArgumentNullException("sourceTimeZone");             if ((object)destinationTimeZone == null)                throw new ArgumentNullException("destinationTimeZone");             return TimeZoneInfo.ConvertTime(timestamp, sourceTimeZone, destinationTimeZone);        }         /// <summary>Gets the abbreviated month name for month of the timestamp.</summary>        /// <param name="timestamp">Timestamp from which month name is extracted.</param>        /// <returns>String representation of the month name based on <paramref name="timestamp"/></returns>        public static string AbbreviatedMonthName(this DateTime timestamp)        {            return DateTimeFormatInfo.CurrentInfo.GetAbbreviatedMonthName(timestamp.Month);        }         /// <summary>Gets the full month name for month of the timestamp.</summary>        /// <param name="timestamp">Timestamp from which month name is extracted.</param>        /// <returns>String representation of the month name based on <paramref name="timestamp"/></returns>        public static string MonthName(this DateTime timestamp)        {            return DateTimeFormatInfo.CurrentInfo.GetMonthName(timestamp.Month);        }         /// <summary>Gets the abbreviated weekday name for weekday of the timestamp.</summary>        /// <param name="timestamp">Timestamp from which weekday name is extracted.</param>        /// <returns>String representation of the weekday name based on <paramref name="timestamp"/></returns>        public static string AbbreviatedWeekdayName(this DateTime timestamp)        {            return DateTimeFormatInfo.CurrentInfo.GetAbbreviatedDayName(timestamp.DayOfWeek);        }         /// <summary>Gets the shortest weekday name for weekday of the timestamp.</summary>        /// <param name="timestamp">Timestamp from which weekday name is extracted.</param>        /// <returns>String representation of the short weekday name based on <paramref name="timestamp"/></returns>        public static string ShortWeekdayName(this DateTime timestamp)        {            return DateTimeFormatInfo.CurrentInfo.GetShortestDayName(timestamp.DayOfWeek);        }         /// <summary>Gets the full weekday name for weekday of the timestamp.</summary>        /// <param name="timestamp">Timestamp from which weekday name is extracted.</param>        /// <returns>String representation of the weekday name based on <paramref name="timestamp"/></returns>        public static string WeekdayName(this DateTime timestamp)        {            return DateTimeFormatInfo.CurrentInfo.GetDayName(timestamp.DayOfWeek);        }    }}