Make FSTTimestamp into a public Firestore class (#698)

- FSTTimestamp is now FIRTimestamp, under Firestore/Source/{Public,API}. This is a temporary solution; eventually, FIRTimestamp is supposed to live somewhere under Firebase;
- move most internal Timestamp methods to the public header (the only exception is ISOString).

Author: var-const

Firestore/Example/Firestore.xcodeproj/project.pbxproj

@@ -54,7 +54,6 @@
 		5492E057202154AB00B64F25 /* FIRSnapshotMetadataTests.mm in Sources */ = {isa = PBXBuildFile; fileRef = 5492E04D202154AA00B64F25 /* FIRSnapshotMetadataTests.mm */; };
 		5492E058202154AB00B64F25 /* FSTAPIHelpers.mm in Sources */ = {isa = PBXBuildFile; fileRef = 5492E04E202154AA00B64F25 /* FSTAPIHelpers.mm */; };
 		5492E059202154AB00B64F25 /* FIRQuerySnapshotTests.mm in Sources */ = {isa = PBXBuildFile; fileRef = 5492E04F202154AA00B64F25 /* FIRQuerySnapshotTests.mm */; };
-		5492E062202154B900B64F25 /* FSTTimestampTests.mm in Sources */ = {isa = PBXBuildFile; fileRef = 5492E05B202154B800B64F25 /* FSTTimestampTests.mm */; };
 		5492E063202154B900B64F25 /* FSTViewSnapshotTest.mm in Sources */ = {isa = PBXBuildFile; fileRef = 5492E05C202154B800B64F25 /* FSTViewSnapshotTest.mm */; };
 		5492E064202154B900B64F25 /* FSTQueryListenerTests.mm in Sources */ = {isa = PBXBuildFile; fileRef = 5492E05D202154B900B64F25 /* FSTQueryListenerTests.mm */; };
 		5492E065202154B900B64F25 /* FSTViewTests.mm in Sources */ = {isa = PBXBuildFile; fileRef = 5492E05E202154B900B64F25 /* FSTViewTests.mm */; };
@@ -153,6 +152,7 @@
 		ABF6506C201131F8005F2C74 /* timestamp_test.cc in Sources */ = {isa = PBXBuildFile; fileRef = ABF6506B201131F8005F2C74 /* timestamp_test.cc */; };
 		AFE6114F0D4DAECBA7B7C089 /* Pods_Firestore_IntegrationTests.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = B2FA635DF5D116A67A7441CD /* Pods_Firestore_IntegrationTests.framework */; };
 		B6152AD7202A53CB000E5744 /* document_key_test.cc in Sources */ = {isa = PBXBuildFile; fileRef = B6152AD5202A5385000E5744 /* document_key_test.cc */; };
+		B65D34A9203C995B0076A5E1 /* FIRTimestampTest.m in Sources */ = {isa = PBXBuildFile; fileRef = B65D34A7203C99090076A5E1 /* FIRTimestampTest.m */; };
 		B686F2AF2023DDEE0028D6BE /* field_path_test.cc in Sources */ = {isa = PBXBuildFile; fileRef = B686F2AD2023DDB20028D6BE /* field_path_test.cc */; };
 		B686F2B22025000D0028D6BE /* resource_path_test.cc in Sources */ = {isa = PBXBuildFile; fileRef = B686F2B02024FFD70028D6BE /* resource_path_test.cc */; };
 		C4E749275AD0FBDF9F4716A8 /* Pods_SwiftBuildTest.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 32AD40BF6B0E849B07FFD05E /* Pods_SwiftBuildTest.framework */; };
@@ -243,7 +243,6 @@
 		5492E04E202154AA00B64F25 /* FSTAPIHelpers.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = FSTAPIHelpers.mm; sourceTree = "<group>"; };
 		5492E04F202154AA00B64F25 /* FIRQuerySnapshotTests.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = FIRQuerySnapshotTests.mm; sourceTree = "<group>"; };
 		5492E05A202154B800B64F25 /* FSTSyncEngine+Testing.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = "FSTSyncEngine+Testing.h"; sourceTree = "<group>"; };
-		5492E05B202154B800B64F25 /* FSTTimestampTests.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = FSTTimestampTests.mm; sourceTree = "<group>"; };
 		5492E05C202154B800B64F25 /* FSTViewSnapshotTest.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = FSTViewSnapshotTest.mm; sourceTree = "<group>"; };
 		5492E05D202154B900B64F25 /* FSTQueryListenerTests.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = FSTQueryListenerTests.mm; sourceTree = "<group>"; };
 		5492E05E202154B900B64F25 /* FSTViewTests.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = FSTViewTests.mm; sourceTree = "<group>"; };
@@ -359,6 +358,7 @@
 		ABF6506B201131F8005F2C74 /* timestamp_test.cc */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.cpp; path = timestamp_test.cc; sourceTree = "<group>"; };
 		B2FA635DF5D116A67A7441CD /* Pods_Firestore_IntegrationTests.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = Pods_Firestore_IntegrationTests.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		B6152AD5202A5385000E5744 /* document_key_test.cc */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = document_key_test.cc; sourceTree = "<group>"; };
+		B65D34A7203C99090076A5E1 /* FIRTimestampTest.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = FIRTimestampTest.m; sourceTree = "<group>"; };
 		B686F2AD2023DDB20028D6BE /* field_path_test.cc */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = field_path_test.cc; sourceTree = "<group>"; };
 		B686F2B02024FFD70028D6BE /* resource_path_test.cc */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = resource_path_test.cc; sourceTree = "<group>"; };
 		CE00BABB5A3AAB44A4C209E2 /* Pods-Firestore_Tests.debug.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-Firestore_Tests.debug.xcconfig"; path = "Pods/Target Support Files/Pods-Firestore_Tests/Pods-Firestore_Tests.debug.xcconfig"; sourceTree = "<group>"; };
@@ -697,6 +697,7 @@
 		DE51B1831F0D48AC0013853F /* API */ = {
 			isa = PBXGroup;
 			children = (
+				B65D34A7203C99090076A5E1 /* FIRTimestampTest.m */,
 				5492E045202154AA00B64F25 /* FIRCollectionReferenceTests.mm */,
 				5492E049202154AA00B64F25 /* FIRDocumentReferenceTests.mm */,
 				5492E04B202154AA00B64F25 /* FIRDocumentSnapshotTests.mm */,
@@ -771,7 +772,6 @@
 				5492E05D202154B900B64F25 /* FSTQueryListenerTests.mm */,
 				5492E061202154B900B64F25 /* FSTQueryTests.mm */,
 				5492E05A202154B800B64F25 /* FSTSyncEngine+Testing.h */,
-				5492E05B202154B800B64F25 /* FSTTimestampTests.mm */,
 				5492E05C202154B800B64F25 /* FSTViewSnapshotTest.mm */,
 				5492E05E202154B900B64F25 /* FSTViewTests.mm */,
 			);
@@ -1276,6 +1276,7 @@
 				5492E09E2021552D00B64F25 /* FSTEagerGarbageCollectorTests.mm in Sources */,
 				5492E0C62021557E00B64F25 /* FSTWatchChange+Testing.mm in Sources */,
 				5492E064202154B900B64F25 /* FSTQueryListenerTests.mm in Sources */,
+				B65D34A9203C995B0076A5E1 /* FIRTimestampTest.m in Sources */,
 				5492E03320213FFC00B64F25 /* FSTSyncEngineTestDriver.mm in Sources */,
 				AB380CFE201A2F4500D97691 /* string_util_test.cc in Sources */,
 				5492E0A42021552D00B64F25 /* FSTMemoryQueryCacheTests.mm in Sources */,
@@ -1353,7 +1354,6 @@
 				AB380D02201BC69F00D97691 /* bits_test.cc in Sources */,
 				548DB929200D59F600E00ABC /* comparison_test.cc in Sources */,
 				5492E03D2021401F00B64F25 /* FSTAssertTests.mm in Sources */,
-				5492E062202154B900B64F25 /* FSTTimestampTests.mm in Sources */,
 				AB38D93020236E21000A432D /* database_info_test.cc in Sources */,
 				5492E052202154AB00B64F25 /* FIRGeoPointTests.mm in Sources */,
 				5492E0C72021557E00B64F25 /* FSTSerializerBetaTests.mm in Sources */,

Firestore/Example/Tests/API/FIRTimestampTest.m

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2017 Google
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#import <XCTest/XCTest.h>
+
+#import "Firestore/Source/API/FIRTimestamp+Internal.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface FIRTimestampTest : XCTestCase
+@end
+
+NSDate *TestDate(int year, int month, int day, int hour, int minute, int second) {
+  NSDateComponents *comps = [[NSDateComponents alloc] init];
+  comps.year = year;
+  comps.month = month;
+  comps.day = day;
+  comps.hour = hour;
+  comps.minute = minute;
+  comps.second = second;
+  // Force time zone to UTC to avoid these values changing due to daylight saving.
+  comps.timeZone = [NSTimeZone timeZoneForSecondsFromGMT:0];
+
+  return [[NSCalendar currentCalendar] dateFromComponents:comps];
+}
+
+@implementation FIRTimestampTest
+
+- (void)testFromDate {
+  // Use an NSDate such that its fractional seconds have an exact representation to avoid losing
+  // precision.
+  NSDate *input = [NSDate dateWithTimeIntervalSinceReferenceDate:1.5];
+
+  FIRTimestamp *actual = [FIRTimestamp timestampWithDate:input];
+  static const int64_t kSecondsFromEpochToReferenceDate = 978307200;
+  XCTAssertEqual(kSecondsFromEpochToReferenceDate + 1, actual.seconds);
+  XCTAssertEqual(500000000, actual.nanoseconds);
+
+  FIRTimestamp *expected =
+      [[FIRTimestamp alloc] initWithSeconds:(kSecondsFromEpochToReferenceDate + 1)
+                                nanoseconds:500000000];
+  XCTAssertEqualObjects(expected, actual);
+}
+
+- (void)testSO8601String {
+  NSDate *date = TestDate(1912, 4, 14, 23, 40, 0);
+  FIRTimestamp *timestamp =
+      [[FIRTimestamp alloc] initWithSeconds:(int64_t)date.timeIntervalSince1970
+                                nanoseconds:543000000];
+  XCTAssertEqualObjects(timestamp.ISO8601String, @"1912-04-14T23:40:00.543000000Z");
+}
+
+- (void)testISO8601String_withLowMilliseconds {
+  NSDate *date = TestDate(1912, 4, 14, 23, 40, 0);
+  FIRTimestamp *timestamp =
+      [[FIRTimestamp alloc] initWithSeconds:(int64_t)date.timeIntervalSince1970
+                                nanoseconds:7000000];
+  XCTAssertEqualObjects(timestamp.ISO8601String, @"1912-04-14T23:40:00.007000000Z");
+}
+
+- (void)testISO8601String_withLowNanos {
+  FIRTimestamp *timestamp = [[FIRTimestamp alloc] initWithSeconds:0 nanoseconds:1];
+  XCTAssertEqualObjects(timestamp.ISO8601String, @"1970-01-01T00:00:00.000000001Z");
+}
+
+- (void)testISO8601String_withNegativeSeconds {
+  FIRTimestamp *timestamp = [[FIRTimestamp alloc] initWithSeconds:-1 nanoseconds:999999999];
+  XCTAssertEqualObjects(timestamp.ISO8601String, @"1969-12-31T23:59:59.999999999Z");
+}
+
+- (void)testCompare {
+  NSArray<FIRTimestamp *> *timestamps = @[
+    [[FIRTimestamp alloc] initWithSeconds:12344 nanoseconds:999999999],
+    [[FIRTimestamp alloc] initWithSeconds:12345 nanoseconds:0],
+    [[FIRTimestamp alloc] initWithSeconds:12345 nanoseconds:000000001],
+    [[FIRTimestamp alloc] initWithSeconds:12345 nanoseconds:99999999],
+    [[FIRTimestamp alloc] initWithSeconds:12345 nanoseconds:100000000],
+    [[FIRTimestamp alloc] initWithSeconds:12345 nanoseconds:100000001],
+    [[FIRTimestamp alloc] initWithSeconds:12346 nanoseconds:0],
+  ];
+  for (int i = 0; i < timestamps.count - 1; ++i) {
+    XCTAssertEqual(NSOrderedAscending, [timestamps[i] compare:timestamps[i + 1]]);
+    XCTAssertEqual(NSOrderedDescending, [timestamps[i + 1] compare:timestamps[i]]);
+  }
+}
+
+@end
+
+NS_ASSUME_NONNULL_END

Firestore/Example/Tests/Core/FSTTimestampTests.mm

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+#import <FirebaseFirestore/FIRTimestamp.h>
 #import <FirebaseFirestore/FirebaseFirestore.h>
 
 #import <XCTest/XCTest.h>
@@ -220,4 +221,28 @@ - (void)testFieldsWithSpecialCharsCanBeUsedInOrderBy {
   [self awaitExpectations];
 }
 
+- (NSDictionary<NSString *, id> *)testDataWithTimestamp:(FIRTimestamp *)timestamp {
+  return @{
+    @"timestamp" : [timestamp approximateDateValue],
+    @"metadata" : @{@"nestedTimestamp" : [timestamp approximateDateValue]}
+  };
+}
+
+// This test should break once the default for how timestamps are returned changes.
+- (void)testThatDataContainsNativeDateType {
+  NSDate *date = [NSDate date];
+  FIRTimestamp *timestamp = [FIRTimestamp timestampWithDate:date];
+  FIRDocumentReference *doc = [self documentRef];
+  [self writeDocumentRef:doc data:[self testDataWithTimestamp:timestamp]];
+
+  FIRDocumentSnapshot *result = [self readDocumentForRef:doc];
+  NSDate *resultDate = result.data[@"timestamp"];
+  XCTAssertEqualWithAccuracy([resultDate timeIntervalSince1970], [date timeIntervalSince1970],
+                             0.000001);
+  XCTAssertEqualObjects(result.data[@"timestamp"], resultDate);
+  NSDate *resultNestedDate = result[@"metadata.nestedTimestamp"];
+  XCTAssertEqualWithAccuracy([resultNestedDate timeIntervalSince1970], [date timeIntervalSince1970],
+                             0.000001);
+}
+
 @end

Firestore/Example/Tests/Integration/API/FIRFieldsTests.mm

@@ -16,6 +16,7 @@
 
 #import <FirebaseFirestore/FirebaseFirestore.h>
 
+#import <FirebaseFirestore/FIRTimestamp.h>
 #import <GRPCClient/GRPCCall+ChannelCredentials.h>
 #import <GRPCClient/GRPCCall+Tests.h>
 #import <XCTest/XCTest.h>
@@ -26,7 +27,6 @@
 #import "Firestore/Source/Core/FSTFirestoreClient.h"
 #import "Firestore/Source/Core/FSTQuery.h"
 #import "Firestore/Source/Core/FSTSnapshotVersion.h"
-#import "Firestore/Source/Core/FSTTimestamp.h"
 #import "Firestore/Source/Local/FSTQueryData.h"
 #import "Firestore/Source/Model/FSTDocumentKey.h"
 #import "Firestore/Source/Model/FSTFieldValue.h"
@@ -214,7 +214,7 @@ - (void)testStreamingWrite {
 
   FSTSetMutation *mutation = [self setMutation];
   FSTMutationBatch *batch = [[FSTMutationBatch alloc] initWithBatchID:23
-                                                       localWriteTime:[FSTTimestamp timestamp]
+                                                       localWriteTime:[FIRTimestamp timestamp]
                                                             mutations:@[ mutation ]];
   [_testWorkerQueue dispatchAsync:^{
     [_remoteStore commitBatch:batch];

Firestore/Example/Tests/Integration/FSTDatastoreTests.mm

@@ -16,6 +16,7 @@
 
 #import "Firestore/Source/Local/FSTLocalSerializer.h"
 
+#import <FirebaseFirestore/FIRTimestamp.h>
 #import <XCTest/XCTest.h>
 
 #import "Firestore/Protos/objc/firestore/local/MaybeDocument.pbobjc.h"
@@ -29,7 +30,6 @@
 #import "Firestore/Protos/objc/google/type/Latlng.pbobjc.h"
 #import "Firestore/Source/Core/FSTQuery.h"
 #import "Firestore/Source/Core/FSTSnapshotVersion.h"
-#import "Firestore/Source/Core/FSTTimestamp.h"
 #import "Firestore/Source/Local/FSTQueryData.h"
 #import "Firestore/Source/Model/FSTDocument.h"
 #import "Firestore/Source/Model/FSTDocumentKey.h"
@@ -83,7 +83,7 @@ - (void)testEncodesMutationBatch {
                           @"num" : @1 })
       precondition:[FSTPrecondition preconditionWithExists:YES]];
   FSTMutation *del = FSTTestDeleteMutation(@"baz/quux");
-  FSTTimestamp *writeTime = [FSTTimestamp timestamp];
+  FIRTimestamp *writeTime = [FIRTimestamp timestamp];
   FSTMutationBatch *model = [[FSTMutationBatch alloc] initWithBatchID:42
                                                        localWriteTime:writeTime
                                                             mutations:@[ set, patch, del ]];
@@ -109,7 +109,7 @@ - (void)testEncodesMutationBatch {
 
   GPBTimestamp *writeTimeProto = [GPBTimestamp message];
   writeTimeProto.seconds = writeTime.seconds;
-  writeTimeProto.nanos = writeTime.nanos;
+  writeTimeProto.nanos = writeTime.nanoseconds;
 
   FSTPBWriteBatch *batchProto = [FSTPBWriteBatch message];
   batchProto.batchId = 42;

Firestore/Example/Tests/Local/FSTLocalSerializerTests.mm

@@ -16,10 +16,10 @@
 
 #import "Firestore/Source/Local/FSTLocalStore.h"
 
+#import <FirebaseFirestore/FIRTimestamp.h>
 #import <XCTest/XCTest.h>
 
 #import "Firestore/Source/Core/FSTQuery.h"
-#import "Firestore/Source/Core/FSTTimestamp.h"
 #import "Firestore/Source/Local/FSTEagerGarbageCollector.h"
 #import "Firestore/Source/Local/FSTLocalWriteResult.h"
 #import "Firestore/Source/Local/FSTNoOpGarbageCollector.h"
@@ -127,7 +127,7 @@ - (void)writeMutations:(NSArray<FSTMutation *> *)mutations {
   FSTLocalWriteResult *result = [self.localStore locallyWriteMutations:mutations];
   XCTAssertNotNil(result);
   [self.batches addObject:[[FSTMutationBatch alloc] initWithBatchID:result.batchID
-                                                     localWriteTime:[FSTTimestamp timestamp]
+                                                     localWriteTime:[FIRTimestamp timestamp]
                                                           mutations:mutations]];
   self.lastChanges = result.changes;
 }
@@ -228,7 +228,7 @@ - (void)testMutationBatchKeys {
   FSTMutation *set1 = FSTTestSetMutation(@"foo/bar", @{@"foo" : @"bar"});
   FSTMutation *set2 = FSTTestSetMutation(@"bar/baz", @{@"bar" : @"baz"});
   FSTMutationBatch *batch = [[FSTMutationBatch alloc] initWithBatchID:1
-                                                       localWriteTime:[FSTTimestamp timestamp]
+                                                       localWriteTime:[FIRTimestamp timestamp]
                                                             mutations:@[ set1, set2 ]];
   FSTDocumentKeySet *keys = [batch keys];
   XCTAssertEqual(keys.count, 2);