Click or drag to resize
OSIsoft, LLC

AFTimeRangeTryParse Method (String, String, IFormatProvider, AFTimeRange)

Converts the specified local date and time string representations of the start and end times to its AFTimeRange equivalent by using the specified culture-specific formatting information and returns a value that indicates whether the conversion succeeded.

Namespace:  OSIsoft.AF.Time
Assembly:  OSIsoft.AFSDK (in OSIsoft.AFSDK.dll) Version: 2.10.6.195
Syntax
public static bool TryParse(
	string startTime,
	string endTime,
	IFormatProvider provider,
	out AFTimeRange result
)

Parameters

startTime
Type: SystemString

The starting time of the time range represented by this object, specified in a string format. Strings are interpreted as local time unless it also contains a time zone indicator, such as a trailing "Z" or "GMT". PI Time formats ("*", "T", "*-1h", "+3d", etc.) are also supported.

Relative parameter rules:

  • If the startTime starts with "+" or "-" (without a "*" specified), then the start time will be relative to the end time.
  • If the endTime starts with "+" or "-" (without a "*" specified) and the startTime does not start with "+" or "-", then the end time will be relative to the start time.
  • If neither of these conditions are true, then the times are not relative to each other.

endTime
Type: SystemString

The ending time of the time range represented by this object, specified in a string format. Strings are interpreted as local time unless it also contains a time zone indicator, such as a trailing "Z" or "GMT". PI Time formats ("*", "T", "*-1h", "+3d", etc.) are also supported.

Relative parameter rules:

  • If the startTime starts with "+" or "-" (without a "*" specified), then the start time will be relative to the end time.
  • If the endTime starts with "+" or "-" (without a "*" specified) and the startTime does not start with "+" or "-", then the end time will be relative to the start time.
  • If neither of these conditions are true, then the times are not relative to each other.

provider
Type: SystemIFormatProvider

An object that supplies culture-specific formatting information about the time string parameters. The AFTimeZoneFormatProvider can be used to provide the AFTimeZone to be used when parsing. The AFLocaleIndependentFormatProvider can be used when parsing PI SDK locale independent time strings.

If or an AFTimeZoneFormatProvider is specified with the Provider as , then CurrentCulture will be used first when parsing the time strings. If the parsing fails in this case, then a second attempt is made to parse using InvariantCulture.

result
Type: OSIsoft.AF.TimeAFTimeRange
When this method returns, contains the AFTimeRange value equivalent to the date and time strings contained in startTime and endTime if the conversion succeeded. If conversion failed, then a default AFTimeSpan is returned. The conversion fails if the startTime or endTime parameters do not contain a valid string representation of a data and time.

Return Value

Type: Boolean
Returns if startTime and endTime parameters were converted successfully; otherwise, .
Remarks

This method parses a string that can contain a date, time, time zone information, and a relative interval. The input string has two parts each of which are optional: the date time part and the interval part. The date time part can be "Today" (or "T"), "Yesterday" (or "Y"), a weekday name, a month name, "*" (current time), , an Empty string, a number less than 32 (day of month), a four digit number greater than or equal 1970 (year), or a date and time specification in any format supported by the DateTime.TryParse method. The SQL time string format of hh:mm:ss:fff (three fractional digits are required for this format) is also supported for the time portion of the date time part.

A or Empty string is equivalent to "*" and represents the current time. "Today" and "Yesterday" are the beginning of the specified day at the first hour (normally at 0 hours) local time. A weekday name (either full name or abbreviation) specifies the most current occurrence at the first hour (normally at 0 hours) local time. For example if the current time is Tuesday, specifying a weekday of Wednesday would set the time to the beginning of the day six days ago. A month name (either full name or abbreviation) specifies the current day of the month at the first hour (normally at 0 hours) local time. An absolute date and time specification can be enclosed in double or single quotes (" or ') in any format supported by DateTime.TryParse.

When only the time portion of the date time part is specified, then the input is evaluated as the time offset of the current day.

Note Note
If a reference time is specified, then the 'current' time is evaluated as the specified reference time. If the Daylight Savings adjustment rules for a timezone make hour 0 local time invalid or ambiguous, then the first valid hour for the timezone will be used as the first hour local time.

The interval part follows the date time part in one of the following formats. If the date time part is specified in a DateTime format (format parsed by DateTime.TryParse), then only the first format with interval names specified is allowed unless the date time part is enclosed in double or single quotes (" or '). Normally the first '+' or '-' operator is required when combined with a date time part.

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

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
See Also
Enabling Operational Intelligence