Skip to content

Commit 377dc36

Browse files
cherylEnkiducherylEnkidu
committed
add documentations
1 parent d30437f commit 377dc36

File tree

5 files changed

+161
-119
lines changed

5 files changed

+161
-119
lines changed

‎Firestore/Swift/Source/ExprImpl.swift‎

Lines changed: 13 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -112,64 +112,56 @@ public extension Expression {
112112
return FunctionExpression("array_get", [self, offsetExpr])
113113
}
114114

115-
func gt(_ other: Expression) -> BooleanExpression {
115+
func greaterThan(_ other: Expression) -> BooleanExpression {
116116
return BooleanExpression("gt", [self, other])
117117
}
118118

119-
func gt(_ other: Sendable) -> BooleanExpression {
119+
func greaterThan(_ other: Sendable) -> BooleanExpression {
120120
let exprOther = Helper.sendableToExpr(other)
121121
return BooleanExpression("gt", [self, exprOther])
122122
}
123123

124-
// MARK: - Greater Than or Equal (gte)
125-
126-
func gte(_ other: Expression) -> BooleanExpression {
124+
func greaterThanOrEqualTo(_ other: Expression) -> BooleanExpression {
127125
return BooleanExpression("gte", [self, other])
128126
}
129127

130-
func gte(_ other: Sendable) -> BooleanExpression {
128+
func greaterThanOrEqualTo(_ other: Sendable) -> BooleanExpression {
131129
let exprOther = Helper.sendableToExpr(other)
132130
return BooleanExpression("gte", [self, exprOther])
133131
}
134132

135-
// MARK: - Less Than (lt)
136-
137-
func lt(_ other: Expression) -> BooleanExpression {
133+
func lessThan(_ other: Expression) -> BooleanExpression {
138134
return BooleanExpression("lt", [self, other])
139135
}
140136

141-
func lt(_ other: Sendable) -> BooleanExpression {
137+
func lessThan(_ other: Sendable) -> BooleanExpression {
142138
let exprOther = Helper.sendableToExpr(other)
143139
return BooleanExpression("lt", [self, exprOther])
144140
}
145141

146-
// MARK: - Less Than or Equal (lte)
147-
148-
func lte(_ other: Expression) -> BooleanExpression {
142+
func lessThanOrEqualTo(_ other: Expression) -> BooleanExpression {
149143
return BooleanExpression("lte", [self, other])
150144
}
151145

152-
func lte(_ other: Sendable) -> BooleanExpression {
146+
func lessThanOrEqualTo(_ other: Sendable) -> BooleanExpression {
153147
let exprOther = Helper.sendableToExpr(other)
154148
return BooleanExpression("lte", [self, exprOther])
155149
}
156150

157-
// MARK: - Equal (eq)
158-
159-
func eq(_ other: Expression) -> BooleanExpression {
151+
func equal(_ other: Expression) -> BooleanExpression {
160152
return BooleanExpression("eq", [self, other])
161153
}
162154

163-
func eq(_ other: Sendable) -> BooleanExpression {
155+
func equal(_ other: Sendable) -> BooleanExpression {
164156
let exprOther = Helper.sendableToExpr(other)
165157
return BooleanExpression("eq", [self, exprOther])
166158
}
167159

168-
func neq(_ other: Expression) -> BooleanExpression {
160+
func notEqual(_ other: Expression) -> BooleanExpression {
169161
return BooleanExpression("neq", [self, other])
170162
}
171163

172-
func neq(_ other: Sendable) -> BooleanExpression {
164+
func notEqual(_ other: Sendable) -> BooleanExpression {
173165
return BooleanExpression("neq", [self, Helper.sendableToExpr(other)])
174166
}
175167

@@ -376,7 +368,7 @@ public extension Expression {
376368
return AggregateFunction("sum", [self])
377369
}
378370

379-
func avg() -> AggregateFunction {
371+
func average() -> AggregateFunction {
380372
return AggregateFunction("avg", [self])
381373
}
382374

‎Firestore/Swift/Source/SwiftAPI/Pipeline/Expression.swift‎

Lines changed: 75 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -332,39 +332,89 @@ public protocol Expression: Sendable {
332332
/// - Returns: A new `FunctionExpression` representing the "arrayGet" operation.
333333
func arrayGet(_ offsetExpr: Expression) -> FunctionExpression
334334

335-
func gt(_ other: Expression) -> BooleanExpression
336-
337-
func gt(_ other: Sendable) -> BooleanExpression
338-
339-
// MARK: - Greater Than or Equal (gte)
340-
341-
func gte(_ other: Expression) -> BooleanExpression
342-
343-
func gte(_ other: Sendable) -> BooleanExpression
344-
345-
// MARK: - Less Than (lt)
335+
/// Creates a `BooleanExpr` that returns `true` if this expression is greater
336+
/// than the given expression.
337+
///
338+
/// - Parameter other: The expression to compare against.
339+
/// - Returns: A `BooleanExpr` that can be used in `where` clauses.
340+
func greaterThan(_ other: Expression) -> BooleanExpression
346341

347-
func lt(_ other: Expression) -> BooleanExpression
342+
/// Creates a `BooleanExpr` that returns `true` if this expression is greater
343+
/// than the given value.
344+
///
345+
/// - Parameter other: The value to compare against.
346+
/// - Returns: A `BooleanExpr` that can be used in `where` clauses.
347+
func greaterThan(_ other: Sendable) -> BooleanExpression
348348

349-
func lt(_ other: Sendable) -> BooleanExpression
349+
/// Creates a `BooleanExpr` that returns `true` if this expression is
350+
/// greater than or equal to the given expression.
351+
///
352+
/// - Parameter other: The expression to compare against.
353+
/// - Returns: A `BooleanExpr` that can be used in `where` clauses.
354+
func greaterThanOrEqualTo(_ other: Expression) -> BooleanExpression
350355

351-
// MARK: - Less Than or Equal (lte)
356+
/// Creates a `BooleanExpr` that returns `true` if this expression is
357+
/// greater than or equal to the given value.
358+
///
359+
/// - Parameter other: The value to compare against.
360+
/// - Returns: A `BooleanExpr` that can be used in `where` clauses.
361+
func greaterThanOrEqualTo(_ other: Sendable) -> BooleanExpression
352362

353-
func lte(_ other: Expression) -> BooleanExpression
363+
/// Creates a `BooleanExpr` that returns `true` if this expression is less
364+
/// than the given expression.
365+
///
366+
/// - Parameter other: The expression to compare against.
367+
/// - Returns: A `BooleanExpr` that can be used in `where` clauses.
368+
func lessThan(_ other: Expression) -> BooleanExpression
354369

355-
func lte(_ other: Sendable) -> BooleanExpression
370+
/// Creates a `BooleanExpr` that returns `true` if this expression is less
371+
/// than the given value.
372+
///
373+
/// - Parameter other: The value to compare against.
374+
/// - Returns: A `BooleanExpr` that can be used in `where` clauses.
375+
func lessThan(_ other: Sendable) -> BooleanExpression
356376

357-
// MARK: - Equal (eq)
377+
/// Creates a `BooleanExpr` that returns `true` if this expression is less
378+
/// than or equal to the given expression.
379+
///
380+
/// - Parameter other: The expression to compare against.
381+
/// - Returns: A `BooleanExpr` that can be used in `where` clauses.
382+
func lessThanOrEqualTo(_ other: Expression) -> BooleanExpression
358383

359-
func eq(_ other: Expression) -> BooleanExpression
384+
/// Creates a `BooleanExpr` that returns `true` if this expression is less
385+
/// than or equal to the given value.
386+
///
387+
/// - Parameter other: The value to compare against.
388+
/// - Returns: A `BooleanExpr` that can be used in `where` clauses.
389+
func lessThanOrEqualTo(_ other: Sendable) -> BooleanExpression
360390

361-
func eq(_ other: Sendable) -> BooleanExpression
391+
/// Creates a `BooleanExpr` that returns `true` if this expression is equal
392+
/// to the given expression.
393+
///
394+
/// - Parameter other: The expression to compare against.
395+
/// - Returns: A `BooleanExpr` that can be used in `where` clauses.
396+
func equal(_ other: Expression) -> BooleanExpression
362397

363-
func neq(_ other: Expression) -> BooleanExpression
398+
/// Creates a `BooleanExpr` that returns `true` if this expression is equal
399+
/// to the given value.
400+
///
401+
/// - Parameter other: The value to compare against.
402+
/// - Returns: A `BooleanExpr` that can be used in `where` clauses.
403+
func equal(_ other: Sendable) -> BooleanExpression
364404

365-
func neq(_ other: Sendable) -> BooleanExpression
405+
/// Creates a `BooleanExpr` that returns `true` if this expression is not
406+
/// equal to the given expression.
407+
///
408+
/// - Parameter other: The expression to compare against.
409+
/// - Returns: A `BooleanExpr` that can be used in `where` clauses.
410+
func notEqual(_ other: Expression) -> BooleanExpression
366411

367-
// MARK: Equality with Sendable
412+
/// Creates a `BooleanExpr` that returns `true` if this expression is not
413+
/// equal to the given value.
414+
///
415+
/// - Parameter other: The value to compare against.
416+
/// - Returns: A `BooleanExpr` that can be used in `where` clauses.
417+
func notEqual(_ other: Sendable) -> BooleanExpression
368418

369419
/// Creates an expression that checks if this expression is equal to any of the provided
370420
/// expression values.
@@ -972,11 +1022,11 @@ public protocol Expression: Sendable {
9721022
///
9731023
/// ```swift
9741024
/// // Calculate the average age of users
975-
/// Field("age").avg().alias("averageAge")
1025+
/// Field("age").average().alias("averageAge")
9761026
/// ```
9771027
///
978-
/// - Returns: A new `AggregateFunction` representing the "avg" aggregation.
979-
func avg() -> AggregateFunction
1028+
/// - Returns: A new `AggregateFunction` representing the "average" aggregation.
1029+
func average() -> AggregateFunction
9801030

9811031
/// Creates an aggregation that finds the minimum value of this expression across multiple stage
9821032
/// inputs.

‎Firestore/Swift/Source/SwiftAPI/Pipeline/Pipeline.swift‎

Lines changed: 16 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -44,36 +44,34 @@ import Foundation
4444
/// // Example 1: Select specific fields and rename 'rating' to 'bookRating'.
4545
/// // Assumes `Field("rating").as("bookRating")` is a valid `Selectable` expression.
4646
/// do {
47-
/// let results1 = try await db.pipeline().collection("books")
47+
/// let snapshot1 = try await db.pipeline().collection("books")
4848
/// .select(Field("title"), Field("author"), Field("rating").as("bookRating"))
4949
/// .execute()
50-
/// print("Results 1: \(results1.documents)")
50+
/// print("Results 1: \(snapshot1.results)")
5151
/// } catch {
5252
/// print("Error in example 1: \(error)")
5353
/// }
5454
///
5555
/// // Example 2: Filter documents where 'genre' is "Science Fiction" and 'published' is after 1950.
56-
/// // Assumes `Function.eq`, `Function.gt`, and `Function.and` create `BooleanExpr`.
5756
/// do {
58-
/// let results2 = try await db.pipeline().collection("books")
59-
/// .where(Function.and(
60-
/// Function.eq(Field("genre"), "Science Fiction"),
61-
/// Function.gt(Field("published"), 1950)
62-
/// ))
57+
/// let snapshot2 = try await db.pipeline().collection("books")
58+
/// .where(
59+
/// Field("genre").equal("Science Fiction")
60+
/// && Field("published").greaterThan(1950)
61+
/// )
6362
/// .execute()
64-
/// print("Results 2: \(results2.documents)")
63+
/// print("Results 2: \(snapshot2.results)")
6564
/// } catch {
6665
/// print("Error in example 2: \(error)")
6766
/// }
6867
///
6968
/// // Example 3: Calculate the average rating of books published after 1980.
70-
/// // Assumes `avg()` creates an `Accumulator` and `AggregateWithAlias` is used correctly.
7169
/// do {
72-
/// let results3 = try await db.pipeline().collection("books")
73-
/// .where(Function.gt(Field("published"), 1980))
74-
/// .aggregate(AggregateWithas(avg(Field("rating")), alias: "averageRating"))
70+
/// let snapshot3 = try await db.pipeline().collection("books")
71+
/// .where(Field("published").greaterThan(1980))
72+
/// .aggregate(Field("rating").average().as("averageRating"))
7573
/// .execute()
76-
/// print("Results 3: \(results3.documents)")
74+
/// print("Results 3: \(snapshot3.results)")
7775
/// } catch {
7876
/// print("Error in example 3: \(error)")
7977
/// }
@@ -249,15 +247,16 @@ public struct Pipeline: @unchecked Sendable {
249247
///
250248
/// This stage applies conditions similar to a "WHERE" clause in SQL.
251249
/// Filter documents based on field values using `BooleanExpr` implementations, such as:
252-
/// - Field comparators: `Function.eq`, `Function.lt` (less than), `Function.gt` (greater than).
250+
/// - Field comparators: `Function.equal`, `Function.lessThan` (less than), `Function.gt` (greater
251+
/// than).
253252
/// - Logical operators: `Function.and`, `Function.or`, `Function.not`.
254253
/// - Advanced functions: `Function.regexMatch`, `Function.arrayContains`.
255254
///
256255
/// ```swift
257256
/// // let pipeline: Pipeline = ... // Assume initial pipeline.
258257
/// let filteredPipeline = pipeline.where(
259258
/// Field("rating").gt(4.0) // Rating greater than 4.0.
260-
/// && Field("genre").eq("Science Fiction") // Genre is "Science Fiction".
259+
/// && Field("genre").equal("Science Fiction") // Genre is "Science Fiction".
261260
/// )
262261
/// // let results = try await filteredPipeline.execute()
263262
/// ```
@@ -378,7 +377,7 @@ public struct Pipeline: @unchecked Sendable {
378377
/// // let pipeline: Pipeline = ... // Assume pipeline from "books" collection.
379378
/// // Calculate the average rating for each genre.
380379
/// let groupedAggregationPipeline = pipeline.aggregate(
381-
/// [AggregateWithas(aggregate: avg(Field("rating")), alias: "avg_rating")],
380+
/// [AggregateWithas(aggregate: average(Field("rating")), alias: "avg_rating")],
382381
/// groups: [Field("genre")] // Group by the "genre" field.
383382
/// )
384383
/// // let results = try await groupedAggregationPipeline.execute()

‎Firestore/Swift/Tests/Integration/PipelineApiTests.swift‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ final class PipelineApiTests: FSTIntegrationTestCase {
4545
func testWhereStage() async throws {
4646
_ = db.pipeline().collection("books")
4747
.where(
48-
Field("rating").gt(4.0) && Field("genre").eq("Science Fiction") || Field("tags")
48+
Field("rating").greaterThan(4.0) && Field("genre").equal("Science Fiction") || Field("tags")
4949
.arrayContains("comedy")
5050
)
5151
}
@@ -174,7 +174,7 @@ final class PipelineApiTests: FSTIntegrationTestCase {
174174
_ = db.pipeline().collection("books")
175175
.aggregate(
176176
[
177-
Field("rating").avg().as("averageRating"),
177+
Field("rating").average().as("averageRating"),
178178
CountAll().as("totalBooks"),
179179
]
180180
)
@@ -190,7 +190,7 @@ final class PipelineApiTests: FSTIntegrationTestCase {
190190
// Calculate the average rating and the total number of books and group by field 'genre'
191191
_ = db.pipeline().collection("books")
192192
.aggregate([
193-
Field("rating").avg().as("averageRating"),
193+
Field("rating").average().as("averageRating"),
194194
CountAll().as("totalBooks"),
195195
],
196196
groups: [Field("genre")])
@@ -277,7 +277,7 @@ final class PipelineApiTests: FSTIntegrationTestCase {
277277
_ = db.pipeline().collection("books")
278278
.rawStage(
279279
name: "where",
280-
params: [Field("published").lt(1900)]
280+
params: [Field("published").lessThan(1900)]
281281
)
282282
.select(["title", "author"])
283283

@@ -287,7 +287,7 @@ final class PipelineApiTests: FSTIntegrationTestCase {
287287
_ = db.pipeline().collection("books")
288288
.rawStage(
289289
name: "where",
290-
params: [Field("published").lt(1900)],
290+
params: [Field("published").lessThan(1900)],
291291
options: ["someOptionalParamName": "the argument value for this param"]
292292
)
293293
.select(["title", "author"])
@@ -346,7 +346,7 @@ final class PipelineApiTests: FSTIntegrationTestCase {
346346
}
347347

348348
func testBooleanExpr() async throws {
349-
let isApple: BooleanExpression = Field("type").eq("apple")
349+
let isApple: BooleanExpression = Field("type").equal("apple")
350350

351351
// USAGE: stage where requires an expression of type BooleanExpr
352352
let _: Pipeline = db.pipeline().collection("fruitOptions").where(isApple)

0 commit comments

Comments
 (0)