Merge pull request #430 from sshanks-kx/time

improve date/time casting info

Author: iciobanukx

docs/basics/cmdline.md

@@ -464,10 +464,10 @@ Set the start-of-week offset, where 0 is Saturday. The default is 2, i.e Monday.
 -z [0|1]
 ```
 
-Set the format for `"D"$` date parsing: 0 for mm/dd/yyyy and 1 for dd/mm/yyyy.
+Set the format for `"D"$` date parsing.
 
 :fontawesome-solid-book-open:
-[`\z` system command](syscmds.md#z-date-parsing)
+[`\z` system command](syscmds.md#z-date-parsing) for detail
 
 
 [![](../img/xkcd.tar.png)](https://xkcd.com/1168/)

docs/basics/syscmds.md

@@ -951,7 +951,7 @@ q)\x .z.pi                    / restore default
 \z 0|1
 ```
 
-Show or set the format for `"D"$` date parsing. `B` is 0 for mm/dd/yyyy and 1 for dd/mm/yyyy.
+Show or set the format for `"D"$` date parsing. `0` for mm/dd/yyyy and `1` for dd/mm/yyyy. Default value is `0`.
 
 ```q
 q)\z

docs/ref/cast.md

@@ -136,7 +136,18 @@ q)"x"$"abc"
 
 ## Temporal
 
-Find parts of time:
+The following symbols can be used to extract parts of a temporal type
+
+* `year` to provide year as an integer
+* `month` to provide `month` datatype
+* `mm` to provide month as an integer, where January is 01i
+* `week` to provide a `date` datatype, presenting the week in which the temporal variable resides. The value returned is the start of the week (Monday). If the `date` represents a Monday, it is not altered.
+* `dd` to provide day as an integer, where 1st of the month is 1i
+* `hh` to provide hour as an integer
+* `uu` to provide minutes as an integer
+* `ss` to provide to seconds as an integer
+
+For example:
 
 ```q
 q)`hh`uu`ss$03:55:58.11
@@ -145,6 +156,8 @@ q)`year`dd`mm`hh`uu`ss$2015.10.28D03:55:58
 2015 28 10 3 55 58i
 ```
 
+The following shows which information can be extracted from each temporal [datatype](../basics/datatypes.md)
+
 ```txt
           | year | month | mm | week | dd | hh | uu | ss
 --------------------------------------------------------
@@ -156,14 +169,8 @@ timespan  |      |       |    |      |    | x  | x  | x
 minute    |      |       |    |      |    | x  | x  | x
 second    |      |       |    |      |    | x  | x  | x
 time      |      |       |    |      |    | x  | x  | x
-
-
-milliseconds: "i"$time mod 1000
-milliseconds: "i"$mod[;1000]"t"$datetime
-nanoseconds: "i"$timestamp mod 1000000000
 ```
 
-
 !!! detail "Casting to narrower temporal type truncates rather than rounds"
 
     Such conversions use floor, because the day, hour, minute, second… are all [) notions. (What hour are we in; what millisecond are we in…)
@@ -172,6 +179,13 @@ nanoseconds: "i"$timestamp mod 1000000000
 
     As a consequence `.z.t-.z.n` is typically negative. 
 
+Numeric calculations on the base numeric type can also be used to extract part of a temporal type, for the example using the [`mod`](mod.md) keyword
+
+```q
+milliseconds: "i"$01:00:00.100 mod 1000                         / extract milliseconds from time datatype
+milliseconds: "i"$mod[;1000]"t"$2000.01.01T12:00:00.500         / extract milliseconds from datetime datatype
+nanoseconds: "i"$2014.11.22D17:43:40.123456789 mod 1000000000   / extract nanoseconds from timestamp datatype
+```
 
 ## Identity
 

docs/ref/tok.md

@@ -203,8 +203,8 @@ q)"PZ"$\:"20191122-11:11:11.123"
 [yy]yymmdd
 ddMMM[yy]yy
 yyyy/[mm|MMM]/dd
-[mm|MMM]/dd/[yy]yy  / \z 0  
-dd/[mm|MMM]/[yy]yy  / \z 1
+[mm|MMM]/dd/[yy]yy  / when \z is set to 0 (default)
+dd/[mm|MMM]/[yy]yy  / when \z is set to 1
 ```
 
 :fontawesome-solid-book-open: