comphead commented on code in PR #7732:
URL: https://github.com/apache/arrow-datafusion/pull/7732#discussion_r1348896380
##########
docs/source/user-guide/expressions.md:
##########
@@ -22,60 +22,89 @@
DataFrame methods such as `select` and `filter` accept one or more logical
expressions and there are many functions
available for creating logical expressions. These are documented below.
-Expressions can be chained together using a fluent-style API:
+:::{tip}
+Most functions and methods may receive and return an `Expr`, which can be
chained together using a fluent-style API:
```rust
// create the expression `(a > 6) AND (b < 7)`
col("a").gt(lit(6)).and(col("b").lt(lit(7)))
```
+:::
+
## Identifiers
-| Function | Notes |
-| -------- | -------------------------------------------- |
-| col | Reference a column in a dataframe `col("a")` |
+| Function | Explanation |
+| ---------- | -------------------------------------------- |
+| col(ident) | Reference a column in a dataframe `col("a")` |
## Literal Values
-| Function | Notes |
-| -------- | -------------------------------------------------- |
-| lit | Literal value such as `lit(123)` or `lit("hello")` |
+| Function | Explanation |
+| ---------- | -------------------------------------------------- |
+| lit(value) | Literal value such as `lit(123)` or `lit("hello")` |
+
+:::{note}
+value
+: A type which implement `Literal`
+:::
+
+## Basic Operators
+
+| Operation | Syntax | Method | Function
|
+| ------------------------- | -------- | -------------------------- |
--------------------------- |
+| Arithmetic addition | `x + y` | `x.add(y)` | `add(x,
y)` |
+| Arithmetic subtraction | `x - y` | `x.sub(y)` | `sub(x,
y)` |
+| Arithmetic multiplication | `x * y` | `x.mul(y)` | `mul(x,
y)` |
+| Arithmetic division | `x / y` | `x.div(y)` | `div(x,
y)` |
+| Arithmetic remainder | `x % y` | `x.r#mod(y)` |
`r#mod(x, y)` |
+| Arithmetic negation | `-x` | `x.neg()` | `neg(x,
y)` |
+| Bitwise AND | `x & y` | `x.bitwise_and(y)` |
`bitwise_and(x, y)` |
+| Bitwise OR | `x \| y` | `x.bitwise_or(y)` |
`bitwise_or(x, y)` |
+| Bitwise XOR | `x ^ y` | `x.bitwise_xor(y)` |
`bitwise_xor(x, y)` |
+| Bitwise left shift | `x << y` | `x.bitwise_shift_left(y)` |
`bitwise_shift_left(x, y)` |
+| Bitwise right shift | `x >> y` | `x.bitwise_shift_right(y)` |
`bitwise_shift_right(x, y)` |
+| Logical NOT | `!x` | `x.not()` | `not(x)`
|
+
+:::{note}
+`mod` is a reserved keyword in Rust, we use a raw identifier to name the
`r#mod` function.
+:::
+
+:::{note}
+`!` is a bitwise or logical complement operator in Rust, but it only works as
a logical NOT in expression API.
+:::
## Boolean Expressions
-| Function | Notes |
-| -------- | ----------------------------------------- |
-| and | `and(expr1, expr2)` or `expr1.and(expr2)` |
-| or | `or(expr1, expr2)` or `expr1.or(expr2)` |
-| not | `not(expr)` or `expr.not()` |
-
-## Bitwise expressions
+| Function | Method | Explanation |
+| ----------- | ---------- | ----------- |
+| `and(x, y)` | `x.and(y)` | Logical AND |
+| `or(x, y)` | `x.or(y)` | Logical OR |
+| `not(x)` | `x.not()` | Logical NOT |
-| Function | Notes
|
-| ------------------- |
------------------------------------------------------------------------- |
-| bitwise_and | `bitwise_and(expr1, expr2)` or
`expr1.bitwise_and(expr2)` |
-| bitwise_or | `bitwise_or(expr1, expr2)` or
`expr1.bitwise_or(expr2)` |
-| bitwise_xor | `bitwise_xor(expr1, expr2)` or
`expr1.bitwise_xor(expr2)` |
-| bitwise_shift_right | `bitwise_shift_right(expr1, expr2)` or
`expr1.bitwise_shift_right(expr2)` |
-| bitwise_shift_left | `bitwise_shift_left(expr1, expr2)` or
`expr1.bitwise_shift_left(expr2)` |
+:::{note}
+Since `&&` and `||` are existed as logical operators in Rust, but those are
not overloadable and not works with expression API.
+:::
## Comparison Expressions
-| Function | Notes |
-| -------- | --------------------- |
-| eq | `expr1.eq(expr2)` |
-| gt | `expr1.gt(expr2)` |
-| gt_eq | `expr1.gt_eq(expr2)` |
-| lt | `expr1.lt(expr2)` |
-| lt_eq | `expr1.lt_eq(expr2)` |
-| not_eq | `expr1.not_eq(expr2)` |
+| Function | Method | Explanation |
Review Comment:
When I read the doc I cannot understand quickly when should I use method and
when should I use function, thats my concern
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
