add some docs for timestamptz (#257)

Author: mtoy-googly-moogly

src/documentation/language/datatypes.malloynb

@@ -67,21 +67,27 @@ For expressions which return a `boolean`, e.g. `might_be_null > 0`:
 
 This is true for all the comparison operators (`>`, `=`, etc.) as well as functions which return a boolean (e.g. `starts_with`, `is_inf`, etc.).
 
-## Timestamp
+## Timestamp and Timestamptz
 
-A `timestamp` represents an instant in time.
+A `timestamp` and `timestamptz` both represent an instant in time. They work interchangeably in Malloy and have the same semantics. The distinction exists to support different database column storage formats.
 
-Malloy's approach to timezone related computations relating to timestamp data is explained in the [Timezones](timezones.malloynb) section.
+Malloy's approach to timezone related computations is explained in the [Timezones](timezones.malloynb) section.
 
 ### Timestamp literals
 
-Timestamp literals are specified in Malloy with the <code>@</code> character. Seconds, subsecond resolution, and locale are optional.
+Timestamp literals are specified in Malloy with the <code>@</code> character. Seconds and subsecond resolution are optional.
 
-* `@2001-02-03 04:05:06.001[America/Mexico_City]`
 * `@2001-02-03 04:05:06.001`
 * `@2001-02-03 04:05:06`
 * `@2001-02-03 04:05`
 
+A timezone can optionally be specified in square brackets:
+
+* `@2001-02-03 04:05:06[America/Mexico_City]`
+* `@2001-02-03 04:05:06.001[UTC]`
+
+On databases that support `timestamptz`, embedding a timezone in a literal produces a `timestamptz` literal.
+
 In addition, in any of the above, a `T` can be used instead of a space between the date and time portion of the timestamp string, as in
 
 * `@2001-02-03T04:05:06.001`

src/documentation/language/timestamp-operations.malloynb

@@ -35,3 +35,31 @@ expression | meaning | result
 `second(expr)` | second of minute 0-59 | 5
 
 * See [Timezones](timezones.malloynb) for information on how extraction interacts with timezones.
+
+## Casting
+
+Timestamps and dates can be cast between types using the `::` operator.
+
+### Casting to and from Date
+
+When casting between `date` and timestamp-like types (`timestamp` or `timestamptz`), the query timezone is used to determine the conversion:
+
+expression | meaning
+---- | ----
+`date_value::timestamp` | Interprets the date as midnight in the query timezone, returns a timestamp
+`date_value::timestamptz` | Interprets the date as midnight in the query timezone, returns a timestamptz
+`timestamp_value::date` | Converts the timestamp to a date in the query timezone
+`timestamptz_value::date` | Converts the timestamptz to a date in the query timezone
+
+For example, with `timezone: 'America/Mexico_City'`:
+- `@2020-02-20::timestamptz` creates a timestamptz representing midnight on Feb 20 in Mexico City
+- `@2020-02-20 00:00:00[UTC]::date` produces `@2020-02-19` (because midnight UTC is Feb 19 in Mexico City)
+
+### Casting between Timestamp and Timestamptz
+
+expression | meaning
+---- | ----
+`timestamp_value::timestamptz` | Converts timestamp to timestamptz (when no query timezone, interprets as UTC)
+`timestamptz_value::timestamp` | Converts timestamptz to timestamp in the query timezone
+
+* See [Timezones](timezones.malloynb) for more information on how timezones interact with casting.