Add nullif scalar function

Author: stephencelis

Sources/StructuredQueriesCore/Documentation.docc/Articles/ScalarFunctions.md

@@ -40,6 +40,7 @@ Explore the full list of available functions below.
 
 - ``QueryExpression/??(_:_:)``
 - ``QueryExpression/ifnull(_:)``
+- ``QueryExpression/nullif(_:)``
 
 ### Bytes
 

Sources/StructuredQueriesCore/ScalarFunctions.swift

@@ -67,6 +67,30 @@ where QueryValue: _OptionalPromotable, QueryValue._Optionalized.Wrapped: Numeric
   }
 }
 
+extension QueryExpression where QueryValue: _OptionalPromotable {
+  /// Wraps this query expression with the `nullif` function.
+  ///
+  /// ```swift
+  /// Reminder
+  ///   .select { $0.title.nullif("") }
+  /// // SELECT nullif("reminders"."title", '')
+  /// // FROM "reminders"
+  /// ```
+  ///
+  /// - Parameter other: An expression to compare against this expression.
+  /// - Returns: An optional expression of the `nullif` function wrapping this expression, which is
+  ///   `NULL` when both expressions are equal.
+  public func nullif<Other: QueryExpression>(
+    _ other: Other
+  ) -> some QueryExpression<QueryValue._Optionalized>
+  where
+    Other.QueryValue: _OptionalPromotable,
+    Other.QueryValue._Optionalized == QueryValue._Optionalized
+  {
+    QueryFunction("nullif", self, other)
+  }
+}
+
 extension QueryExpression where QueryValue: _OptionalProtocol {
   /// Wraps this optional query expression with the `ifnull` function.
   ///

Tests/StructuredQueriesTests/ScalarFunctionsTests.swift

@@ -220,5 +220,53 @@ extension SnapshotTests {
         """
       }
     }
+
+    @Test func nullif() {
+      assertQuery(Reminder.select { ($0.priority, $0.priority.nullif(Priority.high)) }) {
+        """
+        SELECT "reminders"."priority", nullif("reminders"."priority", 3)
+        FROM "reminders"
+        """
+      } results: {
+        """
+        ┌─────────┬─────────┐
+        │ nil     │ nil     │
+        │ nil     │ nil     │
+        │ .high   │ nil     │
+        │ nil     │ nil     │
+        │ nil     │ nil     │
+        │ .high   │ nil     │
+        │ .low    │ .low    │
+        │ .high   │ nil     │
+        │ nil     │ nil     │
+        │ .medium │ .medium │
+        └─────────┴─────────┘
+        """
+      }
+    }
+
+    @Test func nullifPromotesNonOptional() {
+      assertQuery(Reminder.select { $0.title.nullif("Groceries") }) {
+        """
+        SELECT nullif("reminders"."title", 'Groceries')
+        FROM "reminders"
+        """
+      } results: {
+        """
+        ┌────────────────────────────┐
+        │ nil                        │
+        │ "Haircut"                  │
+        │ "Doctor appointment"       │
+        │ "Take a walk"              │
+        │ "Buy concert tickets"      │
+        │ "Pick up kids from school" │
+        │ "Get laundry"              │
+        │ "Take out trash"           │
+        │ "Call accountant"          │
+        │ "Send weekly emails"       │
+        └────────────────────────────┘
+        """
+      }
+    }
   }
 }