Click or drag to resize
OSIsoft, LLC

AFTimeSpan Structure

This is a structure which represents a time interval.

Namespace:  OSIsoft.AF.Time
Assembly:  OSIsoft.AFSDK (in OSIsoft.AFSDK.dll) Version: 2.10.6.195
Syntax
[SerializableAttribute]
public struct AFTimeSpan : IComparable, 
	IComparable<AFTimeSpan>, IEquatable<AFTimeSpan>

The AFTimeSpan type exposes the following members.

Constructors
  NameDescription
Public methodAFTimeSpan(TimeSpan)
Creates a new AFTimeSpan object from the specified TimeSpan.
Public methodAFTimeSpan(TimeSpan, AFTimeZone)
Creates a new AFTimeSpan object from the specified TimeSpan and AFTimeZone.
Public methodAFTimeSpan(Int32, Int32, Int32, Double, Double, Double, Double)
Creates a new AFTimeSpan object that optionally specifies the number of years, months, days, hours, minutes, seconds, and milliseconds.
Public methodAFTimeSpan(AFTimeZone, Int32, Int32, Int32, Double, Double, Double, Double)
Creates a new AFTimeSpan object from a specified AFTimeZone and optionally specifies the number of years, months, days, hours, minutes, seconds, and milliseconds.
Top
Properties
  NameDescription
Public propertyDays
Gets the days component of the time interval represented by the current AFTimeSpan structure.
Public propertyHours
Gets the fixed hours component of the time interval represented by the current AFTimeSpan structure.
Public propertyIsNegative
Indicates if the current AFTimeSpan represents a negative span.
Public propertyMilliseconds
Gets the milliseconds component of the time interval represented by the current AFTimeSpan structure.
Public propertyMinutes
Gets the fixed minutes component of the time interval represented by the current AFTimeSpan structure.
Public propertyMonths
Gets the months component of the time interval represented by the current AFTimeSpan structure.
Public propertySeconds
Gets the seconds component of the time interval represented by the current AFTimeSpan structure.
Public propertyTicks
Get the number of ticks that represent the value of the current AFTimeSpan structure.
Public propertyTimeZone
Indicates the time zone of the current AFTimeSpan used to do time arithmetic.
Public propertyYears
Gets the years component of the time interval represented by the current AFTimeSpan structure.
Top
Methods
  NameDescription
Public methodAdd
Add the time span to the specified time.
Public methodCompareTo(Object)
Compares this instance with a specified Object.
Public methodCompareTo(AFTimeSpan)
Compares this instance with a specified AFTimeSpan.
Public methodDuration
Returns a new AFTimeSpan object whose value is the absolute value of the current AFTimeSpan object.
Public methodEquals(Object)
Determines whether the specified Object is equal to the current object.
(Overrides ValueTypeEquals(Object).)
Public methodEquals(AFTimeSpan)
Indicates whether the current object is equal to another object of the same type.
Public methodGetEvenTimeIntervalDefinitions
Get the list of evenly spaced interval definitions that are within the specified AFTimeRange.
Public methodGetHashCode
Gets the hash code for this instance of the object which is suitable for use in hashing algorithms and data structures like a hash table.
(Overrides ValueTypeGetHashCode.)
Public methodGetIntervalTimes
Get the list of interval times for the specified AFTimeRange.
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodMultiply
Multiply the time span by the specified factor from the specified time.
Public methodNegate
Returns a AFTimeSpan whose value is the negated value of this instance.
Public methodStatic memberParse(String, IFormatProvider)
Converts the string representation of a time interval to its AFTimeSpan equivalent.
Public methodStatic memberParse(String, AFTimeZone, IFormatProvider)
Converts the string representation of a time interval to its AFTimeSpan equivalent with a specified AFTimeZone.
Public methodToString
Returns a String that represents the current object.
(Overrides ValueTypeToString.)
Public methodToString(IFormatProvider)
Returns a String that represents the current object.
Public methodToString(IFormatProvider, Boolean)
Returns a String that represents the current object.
Public methodToTimeSpan
Returns the time span as a standard TimeSpan object.
Public methodStatic memberTryParse(String, AFTimeSpan)
Converts the string representation of a time interval to its AFTimeSpan equivalent by using the CurrentCulture and returns a value that indicates whether the conversion succeeded.
Public methodStatic memberTryParse(String, IFormatProvider, AFTimeSpan)
Converts the string representation of a time interval to its AFTimeSpan equivalent by using the specified culture-specific formatting information and returns a value that indicates whether the conversion succeeded.
Public methodStatic memberTryParse(String, IFormatProvider, AFTimeZone, AFTimeSpan)
Converts the string representation of a time interval to its AFTimeSpan equivalent with a specified AFTimeZone by using the specified culture-specific formatting information and returns a value that indicates whether the conversion succeeded.
Top
Operators
  NameDescription
Public operatorStatic memberEquality
The equality operator (==) compares its operands to determine if they are equal.
Public operatorStatic memberGreaterThan
The greater than relation operator (>) compares its operands to determine which one is greater than the other.
Public operatorStatic memberGreaterThanOrEqual
The greater than or equal relation operator (>=) compares its operands to determine which one is greater than or equal to the other.
Public operatorStatic memberInequality
The inequality operator (!=) compares its operands to determine if they are not equal.
Public operatorStatic memberLessThan
The less than relation operator (<) compares its operands to determine which one is less than the other.
Public operatorStatic memberLessThanOrEqual
The less than or equal relation operator (<=) compares its operands to determine which one is less than or equal to the other.
Top
Fields
  NameDescription
Public fieldStatic memberZero
Represents the zero AFTimeSpan value.
Top
Remarks

A AFTimeSpan represents a time interval (duration of time or elapsed time) that is measured as a positive or negative number of years, months, days, hours, minutes, seconds, milliseconds, and fractions of a millisecond. The AFTimeSpan can also be used to represent the time of day, but only if the time is unrelated to a particular date. Otherwise, AFTime should be used instead.

A time interval in units of time larger than hours (i.e. days, months, and years) will represent a varying interval length depending upon the local time specified when calling the Add(AFTime) or Multiply(AFTime, Int32) methods. A time interval specified in days will represent a varying number of hours depending upon the local time specified and daylight savings rules in effect when calling the Add(AFTime) or Multiply(AFTime, Int32) methods. Time intervals of smaller units of time will represent a fixed interval. See Add(AFTime) or Multiply(AFTime, Int32) for more information about time arithmetic.

The time interval specification is in one of the following forms:

[+|-]<number>[.<number>] <interval> { [+|-]<number>[.<number>] <interval> }*

or

[+|-]{ hh | [hh][:[mm][:ss[.ff]]] }

Elements in square brackets ([ and ]) are optional. Alternatives are separated by a vertical bar (|). A star (*) after a group enclosed in braces ({ and }) indicates that zero or more instances of the group is allowed. The '+' or '-' operators are optional and if not specified defaults to the '+' (e.g. '5h10m' is the same as '5h+10m'). If only a number is specified (e.g. '10'), then it would match the second form and be interpreted as the number of hours.

The following table describes each element.

ElementDescription
<number> A number consisting of one or more digits.
<interval> The name, short name, or plural name of a standard interval. The table below defines the standard intervals.
+ An optional plus sign, which indicates a positive AFTimeSpan value.
- An optional minus sign, which indicates a negative AFTimeSpan value.
. A culture-sensitive symbol that separates seconds from fractions of a second. The invariant format uses a period (".") character.
hh Hours. If hours are omitted, then time separator must be specified before the minutes.
: A culture-sensitive time separator symbol. The invariant format uses a colon (":") character.
mm Optional minutes.
ss Optional seconds.
ff Optional fractional seconds.
Note Notes to Callers
Some formats with missing hours, minutes, and/or seconds that were supported by PI Time are not supported. For example "hh:mm" is supported, but "hh::ss", ":mm:ss", and "::s" are some formats that are not supported. The format must be supported by the DateTime.TryParse method.

This is a table of the standard intervals. Either the plural full name, non-plural full name, or short name can be used as the name of the interval. The 'Fractions Allowed' column indicates if a fractional value is allowed for the interval type.

NameShort NameFractions Allowed
millisecond(s)msYes
second(s)sYes
minute(s)mYes
hour(s)hYes
day(s)dNo
month(s)moNo
year(s)yNo
week(s)wNo
weekday(s)wdNo
yearday(s)ydNo

Arithmetic with time may be done in UTC time or in local time depending on how the time span was defined. Due to some regions using daylight savings time, calendars with leap years and interval units that vary in length (e.g. month), arithmetic increments in local time may not change uniformly. Since UTC time do not adjust for daylight savings time, arithmetic increments in UTC time change in uniform step sizes.

UTC time as used in AF is actually TAI time (Temps Atomique International, or atomic clock time). True UTC time includes leap seconds. Leap seconds introduce variable interval durations for all intervals greater than seconds. For time arithmetic in AF, adding or subtracting time in UTC units may be done by converting all intervals to seconds. For example, adding 24 hours is equivalent to adding 86400 seconds. Additionally, only UTC arithmetic is capable of fractional interval steps. Adding 1.5 hours is equivalent to adding 5400 seconds. Intervals year, month, and day do not allow fractions because they are variable length. For example, adding a fraction of a month would require choosing between a month containing 28, 29, 30, or 31 days.

Local time is also known as wall clock time. Daylight savings time may cause a discontinuity in time and is observed by many regions. This may cause intervals and durations to vary during the daylight savings changes. Depending on the desired result, calculations based on such durations may be done in UTC or local time depending on how the AFTimeSpan is defined. The AFTime objects can provide UTC seconds for calculating durations or local date (in units of days).

Local time addition of days may cover 24 hours or sometimes 23 or 25 hours. If a local time calculation causes the resultant local time to fall within the spring standard to daylight transition, the time is illegal. Rather than return an error, the time in the previous hour is returned. Specifying a time or a time calculation that produces a local time in the ambiguous hour in the fall will result in using the current system's daylight or standard setting.

The addition of months to a given day may cause the day to be out of range for the next month. For instance, March 31 + 1 month would result in April 30 if the Add(AFTime) method is used. The assumption is that the end of the month is desired. Thus, if a sequence of times of the end of the month is desired, a start time of January 31 + # months should be used for each time in the sequence. A cumulative addition will result in January 31, February 28, March 28, etc. (unless it is a leap year, in which case the 29th of all months after January would result).

Adding years will typically result in the same day of the resultant year. However, adding one year from the leap year day Feb 29, will result in Feb 28 of the following year.

Examples
// This example shows how to create an AFTimeSpan and
// use it to add intervals to AFTime.

// Create AFTimeSpan using constructor
AFTime now = AFTime.Now;
AFTimeSpan span = new AFTimeSpan(hours: 12, minutes: 30);
AFTime newTime = span.Add(now);
Console.WriteLine("TimeSpan = '{0}', Now+Span = '{1}'",
    span, newTime.LocalTime);

// Plus one day
span = AFTimeSpan.Parse("1d");
newTime = span.Add(now);
Console.WriteLine("TimeSpan = '{0}', Now+Span = '{1}'",
    span, newTime.LocalTime);

// Minus one day
span = AFTimeSpan.Parse("-1 Day");
newTime = span.Add(now);
Console.WriteLine("TimeSpan = '{0}', Now+Span = '{1}'",
    span, newTime.LocalTime);

// A combination of intervals
span = AFTimeSpan.Parse("+3y-2mo+6hours - 15m+30s15ms");
newTime = span.Add(now);
Console.WriteLine("TimeSpan = '{0}', Now+Span = '{1}'",
    span, newTime.LocalTime);

// A time format interval with omitted minutes
span = AFTimeSpan.Parse("-6::30.56");
newTime = span.Add(now);
Console.WriteLine("TimeSpan = '{0}', Now+Span = '{1}'",
    span, newTime.LocalTime);

// Create an AFTimeSpan without throwing an exception for an invalid string
string input = "Y+4dd";
AFTimeSpan result;
if (!AFTimeSpan.TryParse(input, out result))
    Console.WriteLine("Input '{0}' was not valid.", input);
else
    Console.WriteLine("Input '{0}' = '{1}'", input, result);
Version Information

AFSDK

Supported in: 2.10.5, 2.10, 2.9.5, 2.9, 2.8.5, 2.8, 2.7.5, 2.7, 2.6, 2.5, 2.4
See Also
Enabling Operational Intelligence