feat: Add timestamp expressions (#7955)

Add new timestamp expressions `timestamp_diff` and `timestamp_extract`
and integration tests for the expressions

The expression `timestamp_trunc` already existed in the repo with
integration tests.
Add methods for timestampTruncWithTimezone to avoid signature collision.
Add methods to allow timezone as parameter in chained expressions.
Amend the tests for the `timestamp_trunc` expression

Ported from firebase/firebase-js-sdk#9728

Author: yvonnep165

firebase-firestore/CHANGELOG.md

@@ -1,5 +1,7 @@
 # Unreleased
 
+- [feature] Added support for `timestampTruncate`, `timestampDiff`, and `timestampExtract` Pipeline expressions.
+  [#7955](https://github.com/firebase/firebase-android-sdk/pull/7955)
 - [feature] Pipeline operations are GA now.
 - [feature] Added support for Pipeline Subqueries, including `define` and `variable` expressions.
   [#7736](https://github.com/firebase/firebase-android-sdk/pull/7736)

firebase-firestore/api.txt

@@ -1263,6 +1263,32 @@ package com.google.firebase.firestore.pipeline {
     method public static final com.google.firebase.firestore.pipeline.Expression timestampAdd(String fieldName, com.google.firebase.firestore.pipeline.Expression unit, com.google.firebase.firestore.pipeline.Expression amount);
     method public static final com.google.firebase.firestore.pipeline.Expression timestampAdd(String fieldName, String unit, long amount);
     method public final com.google.firebase.firestore.pipeline.Expression timestampAdd(String unit, long amount);
+    method public final com.google.firebase.firestore.pipeline.Expression timestampDiff(com.google.firebase.firestore.pipeline.Expression start, com.google.firebase.firestore.pipeline.Expression unit);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampDiff(com.google.firebase.firestore.pipeline.Expression end, com.google.firebase.firestore.pipeline.Expression start, com.google.firebase.firestore.pipeline.Expression unit);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampDiff(com.google.firebase.firestore.pipeline.Expression end, com.google.firebase.firestore.pipeline.Expression start, String unit);
+    method public final com.google.firebase.firestore.pipeline.Expression timestampDiff(com.google.firebase.firestore.pipeline.Expression start, String unit);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampDiff(com.google.firebase.firestore.pipeline.Expression end, String startFieldName, String unit);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampDiff(String endFieldName, com.google.firebase.firestore.pipeline.Expression start, String unit);
+    method public final com.google.firebase.firestore.pipeline.Expression timestampDiff(String startFieldName, String unit);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampDiff(String endFieldName, String startFieldName, String unit);
+    method public final com.google.firebase.firestore.pipeline.Expression timestampExtract(com.google.firebase.firestore.pipeline.Expression part);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampExtract(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression part);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampExtract(com.google.firebase.firestore.pipeline.Expression timestamp, String part);
+    method public final com.google.firebase.firestore.pipeline.Expression timestampExtract(String part);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampExtract(String fieldName, com.google.firebase.firestore.pipeline.Expression part);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampExtract(String fieldName, String part);
+    method public final com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(com.google.firebase.firestore.pipeline.Expression part, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression part, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression part, String timezone);
+    method public final com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(com.google.firebase.firestore.pipeline.Expression part, String timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, String part, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, String part, String timezone);
+    method public final com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(String part, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(String fieldName, com.google.firebase.firestore.pipeline.Expression part, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(String fieldName, com.google.firebase.firestore.pipeline.Expression part, String timezone);
+    method public final com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(String part, String timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(String fieldName, String part, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(String fieldName, String part, String timezone);
     method public final com.google.firebase.firestore.pipeline.Expression timestampSubtract(com.google.firebase.firestore.pipeline.Expression unit, com.google.firebase.firestore.pipeline.Expression amount);
     method public static final com.google.firebase.firestore.pipeline.Expression timestampSubtract(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression unit, com.google.firebase.firestore.pipeline.Expression amount);
     method public static final com.google.firebase.firestore.pipeline.Expression timestampSubtract(com.google.firebase.firestore.pipeline.Expression timestamp, String unit, long amount);
@@ -1280,14 +1306,22 @@ package com.google.firebase.firestore.pipeline {
     method public static final com.google.firebase.firestore.pipeline.Expression timestampToUnixSeconds(String fieldName);
     method public final com.google.firebase.firestore.pipeline.Expression timestampTruncate(com.google.firebase.firestore.pipeline.Expression granularity);
     method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncate(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression granularity);
-    method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncate(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression granularity, String timezone);
     method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncate(com.google.firebase.firestore.pipeline.Expression timestamp, String granularity);
-    method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncate(com.google.firebase.firestore.pipeline.Expression timestamp, String granularity, String timezone);
     method public final com.google.firebase.firestore.pipeline.Expression timestampTruncate(String granularity);
     method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncate(String fieldName, com.google.firebase.firestore.pipeline.Expression granularity);
-    method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncate(String fieldName, com.google.firebase.firestore.pipeline.Expression granularity, String timezone);
     method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncate(String fieldName, String granularity);
-    method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncate(String fieldName, String granularity, String timezone);
+    method public final com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(com.google.firebase.firestore.pipeline.Expression granularity, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression granularity, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression granularity, String timezone);
+    method public final com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(com.google.firebase.firestore.pipeline.Expression granularity, String timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, String granularity, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, String granularity, String timezone);
+    method public final com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(String granularity, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(String fieldName, com.google.firebase.firestore.pipeline.Expression granularity, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(String fieldName, com.google.firebase.firestore.pipeline.Expression granularity, String timezone);
+    method public final com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(String granularity, String timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(String fieldName, String granularity, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public static final com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(String fieldName, String granularity, String timezone);
     method public final com.google.firebase.firestore.pipeline.Expression toLower();
     method public static final com.google.firebase.firestore.pipeline.Expression toLower(com.google.firebase.firestore.pipeline.Expression stringExpression);
     method public static final com.google.firebase.firestore.pipeline.Expression toLower(String fieldName);
@@ -1637,6 +1671,23 @@ package com.google.firebase.firestore.pipeline {
     method public com.google.firebase.firestore.pipeline.Expression timestampAdd(com.google.firebase.firestore.pipeline.Expression timestamp, String unit, long amount);
     method public com.google.firebase.firestore.pipeline.Expression timestampAdd(String fieldName, com.google.firebase.firestore.pipeline.Expression unit, com.google.firebase.firestore.pipeline.Expression amount);
     method public com.google.firebase.firestore.pipeline.Expression timestampAdd(String fieldName, String unit, long amount);
+    method public com.google.firebase.firestore.pipeline.Expression timestampDiff(com.google.firebase.firestore.pipeline.Expression end, com.google.firebase.firestore.pipeline.Expression start, com.google.firebase.firestore.pipeline.Expression unit);
+    method public com.google.firebase.firestore.pipeline.Expression timestampDiff(com.google.firebase.firestore.pipeline.Expression end, com.google.firebase.firestore.pipeline.Expression start, String unit);
+    method public com.google.firebase.firestore.pipeline.Expression timestampDiff(com.google.firebase.firestore.pipeline.Expression end, String startFieldName, String unit);
+    method public com.google.firebase.firestore.pipeline.Expression timestampDiff(String endFieldName, com.google.firebase.firestore.pipeline.Expression start, String unit);
+    method public com.google.firebase.firestore.pipeline.Expression timestampDiff(String endFieldName, String startFieldName, String unit);
+    method public com.google.firebase.firestore.pipeline.Expression timestampExtract(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression part);
+    method public com.google.firebase.firestore.pipeline.Expression timestampExtract(com.google.firebase.firestore.pipeline.Expression timestamp, String part);
+    method public com.google.firebase.firestore.pipeline.Expression timestampExtract(String fieldName, com.google.firebase.firestore.pipeline.Expression part);
+    method public com.google.firebase.firestore.pipeline.Expression timestampExtract(String fieldName, String part);
+    method public com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression part, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression part, String timezone);
+    method public com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, String part, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, String part, String timezone);
+    method public com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(String fieldName, com.google.firebase.firestore.pipeline.Expression part, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(String fieldName, com.google.firebase.firestore.pipeline.Expression part, String timezone);
+    method public com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(String fieldName, String part, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public com.google.firebase.firestore.pipeline.Expression timestampExtractWithTimezone(String fieldName, String part, String timezone);
     method public com.google.firebase.firestore.pipeline.Expression timestampSubtract(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression unit, com.google.firebase.firestore.pipeline.Expression amount);
     method public com.google.firebase.firestore.pipeline.Expression timestampSubtract(com.google.firebase.firestore.pipeline.Expression timestamp, String unit, long amount);
     method public com.google.firebase.firestore.pipeline.Expression timestampSubtract(String fieldName, com.google.firebase.firestore.pipeline.Expression unit, com.google.firebase.firestore.pipeline.Expression amount);
@@ -1648,13 +1699,17 @@ package com.google.firebase.firestore.pipeline {
     method public com.google.firebase.firestore.pipeline.Expression timestampToUnixSeconds(com.google.firebase.firestore.pipeline.Expression expr);
     method public com.google.firebase.firestore.pipeline.Expression timestampToUnixSeconds(String fieldName);
     method public com.google.firebase.firestore.pipeline.Expression timestampTruncate(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression granularity);
-    method public com.google.firebase.firestore.pipeline.Expression timestampTruncate(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression granularity, String timezone);
     method public com.google.firebase.firestore.pipeline.Expression timestampTruncate(com.google.firebase.firestore.pipeline.Expression timestamp, String granularity);
-    method public com.google.firebase.firestore.pipeline.Expression timestampTruncate(com.google.firebase.firestore.pipeline.Expression timestamp, String granularity, String timezone);
     method public com.google.firebase.firestore.pipeline.Expression timestampTruncate(String fieldName, com.google.firebase.firestore.pipeline.Expression granularity);
-    method public com.google.firebase.firestore.pipeline.Expression timestampTruncate(String fieldName, com.google.firebase.firestore.pipeline.Expression granularity, String timezone);
     method public com.google.firebase.firestore.pipeline.Expression timestampTruncate(String fieldName, String granularity);
-    method public com.google.firebase.firestore.pipeline.Expression timestampTruncate(String fieldName, String granularity, String timezone);
+    method public com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression granularity, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, com.google.firebase.firestore.pipeline.Expression granularity, String timezone);
+    method public com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, String granularity, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(com.google.firebase.firestore.pipeline.Expression timestamp, String granularity, String timezone);
+    method public com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(String fieldName, com.google.firebase.firestore.pipeline.Expression granularity, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(String fieldName, com.google.firebase.firestore.pipeline.Expression granularity, String timezone);
+    method public com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(String fieldName, String granularity, com.google.firebase.firestore.pipeline.Expression timezone);
+    method public com.google.firebase.firestore.pipeline.Expression timestampTruncateWithTimezone(String fieldName, String granularity, String timezone);
     method public com.google.firebase.firestore.pipeline.Expression toLower(com.google.firebase.firestore.pipeline.Expression stringExpression);
     method public com.google.firebase.firestore.pipeline.Expression toLower(String fieldName);
     method public com.google.firebase.firestore.pipeline.Expression toUpper(com.google.firebase.firestore.pipeline.Expression stringExpression);