polars-df 0.5.0 → 0.7.0

data/lib/polars/sql_context.rb

@@ -0,0 +1,194 @@
+module Polars
+  # Run SQL queries against DataFrame/LazyFrame data.
+  class SQLContext
+    # @private
+    attr_accessor :_ctxt, :_eager_execution
+
+    # Initialize a new `SQLContext`.
+    def initialize(frames = nil, eager_execution: false, **named_frames)
+      self._ctxt = RbSQLContext.new
+      self._eager_execution = eager_execution
+
+      frames = (frames || {}).to_h
+
+      if frames.any? || named_frames.any?
+        register_many(frames, **named_frames)
+      end
+    end
+
+    # Parse the given SQL query and execute it against the registered frame data.
+    #
+    # @param query [String]
+    #   A valid string SQL query.
+    # @param eager [Boolean]
+    #   Apply the query eagerly, returning `DataFrame` instead of `LazyFrame`.
+    #   If unset, the value of the init-time parameter "eager_execution" will be
+    #   used. (Note that the query itself is always executed in lazy-mode; this
+    #   parameter only impacts the type of the returned frame).
+    #
+    # @return [Object]
+    #
+    # @example Execute a SQL query against the registered frame data:
+    #   df = Polars::DataFrame.new(
+    #     [
+    #       ["The Godfather", 1972, 6_000_000, 134_821_952, 9.2],
+    #       ["The Dark Knight", 2008, 185_000_000, 533_316_061, 9.0],
+    #       ["Schindler's List", 1993, 22_000_000, 96_067_179, 8.9],
+    #       ["Pulp Fiction", 1994, 8_000_000, 107_930_000, 8.9],
+    #       ["The Shawshank Redemption", 1994, 25_000_000, 28_341_469, 9.3],
+    #     ],
+    #     schema: ["title", "release_year", "budget", "gross", "imdb_score"]
+    #   )
+    #   ctx = Polars::SQLContext.new(films: df)
+    #   ctx.execute(
+    #     "
+    #     SELECT title, release_year, imdb_score
+    #     FROM films
+    #     WHERE release_year > 1990
+    #     ORDER BY imdb_score DESC
+    #     ",
+    #     eager: true
+    #   )
+    #   # =>
+    #   # shape: (4, 3)
+    #   # ┌──────────────────────────┬──────────────┬────────────┐
+    #   # │ title                    ┆ release_year ┆ imdb_score │
+    #   # │ ---                      ┆ ---          ┆ ---        │
+    #   # │ str                      ┆ i64          ┆ f64        │
+    #   # ╞══════════════════════════╪══════════════╪════════════╡
+    #   # │ The Shawshank Redemption ┆ 1994         ┆ 9.3        │
+    #   # │ The Dark Knight          ┆ 2008         ┆ 9.0        │
+    #   # │ Schindler's List         ┆ 1993         ┆ 8.9        │
+    #   # │ Pulp Fiction             ┆ 1994         ┆ 8.9        │
+    #   # └──────────────────────────┴──────────────┴────────────┘
+    #
+    # @example Execute a GROUP BY query:
+    #   ctx.execute(
+    #     "
+    #     SELECT
+    #         MAX(release_year / 10) * 10 AS decade,
+    #         SUM(gross) AS total_gross,
+    #         COUNT(title) AS n_films,
+    #     FROM films
+    #     GROUP BY (release_year / 10) -- decade
+    #     ORDER BY total_gross DESC
+    #     ",
+    #     eager: true
+    #   )
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌────────┬─────────────┬─────────┐
+    #   # │ decade ┆ total_gross ┆ n_films │
+    #   # │ ---    ┆ ---         ┆ ---     │
+    #   # │ i64    ┆ i64         ┆ u32     │
+    #   # ╞════════╪═════════════╪═════════╡
+    #   # │ 2000   ┆ 533316061   ┆ 1       │
+    #   # │ 1990   ┆ 232338648   ┆ 3       │
+    #   # │ 1970   ┆ 134821952   ┆ 1       │
+    #   # └────────┴─────────────┴─────────┘
+    def execute(query, eager: nil)
+      res = Utils.wrap_ldf(_ctxt.execute(query))
+      eager || _eager_execution ? res.collect : res
+    end
+
+    # Register a single frame as a table, using the given name.
+    #
+    # @param name [String]
+    #   Name of the table.
+    # @param frame [Object]
+    #   eager/lazy frame to associate with this table name.
+    #
+    # @return [SQLContext]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"hello" => ["world"]})
+    #   ctx = Polars::SQLContext.new
+    #   ctx.register("frame_data", df).execute("SELECT * FROM frame_data").collect
+    #   # =>
+    #   # shape: (1, 1)
+    #   # ┌───────┐
+    #   # │ hello │
+    #   # │ ---   │
+    #   # │ str   │
+    #   # ╞═══════╡
+    #   # │ world │
+    #   # └───────┘
+    def register(name, frame)
+      if frame.is_a?(DataFrame)
+        frame = frame.lazy
+      end
+      _ctxt.register(name.to_s, frame._ldf)
+      self
+    end
+
+    # Register multiple eager/lazy frames as tables, using the associated names.
+    #
+    # @param frames [Hash]
+    #   A `{name:frame, ...}` mapping.
+    # @param named_frames [Object]
+    #   Named eager/lazy frames, provided as kwargs.
+    #
+    # @return [SQLContext]
+    def register_many(frames, **named_frames)
+      frames = (frames || {}).to_h
+      frames = frames.merge(named_frames)
+      frames.each do |name, frame|
+        register(name, frame)
+      end
+      self
+    end
+
+    # Unregister one or more eager/lazy frames by name.
+    #
+    # @param names [Object]
+    #   Names of the tables to unregister.
+    #
+    # @return [SQLContext]
+    #
+    # @example Register with a SQLContext object:
+    #   df0 = Polars::DataFrame.new({"ints" => [9, 8, 7, 6, 5]})
+    #   lf1 = Polars::LazyFrame.new({"text" => ["a", "b", "c"]})
+    #   lf2 = Polars::LazyFrame.new({"misc" => ["testing1234"]})
+    #   ctx = Polars::SQLContext.new(test1: df0, test2: lf1, test3: lf2)
+    #   ctx.tables
+    #   # => ["test1", "test2", "test3"]
+    #
+    # @example Unregister one or more of the tables:
+    #   ctx.unregister(["test1", "test3"]).tables
+    #   # => ["test2"]
+    def unregister(names)
+      if names.is_a?(String)
+        names = [names]
+      end
+      names.each do |nm|
+        _ctxt.unregister(nm)
+      end
+      self
+    end
+
+    # Return a list of the registered table names.
+    #
+    # @return [Array]
+    #
+    # @example Executing as SQL:
+    #   frame_data = Polars::DataFrame.new({"hello" => ["world"]})
+    #   ctx = Polars::SQLContext.new(hello_world: frame_data)
+    #   ctx.execute("SHOW TABLES", eager: true)
+    #   # =>
+    #   # shape: (1, 1)
+    #   # ┌─────────────┐
+    #   # │ name        │
+    #   # │ ---         │
+    #   # │ str         │
+    #   # ╞═════════════╡
+    #   # │ hello_world │
+    #   # └─────────────┘
+    #
+    # @example Calling the method:
+    #   ctx.tables
+    #   # => ["hello_world"]
+    def tables
+      _ctxt.get_tables.sort
+    end
+  end
+end

data/lib/polars/string_expr.rb

@@ -9,11 +9,134 @@ 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,
+      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)
+      Utils.wrap_expr(
+        self._rbexpr.str_to_datetime(
+          format,
+          time_unit,
+          time_zone,
+          strict,
+          exact,
+          cache,
+          ambiguous._rbexpr
+        )
+      )
+    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 dtype [Object]
     #   The data type to convert into. Can be either Date, Datetime, or Time.
-    # @param fmt [String]
+    # @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"`.
@@ -38,10 +161,10 @@ module Polars
     #   s.str.strptime(Polars::Datetime, "%Y-%m-%d %H:%M%#z")
     #   # =>
     #   # shape: (2,)
-    #   # Series: '' [datetime[μs, +00:00]]
+    #   # Series: '' [datetime[μs, UTC]]
     #   # [
-    #   #         2020-01-01 01:00:00 +00:00
-    #   #         2020-01-01 02:00:00 +00:00
+    #   #         2020-01-01 01:00:00 UTC
+    #   #         2020-01-01 02:00:00 UTC
     #   # ]
     #
     # @example Dealing with different formats.
@@ -71,16 +194,18 @@ module Polars
     #   #         2022-01-31
     #   #         2001-07-08
     #   # ]
-    def strptime(dtype, fmt = nil, strict: true, exact: true, cache: true, tz_aware: false, utc: false)
+    def strptime(dtype, format = nil, strict: true, exact: true, cache: true, utc: false)
+      _validate_format_argument(format)
+
       if dtype == Date
-        Utils.wrap_expr(_rbexpr.str_parse_date(fmt, strict, exact, cache))
+        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
-        Utils.wrap_expr(_rbexpr.str_parse_datetime(fmt, time_unit, time_zone, strict, exact, cache, tz_aware, utc))
+        to_datetime(format, time_unit: time_unit, time_zone: time_zone, strict: strict, exact: exact, cache: cache)
       elsif dtype == Time
-        Utils.wrap_expr(_rbexpr.str_parse_time(fmt, strict, exact, cache))
+        to_time(format, strict: strict, cache: cache)
       else
         raise ArgumentError, "dtype should be of type {Date, Datetime, Time}"
       end
@@ -115,7 +240,7 @@ module Polars
     #   # │ 東京 ┆ 6      ┆ 2      │
     #   # └──────┴────────┴────────┘
     def lengths
-      Utils.wrap_expr(_rbexpr.str_lengths)
+      Utils.wrap_expr(_rbexpr.str_len_bytes)
     end
 
     # Get length of the strings as `:u32` (as number of chars).
@@ -147,13 +272,15 @@ module Polars
     #   # │ 東京 ┆ 6      ┆ 2      │
     #   # └──────┴────────┴────────┘
     def n_chars
-      Utils.wrap_expr(_rbexpr.str_n_chars)
+      Utils.wrap_expr(_rbexpr.str_len_chars)
     end
 
     # Vertically concat the values in the Series to a single string value.
     #
     # @param delimiter [String]
     #   The delimiter to insert between consecutive string values.
+    # @param ignore_nulls [Boolean]
+    #   Ignore null values (default).
     #
     # @return [Expr]
     #
@@ -162,15 +289,28 @@ module Polars
     #   df.select(Polars.col("foo").str.concat("-"))
     #   # =>
     #   # shape: (1, 1)
-    #   # ┌──────────┐
-    #   # │ foo      │
-    #   # │ ---      │
-    #   # │ str      │
-    #   # ╞══════════╡
-    #   # │ 1-null-2 │
-    #   # └──────────┘
-    def concat(delimiter = "-")
-      Utils.wrap_expr(_rbexpr.str_concat(delimiter))
+    #   # ┌─────┐
+    #   # │ foo │
+    #   # │ --- │
+    #   # │ str │
+    #   # ╞═════╡
+    #   # │ 1-2 │
+    #   # └─────┘
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"foo" => [1, nil, 2]})
+    #   df.select(Polars.col("foo").str.concat("-", ignore_nulls: false))
+    #   # =>
+    #   # shape: (1, 1)
+    #   # ┌──────┐
+    #   # │ foo  │
+    #   # │ ---  │
+    #   # │ str  │
+    #   # ╞══════╡
+    #   # │ null │
+    #   # └──────┘
+    def concat(delimiter = "-", ignore_nulls: true)
+      Utils.wrap_expr(_rbexpr.str_concat(delimiter, ignore_nulls))
     end
 
     # Transform to uppercase variant.
@@ -217,7 +357,7 @@ module Polars
 
     # Remove leading and trailing whitespace.
     #
-    # @param matches [String, nil]
+    # @param characters [String, nil]
     #   An optional single character that should be trimmed.
     #
     # @return [Expr]
@@ -236,16 +376,15 @@ module Polars
     #   # │ trail │
     #   # │ both  │
     #   # └───────┘
-    def strip(matches = nil)
-      if !matches.nil? && matches.length > 1
-        raise ArgumentError, "matches should contain a single character"
-      end
-      Utils.wrap_expr(_rbexpr.str_strip(matches))
+    def strip_chars(characters = nil)
+      characters = Utils.parse_as_expression(characters, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.str_strip_chars(characters))
     end
+    alias_method :strip, :strip_chars
 
     # Remove leading whitespace.
     #
-    # @param matches [String, nil]
+    # @param characters [String, nil]
     #   An optional single character that should be trimmed.
     #
     # @return [Expr]
@@ -264,16 +403,15 @@ module Polars
     #   # │ trail  │
     #   # │ both   │
     #   # └────────┘
-    def lstrip(matches = nil)
-      if !matches.nil? && matches.length > 1
-        raise ArgumentError, "matches should contain a single character"
-      end
-      Utils.wrap_expr(_rbexpr.str_lstrip(matches))
+    def strip_chars_start(characters = nil)
+      characters = Utils.parse_as_expression(characters, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.str_strip_chars_start(characters))
     end
+    alias_method :lstrip, :strip_chars_start
 
     # Remove trailing whitespace.
     #
-    # @param matches [String, nil]
+    # @param characters [String, nil]
     #   An optional single character that should be trimmed.
     #
     # @return [Expr]
@@ -292,12 +430,11 @@ module Polars
     #   # │ trail │
     #   # │  both │
     #   # └───────┘
-    def rstrip(matches = nil)
-      if !matches.nil? && matches.length > 1
-        raise ArgumentError, "matches should contain a single character"
-      end
-      Utils.wrap_expr(_rbexpr.str_rstrip(matches))
+    def strip_chars_end(characters = nil)
+      characters = Utils.parse_as_expression(characters, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.str_strip_chars_end(characters))
     end
+    alias_method :rstrip, :strip_chars_end
 
     # Fills the string with zeroes.
     #
@@ -341,13 +478,13 @@ module Polars
       Utils.wrap_expr(_rbexpr.str_zfill(alignment))
     end
 
-    # Return the string left justified in a string of length `width`.
+    # Return the string left justified in a string of length `length`.
     #
     # Padding is done using the specified `fillchar`.
-    # The original string is returned if `width` is less than or equal to
+    # The original string is returned if `length` is less than or equal to
     # `s.length`.
     #
-    # @param width [Integer]
+    # @param length [Integer]
     #   Justify left to this length.
     # @param fillchar [String]
     #   Fill with this ASCII character.
@@ -369,17 +506,18 @@ module Polars
     #   # │ null         │
     #   # │ hippopotamus │
     #   # └──────────────┘
-    def ljust(width, fillchar = " ")
-      Utils.wrap_expr(_rbexpr.str_ljust(width, fillchar))
+    def ljust(length, fillchar = " ")
+      Utils.wrap_expr(_rbexpr.str_pad_end(length, fillchar))
     end
+    alias_method :pad_end, :ljust
 
-    # Return the string right justified in a string of length `width`.
+    # Return the string right justified in a string of length `length`.
     #
     # Padding is done using the specified `fillchar`.
-    # The original string is returned if `width` is less than or equal to
+    # The original string is returned if `length` is less than or equal to
     # `s.length`.
     #
-    # @param width [Integer]
+    # @param length [Integer]
     #   Justify right to this length.
     # @param fillchar [String]
     #   Fill with this ASCII character.
@@ -401,9 +539,10 @@ module Polars
     #   # │ null         │
     #   # │ hippopotamus │
     #   # └──────────────┘
-    def rjust(width, fillchar = " ")
-      Utils.wrap_expr(_rbexpr.str_rjust(width, fillchar))
+    def rjust(length, fillchar = " ")
+      Utils.wrap_expr(_rbexpr.str_pad_start(length, fillchar))
     end
+    alias_method :pad_start, :rjust
 
     # Check if string contains a substring that matches a regex.
     #
@@ -547,11 +686,11 @@ module Polars
     #   # │ {null,null} │
     #   # │ {2,false}   │
     #   # └─────────────┘
-    def json_extract(dtype = nil)
+    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))
+      Utils.wrap_expr(_rbexpr.str_json_extract(dtype, infer_schema_length))
     end
 
     # Extract the first match of json string with provided JSONPath expression.
@@ -744,9 +883,11 @@ module Polars
     #   # │ 5            │
     #   # │ 6            │
     #   # └──────────────┘
-    def count_match(pattern)
-      Utils.wrap_expr(_rbexpr.count_match(pattern))
+    def count_matches(pattern, literal: false)
+      pattern = Utils.parse_as_expression(pattern, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.str_count_matches(pattern, literal))
     end
+    alias_method :count_match, :count_matches
 
     # Split the string by a substring.
     #
@@ -772,6 +913,7 @@ module Polars
     #   # │ ["foo", "bar", "baz"] │
     #   # └───────────────────────┘
     def split(by, inclusive: false)
+      by = Utils.parse_as_expression(by, str_as_lit: true)
       if inclusive
         Utils.wrap_expr(_rbexpr.str_split_inclusive(by))
       else
@@ -814,6 +956,7 @@ module Polars
     #   # │ {"d","4"}   │
     #   # └─────────────┘
     def split_exact(by, n, inclusive: false)
+      by = Utils.parse_as_expression(by, str_as_lit: true)
       if inclusive
         Utils.wrap_expr(_rbexpr.str_split_exact_inclusive(by, n))
       else
@@ -850,6 +993,7 @@ module Polars
     #   # │ {"foo","bar baz"} │
     #   # └───────────────────┘
     def splitn(by, n)
+      by = Utils.parse_as_expression(by, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_splitn(by, n))
     end
 
@@ -968,7 +1112,53 @@ module Polars
     #   # │ r   │
     #   # └─────┘
     def explode
-      Utils.wrap_expr(_rbexpr.explode)
+      Utils.wrap_expr(_rbexpr.str_explode)
+    end
+
+    # Convert an Utf8 column into an Int64 column with base radix.
+    #
+    # @param base [Integer]
+    #   Positive integer which is the base of the string we are parsing.
+    #   Default: 10.
+    # @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.with_columns(Polars.col("bin").str.to_integer(base: 2, strict: false).alias("parsed"))
+    #   # =>
+    #   # shape: (4, 2)
+    #   # ┌─────────┬────────┐
+    #   # │ bin     ┆ parsed │
+    #   # │ ---     ┆ ---    │
+    #   # │ str     ┆ i64    │
+    #   # ╞═════════╪════════╡
+    #   # │ 110     ┆ 6      │
+    #   # │ 101     ┆ 5      │
+    #   # │ 010     ┆ 2      │
+    #   # │ invalid ┆ null   │
+    #   # └─────────┴────────┘
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"hex" => ["fa1e", "ff00", "cafe", nil]})
+    #   df.with_columns(Polars.col("hex").str.to_integer(base: 16, strict: true).alias("parsed"))
+    #   # =>
+    #   # shape: (4, 2)
+    #   # ┌──────┬────────┐
+    #   # │ hex  ┆ parsed │
+    #   # │ ---  ┆ ---    │
+    #   # │ str  ┆ i64    │
+    #   # ╞══════╪════════╡
+    #   # │ fa1e ┆ 64030  │
+    #   # │ ff00 ┆ 65280  │
+    #   # │ cafe ┆ 51966  │
+    #   # │ null ┆ null   │
+    #   # └──────┴────────┘
+    def to_integer(base: 10, strict: true)
+      Utils.wrap_expr(_rbexpr.str_to_integer(base, strict))
     end
 
     # Parse integers with base radix from strings.
@@ -999,24 +1189,14 @@ module Polars
     #   # │ 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))
+      to_integer(base: 2, strict: strict).cast(Int32, strict: strict)
+    end
+
+    private
+
+    def _validate_format_argument(format)
+      # TODO
     end
   end
 end