AF SDK Reference

AFTimeSpan Structure

Save PDF

TABLE OF CONTENTS

AFTimeSpan Structure

Save PDF

Last UpdatedNov 18, 2025
13 minute read

This is a structure which represents a time interval.

Namespace: OSIsoft.AF.Time
Assembly: OSIsoft.AFSDK (in OSIsoft.AFSDK.dll) Version: 3.1.1.1182

Syntax

[SerializableAttribute]
public struct AFTimeSpan : IComparable, 
	IComparable<AFTimeSpan>, IEquatable<AFTimeSpan>

<SerializableAttribute>
Public Structure AFTimeSpan
	Implements IComparable, IComparable(Of AFTimeSpan), 
	IEquatable(Of AFTimeSpan)

Dim instance As AFTimeSpan

[SerializableAttribute]
public value class AFTimeSpan : IComparable, 
	IComparable<AFTimeSpan>, IEquatable<AFTimeSpan>

[<SealedAttribute>]
[<SerializableAttribute>]
type AFTimeSpan =  
    struct
        interface IComparable
        interface IComparable<AFTimeSpan>
        interface IEquatable<AFTimeSpan>
    end

The AFTimeSpan type exposes the following members.

Constructors

	Name	Description
	AFTimeSpan(TimeSpan)	Creates a new AFTimeSpan object from the specified TimeSpan.
	AFTimeSpan(TimeSpan, AFTimeZone)	Creates a new AFTimeSpan object from the specified TimeSpan and AFTimeZone.
	AFTimeSpan(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.
	AFTimeSpan(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.

Properties

	Name	Description
	Days	Gets the days component of the time interval represented by the current AFTimeSpan structure.
	Hours	Gets the fixed hours component of the time interval represented by the current AFTimeSpan structure.
	IsNegative	Indicates if the current AFTimeSpan represents a negative span.
	Milliseconds	Gets the milliseconds component of the time interval represented by the current AFTimeSpan structure.
	Minutes	Gets the fixed minutes component of the time interval represented by the current AFTimeSpan structure.
	Months	Gets the months component of the time interval represented by the current AFTimeSpan structure.
	Seconds	Gets the seconds component of the time interval represented by the current AFTimeSpan structure.
	Ticks	Get the number of ticks that represent the value of the current AFTimeSpan structure.
	TimeZone	Indicates the time zone of the current AFTimeSpan used to do time arithmetic.
	Years	Gets the years component of the time interval represented by the current AFTimeSpan structure.

Methods

	Name	Description
	Add	Add the time span to the specified time.
	CompareTo(Object)	Compares this instance with a specified Object.
	CompareTo(AFTimeSpan)	Compares this instance with a specified AFTimeSpan.
	Duration	Returns a new AFTimeSpan object whose value is the absolute value of the current AFTimeSpan object.
	Equals(Object)	Determines whether the specified Object is equal to the current object. (Overrides ValueTypeEquals(Object).)
	Equals(AFTimeSpan)	Indicates whether the current object is equal to another object of the same type.
	GetEvenTimeIntervalDefinitions	Get the list of evenly spaced interval definitions that are within the specified AFTimeRange.
	GetHashCode	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.)
	GetIntervalTimes	Get the list of interval times for the specified AFTimeRange.
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	Multiply	Multiply the time span by the specified factor from the specified time.
	Negate	Returns a AFTimeSpan whose value is the negated value of this instance.
	Parse(String, IFormatProvider)	Converts the string representation of a time interval to its AFTimeSpan equivalent.
	Parse(String, AFTimeZone, IFormatProvider)	Converts the string representation of a time interval to its AFTimeSpan equivalent with a specified AFTimeZone.
	ToString	Returns a String that represents the current object. (Overrides ValueTypeToString.)
	ToString(IFormatProvider)	Returns a String that represents the current object.
	ToString(IFormatProvider, Boolean)	Returns a String that represents the current object.
	ToTimeSpan	Returns the time span as a standard TimeSpan object.
	TryParse(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.
	TryParse(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.
	TryParse(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.

Operators

	Name	Description
	Equality	The equality operator (==) compares its operands to determine if they are equal.
	GreaterThan	The greater than relation operator (>) compares its operands to determine which one is greater than the other.
	GreaterThanOrEqual	The greater than or equal relation operator (>=) compares its operands to determine which one is greater than or equal to the other.
	Inequality	The inequality operator (!=) compares its operands to determine if they are not equal.
	LessThan	The less than relation operator (<) compares its operands to determine which one is less than the other.
	LessThanOrEqual	The less than or equal relation operator (<=) compares its operands to determine which one is less than or equal to the other.

Fields

	Name	Description
	Zero	Represents the zero AFTimeSpan value.

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> }*

[+|-]{ 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.

Element	Description
<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.

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.

Name	Short Name	Fractions Allowed
millisecond(s)	ms	Yes
second(s)	s	Yes
minute(s)	m	Yes
hour(s)	h	Yes
day(s)	d	No
month(s)	mo	No
year(s)	y	No
week(s)	w	No
weekday(s)	wd	No
yearday(s)	yd	No

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);

' This example shows how to use the AFTimeSpan class
' to add intervals to AFTime.

' Create AFTimeSpan using constructor
Dim now As AFTime = AFTime.Now
Dim span As AFTimeSpan = New AFTimeSpan(hours:=12, minutes:=30)
Dim newTime As AFTime = 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
Dim input As String = "Y+4dd"
Dim result As AFTimeSpan
If Not AFTimeSpan.TryParse(input, result) Then
    Console.WriteLine("Input '{0}' was not valid.", input)
Else
    Console.WriteLine("Input '{0}' = '{1}'", input, result)
End If

No code example is currently available or this language may not be supported.

AF SDK Reference