diff --git a/arrow-string/src/like.rs b/arrow-string/src/like.rs index e30e09146c6d..f9e387485f7a 100644 --- a/arrow-string/src/like.rs +++ b/arrow-string/src/like.rs @@ -53,16 +53,22 @@ impl std::fmt::Display for Op { /// Perform SQL `left LIKE right` /// +/// # Supported DataTypes +/// +/// `left` and `right` must be the same type, and one of +/// - Utf8 +/// - LargeUtf8 +/// - Utf8View +/// /// There are two wildcards supported with the LIKE operator: /// /// 1. `%` - The percent sign represents zero, one, or multiple characters /// 2. `_` - The underscore represents a single character /// -/// For example: +/// Example /// ``` /// # use arrow_array::{StringArray, BooleanArray}; /// # use arrow_string::like::like; -/// # /// let strings = StringArray::from(vec!["Arrow", "Arrow", "Arrow", "Ar"]); /// let patterns = StringArray::from(vec!["A%", "B%", "A.", "A_"]); /// @@ -75,39 +81,107 @@ pub fn like(left: &dyn Datum, right: &dyn Datum) -> Result Result { like_op(Op::ILike(false), left, right) } /// Perform SQL `left NOT LIKE right` /// -/// See the documentation on [`like`] for more details +/// # Notes +/// - This is a negative of [`like`] +/// - See the documentation on [`like`] for more details pub fn nlike(left: &dyn Datum, right: &dyn Datum) -> Result { like_op(Op::Like(true), left, right) } /// Perform SQL `left NOT ILIKE right` /// -/// See the documentation on [`ilike`] for more details +/// # Notes +/// - This is a negative of [`like`] +/// - See the documentation on [`ilike`] for more details pub fn nilike(left: &dyn Datum, right: &dyn Datum) -> Result { like_op(Op::ILike(true), left, right) } /// Perform SQL `STARTSWITH(left, right)` +/// +/// # Supported DataTypes +/// +/// `left` and `right` must be the same type, and one of +/// - Utf8 +/// - LargeUtf8 +/// - Utf8View +/// - Binary +/// - LargeBinary +/// - BinaryView +/// +/// # Example +/// ``` +/// # use arrow_array::{StringArray, BooleanArray}; +/// # use arrow_string::like::{like, starts_with}; +/// let strings = StringArray::from(vec!["arrow-rs", "arrow-rs", "arrow-rs", "Parquet"]); +/// let patterns = StringArray::from(vec!["arr", "arrow", "arrow-cpp", "p"]); +/// +/// let result = starts_with(&strings, &patterns).unwrap(); +/// assert_eq!(result, BooleanArray::from(vec![true, true, false, false])); +/// ``` pub fn starts_with(left: &dyn Datum, right: &dyn Datum) -> Result { like_op(Op::StartsWith, left, right) } /// Perform SQL `ENDSWITH(left, right)` +/// +/// # Supported DataTypes +/// +/// `left` and `right` must be the same type, and one of +/// - Utf8 +/// - LargeUtf8 +/// - Utf8View +/// - Binary +/// - LargeBinary +/// - BinaryView +/// +/// # Example +/// ``` +/// # use arrow_array::{StringArray, BooleanArray}; +/// # use arrow_string::like::{ends_with, like, starts_with}; +/// let strings = StringArray::from(vec!["arrow-rs", "arrow-rs", "Parquet"]); +/// let patterns = StringArray::from(vec!["arr", "-rs", "t"]); +/// +/// let result = ends_with(&strings, &patterns).unwrap(); +/// assert_eq!(result, BooleanArray::from(vec![false, true, true])); +/// ``` pub fn ends_with(left: &dyn Datum, right: &dyn Datum) -> Result { like_op(Op::EndsWith, left, right) } /// Perform SQL `CONTAINS(left, right)` +/// +/// # Supported DataTypes +/// +/// `left` and `right` must be the same type, and one of +/// - Utf8 +/// - LargeUtf8 +/// - Utf8View +/// - Binary +/// - LargeBinary +/// - BinaryView +/// +/// # Example +/// ``` +/// # use arrow_array::{StringArray, BooleanArray}; +/// # use arrow_string::like::{contains, like, starts_with}; +/// let strings = StringArray::from(vec!["arrow-rs", "arrow-rs", "arrow-rs", "Parquet"]); +/// let patterns = StringArray::from(vec!["arr", "-rs", "arrow-cpp", "X"]); +/// +/// let result = contains(&strings, &patterns).unwrap(); +/// assert_eq!(result, BooleanArray::from(vec![true, true, false, false])); +/// ``` pub fn contains(left: &dyn Datum, right: &dyn Datum) -> Result { like_op(Op::Contains, left, right) }