polars-df 0.15.0 → 0.26.0

data/lib/polars/string_expr.rb

@@ -63,6 +63,13 @@ module Polars
     #   in the target string.
     # @param cache [Boolean]
     #   Use a cache of unique, converted datetimes to apply the conversion.
+    # @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]
     #
@@ -145,9 +152,15 @@ 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 utc [Boolean]
-    #   Parse timezone aware datetimes as UTC. This may be useful if you have data
-    #   with mixed offsets.
+    # @param cache [Boolean]
+    #   Use a cache of unique, converted dates to apply the datetime conversion.
+    # @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]
     #
@@ -194,7 +207,14 @@ module Polars
     #   #         2022-01-31
     #   #         2001-07-08
     #   # ]
-    def strptime(dtype, format = nil, strict: true, exact: true, cache: true, utc: false)
+    def strptime(
+      dtype,
+      format = nil,
+      strict: true,
+      exact: true,
+      cache: true,
+      ambiguous: "raise"
+    )
       _validate_format_argument(format)
 
       if dtype == Date
@@ -203,7 +223,15 @@ module Polars
         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)
+        to_datetime(
+          format,
+          time_unit: time_unit,
+          time_zone: time_zone,
+          strict: strict,
+          exact: exact,
+          cache: cache,
+          ambiguous: ambiguous
+        )
       elsif dtype == Time
         to_time(format, strict: strict, cache: cache)
       else
@@ -213,10 +241,8 @@ module Polars
 
     # Convert a String column into a Decimal column.
     #
-    # This method infers the needed parameters `precision` and `scale`.
-    #
-    # @param inference_length [Integer]
-    #   Number of elements to parse to determine the `precision` and `scale`.
+    # @param scale [Integer]
+    #   Number of digits after the comma to use for the decimals.
     #
     # @return [Expr]
     #
@@ -234,13 +260,13 @@ module Polars
     #       ]
     #     }
     #   )
-    #   df.with_columns(numbers_decimal: Polars.col("numbers").str.to_decimal)
+    #   df.with_columns(numbers_decimal: Polars.col("numbers").str.to_decimal(scale: 2))
     #   # =>
     #   # shape: (7, 2)
     #   # ┌───────────┬─────────────────┐
     #   # │ numbers   ┆ numbers_decimal │
     #   # │ ---       ┆ ---             │
-    #   # │ str       ┆ decimal[*,2]    │
+    #   # │ str       ┆ decimal[38,2]   │
     #   # ╞═══════════╪═════════════════╡
     #   # │ 40.12     ┆ 40.12           │
     #   # │ 3420.13   ┆ 3420.13         │
@@ -250,8 +276,8 @@ module Polars
     #   # │ 143.09    ┆ 143.09          │
     #   # │ 143.9     ┆ 143.90          │
     #   # └───────────┴─────────────────┘
-    def to_decimal(inference_length = 100)
-      Utils.wrap_expr(_rbexpr.str_to_decimal(inference_length))
+    def to_decimal(scale:)
+      Utils.wrap_expr(_rbexpr.str_to_decimal(scale))
     end
 
     # Get length of the strings as `:u32` (as number of bytes).
@@ -285,7 +311,6 @@ module Polars
     def len_bytes
       Utils.wrap_expr(_rbexpr.str_len_bytes)
     end
-    alias_method :lengths, :len_bytes
 
     # Get length of the strings as `:u32` (as number of chars).
     #
@@ -318,7 +343,6 @@ module Polars
     def len_chars
       Utils.wrap_expr(_rbexpr.str_len_chars)
     end
-    alias_method :n_chars, :len_chars
 
     # Vertically concat the values in the Series to a single string value.
     #
@@ -354,10 +378,74 @@ module Polars
     #   # ╞══════╡
     #   # │ null │
     #   # └──────┘
-    def join(delimiter = "-", ignore_nulls: true)
+    def join(delimiter = "", ignore_nulls: true)
       Utils.wrap_expr(_rbexpr.str_join(delimiter, ignore_nulls))
     end
-    alias_method :concat, :join
+
+    # Returns string values with all regular expression meta characters escaped.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"text" => ["abc", "def", nil, "abc(\\w+)"]})
+    #   df.with_columns(Polars.col("text").str.escape_regex.alias("escaped"))
+    #   # =>
+    #   # shape: (4, 2)
+    #   # ┌──────────┬──────────────┐
+    #   # │ text     ┆ escaped      │
+    #   # │ ---      ┆ ---          │
+    #   # │ str      ┆ str          │
+    #   # ╞══════════╪══════════════╡
+    #   # │ abc      ┆ abc          │
+    #   # │ def      ┆ def          │
+    #   # │ null     ┆ null         │
+    #   # │ abc(\w+) ┆ abc\(\\w\+\) │
+    #   # └──────────┴──────────────┘
+    def escape_regex
+      Utils.wrap_expr(_rbexpr.str_escape_regex)
+    end
+
+    # Returns the Unicode normal form of the string values.
+    #
+    # This uses the forms described in Unicode Standard Annex 15: <https://www.unicode.org/reports/tr15/>.
+    #
+    # @param form ['NFC', 'NFKC', 'NFD', 'NFKD']
+    #   Unicode form to use.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"text" => ["01²", "ＫＡＤＯＫＡＷＡ"]})
+    #   new = df.with_columns(
+    #     nfc: Polars.col("text").str.normalize("NFC"),
+    #     nfkc: Polars.col("text").str.normalize("NFKC")
+    #   )
+    #   # =>
+    #   # shape: (2, 3)
+    #   # ┌──────────────────┬──────────────────┬──────────┐
+    #   # │ text             ┆ nfc              ┆ nfkc     │
+    #   # │ ---              ┆ ---              ┆ ---      │
+    #   # │ str              ┆ str              ┆ str      │
+    #   # ╞══════════════════╪══════════════════╪══════════╡
+    #   # │ 01²              ┆ 01²              ┆ 012      │
+    #   # │ ＫＡＤＯＫＡＷＡ ┆ ＫＡＤＯＫＡＷＡ ┆ KADOKAWA │
+    #   # └──────────────────┴──────────────────┴──────────┘
+    #
+    # @example
+    #   new.select(Polars.all.str.len_bytes)
+    #   # =>
+    #   # shape: (2, 3)
+    #   # ┌──────┬─────┬──────┐
+    #   # │ text ┆ nfc ┆ nfkc │
+    #   # │ ---  ┆ --- ┆ ---  │
+    #   # │ u32  ┆ u32 ┆ u32  │
+    #   # ╞══════╪═════╪══════╡
+    #   # │ 4    ┆ 4   ┆ 3    │
+    #   # │ 24   ┆ 24  ┆ 8    │
+    #   # └──────┴─────┴──────┘
+    def normalize(form = "NFC")
+      Utils.wrap_expr(_rbexpr.str_normalize(form))
+    end
 
     # Transform to uppercase variant.
     #
@@ -433,7 +521,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"foo" => [" lead", "trail ", " both "]})
-    #   df.select(Polars.col("foo").str.strip)
+    #   df.select(Polars.col("foo").str.strip_chars)
     #   # =>
     #   # shape: (3, 1)
     #   # ┌───────┐
@@ -449,7 +537,6 @@ module Polars
       characters = Utils.parse_into_expression(characters, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_strip_chars(characters))
     end
-    alias_method :strip, :strip_chars
 
     # Remove leading whitespace.
     #
@@ -460,7 +547,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"foo" => [" lead", "trail ", " both "]})
-    #   df.select(Polars.col("foo").str.lstrip)
+    #   df.select(Polars.col("foo").str.strip_chars_start)
     #   # =>
     #   # shape: (3, 1)
     #   # ┌────────┐
@@ -476,7 +563,6 @@ module Polars
       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
 
     # Remove trailing whitespace.
     #
@@ -487,7 +573,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"foo" => [" lead", "trail ", " both "]})
-    #   df.select(Polars.col("foo").str.rstrip)
+    #   df.select(Polars.col("foo").str.strip_chars_end)
     #   # =>
     #   # shape: (3, 1)
     #   # ┌───────┐
@@ -503,7 +589,6 @@ module Polars
       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
 
     # Remove prefix.
     #
@@ -590,9 +675,9 @@ module Polars
     #   # │ null         ┆ null         │
     #   # └──────────────┴──────────────┘
     def pad_start(length, fill_char = " ")
+      length = Utils.parse_into_expression(length)
       Utils.wrap_expr(_rbexpr.str_pad_start(length, fill_char))
     end
-    alias_method :rjust, :pad_start
 
     # Pad the end of the string until it reaches the given length.
     #
@@ -620,9 +705,9 @@ module Polars
     #   # │ null         ┆ null         │
     #   # └──────────────┴──────────────┘
     def pad_end(length, fill_char = " ")
+      length = Utils.parse_into_expression(length)
       Utils.wrap_expr(_rbexpr.str_pad_end(length, fill_char))
     end
-    alias_method :ljust, :pad_end
 
     # Fills the string with zeroes.
     #
@@ -664,6 +749,9 @@ module Polars
     #   A valid regex pattern.
     # @param literal [Boolean]
     #   Treat pattern as a literal string.
+    # @param strict [Boolean]
+    #   Raise an error if the underlying pattern is not a valid regex,
+    #   otherwise mask out with a null value.
     #
     # @return [Expr]
     #
@@ -693,16 +781,78 @@ module Polars
       Utils.wrap_expr(_rbexpr.str_contains(pattern, literal, strict))
     end
 
+    # Return the bytes offset of the first substring matching a pattern.
+    #
+    # If the pattern is not found, returns nil.
+    #
+    # @param pattern [String]
+    #   A valid regular expression pattern, compatible with the [regex crate](https://docs.rs/regex/latest/regex/).
+    # @param literal [Boolean]
+    #   Treat `pattern` as a literal string, not as a regular expression.
+    # @param strict [Boolean]
+    #   Raise an error if the underlying pattern is not a valid regex,
+    #   otherwise mask out with a null value.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   To modify regular expression behaviour (such as case-sensitivity) with
+    #   flags, use the inline `(?iLmsuxU)` syntax.
+    #
+    # @example Find the index of the first substring matching a regex or literal pattern:
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "txt" => ["Crab", "Lobster", nil, "Crustacean"],
+    #       "pat" => ["a[bc]", "b.t", "[aeiuo]", "(?i)A[BC]"]
+    #     }
+    #   )
+    #   df.select(
+    #     Polars.col("txt"),
+    #     Polars.col("txt").str.find("a|e").alias("a|e (regex)"),
+    #     Polars.col("txt").str.find("e", literal: true).alias("e (lit)"),
+    #   )
+    #   # =>
+    #   # shape: (4, 3)
+    #   # ┌────────────┬─────────────┬─────────┐
+    #   # │ txt        ┆ a|e (regex) ┆ e (lit) │
+    #   # │ ---        ┆ ---         ┆ ---     │
+    #   # │ str        ┆ u32         ┆ u32     │
+    #   # ╞════════════╪═════════════╪═════════╡
+    #   # │ Crab       ┆ 2           ┆ null    │
+    #   # │ Lobster    ┆ 5           ┆ 5       │
+    #   # │ null       ┆ null        ┆ null    │
+    #   # │ Crustacean ┆ 5           ┆ 7       │
+    #   # └────────────┴─────────────┴─────────┘
+    #
+    # @example Match against a pattern found in another column or (expression):
+    #   df.with_columns(Polars.col("txt").str.find(Polars.col("pat")).alias("find_pat"))
+    #   # =>
+    #   # shape: (4, 3)
+    #   # ┌────────────┬───────────┬──────────┐
+    #   # │ txt        ┆ pat       ┆ find_pat │
+    #   # │ ---        ┆ ---       ┆ ---      │
+    #   # │ str        ┆ str       ┆ u32      │
+    #   # ╞════════════╪═══════════╪══════════╡
+    #   # │ Crab       ┆ a[bc]     ┆ 2        │
+    #   # │ Lobster    ┆ b.t       ┆ 2        │
+    #   # │ null       ┆ [aeiuo]   ┆ null     │
+    #   # │ Crustacean ┆ (?i)A[BC] ┆ 5        │
+    #   # └────────────┴───────────┴──────────┘
+    def find(pattern, literal: false, strict: true)
+      pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.str_find(pattern, literal, strict))
+    end
+
     # Check if string values end with a substring.
     #
-    # @param sub [String]
+    # @param suffix [String]
     #   Suffix substring.
     #
     # @return [Expr]
     #
     # @example
     #   df = Polars::DataFrame.new({"fruits" => ["apple", "mango", nil]})
-    #   df.with_column(
+    #   df.with_columns(
     #     Polars.col("fruits").str.ends_with("go").alias("has_suffix")
     #   )
     #   # =>
@@ -728,21 +878,21 @@ module Polars
     #   # ╞════════╡
     #   # │ mango  │
     #   # └────────┘
-    def ends_with(sub)
-      sub = Utils.parse_into_expression(sub, str_as_lit: true)
-      Utils.wrap_expr(_rbexpr.str_ends_with(sub))
+    def ends_with(suffix)
+      suffix_rbexpr = Utils.parse_into_expression(suffix, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.str_ends_with(suffix_rbexpr))
     end
 
     # Check if string values start with a substring.
     #
-    # @param sub [String]
+    # @param prefix [String]
     #   Prefix substring.
     #
     # @return [Expr]
     #
     # @example
     #   df = Polars::DataFrame.new({"fruits" => ["apple", "mango", nil]})
-    #   df.with_column(
+    #   df.with_columns(
     #     Polars.col("fruits").str.starts_with("app").alias("has_prefix")
     #   )
     #   # =>
@@ -768,9 +918,9 @@ module Polars
     #   # ╞════════╡
     #   # │ apple  │
     #   # └────────┘
-    def starts_with(sub)
-      sub = Utils.parse_into_expression(sub, str_as_lit: true)
-      Utils.wrap_expr(_rbexpr.str_starts_with(sub))
+    def starts_with(prefix)
+      prefix_rbexpr = Utils.parse_into_expression(prefix, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.str_starts_with(prefix_rbexpr))
     end
 
     # Parse string values as JSON.
@@ -778,8 +928,9 @@ module Polars
     # 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.
+    #   The dtype to cast the extracted value to.
+    # @param infer_schema_length [Integer]
+    #   Deprecated and ignored.
     #
     # @return [Expr]
     #
@@ -788,25 +939,27 @@ module Polars
     #     {"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_decode(dtype))
+    #   df.with_columns(decoded: Polars.col("json").str.json_decode(dtype))
     #   # =>
-    #   # shape: (3, 1)
-    #   # ┌───────────┐
-    #   # │ json      │
-    #   # │ ---       │
-    #   # │ struct[2] │
-    #   # ╞═══════════╡
-    #   # │ {1,true}  │
-    #   # │ null      │
-    #   # │ {2,false} │
-    #   # └───────────┘
-    def json_decode(dtype = nil, infer_schema_length: 100)
-      if !dtype.nil?
-        dtype = Utils.rb_type_to_dtype(dtype)
+    #   # shape: (3, 2)
+    #   # ┌─────────────────────┬───────────┐
+    #   # │ json                ┆ decoded   │
+    #   # │ ---                 ┆ ---       │
+    #   # │ str                 ┆ struct[2] │
+    #   # ╞═════════════════════╪═══════════╡
+    #   # │ {"a":1, "b": true}  ┆ {1,true}  │
+    #   # │ null                ┆ null      │
+    #   # │ {"a":2, "b": false} ┆ {2,false} │
+    #   # └─────────────────────┴───────────┘
+    def json_decode(dtype, infer_schema_length: nil)
+      if dtype.nil?
+        msg = "`Expr.str.json_decode` needs an explicitly given `dtype` otherwise Polars is not able to determine the output type. If you want to eagerly infer datatype you can use `Series.str.json_decode`."
+        raise TypeError, msg
       end
-      Utils.wrap_expr(_rbexpr.str_json_decode(dtype, infer_schema_length))
+
+      dtype_expr = Utils.parse_into_datatype_expr(dtype)._rbdatatype_expr
+      Utils.wrap_expr(_rbexpr.str_json_decode(dtype_expr))
     end
-    alias_method :json_extract, :json_decode
 
     # Extract the first match of json string with provided JSONPath expression.
     #
@@ -1036,6 +1189,8 @@ module Polars
     #
     # @param pattern [String]
     #   A valid regex pattern
+    # @param literal [Boolean]
+    #   Treat `pattern` as a literal string, not as a regular expression.
     #
     # @return [Expr]
     #
@@ -1043,7 +1198,7 @@ module Polars
     #   df = Polars::DataFrame.new({"foo" => ["123 bla 45 asd", "xyz 678 910t"]})
     #   df.select(
     #     [
-    #       Polars.col("foo").str.count_match('\d').alias("count_digits")
+    #       Polars.col("foo").str.count_matches('\d').alias("count_digits")
     #     ]
     #   )
     #   # =>
@@ -1060,7 +1215,6 @@ module Polars
       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
 
     # Split the string by a substring.
     #
@@ -1068,6 +1222,11 @@ module Polars
     #   Substring to split by.
     # @param inclusive [Boolean]
     #   If true, include the split character/string in the results.
+    # @param literal [Boolean]
+    #   Treat `by` as a literal string, not as a regular expression.
+    # @param strict [Boolean]
+    #   Raise an error if the underlying pattern is not a valid regex,
+    #   otherwise mask out with a null value.
     #
     # @return [Expr]
     #
@@ -1085,12 +1244,22 @@ module Polars
     #   # │ ["foo-bar"]           │
     #   # │ ["foo", "bar", "baz"] │
     #   # └───────────────────────┘
-    def split(by, inclusive: false)
-      by = Utils.parse_into_expression(by, str_as_lit: true)
+    def split(by, inclusive: false, literal: true, strict: true)
+      by_rbexpr = Utils.parse_into_expression(by, str_as_lit: true)
+
+      if !literal
+        if inclusive
+          return Utils.wrap_expr(
+            _rbexpr.str_split_regex_inclusive(by_rbexpr, strict)
+          )
+        end
+        return Utils.wrap_expr(_rbexpr.str_split_regex(by_rbexpr, strict))
+      end
+
       if inclusive
-        return Utils.wrap_expr(_rbexpr.str_split_inclusive(by))
+        return Utils.wrap_expr(_rbexpr.str_split_inclusive(by_rbexpr))
       end
-      Utils.wrap_expr(_rbexpr.str_split(by))
+      Utils.wrap_expr(_rbexpr.str_split(by_rbexpr))
     end
 
     # Split the string by a substring using `n` splits.
@@ -1177,12 +1346,14 @@ module Polars
     #   Replacement string.
     # @param literal [Boolean]
     #   Treat pattern as a literal string.
+    # @param n [Integer]
+    #   Number of matches to replace.
     #
     # @return [Expr]
     #
     # @example
     #   df = Polars::DataFrame.new({"id" => [1, 2], "text" => ["123abc", "abc456"]})
-    #   df.with_column(
+    #   df.with_columns(
     #     Polars.col("text").str.replace('abc\b', "ABC")
     #   )
     #   # =>
@@ -1214,7 +1385,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"id" => [1, 2], "text" => ["abcabc", "123a123"]})
-    #   df.with_column(Polars.col("text").str.replace_all("a", "-"))
+    #   df.with_columns(Polars.col("text").str.replace_all("a", "-"))
     #   # =>
     #   # shape: (2, 2)
     #   # ┌─────┬─────────┐
@@ -1265,7 +1436,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"s" => ["pear", nil, "papaya", "dragonfruit"]})
-    #   df.with_column(
+    #   df.with_columns(
     #     Polars.col("s").str.slice(-3).alias("s_sliced")
     #   )
     #   # =>
@@ -1286,6 +1457,130 @@ module Polars
       Utils.wrap_expr(_rbexpr.str_slice(offset, length))
     end
 
+    # Return the first n characters of each string in a String Series.
+    #
+    # @param n [Integer]
+    #   Length of the slice (integer or expression). Negative indexing is supported;
+    #   see note (2) below.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   1) The `n` input is defined in terms of the number of characters in the (UTF8)
+    #      string. A character is defined as a [Unicode scalar value](https://www.unicode.org/glossary/#unicode_scalar_value). A single
+    #      character is represented by a single byte when working with ASCII text, and a
+    #      maximum of 4 bytes otherwise.
+    #
+    #   2) When the `n` input is negative, `head` returns characters up to the `n`th
+    #      from the end of the string. For example, if `n = -3`, then all characters
+    #      except the last three are returned.
+    #
+    #   3) If the length of the string has fewer than `n` characters, the full string is
+    #      returned.
+    #
+    # @example Return up to the first 5 characters:
+    #   df = Polars::DataFrame.new({"s" => ["pear", nil, "papaya", "dragonfruit"]})
+    #   df.with_columns(Polars.col("s").str.head(5).alias("s_head_5"))
+    #   # =>
+    #   # shape: (4, 2)
+    #   # ┌─────────────┬──────────┐
+    #   # │ s           ┆ s_head_5 │
+    #   # │ ---         ┆ ---      │
+    #   # │ str         ┆ str      │
+    #   # ╞═════════════╪══════════╡
+    #   # │ pear        ┆ pear     │
+    #   # │ null        ┆ null     │
+    #   # │ papaya      ┆ papay    │
+    #   # │ dragonfruit ┆ drago    │
+    #   # └─────────────┴──────────┘
+    #
+    # @example Return characters determined by column `n`:
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "s" => ["pear", nil, "papaya", "dragonfruit"],
+    #       "n" => [3, 4, -2, -5]
+    #     }
+    #   )
+    #   df.with_columns(Polars.col("s").str.head("n").alias("s_head_n"))
+    #   # =>
+    #   # shape: (4, 3)
+    #   # ┌─────────────┬─────┬──────────┐
+    #   # │ s           ┆ n   ┆ s_head_n │
+    #   # │ ---         ┆ --- ┆ ---      │
+    #   # │ str         ┆ i64 ┆ str      │
+    #   # ╞═════════════╪═════╪══════════╡
+    #   # │ pear        ┆ 3   ┆ pea      │
+    #   # │ null        ┆ 4   ┆ null     │
+    #   # │ papaya      ┆ -2  ┆ papa     │
+    #   # │ dragonfruit ┆ -5  ┆ dragon   │
+    #   # └─────────────┴─────┴──────────┘
+    def head(n)
+      n = Utils.parse_into_expression(n)
+      Utils.wrap_expr(_rbexpr.str_head(n))
+    end
+
+    # Return the last n characters of each string in a String Series.
+    #
+    # @param n [Integer]
+    #   Length of the slice (integer or expression). Negative indexing is supported;
+    #   see note (2) below.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   1) The `n` input is defined in terms of the number of characters in the (UTF8)
+    #      string. A character is defined as a [Unicode scalar value](https://www.unicode.org/glossary/#unicode_scalar_value). A single
+    #      character is represented by a single byte when working with ASCII text, and a
+    #      maximum of 4 bytes otherwise.
+    #
+    #   2) When the `n` input is negative, `tail` returns characters starting from the
+    #      `n`th from the beginning of the string. For example, if `n = -3`, then all
+    #      characters except the first three are returned.
+    #
+    #   3) If the length of the string has fewer than `n` characters, the full string is
+    #      returned.
+    #
+    # @example Return up to the last 5 characters:
+    #   df = Polars::DataFrame.new({"s" => ["pear", nil, "papaya", "dragonfruit"]})
+    #   df.with_columns(Polars.col("s").str.tail(5).alias("s_tail_5"))
+    #   # =>
+    #   # shape: (4, 2)
+    #   # ┌─────────────┬──────────┐
+    #   # │ s           ┆ s_tail_5 │
+    #   # │ ---         ┆ ---      │
+    #   # │ str         ┆ str      │
+    #   # ╞═════════════╪══════════╡
+    #   # │ pear        ┆ pear     │
+    #   # │ null        ┆ null     │
+    #   # │ papaya      ┆ apaya    │
+    #   # │ dragonfruit ┆ fruit    │
+    #   # └─────────────┴──────────┘
+    #
+    # @example Return characters determined by column `n`:
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "s" => ["pear", nil, "papaya", "dragonfruit"],
+    #       "n" => [3, 4, -2, -5]
+    #     }
+    #   )
+    #   df.with_columns(Polars.col("s").str.tail("n").alias("s_tail_n"))
+    #   # =>
+    #   # shape: (4, 3)
+    #   # ┌─────────────┬─────┬──────────┐
+    #   # │ s           ┆ n   ┆ s_tail_n │
+    #   # │ ---         ┆ --- ┆ ---      │
+    #   # │ str         ┆ i64 ┆ str      │
+    #   # ╞═════════════╪═════╪══════════╡
+    #   # │ pear        ┆ 3   ┆ ear      │
+    #   # │ null        ┆ 4   ┆ null     │
+    #   # │ papaya      ┆ -2  ┆ paya     │
+    #   # │ dragonfruit ┆ -5  ┆ nfruit   │
+    #   # └─────────────┴─────┴──────────┘
+    def tail(n)
+      n = Utils.parse_into_expression(n)
+      Utils.wrap_expr(_rbexpr.str_tail(n))
+    end
+
     # Convert an Utf8 column into an Int64 column with base radix.
     #
     # @param base [Integer]
@@ -1328,41 +1623,9 @@ module Polars
     #   # │ cafe ┆ 51966  │
     #   # │ null ┆ null   │
     #   # └──────┴────────┘
-    def to_integer(base: 10, strict: true)
+    def to_integer(base: 10, dtype: Int64, strict: true)
       base = Utils.parse_into_expression(base, str_as_lit: false)
-      Utils.wrap_expr(_rbexpr.str_to_integer(base, strict))
-    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 │
-    #   # └──────┘
-    def parse_int(radix = 2, strict: true)
-      to_integer(base: 2, strict: strict).cast(Int32, strict: strict)
+      Utils.wrap_expr(_rbexpr.str_to_integer(base, dtype, strict))
     end
 
     # Use the aho-corasick algorithm to find matches.
@@ -1403,7 +1666,7 @@ module Polars
     #   # │ Can you feel the love tonight   ┆ true         │
     #   # └─────────────────────────────────┴──────────────┘
     def contains_any(patterns, ascii_case_insensitive: false)
-      patterns = Utils.parse_into_expression(patterns, str_as_lit: false, list_as_series: true)
+      patterns = Utils.parse_into_expression(patterns, str_as_lit: false)
       Utils.wrap_expr(
         _rbexpr.str_contains_any(patterns, ascii_case_insensitive)
       )
@@ -1411,15 +1674,19 @@ module Polars
 
     # Use the aho-corasick algorithm to replace many matches.
     #
-    # @param patterns [String]
+    # @param patterns [Object]
     #   String patterns to search and replace.
-    # @param replace_with [String]
+    # @param replace_with [Object]
     #   Strings to replace where a pattern was a match.
     #   This can be broadcasted. So it supports many:one and many:many.
     # @param ascii_case_insensitive [Boolean]
     #   Enable ASCII-aware case insensitive matching.
     #   When this option is enabled, searching will be performed without respect
     #   to case for ASCII letters (a-z and A-Z) only.
+    # @param leftmost [Boolean]
+    #   Guarantees in case there are overlapping matches that the leftmost match
+    #   is used. In case there are multiple candidates for the leftmost match
+    #   the pattern which comes first in patterns is used.
     #
     # @return [Expr]
     #
@@ -1437,7 +1704,7 @@ module Polars
     #     Polars.col("lyrics")
     #     .str.replace_many(
     #       ["me", "you", "they"],
-    #       ""
+    #       [""]
     #     )
     #     .alias("removes_pronouns")
     #   )
@@ -1473,22 +1740,209 @@ module Polars
     #   # │ Tell me what you want, what yo… ┆ Tell you what me want, what me… │
     #   # │ 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_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
-      )
+    def replace_many(
+      patterns,
+      replace_with = NO_DEFAULT,
+      ascii_case_insensitive: false,
+      leftmost: false
+    )
+      if replace_with == NO_DEFAULT
+        if !patterns.is_a?(Hash)
+          msg = "`replace_with` argument is required if `patterns` argument is not a Hash type"
+          raise TypeError, msg
+        end
+        # Early return in case of an empty mapping.
+        if patterns.empty?
+          return Utils.wrap_expr(_rbexpr)
+        end
+        replace_with = patterns.values
+        patterns = patterns.keys
+      end
+
+      patterns = Utils.parse_into_expression(patterns, str_as_lit: false)
+      replace_with = Utils.parse_into_expression(replace_with, str_as_lit: true)
       Utils.wrap_expr(
         _rbexpr.str_replace_many(
-          patterns, replace_with, ascii_case_insensitive
+          patterns, replace_with, ascii_case_insensitive, leftmost
         )
       )
     end
 
+    # Use the Aho-Corasick algorithm to extract many matches.
+    #
+    # @param patterns [Object]
+    #   String patterns to search.
+    # @param ascii_case_insensitive [Boolean]
+    #   Enable ASCII-aware case-insensitive matching.
+    #   When this option is enabled, searching will be performed without respect
+    #   to case for ASCII letters (a-z and A-Z) only.
+    # @param overlapping [Boolean]
+    #   Whether matches may overlap.
+    # @param leftmost [Boolean]
+    #   Guarantees in case there are overlapping matches that the leftmost match
+    #   is used. In case there are multiple candidates for the leftmost match
+    #   the pattern which comes first in patterns is used. May not be used
+    #   together with overlapping: true.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   This method supports matching on string literals only, and does not support
+    #   regular expression matching.
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"values" => ["discontent"]})
+    #   patterns = ["winter", "disco", "onte", "discontent"]
+    #   df.with_columns(
+    #     Polars.col("values")
+    #     .str.extract_many(patterns, overlapping: false)
+    #     .alias("matches"),
+    #     Polars.col("values")
+    #     .str.extract_many(patterns, overlapping: true)
+    #     .alias("matches_overlapping"),
+    #   )
+    #   # =>
+    #   # shape: (1, 3)
+    #   # ┌────────────┬───────────┬─────────────────────────────────┐
+    #   # │ values     ┆ matches   ┆ matches_overlapping             │
+    #   # │ ---        ┆ ---       ┆ ---                             │
+    #   # │ str        ┆ list[str] ┆ list[str]                       │
+    #   # ╞════════════╪═══════════╪═════════════════════════════════╡
+    #   # │ discontent ┆ ["disco"] ┆ ["disco", "onte", "discontent"… │
+    #   # └────────────┴───────────┴─────────────────────────────────┘
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "values" => ["discontent", "rhapsody"],
+    #       "patterns" => [
+    #         ["winter", "disco", "onte", "discontent"],
+    #         ["rhap", "ody", "coalesce"]
+    #       ]
+    #     }
+    #   )
+    #   df.select(Polars.col("values").str.extract_many("patterns"))
+    #   # =>
+    #   # shape: (2, 1)
+    #   # ┌─────────────────┐
+    #   # │ values          │
+    #   # │ ---             │
+    #   # │ list[str]       │
+    #   # ╞═════════════════╡
+    #   # │ ["disco"]       │
+    #   # │ ["rhap", "ody"] │
+    #   # └─────────────────┘
+    def extract_many(
+      patterns,
+      ascii_case_insensitive: false,
+      overlapping: false,
+      leftmost: false
+    )
+      if overlapping && leftmost
+        msg = "can not match overlapping patterns when leftmost == true"
+        raise ArgumentError, msg
+      end
+      patterns = Utils.parse_into_expression(patterns, str_as_lit: false)
+      Utils.wrap_expr(
+        _rbexpr.str_extract_many(patterns, ascii_case_insensitive, overlapping, leftmost)
+      )
+    end
+
+    # Use the Aho-Corasick algorithm to find many matches.
+    #
+    # The function will return the bytes offset of the start of each match.
+    # The return type will be `List<UInt32>`
+    #
+    # @param patterns [Object]
+    #   String patterns to search.
+    # @param ascii_case_insensitive [Boolean]
+    #   Enable ASCII-aware case-insensitive matching.
+    #   When this option is enabled, searching will be performed without respect
+    #   to case for ASCII letters (a-z and A-Z) only.
+    # @param overlapping [Boolean]
+    #   Whether matches may overlap.
+    # @param leftmost [Boolean]
+    #   Guarantees in case there are overlapping matches that the leftmost match
+    #   is used. In case there are multiple candidates for the leftmost match
+    #   the pattern which comes first in patterns is used. May not be used
+    #   together with overlapping: true.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   This method supports matching on string literals only, and does not support
+    #   regular expression matching.
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"values" => ["discontent"]})
+    #   patterns = ["winter", "disco", "onte", "discontent"]
+    #   df.with_columns(
+    #     Polars.col("values")
+    #     .str.extract_many(patterns, overlapping: false)
+    #     .alias("matches"),
+    #     Polars.col("values")
+    #     .str.extract_many(patterns, overlapping: true)
+    #     .alias("matches_overlapping"),
+    #   )
+    #   # =>
+    #   # shape: (1, 3)
+    #   # ┌────────────┬───────────┬─────────────────────────────────┐
+    #   # │ values     ┆ matches   ┆ matches_overlapping             │
+    #   # │ ---        ┆ ---       ┆ ---                             │
+    #   # │ str        ┆ list[str] ┆ list[str]                       │
+    #   # ╞════════════╪═══════════╪═════════════════════════════════╡
+    #   # │ discontent ┆ ["disco"] ┆ ["disco", "onte", "discontent"… │
+    #   # └────────────┴───────────┴─────────────────────────────────┘
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "values" => ["discontent", "rhapsody"],
+    #       "patterns" => [
+    #         ["winter", "disco", "onte", "discontent"],
+    #         ["rhap", "ody", "coalesce"]
+    #       ]
+    #     }
+    #   )
+    #   df.select(Polars.col("values").str.find_many("patterns"))
+    #   # =>
+    #   # shape: (2, 1)
+    #   # ┌───────────┐
+    #   # │ values    │
+    #   # │ ---       │
+    #   # │ list[u32] │
+    #   # ╞═══════════╡
+    #   # │ [0]       │
+    #   # │ [0, 5]    │
+    #   # └───────────┘
+    def find_many(
+      patterns,
+      ascii_case_insensitive: false,
+      overlapping: false,
+      leftmost: false
+    )
+      if overlapping && leftmost
+        msg = "can not match overlapping patterns when leftmost == true"
+        raise ArgumentError, msg
+      end
+      patterns = Utils.parse_into_expression(patterns, str_as_lit: false)
+      Utils.wrap_expr(
+        _rbexpr.str_find_many(patterns, ascii_case_insensitive, overlapping, leftmost)
+      )
+    end
+
     private
 
     def _validate_format_argument(format)
-      # TODO
+      if !format.nil? && format.include?(".%f")
+        message = (
+          "Detected the pattern `.%f` in the chrono format string." +
+          " This pattern should not be used to parse values after a decimal point." +
+          " Use `%.f` instead." +
+          " See the full specification: https://docs.rs/chrono/latest/chrono/format/strftime"
+        )
+        warn message
+      end
     end
   end
 end