polars-df 0.23.0 → 0.24.0

data/lib/polars/functions/aggregation/horizontal.rb

@@ -247,6 +247,5 @@ module Polars
         "cum_sum"
       )
     end
-    alias_method :cumsum_horizontal, :cum_sum_horizontal
   end
 end

data/lib/polars/functions/aggregation/vertical.rb

@@ -46,7 +46,7 @@ module Polars
         return col("*")
       end
 
-      col(*names).all(drop_nulls: ignore_nulls)
+      col(*names).all(ignore_nulls: ignore_nulls)
     end
 
     # Evaluate a bitwise OR operation.
@@ -78,7 +78,7 @@ module Polars
     #   # │ true │
     #   # └──────┘
     def any(*names, ignore_nulls: true)
-      col(*names).any(drop_nulls: ignore_nulls)
+      col(*names).any(ignore_nulls: ignore_nulls)
     end
 
     # Get the maximum value.
@@ -277,6 +277,5 @@ module Polars
     def cum_sum(*names)
       col(*names).cum_sum
     end
-    alias_method :cumsum, :cum_sum
   end
 end

data/lib/polars/functions/as_datatype.rb

@@ -1,5 +1,233 @@
 module Polars
   module Functions
+    # Create a Polars literal expression of type Datetime.
+    #
+    # @param year [Object]
+    #   Column or literal.
+    # @param month [Object]
+    #   Column or literal, ranging from 1-12.
+    # @param day [Object]
+    #   Column or literal, ranging from 1-31.
+    # @param hour [Object]
+    #   Column or literal, ranging from 0-23.
+    # @param minute [Object]
+    #   Column or literal, ranging from 0-59.
+    # @param second [Object]
+    #   Column or literal, ranging from 0-59.
+    # @param microsecond [Object]
+    #   Column or literal, ranging from 0-999999.
+    # @param time_unit ['us', 'ms', 'ns']
+    #   Time unit of the resulting expression.
+    # @param time_zone [Object]
+    #   Time zone of the resulting expression.
+    # @param ambiguous ['raise', 'earliest', 'latest', 'null']
+    #   Determine how to deal with ambiguous datetimes:
+    #
+    #   - `'raise'` (default): raise
+    #   - `'earliest'`: use the earliest datetime
+    #   - `'latest'`: use the latest datetime
+    #   - `'null'`: set to null
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "month" => [1, 2, 3],
+    #       "day" => [4, 5, 6],
+    #       "hour" => [12, 13, 14],
+    #       "minute" => [15, 30, 45]
+    #     }
+    #   )
+    #   df.with_columns(
+    #     Polars.datetime(
+    #       2024,
+    #       Polars.col("month"),
+    #       Polars.col("day"),
+    #       Polars.col("hour"),
+    #       Polars.col("minute"),
+    #       time_zone: "Australia/Sydney"
+    #     )
+    #   )
+    #   # =>
+    #   # shape: (3, 5)
+    #   # ┌───────┬─────┬──────┬────────┬────────────────────────────────┐
+    #   # │ month ┆ day ┆ hour ┆ minute ┆ datetime                       │
+    #   # │ ---   ┆ --- ┆ ---  ┆ ---    ┆ ---                            │
+    #   # │ i64   ┆ i64 ┆ i64  ┆ i64    ┆ datetime[μs, Australia/Sydney] │
+    #   # ╞═══════╪═════╪══════╪════════╪════════════════════════════════╡
+    #   # │ 1     ┆ 4   ┆ 12   ┆ 15     ┆ 2024-01-04 12:15:00 AEDT       │
+    #   # │ 2     ┆ 5   ┆ 13   ┆ 30     ┆ 2024-02-05 13:30:00 AEDT       │
+    #   # │ 3     ┆ 6   ┆ 14   ┆ 45     ┆ 2024-03-06 14:45:00 AEDT       │
+    #   # └───────┴─────┴──────┴────────┴────────────────────────────────┘
+    #
+    # @example We can also use `Polars.datetime` for filtering:
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "start" => [
+    #         DateTime.new(2024, 1, 1, 0, 0, 0),
+    #         DateTime.new(2024, 1, 1, 0, 0, 0),
+    #         DateTime.new(2024, 1, 1, 0, 0, 0)
+    #       ],
+    #       "end" => [
+    #         DateTime.new(2024, 5, 1, 20, 15, 10),
+    #         DateTime.new(2024, 7, 1, 21, 25, 20),
+    #         DateTime.new(2024, 9, 1, 22, 35, 30)
+    #       ]
+    #     }
+    #   )
+    #   df.filter(Polars.col("end") > Polars.datetime(2024, 6, 1))
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌─────────────────────┬─────────────────────┐
+    #   # │ start               ┆ end                 │
+    #   # │ ---                 ┆ ---                 │
+    #   # │ datetime[ns]        ┆ datetime[ns]        │
+    #   # ╞═════════════════════╪═════════════════════╡
+    #   # │ 2024-01-01 00:00:00 ┆ 2024-07-01 21:25:20 │
+    #   # │ 2024-01-01 00:00:00 ┆ 2024-09-01 22:35:30 │
+    #   # └─────────────────────┴─────────────────────┘
+    def datetime(
+      year,
+      month,
+      day,
+      hour = nil,
+      minute = nil,
+      second = nil,
+      microsecond = nil,
+      time_unit: "us",
+      time_zone: nil,
+      ambiguous: "raise"
+    )
+      ambiguous_expr = Utils.parse_into_expression(ambiguous, str_as_lit: true)
+      year_expr = Utils.parse_into_expression(year)
+      month_expr = Utils.parse_into_expression(month)
+      day_expr = Utils.parse_into_expression(day)
+
+      hour_expr = !hour.nil? ? Utils.parse_into_expression(hour) : nil
+      minute_expr = !minute.nil? ? Utils.parse_into_expression(minute) : nil
+      second_expr = !second.nil? ? Utils.parse_into_expression(second) : nil
+      microsecond_expr = (
+        !microsecond.nil? ? Utils.parse_into_expression(microsecond) : nil
+      )
+
+      Utils.wrap_expr(
+        Plr.datetime(
+          year_expr,
+          month_expr,
+          day_expr,
+          hour_expr,
+          minute_expr,
+          second_expr,
+          microsecond_expr,
+          time_unit,
+          time_zone,
+          ambiguous_expr
+        )
+      )
+    end
+
+    # Create a Polars literal expression of type Date.
+    #
+    # @param year [Object]
+    #   column or literal.
+    # @param month [Object]
+    #   column or literal, ranging from 1-12.
+    # @param day [Object]
+    #   column or literal, ranging from 1-31.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "month" => [1, 2, 3],
+    #       "day" => [4, 5, 6]
+    #     }
+    #   )
+    #   df.with_columns(Polars.date(2024, Polars.col("month"), Polars.col("day")))
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌───────┬─────┬────────────┐
+    #   # │ month ┆ day ┆ date       │
+    #   # │ ---   ┆ --- ┆ ---        │
+    #   # │ i64   ┆ i64 ┆ date       │
+    #   # ╞═══════╪═════╪════════════╡
+    #   # │ 1     ┆ 4   ┆ 2024-01-04 │
+    #   # │ 2     ┆ 5   ┆ 2024-02-05 │
+    #   # │ 3     ┆ 6   ┆ 2024-03-06 │
+    #   # └───────┴─────┴────────────┘
+    #
+    # @example We can also use `pl.date` for filtering:
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "start" => [Date.new(2024, 1, 1), Date.new(2024, 1, 1), Date.new(2024, 1, 1)],
+    #       "end" => [Date.new(2024, 5, 1), Date.new(2024, 7, 1), Date.new(2024, 9, 1)]
+    #     }
+    #   )
+    #   df.filter(Polars.col("end") > Polars.date(2024, 6, 1))
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌────────────┬────────────┐
+    #   # │ start      ┆ end        │
+    #   # │ ---        ┆ ---        │
+    #   # │ date       ┆ date       │
+    #   # ╞════════════╪════════════╡
+    #   # │ 2024-01-01 ┆ 2024-07-01 │
+    #   # │ 2024-01-01 ┆ 2024-09-01 │
+    #   # └────────────┴────────────┘
+    def date(
+      year,
+      month,
+      day
+    )
+      datetime(year, month, day).cast(Date).alias("date")
+    end
+
+    # Create a Polars literal expression of type Time.
+    #
+    # @param hour [Object]
+    #   column or literal, ranging from 0-23.
+    # @param minute [Object]
+    #   column or literal, ranging from 0-59.
+    # @param second [Object]
+    #   column or literal, ranging from 0-59.
+    # @param microsecond [Object]
+    #   column or literal, ranging from 0-999999.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "hour" => [12, 13, 14],
+    #       "minute" => [15, 30, 45]
+    #     }
+    #   )
+    #   df.with_columns(Polars.time(Polars.col("hour"), Polars.col("minute")))
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌──────┬────────┬──────────┐
+    #   # │ hour ┆ minute ┆ time     │
+    #   # │ ---  ┆ ---    ┆ ---      │
+    #   # │ i64  ┆ i64    ┆ time     │
+    #   # ╞══════╪════════╪══════════╡
+    #   # │ 12   ┆ 15     ┆ 12:15:00 │
+    #   # │ 13   ┆ 30     ┆ 13:30:00 │
+    #   # │ 14   ┆ 45     ┆ 14:45:00 │
+    #   # └──────┴────────┴──────────┘
+    def time(
+      hour = nil,
+      minute = nil,
+      second = nil,
+      microsecond = nil
+    )
+      epoch_start = [1970, 1, 1]
+      datetime(*epoch_start, hour, minute, second, microsecond)
+        .cast(Time)
+        .alias("time")
+    end
+
     # Create polars `Duration` from distinct time components.
     #
     # @return [Expr]
@@ -41,8 +269,12 @@ module Polars
       milliseconds: nil,
       microseconds: nil,
       nanoseconds: nil,
-      time_unit: "us"
+      time_unit: nil
     )
+      if !nanoseconds.nil? && time_unit.nil?
+        time_unit = "ns"
+      end
+
       if !weeks.nil?
         weeks = Utils.parse_into_expression(weeks, str_as_lit: false)
       end
@@ -68,6 +300,10 @@ module Polars
         nanoseconds = Utils.parse_into_expression(nanoseconds, str_as_lit: false)
       end
 
+      if time_unit.nil?
+        time_unit = "us"
+      end
+
       Utils.wrap_expr(
         Plr.duration(
           weeks,
@@ -140,6 +376,49 @@ module Polars
       Utils.wrap_expr(Plr.concat_list(exprs))
     end
 
+    # Horizontally concatenate columns into a single array column.
+    #
+    # Non-array columns are reshaped to a unit-width array. All columns must have
+    # a dtype of either `Polars::Array.new(<DataType>, width)` or `Polars::<DataType>`.
+    #
+    # @note
+    #   This functionality is considered **unstable**. It may be changed
+    #   at any point without it being considered a breaking change.
+    #
+    # @param exprs [Object]
+    #   Columns to concatenate into a single array column. Accepts expression input.
+    #   Strings are parsed as column names, other non-expression inputs are parsed as
+    #   literals.
+    # @param more_exprs [Array]
+    #   Additional columns to concatenate into a single array column, specified as
+    #   positional arguments.
+    #
+    # @return [Expr]
+    #
+    # @example Concatenate 2 array columns:
+    #   Polars.select(
+    #     a: Polars::Series.new([[1], [3], nil], dtype: Polars::Array.new(Polars::Int64, 1)),
+    #     b: Polars::Series.new([[3], [nil], [5]], dtype: Polars::Array.new(Polars::Int64, 1))
+    #   ).with_columns(
+    #     Polars.concat_arr("a", "b").alias("concat_arr(a, b)"),
+    #     Polars.concat_arr("a", Polars.first("b")).alias("concat_arr(a, first(b))")
+    #   )
+    #   # =>
+    #   # shape: (3, 4)
+    #   # ┌───────────────┬───────────────┬──────────────────┬─────────────────────────┐
+    #   # │ a             ┆ b             ┆ concat_arr(a, b) ┆ concat_arr(a, first(b)) │
+    #   # │ ---           ┆ ---           ┆ ---              ┆ ---                     │
+    #   # │ array[i64, 1] ┆ array[i64, 1] ┆ array[i64, 2]    ┆ array[i64, 2]           │
+    #   # ╞═══════════════╪═══════════════╪══════════════════╪═════════════════════════╡
+    #   # │ [1]           ┆ [3]           ┆ [1, 3]           ┆ [1, 3]                  │
+    #   # │ [3]           ┆ [null]        ┆ [3, null]        ┆ [3, 3]                  │
+    #   # │ null          ┆ [5]           ┆ null             ┆ null                    │
+    #   # └───────────────┴───────────────┴──────────────────┴─────────────────────────┘
+    def concat_arr(exprs, *more_exprs)
+      exprs = Utils.parse_into_list_of_expressions(exprs, *more_exprs)
+      Utils.wrap_expr(Plr.concat_arr(exprs))
+    end
+
     # Collect several columns into a Series of dtype Struct.
     #
     # @param exprs [Array]
@@ -194,7 +473,7 @@ module Polars
     #
     # @example Use keyword arguments to easily name each struct field.
     #   df.select(Polars.struct(p: "int", q: "bool").alias("my_struct")).schema
-    #   # => {"my_struct"=>Polars::Struct({"p"=>Polars::Int64, "q"=>Polars::Boolean})}
+    #   # => Polars::Schema({"my_struct"=>Polars::Struct({"p"=>Polars::Int64, "q"=>Polars::Boolean})})
     def struct(*exprs, schema: nil, eager: false, **named_exprs)
       rbexprs = Utils.parse_into_list_of_expressions(*exprs, **named_exprs)
       expr = Utils.wrap_expr(Plr.as_struct(rbexprs))
@@ -221,7 +500,10 @@ module Polars
     #
     # @param exprs [Object]
     #   Columns to concat into a Utf8 Series.
-    # @param sep [String]
+    # @param more_exprs [Array]
+    #   Additional columns to concatenate into a single string column, specified as
+    #   positional arguments.
+    # @param separator [String]
     #   String value that will be used to separate the values.
     # @param ignore_nulls [Boolean]
     #   Ignore null values (default).
@@ -244,7 +526,7 @@ module Polars
     #           Polars.col("b"),
     #           Polars.col("c")
     #         ],
-    #         sep: " "
+    #         separator: " "
     #       ).alias("full_sentence")
     #     ]
     #   )
@@ -259,9 +541,9 @@ module Polars
     #   # │ 2   ┆ cats ┆ swim ┆ 4 cats swim   │
     #   # │ 3   ┆ null ┆ walk ┆ null          │
     #   # └─────┴──────┴──────┴───────────────┘
-    def concat_str(exprs, sep: "", ignore_nulls: false)
-      exprs = Utils.parse_into_list_of_expressions(exprs)
-      Utils.wrap_expr(Plr.concat_str(exprs, sep, ignore_nulls))
+    def concat_str(exprs, *more_exprs, separator: "", ignore_nulls: false)
+      exprs = Utils.parse_into_list_of_expressions(exprs, *more_exprs)
+      Utils.wrap_expr(Plr.concat_str(exprs, separator, ignore_nulls))
     end
 
     # Format expressions as a string.
@@ -314,7 +596,7 @@ module Polars
         end
       end
 
-      concat_str(exprs, sep: "")
+      concat_str(exprs, separator: "")
     end
   end
 end

data/lib/polars/functions/eager.rb

@@ -93,7 +93,7 @@ module Polars
     #   # │ 2   ┆ 4    ┆ 5    ┆ null │
     #   # │ 3   ┆ null ┆ 6    ┆ 8    │
     #   # └─────┴──────┴──────┴──────┘
-    def concat(items, rechunk: true, how: "vertical", parallel: true)
+    def concat(items, rechunk: false, how: "vertical", parallel: true)
       elems = items.to_a
 
       if elems.empty?
@@ -152,7 +152,7 @@ module Polars
               parallel,
               true
             )
-          ).collect(no_optimization: true)
+          ).collect(optimizations: QueryOptFlags._eager)
         elsif how == "diagonal"
           out = Utils.wrap_df(Plr.concat_df_diagonal(elems))
         elsif how == "diagonal_relaxed"
@@ -163,7 +163,7 @@ module Polars
               parallel,
               true
             )
-          ).collect(no_optimization: true)
+          ).collect(optimizations: QueryOptFlags._eager)
         elsif how == "horizontal"
           out = Utils.wrap_df(Plr.concat_df_horizontal(elems))
         else
@@ -206,7 +206,194 @@ module Polars
       end
     end
 
-    # Align a sequence of frames using the unique values from one or more columns as a key.
+    # Combine multiple DataFrames, LazyFrames, or Series into a single object.
+    #
+    # @note
+    #   This function does not guarantee any specific ordering of rows in the result.
+    #   If you need predictable row ordering, use `Polars.concat` instead.
+    #
+    # @param items [Array]
+    #   DataFrames, LazyFrames, or Series to concatenate.
+    # @param how ['vertical', 'vertical_relaxed', 'diagonal', 'diagonal_relaxed', 'horizontal', 'align', 'align_full', 'align_inner', 'align_left', 'align_right']
+    #   Note that `Series` only support the `vertical` strategy.
+    #
+    #   * vertical: Applies multiple `vstack` operations.
+    #   * vertical_relaxed: Same as `vertical`, but additionally coerces columns to
+    #     their common supertype *if* they are mismatched (eg: Int32 → Int64).
+    #   * diagonal: Finds a union between the column schemas and fills missing column
+    #     values with `null`.
+    #   * diagonal_relaxed: Same as `diagonal`, but additionally coerces columns to
+    #     their common supertype *if* they are mismatched (eg: Int32 → Int64).
+    #   * horizontal: Stacks Series from DataFrames horizontally and fills with `null`
+    #     if the lengths don't match.
+    #   * align, align_full, align_left, align_right: Combines frames horizontally,
+    #     auto-determining the common key columns and aligning rows using the same
+    #     logic as `align_frames` (note that "align" is an alias for "align_full").
+    #     The "align" strategy determines the type of join used to align the frames,
+    #     equivalent to the "how" parameter on `align_frames`. Note that the common
+    #     join columns are automatically coalesced, but other column collisions
+    #     will raise an error (if you need more control over this you should use
+    #     a suitable `join` method directly).
+    #
+    # @return [Object]
+    #
+    # @example
+    #   df1 = Polars::DataFrame.new({"a" => [1], "b" => [3]})
+    #   df2 = Polars::DataFrame.new({"a" => [2], "b" => [4]})
+    #   Polars.union([df1, df2])
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌─────┬─────┐
+    #   # │ a   ┆ b   │
+    #   # │ --- ┆ --- │
+    #   # │ i64 ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ 1   ┆ 3   │
+    #   # │ 2   ┆ 4   │
+    #   # └─────┴─────┘
+    #
+    # @example
+    #   df1 = Polars::DataFrame.new({"a" => [1], "b" => [3]})
+    #   df2 = Polars::DataFrame.new({"a" => [2.5], "b" => [4]})
+    #   Polars.union([df1, df2], how: "vertical_relaxed")
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌─────┬─────┐
+    #   # │ a   ┆ b   │
+    #   # │ --- ┆ --- │
+    #   # │ f64 ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ 1.0 ┆ 3   │
+    #   # │ 2.5 ┆ 4   │
+    #   # └─────┴─────┘
+    #
+    # @example
+    #   df_h1 = Polars::DataFrame.new({"l1" => [1, 2], "l2" => [3, 4]})
+    #   df_h2 = Polars::DataFrame.new({"r1" => [5, 6], "r2" => [7, 8], "r3" => [9, 10]})
+    #   Polars.union([df_h1, df_h2], how: "horizontal")
+    #   # =>
+    #   # shape: (2, 5)
+    #   # ┌─────┬─────┬─────┬─────┬─────┐
+    #   # │ l1  ┆ l2  ┆ r1  ┆ r2  ┆ r3  │
+    #   # │ --- ┆ --- ┆ --- ┆ --- ┆ --- │
+    #   # │ i64 ┆ i64 ┆ i64 ┆ i64 ┆ i64 │
+    #   # ╞═════╪═════╪═════╪═════╪═════╡
+    #   # │ 1   ┆ 3   ┆ 5   ┆ 7   ┆ 9   │
+    #   # │ 2   ┆ 4   ┆ 6   ┆ 8   ┆ 10  │
+    #   # └─────┴─────┴─────┴─────┴─────┘
+    #
+    # @example The "diagonal" strategy allows for some frames to have missing columns, the values for which are filled with `null`:
+    #   df_d1 = Polars::DataFrame.new({"a" => [1], "b" => [3]})
+    #   df_d2 = Polars::DataFrame.new({"a" => [2], "c" => [4]})
+    #   Polars.union([df_d1, df_d2], how: "diagonal")
+    #   # =>
+    #   # shape: (2, 3)
+    #   # ┌─────┬──────┬──────┐
+    #   # │ a   ┆ b    ┆ c    │
+    #   # │ --- ┆ ---  ┆ ---  │
+    #   # │ i64 ┆ i64  ┆ i64  │
+    #   # ╞═════╪══════╪══════╡
+    #   # │ 1   ┆ 3    ┆ null │
+    #   # │ 2   ┆ null ┆ 4    │
+    #   # └─────┴──────┴──────┘
+    def union(
+      items,
+      how: "vertical"
+    )
+      elems = items.to_a
+
+      if elems.empty?
+        msg = "cannot concat empty list"
+        raise ArgumentError, msg
+      elsif elems.length == 1 && (elems[0].is_a?(DataFrame) || elems[0].is_a?(Series) || elems[0].is_a?(LazyFrame))
+        return elems[0]
+      end
+
+      if how.start_with?("align")
+        raise Todo
+      end
+
+      out = nil
+      first = elems[0]
+
+      if first.is_a?(DataFrame)
+        if ["vertical", "vertical_relaxed"].include?(how)
+          out = Utils.wrap_ldf(
+            Plr.concat_lf(
+              elems.map { |df| df.lazy },
+              false,
+              true,
+              how.end_with?("relaxed")
+            )
+          ).collect(optimizations: QueryOptFlags._eager)
+        elsif ["diagonal", "diagonal_relaxed"].include?(how)
+          out = Utils.wrap_ldf(
+            Plr.concat_lf_diagonal(
+              elems.map { |df| df.lazy },
+              false,
+              true,
+              how.end_with?("relaxed")
+            )
+          ).collect(optimizations: QueryOptFlags._eager)
+        elsif how == "horizontal"
+          out = Utils.wrap_df(Plr.concat_df_horizontal(elems))
+        else
+          raise Todo
+          msg = "DataFrame `how` must be one of {{#{allowed}}}, got #{how.inspect}"
+          raise ArgumentError, msg
+        end
+
+      elsif first.is_a?(LazyFrame)
+        if ["vertical", "vertical_relaxed"].include?(how)
+          return Utils.wrap_ldf(
+            Plr.concat_lf(
+              elems,
+              false,
+              true,
+              how.end_with?("relaxed")
+            )
+          )
+        elsif ["diagonal", "diagonal_relaxed"].include?(how)
+          return Utils.wrap_ldf(
+            Plr.concat_lf_diagonal(
+              elems,
+              false,
+              true,
+              how.end_with?("relaxed")
+            )
+          )
+        elsif how == "horizontal"
+          return Utils.wrap_ldf(
+            Plr.concat_lf_horizontal(
+              elems,
+              true
+            )
+          )
+        else
+          raise Todo
+          msg = "LazyFrame `how` must be one of {{#{allowed}}}, got #{how.inspect}"
+          raise ArgumentError, msg
+        end
+
+      elsif first.is_a?(Series)
+        if how == "vertical"
+          out = Utils.wrap_s(Plr.concat_series(elems))
+        else
+          msg = "Series only supports 'vertical' concat strategy"
+          raise ArgumentError, msg
+        end
+
+      elsif first.is_a?(Expr)
+        return Utils.wrap_expr(Plr.concat_expr(elems.map { |e| e._rbexpr }, false))
+      else
+        msg = "did not expect type: #{first.class.name.inspect} in `concat`"
+        raise TypeError, msg
+      end
+
+      out
+    end
+
+    # Align an array of frames using the unique values from one or more columns as a key.
     #
     # Frames that do not contain the given key values have rows injected (with nulls
     # filling the non-key columns), and each resulting frame is sorted by the key.
@@ -219,13 +406,13 @@ module Polars
     # the same number of rows.
     #
     # @param frames [Array]
-    #   Sequence of DataFrames or LazyFrames.
+    #   Array of DataFrames or LazyFrames.
     # @param on [Object]
     #   One or more columns whose unique values will be used to align the frames.
     # @param select [Object]
     #   Optional post-alignment column select to constrain and/or order
     #   the columns returned from the newly aligned frames.
-    # @param reverse [Object]
+    # @param descending [Object]
     #   Sort the alignment column values in descending order; can be a single
     #   boolean or a list of booleans associated with each column in `on`.
     #
@@ -254,7 +441,7 @@ module Polars
     #     }
     #   )
     #   af1, af2, af3 = Polars.align_frames(
-    #     df1, df2, df3, on: "dt", select: ["x", "y"]
+    #     df1, df2, df3, on: "dt", how: "left", select: ["x", "y"]
     #   )
     #   (af1 * af2 * af3).fill_null(0).select(Polars.sum_horizontal("*").alias("dot"))
     #   # =>
@@ -271,9 +458,16 @@ module Polars
     def align_frames(
       *frames,
       on:,
+      how: nil,
       select: nil,
-      reverse: false
+      descending: false
     )
+      # TODO update
+      if how.nil?
+        warn "The default `how` for `align_frames` method will change from `left` to `full` in a future version"
+        how = "left"
+      end
+
       if frames.empty?
         return []
       elsif frames.map(&:class).uniq.length != 1
@@ -285,7 +479,7 @@ module Polars
       alignment_frame = (
         concat(frames.map { |df| df.lazy.select(on) })
           .unique(maintain_order: false)
-          .sort(on, reverse: reverse)
+          .sort(on, descending: descending)
       )
       alignment_frame = (
         eager ? alignment_frame.collect.lazy : alignment_frame.cache
@@ -296,7 +490,7 @@ module Polars
           alignment_frame.join(
             df.lazy,
             on: alignment_frame.columns,
-            how: "left"
+            how: how
           ).select(df.columns)
         end
       if !select.nil?

data/lib/polars/functions/escape_regex.rb

@@ -0,0 +1,21 @@
+module Polars
+  module Functions
+    # Escapes string regex meta characters.
+    #
+    # @param s [String]
+    #   The string whose meta characters will be escaped.
+    #
+    # @return [String]
+    def escape_regex(s)
+      if s.is_a?(Expr)
+        msg = "escape_regex function is unsupported for `Expr`, you may want use `Expr.str.escape_regex` instead"
+        raise TypeError, msg
+      elsif !s.is_a?(::String)
+        msg = "escape_regex function supports only `String` type, got `#{s.class.name}`"
+        raise TypeError, msg
+      end
+
+      Plr.escape_regex(s)
+    end
+  end
+end