Difference between revisions of "Extensions.DateTime.FormatDuration"

From emotive
Jump to navigation Jump to search
(→‎Description: Edited by Ngoc Tran. Fixed the Format pattern specifiers table)
 
(21 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
[[Category:DateTime]]
+
{{DISPLAYTITLE:'''FormatDuration '''}}[[Category:DateTime]]
 
== Classification ==
 
== Classification ==
−
{{ClassificationActivity | FormatDuration | Give a duration in milliseconds from a time stamp. | [[Term]] | [[DateTime|OTX DateTime Extension]] | - | [[OutOfBoundsException]] | - | Yes}}
+
{{ClassificationActivity | FormatDuration | Returns a formatted time representation of a duration in milliseconds. | [[Term]] | [[Extensions.DateTime|OTX DateTime Extension]] | - | [[Core.DataTypes.ComplexDataType.OutOfBoundsException|OutOfBoundsException]] | - | Yes}}
  
−
== Pseudo-Code Syntax ==
+
== OTL Syntax ==
 
<syntaxhighlight lang="java" enclose="div" style="font-size: medium;">
 
<syntaxhighlight lang="java" enclose="div" style="font-size: medium;">
−
String duration = FormatDuration(timeStamp, <<pattern>>);
+
StringTerm DateTime.FormatDuration(NumericTerm duration, StringTerm format);
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
== Description ==
 
== Description ==
−
FormatDuration returns a specified duration in milliseconds as a string representation. Formatting will be made to the format of Date Term, with the difference that the milliseconds elapsed interpreted as a duration, not the date Analog.
+
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 will 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.
 +
 
 +
{{TermReturnValue| [[Core.DataTypes.SimpleDataType.String|String]] | A formatted duration.}}
  
 
== Properties ==
 
== Properties ==
 
{| {{TableHeader}}
 
{| {{TableHeader}}
 
{{TableRowPropertiesHeader}}
 
{{TableRowPropertiesHeader}}
−
{{TableRowPropertie1| Duration | [[String]] | [[Variable]] | - | [0..1] | A formatted time.}}
+
{{TableRowPropertie1| Duration| [[Numeric]] | [[Term]] | - | [1] | Specifies a duration in milliseconds which will be formatted according to the specified format pattern.}}
−
{{TableRowPropertie2| Timestamp | [[Integer]] | [[Term]] | - | [0..1] | This property represents a duration in milliseconds to a string that is formatted according to the specified rules.}}
+
{{TableRowPropertie2| Format | [[Core.DataTypes.SimpleDataType.String|String]] | [[Term]] | - | [0..1] | Represents the format string pattern to format the duration.}}
−
{{TableRowPropertie1 | Pattern | [[String]] | [[Term]] | - | [0..1] | User-specified format for displaying the time.}}
 
 
|}
 
|}
  
−
== Examples ==
+
== OTL Examples ==
−
A duration of {{FontColor|blue||203443}} milliseconds ( {{FontColor|blue||3 minutes 23 seconds and 443 milliseconds}} ), a pattern such as "{{FontColor|blue||'It takes'}} {{FontColor|red||m}} {{FontColor|blue||'minutes and'}} {{FontColor|red||s}} {{FontColor|blue||'.seconds'}} "generates the following formatted output: {{FontColor|blue||"It takes 3 minutes and 23 seconds."}} <br/>
+
<syntaxhighlight lang="java" enclose="div" style="font-size: medium;">
 +
/// Local Declarations
 +
 
 +
String DurationAsString;
  
−
If there is no pattern specified, the output is after the fashion of ISO 8601 ( {{FontColor|blue||'P'yyyy-MM-dd'T'HH: mm: ss' . 'SSS}} ) " {{FontColor|blue||P0000-00-00T00: 03:23.443}}", where "{{FontColor|blue||P}}" designator for the duration and "{{FontColor|blue||T}}" is the designator for time.
+
/// Flow
  
 +
DurationAsString = DateTime.FormatDuration(203443, "mm:ss 'mm:ss'"); // returns: "03:23 mm:ss"
 +
DurationAsString = DateTime.FormatDuration(203443); // returns: "P0-00-00T00:03:23.443"
 +
</syntaxhighlight>
 
== See also ==
 
== See also ==
−
[[GetTimeStamp]] <br/>
+
[[Extensions.DateTime.GetTimeStamp|GetTimeStamp]] <br/>
−
[[FormatDate]]
+
[[Extensions.DateTime.FormatDate|FormatDate]]

Latest revision as of 07:28, 12 February 2020

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 will 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.

Icons Warning.png 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)!

Icons Note.png 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.

Format pattern specifiers
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.

Icons Note.png 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 Numeric Term - [1] Specifies a duration in milliseconds which will be formatted according to the specified format pattern.
Format String Term - [0..1] Represents the format string pattern to format the duration.

OTL Examples

/// Local Declarations

String DurationAsString;

/// Flow

DurationAsString = DateTime.FormatDuration(203443, "mm:ss 'mm:ss'"); // returns: "03:23 mm:ss"
DurationAsString = DateTime.FormatDuration(203443); // returns: "P0-00-00T00:03:23.443"

See also

GetTimeStamp
FormatDate

Retrieved from "http://emotive.de/wiki/index.php?title=Extensions.DateTime.FormatDuration&oldid=10293"