From 8e27aff4718e3da48dd5a2bcc033133726b30ec2 Mon Sep 17 00:00:00 2001 From: Ziy1-Tan Date: Wed, 12 Jul 2023 23:27:34 +0800 Subject: [PATCH] Docs: Expression Signed-off-by: Ziy1-Tan --- cpp/include/gar/utils/expression.h | 133 ++++++++++++++++++++------- cpp/src/expression.cc | 2 +- docs/reference/api-reference-cpp.rst | 70 ++++++++++++++ 3 files changed, 170 insertions(+), 35 deletions(-) diff --git a/cpp/include/gar/utils/expression.h b/cpp/include/gar/utils/expression.h index fb56a9a7e..b972a08c9 100644 --- a/cpp/include/gar/utils/expression.h +++ b/cpp/include/gar/utils/expression.h @@ -28,8 +28,8 @@ namespace GAR_NAMESPACE_INTERNAL { using ArrowExpression = arrow::compute::Expression; /** - * This class wraps an arrow::compute::Expression and provides methods for - * reading arrow::compute::Expression objects + * This class wraps an arrow::compute::Expression and provides a way to + * construct it */ class Expression { public: @@ -49,6 +49,10 @@ class Expression { virtual ArrowExpression Evaluate() = 0; }; +/** + * This class wraps the Property and provides a way to construct property + * expression + */ class ExpressionProperty : public Expression { public: explicit ExpressionProperty(const Property& property) : property_(property) {} @@ -63,6 +67,10 @@ class ExpressionProperty : public Expression { Property property_; }; +/** + * This class wraps the literal. Only bool, int32, int64, float, double and + * string are allowed. + */ template class ExpressionLiteral : public Expression { public: @@ -76,34 +84,46 @@ class ExpressionLiteral : public Expression { T value_; }; -class UnaryOperator : public Expression { +/** + * This class constructs a unary operator expression that accepts only one + * expression + */ +class ExpressionUnaryOp : public Expression { public: - UnaryOperator() = default; - explicit UnaryOperator(std::shared_ptr expr) : expr_(expr) {} - UnaryOperator(const UnaryOperator& other) = default; - virtual ~UnaryOperator() {} + ExpressionUnaryOp() = default; + explicit ExpressionUnaryOp(std::shared_ptr expr) : expr_(expr) {} + ExpressionUnaryOp(const ExpressionUnaryOp& other) = default; + virtual ~ExpressionUnaryOp() {} protected: std::shared_ptr expr_; }; -class ExpressionNot : public UnaryOperator { +/** + * This class constructs a NOT operator expression. e.g. new ExpressionNot(new + * ExpressionLiteral(true)) => NOT TRUE + */ +class ExpressionNot : public ExpressionUnaryOp { public: ExpressionNot() = default; explicit ExpressionNot(std::shared_ptr expr) - : UnaryOperator(expr) {} + : ExpressionUnaryOp(expr) {} ExpressionNot(const ExpressionNot& other) = default; ~ExpressionNot() = default; ArrowExpression Evaluate() override; }; -class ExpressionIsNull : public UnaryOperator { +/** + * This class constructs a IS NULL operator expression. e.g. new + * ExpressionIsNull(new ExpressionProperty("a")) => a IS NULL + */ +class ExpressionIsNull : public ExpressionUnaryOp { public: ExpressionIsNull() = default; explicit ExpressionIsNull(std::shared_ptr expr, bool nan_is_null = false) - : UnaryOperator(expr), nan_is_null_(nan_is_null) {} + : ExpressionUnaryOp(expr), nan_is_null_(nan_is_null) {} ExpressionIsNull(const ExpressionIsNull& other) = default; ~ExpressionIsNull() = default; @@ -113,109 +133,153 @@ class ExpressionIsNull : public UnaryOperator { bool nan_is_null_; }; -class BinaryOperator : public Expression { +/** + * This class constructs a binary operator expression that accepts two + * expressions e.g. a = 1, a > 1, a AND b, a OR b + */ +class ExpressionBinaryOp : public Expression { public: - BinaryOperator() = default; - BinaryOperator(std::shared_ptr lhs, - std::shared_ptr rhs) + ExpressionBinaryOp() = default; + ExpressionBinaryOp(std::shared_ptr lhs, + std::shared_ptr rhs) : lhs_(lhs), rhs_(rhs) {} - BinaryOperator(const BinaryOperator& other) = default; - ~BinaryOperator() = default; + ExpressionBinaryOp(const ExpressionBinaryOp& other) = default; + ~ExpressionBinaryOp() = default; protected: std::shared_ptr lhs_; std::shared_ptr rhs_; }; -class ExpressionEqual : public BinaryOperator { +/** + * This class constructs a EQUAL operator expression. + * e.g. new ExpressionEqual(new ExpressionProperty("a"), new + * ExpressionLiteral(1)) => a = 1 + */ +class ExpressionEqual : public ExpressionBinaryOp { public: ExpressionEqual() = default; ExpressionEqual(std::shared_ptr lhs, std::shared_ptr rhs) - : BinaryOperator(lhs, rhs) {} + : ExpressionBinaryOp(lhs, rhs) {} ExpressionEqual(const ExpressionEqual& other) = default; ~ExpressionEqual() = default; ArrowExpression Evaluate() override; }; -class ExpressionNotEqual : public BinaryOperator { +/** + * This class constructs a NOT EQUAL operator expression. + * e.g. new ExpressionNotEqual(new ExpressionProperty("a"), new + * ExpressionLiteral(1)) => a != 1 + */ +class ExpressionNotEqual : public ExpressionBinaryOp { public: ExpressionNotEqual() = default; ExpressionNotEqual(std::shared_ptr lhs, std::shared_ptr rhs) - : BinaryOperator(lhs, rhs) {} + : ExpressionBinaryOp(lhs, rhs) {} ExpressionNotEqual(const ExpressionNotEqual& other) = default; ~ExpressionNotEqual() = default; ArrowExpression Evaluate() override; }; -class ExpressionGreaterThan : public BinaryOperator { +/** + * This class constructs a GREATER THAN operator expression. + * e.g. new ExpressionGreaterThan(new ExpressionProperty("a"), new + * ExpressionLiteral(1)) => a > 1 + */ +class ExpressionGreaterThan : public ExpressionBinaryOp { public: ExpressionGreaterThan() = default; ExpressionGreaterThan(std::shared_ptr lhs, std::shared_ptr rhs) - : BinaryOperator(lhs, rhs) {} + : ExpressionBinaryOp(lhs, rhs) {} ExpressionGreaterThan(const ExpressionGreaterThan& other) = default; ~ExpressionGreaterThan() = default; ArrowExpression Evaluate() override; }; -class ExpressionGreaterEqual : public BinaryOperator { +/** + * This class constructs a GREATER EQUAL operator expression. + * e.g. new ExpressionGreaterEqual(new ExpressionProperty("a"), new + * ExpressionLiteral(1)) => a >= 1 + */ +class ExpressionGreaterEqual : public ExpressionBinaryOp { public: ExpressionGreaterEqual() = default; ExpressionGreaterEqual(std::shared_ptr lhs, std::shared_ptr rhs) - : BinaryOperator(lhs, rhs) {} + : ExpressionBinaryOp(lhs, rhs) {} ExpressionGreaterEqual(const ExpressionGreaterEqual& other) = default; ~ExpressionGreaterEqual() = default; ArrowExpression Evaluate() override; }; -class ExpressionLessThan : public BinaryOperator { +/** + * This class constructs a LESS THAN operator expression. + * e.g. new ExpressionLessThan(new ExpressionProperty("a"), new + * ExpressionLiteral(1)) => a < 1 + */ +class ExpressionLessThan : public ExpressionBinaryOp { public: ExpressionLessThan() = default; ExpressionLessThan(std::shared_ptr lhs, std::shared_ptr rhs) - : BinaryOperator(lhs, rhs) {} + : ExpressionBinaryOp(lhs, rhs) {} ExpressionLessThan(const ExpressionLessThan& other) = default; ~ExpressionLessThan() = default; ArrowExpression Evaluate() override; }; -class ExpressionLessEqual : public BinaryOperator { +/** + * This class constructs a LESS EQUAL operator expression. + * e.g. new ExpressionLessEqual(new ExpressionProperty("a"), new + * ExpressionLiteral(1)) => a <= 1 + */ +class ExpressionLessEqual : public ExpressionBinaryOp { public: ExpressionLessEqual() = default; ExpressionLessEqual(std::shared_ptr lhs, std::shared_ptr rhs) - : BinaryOperator(lhs, rhs) {} + : ExpressionBinaryOp(lhs, rhs) {} ExpressionLessEqual(const ExpressionLessEqual& other) = default; ~ExpressionLessEqual() = default; ArrowExpression Evaluate() override; }; -class ExpressionAnd : public BinaryOperator { +/** + * This class constructs a AND operator expression. + * e.g. new ExpressionAnd(new ExpressionLiteral(true), new + * ExpressionLiteral(1)) => TRUE AND 1 + */ +class ExpressionAnd : public ExpressionBinaryOp { public: ExpressionAnd() = default; ExpressionAnd(std::shared_ptr lhs, std::shared_ptr rhs) - : BinaryOperator(lhs, rhs) {} + : ExpressionBinaryOp(lhs, rhs) {} ExpressionAnd(const ExpressionAnd& other) = default; ~ExpressionAnd() = default; ArrowExpression Evaluate() override; }; -class ExpressionOr : public BinaryOperator { +/** + * This class constructs a OR operator expression. + * e.g. new ExpressionOr(new ExpressionLiteral(0), new + * ExpressionLiteral(true)) => 0 OR TRUE + */ +class ExpressionOr : public ExpressionBinaryOp { public: ExpressionOr() = default; ExpressionOr(std::shared_ptr lhs, std::shared_ptr rhs) - : BinaryOperator(lhs, rhs) {} + : ExpressionBinaryOp(lhs, rhs) {} ExpressionOr(const ExpressionOr& other) = default; ~ExpressionOr() = default; @@ -223,7 +287,7 @@ class ExpressionOr : public BinaryOperator { }; /** - * Helper functions to Construct Expression. + * Helper functions to construct a Expression. */ [[nodiscard]] static inline std::shared_ptr _Property( const Property& property) { @@ -291,3 +355,4 @@ template } } // namespace GAR_NAMESPACE_INTERNAL #endif // GAR_UTILS_EXPRESSION_H_ + diff --git a/cpp/src/expression.cc b/cpp/src/expression.cc index 3d0ad5525..2b9f061c0 100644 --- a/cpp/src/expression.cc +++ b/cpp/src/expression.cc @@ -24,7 +24,7 @@ ArrowExpression ExpressionNot::Evaluate() { } ArrowExpression ExpressionIsNull::Evaluate() { - return arrow::compute::is_null(expr_->Evaluate()); + return arrow::compute::is_null(expr_->Evaluate(), nan_is_null_); } ArrowExpression ExpressionEqual::Evaluate() { diff --git a/docs/reference/api-reference-cpp.rst b/docs/reference/api-reference-cpp.rst index 8066772c8..5ee9c4796 100644 --- a/docs/reference/api-reference-cpp.rst +++ b/docs/reference/api-reference-cpp.rst @@ -220,3 +220,73 @@ Info Version .. doxygenclass:: GraphArchive::InfoVersion :members: :undoc-members: + +Expression +~~~~~~~~~~~~~~~~~~~ + +.. doxygenclass:: GraphArchive::Expression + :members: + :undoc-members: + +.. doxygenclass:: GraphArchive::ExpressionProperty + :members: + :undoc-members: + +.. doxygenclass:: GraphArchive::ExpressionLiteral + :members: + :undoc-members: + +.. doxygenclass:: GraphArchive::ExpressionNot + :members: + :undoc-members: + +.. doxygenclass:: GraphArchive::ExpressionIsNull + :members: + :undoc-members: + +.. doxygenclass:: GraphArchive::ExpressionEqual + :members: + :undoc-members: + +.. doxygenclass:: GraphArchive::ExpressionNotEqual + :members: + :undoc-members: + +.. doxygenclass:: GraphArchive::ExpressionGreaterThan + :members: + :undoc-members: + +.. doxygenclass:: GraphArchive::ExpressionGreaterEqual + :members: + :undoc-members: + + +.. doxygenclass:: GraphArchive::ExpressionLessThan + :members: + :undoc-members: + +.. doxygenclass:: GraphArchive::ExpressionLessEqual + :members: + :undoc-members: + +.. doxygenclass:: GraphArchive::ExpressionAnd + :members: + :undoc-members: + +.. doxygenclass:: GraphArchive::ExpressionOr + :members: + :undoc-members: + +.. doxygenfunction:: GraphArchive::_Property +.. doxygenfunction:: GraphArchive::_Literal +.. doxygenfunction:: GraphArchive::_Not +.. doxygenfunction:: GraphArchive::_IsNull +.. doxygenfunction:: GraphArchive::_Equal +.. doxygenfunction:: GraphArchive::_NotEqual +.. doxygenfunction:: GraphArchive::_GreaterThan +.. doxygenfunction:: GraphArchive::_GreaterEqual +.. doxygenfunction:: GraphArchive::_LessThan +.. doxygenfunction:: GraphArchive::_LessEqual +.. doxygenfunction:: GraphArchive::_And +.. doxygenfunction:: GraphArchive::_Or +