Skip to content

chore: Format examples in doc strings - expr #18340

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 29, 2025
Merged

chore: Format examples in doc strings - expr #18340

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 37 additions & 26 deletions datafusion/expr-common/src/interval_arithmetic.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1670,22 +1670,23 @@ fn cast_scalar_value(
///
/// // [1, 2) U {NULL}
/// let maybe_null = NullableInterval::MaybeNull {
/// values: Interval::try_new(
/// ScalarValue::Int32(Some(1)),
/// ScalarValue::Int32(Some(2)),
/// ).unwrap(),
/// values: Interval::try_new(
/// ScalarValue::Int32(Some(1)),
/// ScalarValue::Int32(Some(2)),
/// )
/// .unwrap(),
/// };
///
/// // (0, ∞)
/// let not_null = NullableInterval::NotNull {
/// values: Interval::try_new(
/// ScalarValue::Int32(Some(0)),
/// ScalarValue::Int32(None),
/// ).unwrap(),
/// values: Interval::try_new(ScalarValue::Int32(Some(0)), ScalarValue::Int32(None))
/// .unwrap(),
/// };
///
/// // {NULL}
/// let null_interval = NullableInterval::Null { datatype: DataType::Int32 };
/// let null_interval = NullableInterval::Null {
/// datatype: DataType::Int32,
/// };
///
/// // {4}
/// let single_value = NullableInterval::from(ScalarValue::Int32(Some(4)));
Expand Down Expand Up @@ -1787,22 +1788,26 @@ impl NullableInterval {
///
/// ```
/// use datafusion_common::ScalarValue;
/// use datafusion_expr_common::operator::Operator;
/// use datafusion_expr_common::interval_arithmetic::Interval;
/// use datafusion_expr_common::interval_arithmetic::NullableInterval;
/// use datafusion_expr_common::operator::Operator;
///
/// // 4 > 3 -> true
/// let lhs = NullableInterval::from(ScalarValue::Int32(Some(4)));
/// let rhs = NullableInterval::from(ScalarValue::Int32(Some(3)));
/// let result = lhs.apply_operator(&Operator::Gt, &rhs).unwrap();
/// assert_eq!(result, NullableInterval::from(ScalarValue::Boolean(Some(true))));
/// assert_eq!(
/// result,
/// NullableInterval::from(ScalarValue::Boolean(Some(true)))
/// );
///
/// // [1, 3) > NULL -> NULL
/// let lhs = NullableInterval::NotNull {
/// values: Interval::try_new(
/// ScalarValue::Int32(Some(1)),
/// ScalarValue::Int32(Some(3)),
/// ).unwrap(),
/// ScalarValue::Int32(Some(1)),
/// ScalarValue::Int32(Some(3)),
/// )
/// .unwrap(),
/// };
/// let rhs = NullableInterval::from(ScalarValue::Int32(None));
/// let result = lhs.apply_operator(&Operator::Gt, &rhs).unwrap();
Expand All @@ -1811,22 +1816,27 @@ impl NullableInterval {
/// // [1, 3] > [2, 4] -> [false, true]
/// let lhs = NullableInterval::NotNull {
/// values: Interval::try_new(
/// ScalarValue::Int32(Some(1)),
/// ScalarValue::Int32(Some(3)),
/// ).unwrap(),
/// ScalarValue::Int32(Some(1)),
/// ScalarValue::Int32(Some(3)),
/// )
/// .unwrap(),
/// };
/// let rhs = NullableInterval::NotNull {
/// values: Interval::try_new(
/// ScalarValue::Int32(Some(2)),
/// ScalarValue::Int32(Some(4)),
/// ).unwrap(),
/// values: Interval::try_new(
/// ScalarValue::Int32(Some(2)),
/// ScalarValue::Int32(Some(4)),
/// )
/// .unwrap(),
/// };
/// let result = lhs.apply_operator(&Operator::Gt, &rhs).unwrap();
/// // Both inputs are valid (non-null), so result must be non-null
/// assert_eq!(result, NullableInterval::NotNull {
/// // Uncertain whether inequality is true or false
/// values: Interval::UNCERTAIN,
/// });
/// assert_eq!(
/// result,
/// NullableInterval::NotNull {
/// // Uncertain whether inequality is true or false
/// values: Interval::UNCERTAIN,
/// }
/// );
/// ```
pub fn apply_operator(&self, op: &Operator, rhs: &Self) -> Result<Self> {
match op {
Expand Down Expand Up @@ -1924,7 +1934,8 @@ impl NullableInterval {
/// values: Interval::try_new(
/// ScalarValue::Int32(Some(1)),
/// ScalarValue::Int32(Some(4)),
/// ).unwrap(),
/// )
/// .unwrap(),
/// };
/// assert_eq!(interval.single_value(), None);
/// ```
Expand Down
28 changes: 14 additions & 14 deletions datafusion/expr-common/src/signature.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,11 +127,10 @@ pub enum Arity {
/// ```
/// # use arrow::datatypes::DataType;
/// # use datafusion_expr_common::signature::{TypeSignature};
/// // Declares the function must be invoked with a single argument of type `Utf8View`.
/// // if a user calls the function with `Utf8` or `LargeUtf8`, DataFusion will
/// // automatically add a cast to `Utf8View` during planning.
/// let type_signature = TypeSignature::Exact(vec![DataType::Utf8View]);
///
/// // Declares the function must be invoked with a single argument of type `Utf8View`.
/// // if a user calls the function with `Utf8` or `LargeUtf8`, DataFusion will
/// // automatically add a cast to `Utf8View` during planning.
/// let type_signature = TypeSignature::Exact(vec![DataType::Utf8View]);
/// ```
///
/// # Example: Timestamps
Expand All @@ -144,11 +143,11 @@ pub enum Arity {
/// # use arrow::datatypes::{DataType, TimeUnit};
/// # use datafusion_expr_common::signature::{TIMEZONE_WILDCARD, TypeSignature};
/// let type_signature = TypeSignature::Exact(vec![
/// // A nanosecond precision timestamp with ANY timezone
/// // matches Timestamp(Nanosecond, Some("+0:00"))
/// // matches Timestamp(Nanosecond, Some("+5:00"))
/// // does not match Timestamp(Nanosecond, None)
/// DataType::Timestamp(TimeUnit::Nanosecond, Some(TIMEZONE_WILDCARD.into())),
/// // A nanosecond precision timestamp with ANY timezone
/// // matches Timestamp(Nanosecond, Some("+0:00"))
/// // matches Timestamp(Nanosecond, Some("+5:00"))
/// // does not match Timestamp(Nanosecond, None)
/// DataType::Timestamp(TimeUnit::Nanosecond, Some(TIMEZONE_WILDCARD.into())),
/// ]);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Hash)]
Expand Down Expand Up @@ -858,8 +857,8 @@ fn get_data_types(native_type: &NativeType) -> Vec<DataType> {
/// # Examples
///
/// ```
/// use datafusion_common::types::{logical_binary, logical_string, NativeType};
/// use datafusion_expr_common::signature::{Coercion, TypeSignatureClass};
/// use datafusion_common::types::{NativeType, logical_binary, logical_string};
///
/// // Exact coercion that only accepts timestamp types
/// let exact = Coercion::new_exact(TypeSignatureClass::Timestamp);
Expand All @@ -868,7 +867,7 @@ fn get_data_types(native_type: &NativeType) -> Vec<DataType> {
/// let implicit = Coercion::new_implicit(
/// TypeSignatureClass::Native(logical_string()),
/// vec![TypeSignatureClass::Native(logical_binary())],
/// NativeType::String
/// NativeType::String,
/// );
/// ```
///
Expand Down Expand Up @@ -1275,8 +1274,9 @@ impl Signature {
/// ```
/// # use datafusion_expr_common::signature::{Signature, Volatility};
/// # use arrow::datatypes::DataType;
/// let sig = Signature::exact(vec![DataType::Int32, DataType::Utf8], Volatility::Immutable)
/// .with_parameter_names(vec!["count".to_string(), "name".to_string()]);
/// let sig =
/// Signature::exact(vec![DataType::Int32, DataType::Utf8], Volatility::Immutable)
/// .with_parameter_names(vec!["count".to_string(), "name".to_string()]);
/// ```
///
/// # Errors
Expand Down
60 changes: 30 additions & 30 deletions datafusion/expr/src/expr.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,11 +164,11 @@ impl From<sqlparser::ast::NullTreatment> for NullTreatment {
/// # use datafusion_expr::{lit, col, Operator, Expr};
/// // Use the `+` operator to add two columns together
/// let expr = col("c1") + col("c2");
/// assert!(matches!(expr, Expr::BinaryExpr { ..} ));
/// assert!(matches!(expr, Expr::BinaryExpr { .. }));
/// if let Expr::BinaryExpr(binary_expr) = expr {
/// assert_eq!(*binary_expr.left, col("c1"));
/// assert_eq!(*binary_expr.right, col("c2"));
/// assert_eq!(binary_expr.op, Operator::Plus);
/// assert_eq!(*binary_expr.left, col("c1"));
/// assert_eq!(*binary_expr.right, col("c2"));
/// assert_eq!(binary_expr.op, Operator::Plus);
/// }
/// ```
///
Expand All @@ -179,12 +179,12 @@ impl From<sqlparser::ast::NullTreatment> for NullTreatment {
/// # use datafusion_common::ScalarValue;
/// # use datafusion_expr::{lit, col, Operator, Expr};
/// let expr = col("c1").eq(lit(42_i32));
/// assert!(matches!(expr, Expr::BinaryExpr { .. } ));
/// assert!(matches!(expr, Expr::BinaryExpr { .. }));
/// if let Expr::BinaryExpr(binary_expr) = expr {
/// assert_eq!(*binary_expr.left, col("c1"));
/// let scalar = ScalarValue::Int32(Some(42));
/// assert_eq!(*binary_expr.right, Expr::Literal(scalar, None));
/// assert_eq!(binary_expr.op, Operator::Eq);
/// assert_eq!(*binary_expr.left, col("c1"));
/// let scalar = ScalarValue::Int32(Some(42));
/// assert_eq!(*binary_expr.right, Expr::Literal(scalar, None));
/// assert_eq!(binary_expr.op, Operator::Eq);
/// }
/// ```
///
Expand All @@ -197,22 +197,22 @@ impl From<sqlparser::ast::NullTreatment> for NullTreatment {
/// # use datafusion_expr::Expr;
/// // Create a schema c1(int, c2 float)
/// let arrow_schema = Schema::new(vec![
/// Field::new("c1", DataType::Int32, false),
/// Field::new("c2", DataType::Float64, false),
/// Field::new("c1", DataType::Int32, false),
/// Field::new("c2", DataType::Float64, false),
/// ]);
/// // DFSchema is a an Arrow schema with optional relation name
/// let df_schema = DFSchema::try_from_qualified_schema("t1", &arrow_schema)
/// .unwrap();
/// let df_schema = DFSchema::try_from_qualified_schema("t1", &arrow_schema).unwrap();
///
/// // Form Vec<Expr> with an expression for each column in the schema
/// let exprs: Vec<_> = df_schema.iter()
/// .map(Expr::from)
/// .collect();
///
/// assert_eq!(exprs, vec![
/// Expr::from(Column::from_qualified_name("t1.c1")),
/// Expr::from(Column::from_qualified_name("t1.c2")),
/// ]);
/// let exprs: Vec<_> = df_schema.iter().map(Expr::from).collect();
///
/// assert_eq!(
/// exprs,
/// vec![
/// Expr::from(Column::from_qualified_name("t1.c1")),
/// Expr::from(Column::from_qualified_name("t1.c2")),
/// ]
/// );
/// ```
///
/// # Examples: Displaying `Exprs`
Expand Down Expand Up @@ -273,12 +273,13 @@ impl From<sqlparser::ast::NullTreatment> for NullTreatment {
/// let mut scalars = HashSet::new();
/// // apply recursively visits all nodes in the expression tree
/// expr.apply(|e| {
/// if let Expr::Literal(scalar, _) = e {
/// scalars.insert(scalar);
/// }
/// // The return value controls whether to continue visiting the tree
/// Ok(TreeNodeRecursion::Continue)
/// }).unwrap();
/// if let Expr::Literal(scalar, _) = e {
/// scalars.insert(scalar);
/// }
/// // The return value controls whether to continue visiting the tree
/// Ok(TreeNodeRecursion::Continue)
/// })
/// .unwrap();
/// // All subtrees have been visited and literals found
/// assert_eq!(scalars.len(), 2);
/// assert!(scalars.contains(&ScalarValue::Int32(Some(5))));
Expand Down Expand Up @@ -1640,7 +1641,6 @@ impl Expr {
/// let metadata = FieldMetadata::from(metadata);
/// let expr = col("foo").alias_with_metadata("bar", Some(metadata));
/// ```
///
pub fn alias_with_metadata(
self,
name: impl Into<String>,
Expand Down Expand Up @@ -1670,9 +1670,9 @@ impl Expr {
/// # use datafusion_common::metadata::FieldMetadata;
/// let metadata = HashMap::from([("key".to_string(), "value".to_string())]);
/// let metadata = FieldMetadata::from(metadata);
/// let expr = col("foo").alias_qualified_with_metadata(Some("tbl"), "bar", Some(metadata));
/// let expr =
/// col("foo").alias_qualified_with_metadata(Some("tbl"), "bar", Some(metadata));
/// ```
///
pub fn alias_qualified_with_metadata(
self,
relation: Option<impl Into<TableReference>>,
Expand Down
21 changes: 11 additions & 10 deletions datafusion/expr/src/expr_schema.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,15 +82,17 @@ impl ExprSchemable for Expr {
/// # use std::collections::HashMap;
///
/// fn main() {
/// let expr = col("c1") + col("c2");
/// let schema = DFSchema::from_unqualified_fields(
/// vec![
/// Field::new("c1", DataType::Int32, true),
/// Field::new("c2", DataType::Float32, true),
/// ].into(),
/// HashMap::new(),
/// ).unwrap();
/// assert_eq!("Float32", format!("{}", expr.get_type(&schema).unwrap()));
/// let expr = col("c1") + col("c2");
/// let schema = DFSchema::from_unqualified_fields(
/// vec![
/// Field::new("c1", DataType::Int32, true),
/// Field::new("c2", DataType::Float32, true),
/// ]
/// .into(),
/// HashMap::new(),
/// )
/// .unwrap();
/// assert_eq!("Float32", format!("{}", expr.get_type(&schema).unwrap()));
/// }
/// ```
///
Expand Down Expand Up @@ -734,7 +736,6 @@ impl Expr {
/// new projection with the casted expression.
/// 2. **Non-projection plan**: If the subquery isn't a projection, it adds a projection to the plan
/// with the casted first column.
///
pub fn cast_subquery(subquery: Subquery, cast_to_type: &DataType) -> Result<Subquery> {
if subquery.subquery.schema().field(0).data_type() == cast_to_type {
return Ok(subquery);
Expand Down
15 changes: 7 additions & 8 deletions datafusion/expr/src/logical_plan/builder.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -450,14 +450,13 @@ impl LogicalPlanBuilder {
/// # ])) as _;
/// # let table_source = Arc::new(LogicalTableSource::new(employee_schema));
/// // VALUES (1), (2)
/// let input = LogicalPlanBuilder::values(vec![vec![lit(1)], vec![lit(2)]])?
/// .build()?;
/// let input = LogicalPlanBuilder::values(vec![vec![lit(1)], vec![lit(2)]])?.build()?;
/// // INSERT INTO MyTable VALUES (1), (2)
/// let insert_plan = LogicalPlanBuilder::insert_into(
/// input,
/// "MyTable",
/// table_source,
/// InsertOp::Append,
/// input,
/// "MyTable",
/// table_source,
/// InsertOp::Append,
/// )?;
/// # Ok(())
/// # }
Expand Down Expand Up @@ -953,8 +952,8 @@ impl LogicalPlanBuilder {
/// // Form the expression `(left.a != right.a)` AND `(left.b != right.b)`
/// let exprs = vec![
/// col("left.a").eq(col("right.a")),
/// col("left.b").not_eq(col("right.b"))
/// ];
/// col("left.b").not_eq(col("right.b")),
/// ];
///
/// // Perform the equivalent of `left INNER JOIN right ON (a != a2 AND b != b2)`
/// // finding all pairs of rows from `left` and `right` where
Expand Down
12 changes: 6 additions & 6 deletions datafusion/expr/src/logical_plan/display.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,17 +94,17 @@ impl<'n> TreeNodeVisitor<'n> for IndentVisitor<'_, '_> {
/// `foo:Utf8;N` if `foo` is nullable.
///
/// ```
/// use arrow::datatypes::{Field, Schema, DataType};
/// use arrow::datatypes::{DataType, Field, Schema};
/// # use datafusion_expr::logical_plan::display_schema;
/// let schema = Schema::new(vec![
/// Field::new("id", DataType::Int32, false),
/// Field::new("first_name", DataType::Utf8, true),
/// ]);
/// ]);
///
/// assert_eq!(
/// "[id:Int32, first_name:Utf8;N]",
/// format!("{}", display_schema(&schema))
/// );
/// assert_eq!(
/// "[id:Int32, first_name:Utf8;N]",
/// format!("{}", display_schema(&schema))
/// );
/// ```
pub fn display_schema(schema: &Schema) -> impl fmt::Display + '_ {
struct Wrapper<'a>(&'a Schema);
Expand Down
Loading
Loading