Difference between revisions of "Extensions.DateTime.FormatDuration"
Jump to navigation
Jump to search
| Line 1: | Line 1: | ||
{{DISPLAYTITLE:'''FormatDuration '''}}[[Category:DateTime]] | {{DISPLAYTITLE:'''FormatDuration '''}}[[Category:DateTime]] | ||
== Classification == | == Classification == | ||
| − | {{ClassificationActivity | FormatDuration | | + | {{ClassificationActivity | FormatDuration | Returns a formatted time representation of a duration in milliseconds. | [[Term]] | [[Extensions.DateTime|OTX DateTime Extension]] | - | [[Core.DataTypes.ComplexDataType.OutOfBoundsException|OutOfBoundsException]] | - | Yes}} |
== OTL Syntax == | == OTL Syntax == | ||
| Line 9: | Line 9: | ||
== Description == | == Description == | ||
| − | FormatDuration returns a | + | FormatDuration is a term which converts returns a formatted string of a given milliseconds duration. If no custom format is given, the ISO 8601 conform date output shall be formatted equivalent to the custom pattern: |
| + | <blockquote style="text-align:left;"> | ||
| + | ''''P'y-MM-dd'T'HH:mm:ss'.'SSS''' | ||
| + | </blockquote> | ||
| + | Where "P" is the duration designator and "T"is the time designator. | ||
| + | |||
| + | {{Warning|Results from FormatDuration should not be used for test logic, only for user representations, because exchangeability cannot be guaranteed across different run time systems (e.g. ERA, time zone)!}} | ||
| + | |||
| + | {{Note|The format pattern rules are analogous to the rules given for the [https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html class java.text.SimpleDateFormat] as specified by the Java™ 2 Platform Standard Ed. 6.}} | ||
| + | |||
| + | <!--T:2--> | ||
| + | The following table gives an overview of the decoding of the format patterns. | ||
| + | {| style="text-align:left" border="0" cellpadding="5" | ||
| + | |+ style="color:gray" | <small>Format pattern specifiers</small> | ||
| + | |- style="background: gray; color: white; vertical-align:top;" | ||
| + | | '''Specifier(s)''' || '''Meaning''' || '''Example''' | ||
| + | |- | ||
| + | | Y || Years portion of duration || 11, 124 | ||
| + | |- | ||
| + | | M, MM || Months portion of duration, 0-11 count (without / with leading zero) || 2, 02 | ||
| + | |- | ||
| + | | d, dd || Days portion of duration, 0-29365 count (without / with leading zero) | ||
| + | |- | ||
| + | | 3, 09 | ||
| + | |- | ||
| + | | H, HH || Hours portion of duration, 0-23 count (without / with leading zero) || 7, 07 | ||
| + | |- | ||
| + | | m, mm || Minutes portion of duration, 0-59 count (without / with leading zero) || 2, 02 | ||
| + | |- | ||
| + | | s, ss || Seconds portion of duration, 0-59 count (without / with leading zero) || 4, 04 | ||
| + | |- | ||
| + | | S, SS, SSS || Milliseconds of duration, 0-999 count (without / with leading zeros) || 357, 034, 002 | ||
| + | |} | ||
If the duration value is negative, the [[Core.DataTypes.ComplexDataType.OutOfBoundsException|OutOfBoundsException]] exception will be thrown. | If the duration value is negative, the [[Core.DataTypes.ComplexDataType.OutOfBoundsException|OutOfBoundsException]] exception will be thrown. | ||
| − | {{TermReturnValue| [[Core.DataTypes.SimpleDataType.String|String]] | A formatted | + | {{TermReturnValue| [[Core.DataTypes.SimpleDataType.String|String]] | A formatted duration.}} |
== Properties == | == Properties == | ||
{| {{TableHeader}} | {| {{TableHeader}} | ||
{{TableRowPropertiesHeader}} | {{TableRowPropertiesHeader}} | ||
| − | {{TableRowPropertie1| Duration| [[Core.DataTypes.SimpleDataType.Integer|Integer]] | [[Term]] | - | [1] | | + | {{TableRowPropertie1| Duration| [[Core.DataTypes.SimpleDataType.Integer|Integer]] | [[Term]] | - | [1] | Specifies a duration in milliseconds which should be formatted according to the specified format pattern.}} |
| − | {{TableRowPropertie2| Format | [[Core.DataTypes.SimpleDataType.String|String]] | [[Term]] | - | [0..1] | | + | {{TableRowPropertie2| Format | [[Core.DataTypes.SimpleDataType.String|String]] | [[Term]] | - | [0..1] | Represents the format string pattern to format the duration.}} |
|} | |} | ||
== OTL Examples == | == OTL Examples == | ||
<syntaxhighlight lang="java" enclose="div" style="font-size: medium;"> | <syntaxhighlight lang="java" enclose="div" style="font-size: medium;"> | ||
| − | |||
| − | |||
String CurrentTime; | String CurrentTime; | ||
| − | + | CurrentTime = DateTime.FormatDuration(203443, "mm:ss ' mm:ss'"); // returns: "03:23 mm:ss" | |
| − | // | + | CurrentTime = DateTime.FormatDuration(203443); // returns: "P0-00-00T00:03:23.443" |
| − | |||
| − | CurrentTime = DateTime.FormatDuration( | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== See also == | == See also == | ||
[[Extensions.DateTime.GetTimeStamp|GetTimeStamp]] <br/> | [[Extensions.DateTime.GetTimeStamp|GetTimeStamp]] <br/> | ||
[[Extensions.DateTime.FormatDate|FormatDate]] | [[Extensions.DateTime.FormatDate|FormatDate]] | ||
Revision as of 15:48, 12 July 2019
Contents
Classification
| Name | FormatDuration |
| Short Description | Returns a formatted time representation of a duration in milliseconds. |
| Class | Term |
| Extension | OTX DateTime Extension |
| Group | - |
| Exceptions | OutOfBoundsException |
| Checker Rules | - |
| Standard Compliant | Yes |
OTL Syntax
StringTerm DateTime.FormatDuration(NumericTerm duration, StringTerm format);Description
FormatDuration is a term which converts returns a formatted string of a given milliseconds duration. If no custom format is given, the ISO 8601 conform date output shall be formatted equivalent to the custom pattern:
'P'y-MM-dd'T'HH:mm:ss'.'SSS
Where "P" is the duration designator and "T"is the time designator.
Results from FormatDuration should not be used for test logic, only for user representations, because exchangeability cannot be guaranteed across different run time systems (e.g. ERA, time zone)!
The format pattern rules are analogous to the rules given for the class java.text.SimpleDateFormat as specified by the Java™ 2 Platform Standard Ed. 6.
The following table gives an overview of the decoding of the format patterns.
| Specifier(s) | Meaning | Example |
| Y | Years portion of duration | 11, 124 |
| M, MM | Months portion of duration, 0-11 count (without / with leading zero) | 2, 02 |
| d, dd | Days portion of duration, 0-29365 count (without / with leading zero) | |
| 3, 09 | ||
| H, HH | Hours portion of duration, 0-23 count (without / with leading zero) | 7, 07 |
| m, mm | Minutes portion of duration, 0-59 count (without / with leading zero) | 2, 02 |
| s, ss | Seconds portion of duration, 0-59 count (without / with leading zero) | 4, 04 |
| S, SS, SSS | Milliseconds of duration, 0-999 count (without / with leading zeros) | 357, 034, 002 |
If the duration value is negative, the OutOfBoundsException exception will be thrown.
Return Value
The Term returns the value, see table below.
In OTX, Terms are categorized according to its return data type!
| Data Type | Description |
| String | A formatted duration. |
Properties
| Name | Data Type | Class | Default | Cardinality | Description |
| Duration | Integer | Term | - | [1] | Specifies a duration in milliseconds which should be formatted according to the specified format pattern. |
| Format | String | Term | - | [0..1] | Represents the format string pattern to format the duration. |
OTL Examples
String CurrentTime;
CurrentTime = DateTime.FormatDuration(203443, "mm:ss ' mm:ss'"); // returns: "03:23 mm:ss"
CurrentTime = DateTime.FormatDuration(203443); // returns: "P0-00-00T00:03:23.443"