polars-df 0.4.0-x86_64-darwin → 0.6.0-x86_64-darwin

data/lib/polars/string_expr.rb

@@ -9,11 +9,129 @@ module Polars
       self._rbexpr = expr._rbexpr
     end
 
+    # Convert a Utf8 column into a Date column.
+    #
+    # @param format [String]
+    #   Format to use for conversion. Refer to the
+    #   [chrono crate documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)
+    #   for the full specification. Example: `"%Y-%m-%d"`.
+    #   If set to nil (default), the format is inferred from the data.
+    # @param strict [Boolean]
+    #   Raise an error if any conversion fails.
+    # @param exact [Boolean]
+    #   Require an exact format match. If false, allow the format to match anywhere
+    #   in the target string.
+    # @param cache [Boolean]
+    #   Use a cache of unique, converted dates to apply the conversion.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   s = Polars::Series.new(["2020/01/01", "2020/02/01", "2020/03/01"])
+    #   s.str.to_date
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [date]
+    #   # [
+    #   #         2020-01-01
+    #   #         2020-02-01
+    #   #         2020-03-01
+    #   # ]
+    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))
+    end
+
+    # Convert a Utf8 column into a Datetime column.
+    #
+    # @param format [String]
+    #   Format to use for conversion. Refer to the
+    #   [chrono crate documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)
+    #   for the full specification. Example: `"%Y-%m-%d %H:%M:%S"`.
+    #   If set to nil (default), the format is inferred from the data.
+    # @param time_unit ["us", "ns", "ms"]
+    #   Unit of time for the resulting Datetime column. If set to nil (default),
+    #   the time unit is inferred from the format string if given, eg:
+    #   `"%F %T%.3f"` => `Datetime("ms")`. If no fractional second component is
+    #   found, the default is `"us"`.
+    # @param time_zone [String]
+    #   Time zone for the resulting Datetime column.
+    # @param strict [Boolean]
+    #   Raise an error if any conversion fails.
+    # @param exact [Boolean]
+    #   Require an exact format match. If false, allow the format to match anywhere
+    #   in the target string.
+    # @param cache [Boolean]
+    #   Use a cache of unique, converted datetimes to apply the conversion.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   s = Polars::Series.new(["2020-01-01 01:00Z", "2020-01-01 02:00Z"])
+    #   s.str.to_datetime("%Y-%m-%d %H:%M%#z")
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: '' [datetime[μs, UTC]]
+    #   # [
+    #   #         2020-01-01 01:00:00 UTC
+    #   #         2020-01-01 02:00:00 UTC
+    #   # ]
+    def to_datetime(
+      format = nil,
+      time_unit: nil,
+      time_zone: nil,
+      strict: true,
+      exact: true,
+      cache: true
+    )
+      _validate_format_argument(format)
+      Utils.wrap_expr(
+        self._rbexpr.str_to_datetime(
+          format,
+          time_unit,
+          time_zone,
+          strict,
+          exact,
+          cache
+        )
+      )
+    end
+
+    # Convert a Utf8 column into a Time column.
+    #
+    # @param format [String]
+    #   Format to use for conversion. Refer to the
+    #   [chrono crate documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)
+    #   for the full specification. Example: `"%H:%M:%S"`.
+    #   If set to nil (default), the format is inferred from the data.
+    # @param strict [Boolean]
+    #   Raise an error if any conversion fails.
+    # @param cache [Boolean]
+    #   Use a cache of unique, converted times to apply the conversion.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   s = Polars::Series.new(["01:00", "02:00", "03:00"])
+    #   s.str.to_time("%H:%M")
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [time]
+    #   # [
+    #   #         01:00:00
+    #   #         02:00:00
+    #   #         03:00:00
+    #   # ]
+    def to_time(format = nil, strict: true, cache: true)
+      _validate_format_argument(format)
+      Utils.wrap_expr(_rbexpr.str_to_time(format, strict, cache))
+    end
+
     # Parse a Utf8 expression to a Date/Datetime/Time type.
     #
-    # @param datatype [Symbol]
-    #   `:date`, `:dateime`, or `:time`.
-    # @param fmt [String]
+    # @param dtype [Object]
+    #   The data type to convert into. Can be either Date, Datetime, or Time.
+    # @param format [String]
     #   Format to use, refer to the
     #   [chrono strftime documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)
     #   for specification. Example: `"%y-%m-%d"`.
@@ -33,57 +151,58 @@ module Polars
     #   the format string, if given, eg: "%F %T%.3f" => Datetime("ms"). If
     #   no fractional second component is found then the default is "us".
     #
-    # @example
+    # @example Dealing with a consistent format:
+    #   s = Polars::Series.new(["2020-01-01 01:00Z", "2020-01-01 02:00Z"])
+    #   s.str.strptime(Polars::Datetime, "%Y-%m-%d %H:%M%#z")
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: '' [datetime[μs, UTC]]
+    #   # [
+    #   #         2020-01-01 01:00:00 UTC
+    #   #         2020-01-01 02:00:00 UTC
+    #   # ]
+    #
+    # @example Dealing with different formats.
     #   s = Polars::Series.new(
     #     "date",
     #     [
     #       "2021-04-22",
     #       "2022-01-04 00:00:00",
     #       "01/31/22",
-    #       "Sun Jul  8 00:34:60 2001"
+    #       "Sun Jul  8 00:34:60 2001",
     #     ]
     #   )
-    #   s.to_frame.with_column(
-    #     Polars.col("date")
-    #       .str.strptime(:date, "%F", strict: false)
-    #       .fill_null(
-    #         Polars.col("date").str.strptime(:date, "%F %T", strict: false)
-    #       )
-    #       .fill_null(Polars.col("date").str.strptime(:date, "%D", strict: false))
-    #       .fill_null(Polars.col("date").str.strptime(:date, "%c", strict: false))
-    #   )
+    #   s.to_frame.select(
+    #     Polars.coalesce(
+    #       Polars.col("date").str.strptime(Polars::Date, "%F", strict: false),
+    #       Polars.col("date").str.strptime(Polars::Date, "%F %T", strict: false),
+    #       Polars.col("date").str.strptime(Polars::Date, "%D", strict: false),
+    #       Polars.col("date").str.strptime(Polars::Date, "%c", strict: false)
+    #     )
+    #   ).to_series
     #   # =>
-    #   # shape: (4, 1)
-    #   # ┌────────────┐
-    #   # │ date       │
-    #   # │ ---        │
-    #   # │ date       │
-    #   # ╞════════════╡
-    #   # │ 2021-04-22 │
-    #   # │ 2022-01-04 │
-    #   # │ 2022-01-31 │
-    #   # │ 2001-07-08 │
-    #   # └────────────┘
-    def strptime(datatype, fmt = nil, strict: true, exact: true, cache: true, tz_aware: false, utc: false)
-      if !Utils.is_polars_dtype(datatype)
-        raise ArgumentError, "expected: {DataType} got: #{datatype}"
-      end
+    #   # shape: (4,)
+    #   # Series: 'date' [date]
+    #   # [
+    #   #         2021-04-22
+    #   #         2022-01-04
+    #   #         2022-01-31
+    #   #         2001-07-08
+    #   # ]
+    def strptime(dtype, format = nil, strict: true, exact: true, cache: true, utc: false)
+      _validate_format_argument(format)
 
-      if datatype == :date
-        Utils.wrap_expr(_rbexpr.str_parse_date(fmt, strict, exact, cache))
-      elsif datatype == :datetime
-        # TODO fix
-        tu = nil # datatype.tu
-        dtcol = Utils.wrap_expr(_rbexpr.str_parse_datetime(fmt, strict, exact, cache, tz_aware, utc))
-        if tu.nil?
-          dtcol
-        else
-          dtcol.dt.cast_time_unit(tu)
-        end
-      elsif datatype == :time
-        Utils.wrap_expr(_rbexpr.str_parse_time(fmt, strict, exact, cache))
+      if dtype == Date
+        to_date(format, strict: strict, exact: exact, cache: cache)
+      elsif dtype == Datetime || dtype.is_a?(Datetime)
+        dtype = Datetime.new if dtype == Datetime
+        time_unit = dtype.time_unit
+        time_zone = dtype.time_zone
+        to_datetime(format, time_unit: time_unit, time_zone: time_zone, strict: strict, exact: exact, cache: cache)
+      elsif dtype == Time
+        to_time(format, strict: strict, cache: cache)
       else
-        raise ArgumentError, "dtype should be of type :date, :datetime, or :time"
+        raise ArgumentError, "dtype should be of type {Date, Datetime, Time}"
       end
     end
 
@@ -521,6 +640,40 @@ module Polars
       Utils.wrap_expr(_rbexpr.str_starts_with(sub))
     end
 
+    # Parse string values as JSON.
+    #
+    # Throw errors if encounter invalid JSON strings.
+    #
+    # @param dtype [Object]
+    #   The dtype to cast the extracted value to. If nil, the dtype will be
+    #   inferred from the JSON value.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"json" => ['{"a":1, "b": true}', nil, '{"a":2, "b": false}']}
+    #   )
+    #   dtype = Polars::Struct.new([Polars::Field.new("a", Polars::Int64), Polars::Field.new("b", Polars::Boolean)])
+    #   df.select(Polars.col("json").str.json_extract(dtype))
+    #   # =>
+    #   # shape: (3, 1)
+    #   # ┌─────────────┐
+    #   # │ json        │
+    #   # │ ---         │
+    #   # │ struct[2]   │
+    #   # ╞═════════════╡
+    #   # │ {1,true}    │
+    #   # │ {null,null} │
+    #   # │ {2,false}   │
+    #   # └─────────────┘
+    def json_extract(dtype = nil, infer_schema_length: 100)
+      if !dtype.nil?
+        dtype = Utils.rb_type_to_dtype(dtype)
+      end
+      Utils.wrap_expr(_rbexpr.str_json_extract(dtype, infer_schema_length))
+    end
+
     # Extract the first match of json string with provided JSONPath expression.
     #
     # Throw errors if encounter invalid json strings.
@@ -846,10 +999,10 @@ module Polars
     #   # │ 1   ┆ 123ABC │
     #   # │ 2   ┆ abc456 │
     #   # └─────┴────────┘
-    def replace(pattern, value, literal: false)
+    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(pattern._rbexpr, value._rbexpr, literal))
+      Utils.wrap_expr(_rbexpr.str_replace_n(pattern._rbexpr, value._rbexpr, literal, n))
     end
 
     # Replace all matching regex/literal substrings with a new string value.
@@ -912,5 +1065,84 @@ module Polars
     def slice(offset, length = nil)
       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
+
+    # Parse integers with base radix from strings.
+    #
+    # By default base 2. ParseError/Overflows become Nulls.
+    #
+    # @param radix [Integer]
+    #   Positive integer which is the base of the string we are parsing.
+    #   Default: 2.
+    # @param strict [Boolean]
+    #   Bool, Default=true will raise any ParseError or overflow as ComputeError.
+    #   False silently convert to Null.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"bin" => ["110", "101", "010", "invalid"]})
+    #   df.select(Polars.col("bin").str.parse_int(2, strict: false))
+    #   # =>
+    #   # shape: (4, 1)
+    #   # ┌──────┐
+    #   # │ bin  │
+    #   # │ ---  │
+    #   # │ i32  │
+    #   # ╞══════╡
+    #   # │ 6    │
+    #   # │ 5    │
+    #   # │ 2    │
+    #   # │ null │
+    #   # └──────┘
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"hex" => ["fa1e", "ff00", "cafe", nil]})
+    #   df.select(Polars.col("hex").str.parse_int(16, strict: true))
+    #   # =>
+    #   # shape: (4, 1)
+    #   # ┌───────┐
+    #   # │ hex   │
+    #   # │ ---   │
+    #   # │ i32   │
+    #   # ╞═══════╡
+    #   # │ 64030 │
+    #   # │ 65280 │
+    #   # │ 51966 │
+    #   # │ null  │
+    #   # └───────┘
+    def parse_int(radix = 2, strict: true)
+      Utils.wrap_expr(_rbexpr.str_parse_int(radix, strict))
+    end
+
+    private
+
+    def _validate_format_argument(format)
+      # TODO
+    end
   end
 end

data/lib/polars/string_name_space.rb

@@ -10,6 +10,112 @@ module Polars
       self._s = series._s
     end
 
+    # Convert a Utf8 column into a Date column.
+    #
+    # @param format [String]
+    #   Format to use for conversion. Refer to the
+    #   [chrono crate documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)
+    #   for the full specification. Example: `"%Y-%m-%d"`.
+    #   If set to nil (default), the format is inferred from the data.
+    # @param strict [Boolean]
+    #   Raise an error if any conversion fails.
+    # @param exact [Boolean]
+    #   Require an exact format match. If false, allow the format to match anywhere
+    #   in the target string.
+    # @param cache [Boolean]
+    #   Use a cache of unique, converted dates to apply the conversion.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new(["2020/01/01", "2020/02/01", "2020/03/01"])
+    #   s.str.to_date
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [date]
+    #   # [
+    #   #         2020-01-01
+    #   #         2020-02-01
+    #   #         2020-03-01
+    #   # ]
+    def to_date(format = nil, strict: true, exact: true, cache: true)
+      super
+    end
+
+    # Convert a Utf8 column into a Datetime column.
+    #
+    # @param format [String]
+    #   Format to use for conversion. Refer to the
+    #   [chrono crate documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)
+    #   for the full specification. Example: `"%Y-%m-%d %H:%M:%S"`.
+    #   If set to nil (default), the format is inferred from the data.
+    # @param time_unit ["us", "ns", "ms"]
+    #   Unit of time for the resulting Datetime column. If set to nil (default),
+    #   the time unit is inferred from the format string if given, eg:
+    #   `"%F %T%.3f"` => `Datetime("ms")`. If no fractional second component is
+    #   found, the default is `"us"`.
+    # @param time_zone [String]
+    #   Time zone for the resulting Datetime column.
+    # @param strict [Boolean]
+    #   Raise an error if any conversion fails.
+    # @param exact [Boolean]
+    #   Require an exact format match. If false, allow the format to match anywhere
+    #   in the target string.
+    # @param cache [Boolean]
+    #   Use a cache of unique, converted datetimes to apply the conversion.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new(["2020-01-01 01:00Z", "2020-01-01 02:00Z"])
+    #   s.str.to_datetime("%Y-%m-%d %H:%M%#z")
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: '' [datetime[μs, UTC]]
+    #   # [
+    #   #         2020-01-01 01:00:00 UTC
+    #   #         2020-01-01 02:00:00 UTC
+    #   # ]
+    def to_datetime(
+      format = nil,
+      time_unit: nil,
+      time_zone: nil,
+      strict: true,
+      exact: true,
+      cache: true
+    )
+      super
+    end
+
+    # Convert a Utf8 column into a Time column.
+    #
+    # @param format [String]
+    #   Format to use for conversion. Refer to the
+    #   [chrono crate documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)
+    #   for the full specification. Example: `"%H:%M:%S"`.
+    #   If set to nil (default), the format is inferred from the data.
+    # @param strict [Boolean]
+    #   Raise an error if any conversion fails.
+    # @param cache [Boolean]
+    #   Use a cache of unique, converted times to apply the conversion.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new(["01:00", "02:00", "03:00"])
+    #   s.str.to_time("%H:%M")
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [time]
+    #   # [
+    #   #         01:00:00
+    #   #         02:00:00
+    #   #         03:00:00
+    #   # ]
+    def to_time(format = nil, strict: true, cache: true)
+      super
+    end
+
     # Parse a Series of dtype Utf8 to a Date/Datetime Series.
     #
     # @param datatype [Symbol]
@@ -23,10 +129,23 @@ module Polars
     # @param exact [Boolean]
     #   - If true, require an exact format match.
     #   - If false, allow the format to match anywhere in the target string.
+    # @param cache [Boolean]
+    #   Use a cache of unique, converted dates to apply the datetime conversion.
     #
     # @return [Series]
     #
-    # @example
+    # @example Dealing with a consistent format:
+    #   s = Polars::Series.new(["2020-01-01 01:00Z", "2020-01-01 02:00Z"])
+    #   s.str.strptime(Polars::Datetime, "%Y-%m-%d %H:%M%#z")
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: '' [datetime[μs, UTC]]
+    #   # [
+    #   #         2020-01-01 01:00:00 UTC
+    #   #         2020-01-01 02:00:00 UTC
+    #   # ]
+    #
+    # @example Dealing with different formats.
     #   s = Polars::Series.new(
     #     "date",
     #     [
@@ -36,28 +155,24 @@ module Polars
     #       "Sun Jul  8 00:34:60 2001"
     #     ]
     #   )
-    #   s.to_frame.with_column(
-    #     Polars.col("date")
-    #       .str.strptime(:date, "%F", strict: false)
-    #       .fill_null(
-    #         Polars.col("date").str.strptime(:date, "%F %T", strict: false)
-    #       )
-    #       .fill_null(Polars.col("date").str.strptime(:date, "%D", strict: false))
-    #       .fill_null(Polars.col("date").str.strptime(:date, "%c", strict: false))
-    #   )
+    #   s.to_frame.select(
+    #     Polars.coalesce(
+    #       Polars.col("date").str.strptime(Polars::Date, "%F", strict: false),
+    #       Polars.col("date").str.strptime(Polars::Date, "%F %T", strict: false),
+    #       Polars.col("date").str.strptime(Polars::Date, "%D", strict: false),
+    #       Polars.col("date").str.strptime(Polars::Date, "%c", strict: false)
+    #     )
+    #   ).to_series
     #   # =>
-    #   # shape: (4, 1)
-    #   # ┌────────────┐
-    #   # │ date       │
-    #   # │ ---        │
-    #   # │ date       │
-    #   # ╞════════════╡
-    #   # │ 2021-04-22 │
-    #   # │ 2022-01-04 │
-    #   # │ 2022-01-31 │
-    #   # │ 2001-07-08 │
-    #   # └────────────┘
-    def strptime(datatype, fmt = nil, strict: true, exact: true, cache: true, tz_aware: false, utc: false)
+    #   # shape: (4,)
+    #   # Series: 'date' [date]
+    #   # [
+    #   #         2021-04-22
+    #   #         2022-01-04
+    #   #         2022-01-31
+    #   #         2001-07-08
+    #   # ]
+    def strptime(datatype, fmt = nil, strict: true, exact: true, cache: true)
       super
     end
 

data/lib/polars/struct_name_space.rb

@@ -60,5 +60,37 @@ module Polars
     def rename_fields(names)
       super
     end
+
+    # Get the struct definition as a name/dtype schema dict.
+    #
+    # @return [Object]
+    def schema
+      if _s.nil?
+        {}
+      else
+        _s.dtype.to_schema
+      end
+    end
+
+    # Convert this struct Series to a DataFrame with a separate column for each field.
+    #
+    # @return [DataFrame]
+    #
+    # @example
+    #   s = Polars::Series.new([{"a" => 1, "b" => 2}, {"a" => 3, "b" => 4}])
+    #   s.struct.unnest
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌─────┬─────┐
+    #   # │ a   ┆ b   │
+    #   # │ --- ┆ --- │
+    #   # │ i64 ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ 1   ┆ 2   │
+    #   # │ 3   ┆ 4   │
+    #   # └─────┴─────┘
+    def unnest
+      Utils.wrap_df(_s.struct_unnest)
+    end
   end
 end