Differences

This shows you the differences between two versions of the page.

--- syntax:functions:format [2019/12/06 04:45] – andrew
+++ syntax:functions:format [2021/08/30 02:04] (current) – craigt
@@ Line 1: / Line 1: @@
-===== format(date_as_number, format) =====
+====== Format(datetime, format) ======
+Category:  Date and Time function
-Converts //date_as_number// into a text string according to a //format// string.
+\\
+=====Description=====
+This function converts //datetime// as a date serial value into a date-time text value formatted according to //format//.
-^  Example  ^  Result  ^  Notes  ^
+\\
-|  format(41640,'yyyyMMdd')  |20140101  | 41640 corresponds to January 1st, 2014  |
+=====Arguments=====
-|  format(41640,'yy-MM-dd')  |14-01-01  | 41640 corresponds to January 1st, 2014  |
+^Argument^Type^Description^
+|datetime  |Date or Number (date serial)  |An expression representing a date serial value.  The date to convert into a text-based date-time string.|
+|format  |Text  |The layout of the //datetime// value describing the order and type of the date-time components.\\  See the "Format string components" table below.|
+**Return value type:** Text.
+\\
+==== Date-Time format string components ====
+A //format string// defines a formatting template for dates and times. Its components can be put together in any combination. If a character doesn't belong to a format component then it's inserted verbatim.
-=== Format string components ===
+:!: The specifiers below are case-sensitive.
-A format string defines a formatting template for dates. Its components can be put together in any combination. If a character doesn't belong to a format component then it's inserted verbatim.
+^  Date format specifier^  Description  ^
+|  d  |The day of the month, from 1 through 31.  |
-Note that the colon (":") is not a valid symbol for file names and therefore mustn't be used in file names generated using a format string.
+|  dd  |The day of the month, from 01 through 31.  |
+|  ddd  |The abbreviated name of the day of the week.  |
-**Attention** :!: The format components are case sensitive. For instance, "MM" (uppercase) and "mm" (lowercase) are frequently confused by new EasyMorph users but they denote different data/time components (see table below).
-^  Character  ^  Description  ^
-|  y  |The year, from 0 to 99.  |
-|  yy  |The year, from 00 to 99.  |
-|  yyyy  |The year as a four-digit number.  |
 |  M  |The month, from 1 through 12.  |
 |  MM  |The month, from 01 through 12.  |
 |  MMM  |The abbreviated name of the month.  |
 |  MMMM  |The full name of the month.  |
-|  d  |The day of the month, from 1 through 31.  |
+|  y  |The year, from 0 to 99.  |
-|  dd  |The day of the month, from 01 through 31.  |
+|  yy  |The year, from 00 to 99.  |
-|  ddd  |The abbreviated name of the day of the week.  |
+|  yyyy  |The year as a four-digit number.  |
+^  Time format specifier^  Description  ^
 |  h  |The hour, using a 12-hour clock from 1 to 12.  |
 |  hh  |The hour, using a 12-hour clock from 01 to 12.  |
-|  H  |The hour, using a 24-hour clock from 1 to 24.  |
+|  H  |The hour, using a 24-hour clock from 0 to 23.  |
-|  HH  |The hour, using a 24-hour clock from 01 to 24.  |
+|  HH  |The hour, using a 24-hour clock from 00 to 23.  |
 |  m  |The minute, from 0 through 59.  |
 |  mm  |The minute, from 00 through 59.  |
 |  s  |The second, from 0 through 59.  |
 |  ss  |The second, from 00 through 59.  |
-|  tt  |The localized AM/PM designator.  |
+|  t  |The first character of the AM/PM designator.  |
+|  tt  |The AM/PM designator.  |
+\\
+=====Remarks=====
+Note that the colon (":") is not a valid symbol for file names, so in instances where the results of this function are to be used in a file name (e.g., as a date-time stamp), the colon should not be used, or should be //replaced// before generating the file.
+\\
+=====Examples=====
+  format( 41640, 'yyyyMMdd' )  //Returns '20140101' (41640 corresponds to January 1st, 2014.)
+  format( 43658, 'yy-MM-dd' )  //Returns '19-07-12' (43658 corresponds to July 12th, 2019.)
+  format( 41640.75, 'yyyy-MM-dd hh:mmtt' )  //Returns '2014-01-01 06:00PM' (Includes time component.)
-=== See also ===
+\\
+===== See also =====
+  * [[syntax:functions:date|Date(date,format)]]
+  * [[syntax:functions:makedate|MakeDate(year,month,day)]]
   * [[https://msdn.microsoft.com/en-us/library/8kb3ddd4(v=vs.110).aspx|MSDN: Custom Date and Time Format Strings]]
-  * [[syntax:functions:date]]
-  * [[syntax:functions:makedate]]