docs: add .nullif() example

ibis-project · Oct 5, 2023 · 6d405df · 6d405df
1 parent 063cfba
commit 6d405df
Showing 1 changed file with 32 additions and 0 deletions.
diff --git a/ibis/expr/types/generic.py b/ibis/expr/types/generic.py
@@ -370,6 +370,8 @@ def nullif(self, null_if_expr: Value) -> Value:
         Commonly used to avoid divide-by-zero problems by replacing zero with
         `NULL` in the divisor.
 
+        Equivalent to `(self == null_if_expr).ifelse(ibis.null(), self)`.
+
         Parameters
         ----------
         null_if_expr
@@ -379,6 +381,36 @@ def nullif(self, null_if_expr: Value) -> Value:
         -------
         Value
             Value expression
+
+        Examples
+        --------
+        >>> import ibis
+        >>> ibis.options.interactive = True
+        >>> vals = ibis.examples.penguins.fetch().head(5).sex
+        >>> vals
+        ┏━━━━━━━━┓
+        ┃ sex    ┃
+        ┡━━━━━━━━┩
+        │ string │
+        ├────────┤
+        │ male   │
+        │ female │
+        │ female │
+        │ NULL   │
+        │ female │
+        └────────┘
+        >>> vals.nullif("male")
+        ┏━━━━━━━━━━━━━━━━━━━━━┓
+        ┃ NullIf(sex, 'male') ┃
+        ┡━━━━━━━━━━━━━━━━━━━━━┩
+        │ string              │
+        ├─────────────────────┤
+        │ NULL                │
+        │ female              │
+        │ female              │
+        │ NULL                │
+        │ female              │
+        └─────────────────────┘
         """
         return ops.NullIf(self, null_if_expr).to_expr()