polars-df 0.11.0 → 0.12.0

data/lib/polars/string_expr.rb

@@ -39,7 +39,7 @@ module Polars
     #   # ]
     def to_date(format = nil, strict: true, exact: true, cache: true)
       _validate_format_argument(format)
-      Utils.wrap_expr(self._rbexpr.str_to_date(format, strict, exact, cache))
+      Utils.wrap_expr(_rbexpr.str_to_date(format, strict, exact, cache))
     end
 
     # Convert a Utf8 column into a Datetime column.
@@ -83,14 +83,14 @@ module Polars
       strict: true,
       exact: true,
       cache: true,
-      use_earliest: nil,
       ambiguous: "raise"
     )
       _validate_format_argument(format)
-      ambiguous = Utils.rename_use_earliest_to_ambiguous(use_earliest, ambiguous)
-      ambiguous = Polars.lit(ambiguous) unless ambiguous.is_a?(Expr)
+      unless ambiguous.is_a?(Expr)
+        ambiguous = Polars.lit(ambiguous)
+      end
       Utils.wrap_expr(
-        self._rbexpr.str_to_datetime(
+        _rbexpr.str_to_datetime(
           format,
           time_unit,
           time_zone,
@@ -331,7 +331,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"foo" => [1, nil, 2]})
-    #   df.select(Polars.col("foo").str.concat("-"))
+    #   df.select(Polars.col("foo").str.join("-"))
     #   # =>
     #   # shape: (1, 1)
     #   # ┌─────┐
@@ -344,7 +344,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"foo" => [1, nil, 2]})
-    #   df.select(Polars.col("foo").str.concat("-", ignore_nulls: false))
+    #   df.select(Polars.col("foo").str.join("-", ignore_nulls: false))
     #   # =>
     #   # shape: (1, 1)
     #   # ┌──────┐
@@ -354,9 +354,10 @@ module Polars
     #   # ╞══════╡
     #   # │ null │
     #   # └──────┘
-    def concat(delimiter = "-", ignore_nulls: true)
-      Utils.wrap_expr(_rbexpr.str_concat(delimiter, ignore_nulls))
+    def join(delimiter = "-", ignore_nulls: true)
+      Utils.wrap_expr(_rbexpr.str_join(delimiter, ignore_nulls))
     end
+    alias_method :concat, :join
 
     # Transform to uppercase variant.
     #
@@ -446,7 +447,7 @@ module Polars
     #   # │ both  │
     #   # └───────┘
     def strip_chars(characters = nil)
-      characters = Utils.parse_as_expression(characters, str_as_lit: true)
+      characters = Utils.parse_into_expression(characters, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_strip_chars(characters))
     end
     alias_method :strip, :strip_chars
@@ -473,7 +474,7 @@ module Polars
     #   # │ both   │
     #   # └────────┘
     def strip_chars_start(characters = nil)
-      characters = Utils.parse_as_expression(characters, str_as_lit: true)
+      characters = Utils.parse_into_expression(characters, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_strip_chars_start(characters))
     end
     alias_method :lstrip, :strip_chars_start
@@ -500,7 +501,7 @@ module Polars
     #   # │  both │
     #   # └───────┘
     def strip_chars_end(characters = nil)
-      characters = Utils.parse_as_expression(characters, str_as_lit: true)
+      characters = Utils.parse_into_expression(characters, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_strip_chars_end(characters))
     end
     alias_method :rstrip, :strip_chars_end
@@ -530,7 +531,7 @@ module Polars
     #   # │ bar       ┆ bar      │
     #   # └───────────┴──────────┘
     def strip_prefix(prefix)
-      prefix = Utils.parse_as_expression(prefix, str_as_lit: true)
+      prefix = Utils.parse_into_expression(prefix, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_strip_prefix(prefix))
     end
 
@@ -560,7 +561,7 @@ module Polars
     #   # │ bar       ┆          │
     #   # └───────────┴──────────┘
     def strip_suffix(suffix)
-      suffix = Utils.parse_as_expression(suffix, str_as_lit: true)
+      suffix = Utils.parse_into_expression(suffix, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_strip_suffix(suffix))
     end
 
@@ -654,7 +655,7 @@ module Polars
     #   # │ null   ┆ null   │
     #   # └────────┴────────┘
     def zfill(length)
-      length = Utils.parse_as_expression(length)
+      length = Utils.parse_into_expression(length)
       Utils.wrap_expr(_rbexpr.str_zfill(length))
     end
 
@@ -689,7 +690,7 @@ module Polars
     #   # │ null        ┆ null  ┆ null    │
     #   # └─────────────┴───────┴─────────┘
     def contains(pattern, literal: false, strict: true)
-      pattern = Utils.expr_to_lit_or_expr(pattern, str_to_lit: true)._rbexpr
+      pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_contains(pattern, literal, strict))
     end
 
@@ -729,7 +730,7 @@ module Polars
     #   # │ mango  │
     #   # └────────┘
     def ends_with(sub)
-      sub = Utils.expr_to_lit_or_expr(sub, str_to_lit: true)._rbexpr
+      sub = Utils.parse_into_expression(sub, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_ends_with(sub))
     end
 
@@ -769,7 +770,7 @@ module Polars
     #   # │ apple  │
     #   # └────────┘
     def starts_with(sub)
-      sub = Utils.expr_to_lit_or_expr(sub, str_to_lit: true)._rbexpr
+      sub = Utils.parse_into_expression(sub, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_starts_with(sub))
     end
 
@@ -840,7 +841,7 @@ module Polars
     #   # │ true     │
     #   # └──────────┘
     def json_path_match(json_path)
-      json_path = Utils.parse_as_expression(json_path, str_as_lit: true)
+      json_path = Utils.parse_into_expression(json_path, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_json_path_match(json_path))
     end
 
@@ -940,7 +941,7 @@ module Polars
     #   # │ 678 │
     #   # └─────┘
     def extract(pattern, group_index: 1)
-      pattern = Utils.parse_as_expression(pattern, str_as_lit: true)
+      pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_extract(pattern, group_index))
     end
 
@@ -972,8 +973,8 @@ module Polars
     #   # │ ["678", "910"] │
     #   # └────────────────┘
     def extract_all(pattern)
-      pattern = Utils.expr_to_lit_or_expr(pattern, str_to_lit: true)
-      Utils.wrap_expr(_rbexpr.str_extract_all(pattern._rbexpr))
+      pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.str_extract_all(pattern))
     end
 
     # Extract all capture groups for the given regex pattern.
@@ -1057,7 +1058,7 @@ module Polars
     #   # │ 6            │
     #   # └──────────────┘
     def count_matches(pattern, literal: false)
-      pattern = Utils.parse_as_expression(pattern, str_as_lit: true)
+      pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_count_matches(pattern, literal))
     end
     alias_method :count_match, :count_matches
@@ -1086,12 +1087,11 @@ module Polars
     #   # │ ["foo", "bar", "baz"] │
     #   # └───────────────────────┘
     def split(by, inclusive: false)
-      by = Utils.parse_as_expression(by, str_as_lit: true)
+      by = Utils.parse_into_expression(by, str_as_lit: true)
       if inclusive
-        Utils.wrap_expr(_rbexpr.str_split_inclusive(by))
-      else
-        Utils.wrap_expr(_rbexpr.str_split(by))
+        return Utils.wrap_expr(_rbexpr.str_split_inclusive(by))
       end
+      Utils.wrap_expr(_rbexpr.str_split(by))
     end
 
     # Split the string by a substring using `n` splits.
@@ -1129,7 +1129,7 @@ module Polars
     #   # │ {"d","4"}   │
     #   # └─────────────┘
     def split_exact(by, n, inclusive: false)
-      by = Utils.parse_as_expression(by, str_as_lit: true)
+      by = Utils.parse_into_expression(by, str_as_lit: true)
       if inclusive
         Utils.wrap_expr(_rbexpr.str_split_exact_inclusive(by, n))
       else
@@ -1166,7 +1166,7 @@ module Polars
     #   # │ {"foo","bar baz"} │
     #   # └───────────────────┘
     def splitn(by, n)
-      by = Utils.parse_as_expression(by, str_as_lit: true)
+      by = Utils.parse_into_expression(by, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_splitn(by, n))
     end
 
@@ -1197,9 +1197,9 @@ module Polars
     #   # │ 2   ┆ abc456 │
     #   # └─────┴────────┘
     def replace(pattern, value, literal: false, n: 1)
-      pattern = Utils.expr_to_lit_or_expr(pattern, str_to_lit: true)
-      value = Utils.expr_to_lit_or_expr(value, str_to_lit: true)
-      Utils.wrap_expr(_rbexpr.str_replace_n(pattern._rbexpr, value._rbexpr, literal, n))
+      pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
+      value = Utils.parse_into_expression(value, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.str_replace_n(pattern, value, literal, n))
     end
 
     # Replace all matching regex/literal substrings with a new string value.
@@ -1227,9 +1227,9 @@ module Polars
     #   # │ 2   ┆ 123-123 │
     #   # └─────┴─────────┘
     def replace_all(pattern, value, literal: false)
-      pattern = Utils.expr_to_lit_or_expr(pattern, str_to_lit: true)
-      value = Utils.expr_to_lit_or_expr(value, str_to_lit: true)
-      Utils.wrap_expr(_rbexpr.str_replace_all(pattern._rbexpr, value._rbexpr, literal))
+      pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
+      value = Utils.parse_into_expression(value, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.str_replace_all(pattern, value, literal))
     end
 
     # Returns string values in reversed order.
@@ -1282,36 +1282,11 @@ module Polars
     #   # │ dragonfruit ┆ uit      │
     #   # └─────────────┴──────────┘
     def slice(offset, length = nil)
-      offset = Utils.parse_as_expression(offset)
-      length = Utils.parse_as_expression(length)
+      offset = Utils.parse_into_expression(offset)
+      length = Utils.parse_into_expression(length)
       Utils.wrap_expr(_rbexpr.str_slice(offset, length))
     end
 
-    # Returns a column with a separate row for every string character.
-    #
-    # @return [Expr]
-    #
-    # @example
-    #   df = Polars::DataFrame.new({"a": ["foo", "bar"]})
-    #   df.select(Polars.col("a").str.explode)
-    #   # =>
-    #   # shape: (6, 1)
-    #   # ┌─────┐
-    #   # │ a   │
-    #   # │ --- │
-    #   # │ str │
-    #   # ╞═════╡
-    #   # │ f   │
-    #   # │ o   │
-    #   # │ o   │
-    #   # │ b   │
-    #   # │ a   │
-    #   # │ r   │
-    #   # └─────┘
-    def explode
-      Utils.wrap_expr(_rbexpr.str_explode)
-    end
-
     # Convert an Utf8 column into an Int64 column with base radix.
     #
     # @param base [Integer]
@@ -1355,7 +1330,7 @@ module Polars
     #   # │ null ┆ null   │
     #   # └──────┴────────┘
     def to_integer(base: 10, strict: true)
-      base = Utils.parse_as_expression(base, str_as_lit: false)
+      base = Utils.parse_into_expression(base, str_as_lit: false)
       Utils.wrap_expr(_rbexpr.str_to_integer(base, strict))
     end
 
@@ -1429,7 +1404,7 @@ module Polars
     #   # │ Can you feel the love tonight   ┆ true         │
     #   # └─────────────────────────────────┴──────────────┘
     def contains_any(patterns, ascii_case_insensitive: false)
-      patterns = Utils.parse_as_expression(patterns, str_as_lit: false, list_as_lit: false)
+      patterns = Utils.parse_into_expression(patterns, str_as_lit: false, list_as_series: true)
       Utils.wrap_expr(
         _rbexpr.str_contains_any(patterns, ascii_case_insensitive)
       )
@@ -1500,9 +1475,9 @@ module Polars
     #   # │ Can you feel the love tonight   ┆ Can me feel the love tonight    │
     #   # └─────────────────────────────────┴─────────────────────────────────┘
     def replace_many(patterns, replace_with, ascii_case_insensitive: false)
-      patterns = Utils.parse_as_expression(patterns, str_as_lit: false, list_as_lit: false)
-      replace_with = Utils.parse_as_expression(
-        replace_with, str_as_lit: true, list_as_lit: false
+      patterns = Utils.parse_into_expression(patterns, str_as_lit: false, list_as_series: true)
+      replace_with = Utils.parse_into_expression(
+        replace_with, str_as_lit: true, list_as_series: true
       )
       Utils.wrap_expr(
         _rbexpr.str_replace_many(

data/lib/polars/string_name_space.rb

@@ -83,7 +83,7 @@ module Polars
       strict: true,
       exact: true,
       cache: true,
-      use_earliest: nil
+      ambiguous: "raise"
     )
       super
     end
@@ -233,7 +233,7 @@ module Polars
     # @return [Series]
     #
     # @example
-    #   Polars::Series.new([1, nil, 2]).str.concat("-")
+    #   Polars::Series.new([1, nil, 2]).str.join("-")
     #   # =>
     #   # shape: (1,)
     #   # Series: '' [str]
@@ -242,16 +242,17 @@ module Polars
     #   # ]
     #
     # @example
-    #   Polars::Series.new([1, nil, 2]).str.concat("-", ignore_nulls: false)
+    #   Polars::Series.new([1, nil, 2]).str.join("-", ignore_nulls: false)
     #   # =>
     #   # shape: (1,)
     #   # Series: '' [str]
     #   # [
     #   #         null
     #   # ]
-    def concat(delimiter = "-", ignore_nulls: true)
+    def join(delimiter = "-", ignore_nulls: true)
       super
     end
+    alias_method :concat, :join
 
     # Check if strings in Series contain a substring that matches a regex.
     #

data/lib/polars/testing.rb

@@ -271,9 +271,9 @@ module Polars
 
     def _assert_correct_input_type(left, right)
       if left.is_a?(DataFrame) && right.is_a?(DataFrame)
-        return false
+        false
       elsif left.is_a?(LazyFrame) && right.is_a?(DataFrame)
-        return true
+        true
       else
         raise_assertion_error(
           "inputs",

data/lib/polars/utils/constants.rb

@@ -0,0 +1,9 @@
+module Polars
+  module Utils
+    SECONDS_PER_DAY = 86_400
+    SECONDS_PER_HOUR = 3_600
+    NS_PER_SECOND = 1_000_000_000
+    US_PER_SECOND = 1_000_000
+    MS_PER_SECOND = 1_000
+  end
+end

data/lib/polars/utils/convert.rb

@@ -0,0 +1,97 @@
+module Polars
+  module Utils
+    def self.parse_as_duration_string(td)
+      if td.nil? || td.is_a?(::String)
+        return td
+      end
+      _timedelta_to_duration_string(td)
+    end
+
+    def self._timedelta_to_pl_duration(td)
+      td
+    end
+
+    def self.negate_duration_string(duration)
+      if duration.start_with?("-")
+        duration[1..]
+      else
+        "-#{duration}"
+      end
+    end
+
+    def self.date_to_int(d)
+      dt = d.to_datetime.to_time
+      dt.to_i / SECONDS_PER_DAY
+    end
+
+    def self.datetime_to_int(dt, time_unit)
+      dt = dt.to_datetime.to_time
+      if time_unit == "ns"
+        nanos = dt.nsec
+        dt.to_i * NS_PER_SECOND + nanos
+      elsif time_unit == "us"
+        micros = dt.usec
+        dt.to_i * US_PER_SECOND + micros
+      elsif time_unit == "ms"
+        millis = dt.usec / 1000
+        dt.to_i * MS_PER_SECOND + millis
+      elsif time_unit.nil?
+        # Ruby has ns precision
+        nanos = dt.nsec
+        dt.to_i * NS_PER_SECOND + nanos
+      else
+        raise ArgumentError, "time_unit must be one of {{'ns', 'us', 'ms'}}, got #{tu}"
+      end
+    end
+
+    def self._to_ruby_date(value)
+      # days to seconds
+      # important to create from utc. Not doing this leads
+      # to inconsistencies dependent on the timezone you are in.
+      ::Time.at(value * 86400).utc.to_date
+    end
+
+    def self._to_ruby_time(value)
+      if value == 0
+        ::Time.utc(2000, 1, 1)
+      else
+        seconds, nanoseconds = value.divmod(1_000_000_000)
+        minutes, seconds = seconds.divmod(60)
+        hours, minutes = minutes.divmod(60)
+        ::Time.utc(2000, 1, 1, hours, minutes, seconds, nanoseconds / 1000.0)
+      end
+    end
+
+    def self._to_ruby_datetime(value, time_unit = "ns", time_zone = nil)
+      if time_zone.nil? || time_zone == "" || time_zone == "UTC"
+        if time_unit == "ns"
+          ::Time.at(value / 1000000000, value % 1000000000, :nsec).utc
+        elsif time_unit == "us"
+          ::Time.at(value / 1000000, value % 1000000, :usec).utc
+        elsif time_unit == "ms"
+          ::Time.at(value / 1000, value % 1000, :millisecond).utc
+        else
+          raise ArgumentError, "time_unit must be one of {{'ns', 'us', 'ms'}}, got #{time_unit}"
+        end
+      else
+        raise Todo
+      end
+    end
+
+    def self._to_ruby_duration(value, time_unit = "ns")
+      if time_unit == "ns"
+        value / 1e9
+      elsif time_unit == "us"
+        value / 1e6
+      elsif time_unit == "ms"
+        value / 1e3
+      else
+        raise ArgumentError, "time_unit must be one of {{'ns', 'us', 'ms'}}, got #{time_unit}"
+      end
+    end
+
+    def self._to_ruby_decimal(digits, scale)
+      BigDecimal("#{digits}e#{scale}")
+    end
+  end
+end

data/lib/polars/utils/parse.rb

@@ -0,0 +1,89 @@
+module Polars
+  module Utils
+    def self.parse_into_expression(
+      input,
+      str_as_lit: false,
+      list_as_series: false,
+      structify: false,
+      dtype: nil
+    )
+      if input.is_a?(Expr)
+        expr = input
+        if structify
+          expr = _structify_expression(expr)
+        end
+      elsif (input.is_a?(::String) || input.is_a?(Symbol)) && !str_as_lit
+        expr = F.col(input)
+      elsif input.is_a?(::Array) && list_as_series
+        expr = F.lit(Series.new(input), dtype: dtype)
+      else
+        expr = F.lit(input, dtype: dtype)
+      end
+
+      expr._rbexpr
+    end
+
+    def self.parse_into_list_of_expressions(*inputs, __structify: false, **named_inputs)
+      exprs = _parse_positional_inputs(inputs, structify: __structify)
+      if named_inputs.any?
+        named_exprs = _parse_named_inputs(named_inputs, structify: __structify)
+        exprs.concat(named_exprs)
+      end
+
+      exprs
+    end
+
+    def self._parse_positional_inputs(inputs, structify: false)
+      inputs_iter = _parse_inputs_as_iterable(inputs)
+      inputs_iter.map { |e| parse_into_expression(e, structify: structify) }
+    end
+
+    def self._parse_inputs_as_iterable(inputs)
+      if inputs.empty?
+        return []
+      end
+
+      if inputs.length == 1 && inputs[0].is_a?(::Array)
+        return inputs[0]
+      end
+
+      inputs
+    end
+
+    def self._parse_named_inputs(named_inputs, structify: false)
+      named_inputs.map do |name, input|
+        parse_into_expression(input, structify: structify)._alias(name.to_s)
+      end
+    end
+
+    def self.parse_predicates_constraints_into_expression(*predicates, **constraints)
+      all_predicates = _parse_positional_inputs(predicates)
+
+      if constraints.any?
+        constraint_predicates = _parse_constraints(constraints)
+        all_predicates.concat(constraint_predicates)
+      end
+
+      _combine_predicates(all_predicates)
+    end
+
+    def self._parse_constraints(constraints)
+      constraints.map do |name, value|
+        Polars.col(name).eq(value)._rbexpr
+      end
+    end
+
+    def self._combine_predicates(predicates)
+      if !predicates.any?
+        msg = "at least one predicate or constraint must be provided"
+        raise TypeError, msg
+      end
+
+      if predicates.length == 1
+        return predicates[0]
+      end
+
+      Plr.all_horizontal(predicates)
+    end
+  end
+end

data/lib/polars/utils/various.rb

@@ -0,0 +1,76 @@
+module Polars
+  module Utils
+    def self._process_null_values(null_values)
+      if null_values.is_a?(Hash)
+        null_values.to_a
+      else
+        null_values
+      end
+    end
+
+    def self._is_iterable_of(val, eltype)
+      val.all? { |x| x.is_a?(eltype) }
+    end
+
+    def self.is_bool_sequence(val)
+      val.is_a?(::Array) && val.all? { |x| x == true || x == false }
+    end
+
+    def self.is_int_sequence(val)
+      val.is_a?(::Array) && _is_iterable_of(val, Integer)
+    end
+
+    def self.is_str_sequence(val, allow_str: false)
+      if allow_str == false && val.is_a?(::String)
+        false
+      else
+        val.is_a?(::Array) && _is_iterable_of(val, ::String)
+      end
+    end
+
+    def self.arrlen(obj)
+      if obj.is_a?(Range)
+        # size only works for numeric ranges
+        obj.to_a.length
+      elsif obj.is_a?(::String)
+        nil
+      else
+        obj.length
+      end
+    rescue
+      nil
+    end
+
+    def self.normalize_filepath(path, check_not_directory: true)
+      path = File.expand_path(path)
+      if check_not_directory && File.exist?(path) && Dir.exist?(path)
+        raise ArgumentError, "Expected a file path; #{path} is a directory"
+      end
+      path
+    end
+
+    def self.scale_bytes(sz, to:)
+      scaling_factor = {
+        "b" => 1,
+        "k" => 1024,
+        "m" => 1024 ** 2,
+        "g" => 1024 ** 3,
+        "t" => 1024 ** 4
+      }[to[0]]
+      if scaling_factor > 1
+        sz / scaling_factor.to_f
+      else
+        sz
+      end
+    end
+
+    def self.extend_bool(value, n_match, value_name, match_name)
+      values = bool?(value) ? [value] * n_match : value
+      if n_match != values.length
+        msg = "the length of `#{value_name}` (#{values.length}) does not match the length of `#{match_name}` (#{n_match})"
+        raise ValueError, msg
+      end
+      values
+    end
+  end
+end

data/lib/polars/utils/wrap.rb

@@ -0,0 +1,19 @@
+module Polars
+  module Utils
+    def self.wrap_df(df)
+      DataFrame._from_rbdf(df)
+    end
+
+    def self.wrap_ldf(ldf)
+      LazyFrame._from_rbldf(ldf)
+    end
+
+    def self.wrap_s(s)
+      Series._from_rbseries(s)
+    end
+
+    def self.wrap_expr(rbexpr)
+      Expr._from_rbexpr(rbexpr)
+    end
+  end
+end