Difference between revisions of "Extensions.DateTime.FormatDate"

From emotive
Jump to navigation Jump to search
 
(8 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{DISPLAYTITLE:'''FormatDate '''}}[[Category:DateTime]]
 
{{DISPLAYTITLE:'''FormatDate '''}}[[Category:DateTime]]
 
== Classification ==
 
== Classification ==
−
{{ClassificationActivity | FormatDate | Returns a formatted time representation of a timestamp. | [[Term]] | [[Extensions.DateTime|OTX DateTime Extension]] | - | [[Core.DataTypes.ComplexDataType.OutOfBoundsException|OutOfBoundsException]] | - | Yes}}
+
{{ClassificationActivity | FormatDate | Returns a formatted time representation of a timestamp as a string. | [[Term]] | [[Extensions.DateTime|OTX DateTime Extension]] | - | [[Core.DataTypes.ComplexDataType.OutOfBoundsException|OutOfBoundsException]] | - | Yes}}
  
 
== OTL Syntax ==
 
== OTL Syntax ==
 
<syntaxhighlight lang="java" enclose="div" style="font-size: medium;">
 
<syntaxhighlight lang="java" enclose="div" style="font-size: medium;">
−
/// Local Declarations
+
StringTerm DateTime.FormatDate(NumericTerm timestamp, StringTerm format);
−
String StringVariable;
 
−
/// Flow
 
−
StringVariable = FormatDate(IntegerTerm, StringTerm);
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
== Description ==
 
== Description ==
 
<!--T:1-->
 
<!--T:1-->
−
Date format is a term which converts a timestamp in a date format and returns as a string. If there is no formatting specified, is the time to ISO 8601:2004 in the following format:
+
DateFormat is a term which converts a timestamp in a date format and returns as a string. If no custom format is given, the ISO 8601 conform date output will be formatted equivalent to the custom format pattern:
−
<blockquote style="text-align:center;">
+
<blockquote style="text-align:left;">
−
'''YYYY-MM-DDThh:mm:ss[.fff]+hh:mm''' <br/>
+
'''yyyy-MM-dd'T'HH:mm:ss'.'SSSZ'''
−
(The symbols "-", ".", ":", ",", "+" And "T" are delimiters)
 
 
</blockquote>
 
</blockquote>
 +
Where "T" is the time designator and "." is a separator for the following millisecond portion. The pattern is language independent. The currently set locale does not influence the output.
 +
 +
{{Warning|Results from FormatDate 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-->
 
<!--T:2-->
−
The following table gives an overview of the decoding of the individual format icons.
+
The following table gives an overview of the decoding of the format patterns.
−
{| style="text-align:center" border="0" cellpadding="5"
+
{| style="text-align:left" border="0" cellpadding="5"
−
|+ style="color:gray" | <small>Modules of the ISO 8601 time format</small>
+
|+ style="color:gray" | <small>Date format pattern specifiers</small>
 
|- style="background: gray; color: white; vertical-align:top;"  
 
|- style="background: gray; color: white; vertical-align:top;"  
−
| YYYY || MM || DD || hh || mm || ss || fff || hh || mm
+
| '''Specifier(s)''' || '''Meaning''' || '''Presentation''' || '''Example'''
 +
|-
 +
| G || Era || Text (localized) || AD
 +
|-
 +
| yy, yyyy || Year (two digits / four digits) || Number || 11, 2011
 +
|-
 +
| M, MM || Month in year (without / with leading zero) || Number || 9, 09
 +
|-
 +
| MMM, MMMM || Month in year (short form / long form) || Text (localized) || Jan, January
 +
|-
 +
| d, dd || Day in month (without / with leading zero) || Number || 3, 09
 +
|-
 +
| D || Day in year || Number || 304
 +
|-
 +
| F || Day of week of month || Number || 3
 +
|-
 +
| E, EEEE || Day of week (short form / long form) || Text (localized) || Wed, Wednesday
 +
|-
 +
| h, hh || Hours, 1-12 count (without / with leading zero) || Number || 7, 07
 +
|-
 +
| H, HH || Hours, 0-23 count (without / with leading zero) || Number || 7, 07
 +
|-
 +
| m, mm || Minutes (without / with leading zero) || Number || 2, 02
 +
|-
 +
| s, ss || Seconds (without / with leading zero) || Number || 4, 04
 +
|-
 +
| S, SS, SSS || Milliseconds (without / with leading zeros) || Number || 357, 04, 002
 +
|-
 +
| w, W || Week in year / Week in month || Number || 34, 3
 +
|-
 +
| a || AM/PM designator  || Text (localized) || AM
 +
|-
 +
| z, zzzz || Time zone (short form / long form) || Text (localized) || CET, Central European Time
 
|-
 
|-
−
| Year || Month || Day || Hour || Minute || Second || Milisecond || Hour (difference from GMT) || Minute (difference from GMT)
+
| Z || RFC 822 timezone (timeshift to GMT) || Text || +0100
 
|}
 
|}
  
 
If the timestamp value is negative, the [[Core.DataTypes.ComplexDataType.OutOfBoundsException|OutOfBoundsException]] exception will be thrown.
 
If the timestamp value is negative, the [[Core.DataTypes.ComplexDataType.OutOfBoundsException|OutOfBoundsException]] exception will be thrown.
  
−
{{TermReturnValue| [[Core.DataTypes.SimpleDataType.String|String]] | Date in the form according to ISO8601 or as specified.}}
+
{{TermReturnValue| [[Core.DataTypes.SimpleDataType.String|String]] | Formatted string according to the specified format pattern.}}
  
 
== Properties ==
 
== Properties ==
 
{| {{TableHeader}}
 
{| {{TableHeader}}
 
{{TableRowPropertiesHeader}}
 
{{TableRowPropertiesHeader}}
−
{{TableRowPropertie1| Timestamp | [[Core.DataTypes.SimpleDataType.Integer|Integer]] | [[Term]] | - | [1] | This property specifies a date as a time stamp, which is interpreted as the number of milliseconds elapsed since January 1 1970 00:00:00 UTC.}}
+
{{TableRowPropertie1| Timestamp | [[Numeric]] | [[Term]] | - | [1] | Specifies a date/time as a time stamp, which is interpreted as the number of milliseconds elapsed since January 1 1970 00:00:00 UTC.}}
−
{{TableRowPropertie2| Pattern | [[Core.DataTypes.SimpleDataType.String|String]] | [[Term]] | - | [0..1] | This feature can represent time in the desired format.}}
+
{{TableRowPropertie2| Format | [[Core.DataTypes.SimpleDataType.String|String]] | [[Term]] | - | [0..1] | Represents the format string pattern to format the time.}}
 
|}
 
|}
  
Line 44: Line 77:
 
/// Local Declarations
 
/// Local Declarations
  
−
String CurrentTime;
+
String CurrentTimeAsString;
  
 
/// Flow
 
/// Flow
  
−
CurrentTime = DateTime.FormatDate(DateTime.GetTimestamp(), null);
+
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "dd.MM.yyyy"); // returns 09.07.2008
 +
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "yyyy.MM.dd G 'at' HH:mm:ss z"); // returns "2008.07.09 AD at 12:08:56 PDT"
 +
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "EEE, MMM d, ''yy"); // returns "Wed, Jul 4, '01"
 +
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "h:mm a"); // returns "12:08 PM"
 +
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "hh 'o''clock' a, zzzz"); // returns "12 o'clock PM, Pacific Daylight Time"
 +
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "K:mm a, z"); // returns "0:08 PM, PDT"
 +
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "yyyyy.MMMMM.dd GGG hh:mm aaa"); // returns "02001.July.04 AD 12:08 PM"
 +
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "EEE, d MMM yyyy HH:mm:ss Z"); // returns "Wed, 4 Jul 2001 12:08:56 -0700"
 +
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "yyMMddHHmmssZ"); // returns "010704120856-0700"
 +
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "yyyy-MM-dd'T'HH:mm:ss.SSSZ"); // returns "2001-07-04T12:08:56.235-0700"
 +
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "yyyy-MM-dd'T'HH:mm:ss.SSSXXX"); // returns "2001-07-04T12:08:56.235-07:00"
 +
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "YYYY-'W'ww-u"); // returns "2001-W27-3"
 
</syntaxhighlight>
 
</syntaxhighlight>
 
== See also ==
 
== See also ==
 
[[Extensions.DateTime.GetTimeStamp|GetTimeStamp]]<br/>
 
[[Extensions.DateTime.GetTimeStamp|GetTimeStamp]]<br/>
 
[[Extensions.DateTime.FormatDuration|FormatDuration]]
 
[[Extensions.DateTime.FormatDuration|FormatDuration]]

Latest revision as of 10:20, 3 December 2019

Classification

Name FormatDate
Short Description Returns a formatted time representation of a timestamp as a string.
Class Term
Extension OTX DateTime Extension
Group -
Exceptions OutOfBoundsException
Checker Rules -
Standard Compliant Yes

OTL Syntax

StringTerm DateTime.FormatDate(NumericTerm timestamp, StringTerm format);

Description

DateFormat is a term which converts a timestamp in a date format and returns as a string. If no custom format is given, the ISO 8601 conform date output will be formatted equivalent to the custom format pattern:

yyyy-MM-dd'T'HH:mm:ss'.'SSSZ

Where "T" is the time designator and "." is a separator for the following millisecond portion. The pattern is language independent. The currently set locale does not influence the output.

Icons Warning.png Results from FormatDate 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.

Date format pattern specifiers
Specifier(s) Meaning Presentation Example
G Era Text (localized) AD
yy, yyyy Year (two digits / four digits) Number 11, 2011
M, MM Month in year (without / with leading zero) Number 9, 09
MMM, MMMM Month in year (short form / long form) Text (localized) Jan, January
d, dd Day in month (without / with leading zero) Number 3, 09
D Day in year Number 304
F Day of week of month Number 3
E, EEEE Day of week (short form / long form) Text (localized) Wed, Wednesday
h, hh Hours, 1-12 count (without / with leading zero) Number 7, 07
H, HH Hours, 0-23 count (without / with leading zero) Number 7, 07
m, mm Minutes (without / with leading zero) Number 2, 02
s, ss Seconds (without / with leading zero) Number 4, 04
S, SS, SSS Milliseconds (without / with leading zeros) Number 357, 04, 002
w, W Week in year / Week in month Number 34, 3
a AM/PM designator Text (localized) AM
z, zzzz Time zone (short form / long form) Text (localized) CET, Central European Time
Z RFC 822 timezone (timeshift to GMT) Text +0100

If the timestamp 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 Formatted string according to the specified format pattern.

Properties

Name Data Type Class Default Cardinality Description
Timestamp Numeric Term - [1] Specifies a date/time as a time stamp, which is interpreted as the number of milliseconds elapsed since January 1 1970 00:00:00 UTC.
Format String Term - [0..1] Represents the format string pattern to format the time.

OTL Examples

/// Local Declarations

String CurrentTimeAsString;

/// Flow

CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "dd.MM.yyyy"); // returns 09.07.2008
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "yyyy.MM.dd G 'at' HH:mm:ss z"); // returns "2008.07.09 AD at 12:08:56 PDT"
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "EEE, MMM d, ''yy"); // returns "Wed, Jul 4, '01"
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "h:mm a"); // returns "12:08 PM"
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "hh 'o''clock' a, zzzz"); // returns "12 o'clock PM, Pacific Daylight Time"
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "K:mm a, z"); // returns "0:08 PM, PDT"
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "yyyyy.MMMMM.dd GGG hh:mm aaa"); // returns "02001.July.04 AD 12:08 PM"
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "EEE, d MMM yyyy HH:mm:ss Z"); // returns "Wed, 4 Jul 2001 12:08:56 -0700"
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "yyMMddHHmmssZ"); // returns "010704120856-0700"
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "yyyy-MM-dd'T'HH:mm:ss.SSSZ"); // returns "2001-07-04T12:08:56.235-0700"
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "yyyy-MM-dd'T'HH:mm:ss.SSSXXX"); // returns "2001-07-04T12:08:56.235-07:00"
CurrentTimeAsString = DateTime.FormatDate(DateTime.GetTimestamp(), "YYYY-'W'ww-u"); // returns "2001-W27-3"

See also

GetTimeStamp
FormatDuration

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