Class: Polars::StringExpr

Inherits:
Object
  • Object
show all
Defined in:
lib/polars/string_expr.rb

Overview

Namespace for string related expressions.

Instance Method Summary collapse

Instance Method Details

#contains(pattern, literal: false, strict: true) ⇒ Expr

Check if string contains a substring that matches a regex.

Examples:

df = Polars::DataFrame.new({"a" => ["Crab", "cat and dog", "rab$bit", nil]})
df.select(
  [
    Polars.col("a"),
    Polars.col("a").str.contains("cat|bit").alias("regex"),
    Polars.col("a").str.contains("rab$", literal: true).alias("literal")
  ]
)
# =>
# shape: (4, 3)
# ┌─────────────┬───────┬─────────┐
# │ a           ┆ regex ┆ literal │
# │ ---         ┆ ---   ┆ ---     │
# │ str         ┆ bool  ┆ bool    │
# ╞═════════════╪═══════╪═════════╡
# │ Crab        ┆ false ┆ false   │
# │ cat and dog ┆ true  ┆ false   │
# │ rab$bit     ┆ true  ┆ true    │
# │ null        ┆ null  ┆ null    │
# └─────────────┴───────┴─────────┘

Parameters:

  • pattern (String) —

    A valid regex pattern.

  • literal (Boolean) (defaults to: false) —

    Treat pattern as a literal string.

Returns:



692
693
694
695
 
# File 'lib/polars/string_expr.rb', line 692

def contains(pattern, literal: false, strict: true)
  pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.str_contains(pattern, literal, strict))
end

#contains_any(patterns, ascii_case_insensitive: false) ⇒ Expr

Use the aho-corasick algorithm to find matches.

This version determines if any of the patterns find a match.

Examples:

df = Polars::DataFrame.new(
  {
    "lyrics": [
      "Everybody wants to rule the world",
      "Tell me what you want, what you really really want",
      "Can you feel the love tonight"
    ]
  }
)
df.with_columns(
  Polars.col("lyrics").str.contains_any(["you", "me"]).alias("contains_any")
)
# =>
# shape: (3, 2)
# ┌─────────────────────────────────┬──────────────┐
# │ lyrics                          ┆ contains_any │
# │ ---                             ┆ ---          │
# │ str                             ┆ bool         │
# ╞═════════════════════════════════╪══════════════╡
# │ Everybody wants to rule the wo… ┆ false        │
# │ Tell me what you want, what yo… ┆ true         │
# │ Can you feel the love tonight   ┆ true         │
# └─────────────────────────────────┴──────────────┘

Parameters:

  • patterns (String) —

    String patterns to search.

  • ascii_case_insensitive (Boolean) (defaults to: false) —

    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.

Returns:



1406
1407
1408
1409
1410
1411
 
# File 'lib/polars/string_expr.rb', line 1406

def contains_any(patterns, ascii_case_insensitive: 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)
  )
end

#count_matches(pattern, literal: false) ⇒ Expr Also known as: count_match

Count all successive non-overlapping regex matches.

Examples:

df = Polars::DataFrame.new({"foo" => ["123 bla 45 asd", "xyz 678 910t"]})
df.select(
  [
    Polars.col("foo").str.count_match('\d').alias("count_digits")
  ]
)
# =>
# shape: (2, 1)
# ┌──────────────┐
# │ count_digits │
# │ ---          │
# │ u32          │
# ╞══════════════╡
# │ 5            │
# │ 6            │
# └──────────────┘

Parameters:

  • pattern (String) —

    A valid regex pattern

Returns:



1060
1061
1062
1063
 
# File 'lib/polars/string_expr.rb', line 1060

def count_matches(pattern, literal: false)
  pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.str_count_matches(pattern, literal))
end

#decode(encoding, strict: true) ⇒ Expr

Decode a value using the provided encoding.

Examples:

df = Polars::DataFrame.new({"encoded" => ["666f6f", "626172", nil]})
df.select(Polars.col("encoded").str.decode("hex"))
# =>
# shape: (3, 1)
# ┌─────────┐
# │ encoded │
# │ ---     │
# │ binary  │
# ╞═════════╡
# │ b"foo"  │
# │ b"bar"  │
# │ null    │
# └─────────┘

Parameters:

  • encoding ("hex", "base64") —

    The encoding to use.

  • strict (Boolean) (defaults to: true) —

    How to handle invalid inputs:

    • true: An error will be thrown if unable to decode a value.
    • false: Unhandled values will be replaced with nil.

Returns:



874
875
876
877
878
879
880
881
882
 
# File 'lib/polars/string_expr.rb', line 874

def decode(encoding, strict: true)
  if encoding == "hex"
    Utils.wrap_expr(_rbexpr.str_hex_decode(strict))
  elsif encoding == "base64"
    Utils.wrap_expr(_rbexpr.str_base64_decode(strict))
  else
    raise ArgumentError, "encoding must be one of {{'hex', 'base64'}}, got #{encoding}"
  end
end

#encode(encoding) ⇒ Expr

Encode a value using the provided encoding.

Examples:

df = Polars::DataFrame.new({"strings" => ["foo", "bar", nil]})
df.select(Polars.col("strings").str.encode("hex"))
# =>
# shape: (3, 1)
# ┌─────────┐
# │ strings │
# │ ---     │
# │ str     │
# ╞═════════╡
# │ 666f6f  │
# │ 626172  │
# │ null    │
# └─────────┘

Parameters:

  • encoding ("hex", "base64") —

    The encoding to use.

Returns:



905
906
907
908
909
910
911
912
913
 
# File 'lib/polars/string_expr.rb', line 905

def encode(encoding)
  if encoding == "hex"
    Utils.wrap_expr(_rbexpr.str_hex_encode)
  elsif encoding == "base64"
    Utils.wrap_expr(_rbexpr.str_base64_encode)
  else
    raise ArgumentError, "encoding must be one of {{'hex', 'base64'}}, got #{encoding}"
  end
end

#ends_with(sub) ⇒ Expr

Check if string values end with a substring.

Examples:

df = Polars::DataFrame.new({"fruits" => ["apple", "mango", nil]})
df.with_column(
  Polars.col("fruits").str.ends_with("go").alias("has_suffix")
)
# =>
# shape: (3, 2)
# ┌────────┬────────────┐
# │ fruits ┆ has_suffix │
# │ ---    ┆ ---        │
# │ str    ┆ bool       │
# ╞════════╪════════════╡
# │ apple  ┆ false      │
# │ mango  ┆ true       │
# │ null   ┆ null       │
# └────────┴────────────┘

Using ends_with as a filter condition:

df.filter(Polars.col("fruits").str.ends_with("go"))
# =>
# shape: (1, 1)
# ┌────────┐
# │ fruits │
# │ ---    │
# │ str    │
# ╞════════╡
# │ mango  │
# └────────┘

Parameters:

  • sub (String) —

    Suffix substring.

Returns:



732
733
734
735
 
# File 'lib/polars/string_expr.rb', line 732

def ends_with(sub)
  sub = Utils.parse_into_expression(sub, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.str_ends_with(sub))
end

#extract(pattern, group_index: 1) ⇒ Expr

Extract the target capture group from provided patterns.

Examples:

df = Polars::DataFrame.new({"foo" => ["123 bla 45 asd", "xyz 678 910t"]})
df.select(
  [
    Polars.col("foo").str.extract('(\d+)')
  ]
)
# =>
# shape: (2, 1)
# ┌─────┐
# │ foo │
# │ --- │
# │ str │
# ╞═════╡
# │ 123 │
# │ 678 │
# └─────┘

Parameters:

  • pattern (String) —

    A valid regex pattern

  • group_index (Integer) (defaults to: 1) —

    Index of the targeted capture group. Group 0 mean the whole pattern, first group begin at index 1 Default to the first capture group

Returns:



943
944
945
946
 
# File 'lib/polars/string_expr.rb', line 943

def extract(pattern, group_index: 1)
  pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.str_extract(pattern, group_index))
end

#extract_all(pattern) ⇒ Expr

Extracts all matches for the given regex pattern.

Extracts each successive non-overlapping regex match in an individual string as an array.

Examples:

df = Polars::DataFrame.new({"foo" => ["123 bla 45 asd", "xyz 678 910t"]})
df.select(
  [
    Polars.col("foo").str.extract_all('(\d+)').alias("extracted_nrs")
  ]
)
# =>
# shape: (2, 1)
# ┌────────────────┐
# │ extracted_nrs  │
# │ ---            │
# │ list[str]      │
# ╞════════════════╡
# │ ["123", "45"]  │
# │ ["678", "910"] │
# └────────────────┘

Parameters:

  • pattern (String) —

    A valid regex pattern

Returns:



975
976
977
978
 
# File 'lib/polars/string_expr.rb', line 975

def extract_all(pattern)
  pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.str_extract_all(pattern))
end

#extract_groups(pattern) ⇒ Expr

Extract all capture groups for the given regex pattern.

Examples:

df = Polars::DataFrame.new(
  {
    "url": [
      "http://vote.com/ballon_dor?candidate=messi&ref=python",
      "http://vote.com/ballon_dor?candidate=weghorst&ref=polars",
      "http://vote.com/ballon_dor?error=404&ref=rust"
    ]
  }
)
pattern = /candidate=(?<candidate>\w+)&ref=(?<ref>\w+)/.to_s
df.select(captures: Polars.col("url").str.extract_groups(pattern)).unnest(
  "captures"
)
# =>
# shape: (3, 2)
# ┌───────────┬────────┐
# │ candidate ┆ ref    │
# │ ---       ┆ ---    │
# │ str       ┆ str    │
# ╞═══════════╪════════╡
# │ messi     ┆ python │
# │ weghorst  ┆ polars │
# │ null      ┆ null   │
# └───────────┴────────┘

Unnamed groups have their numerical position converted to a string:

pattern = /candidate=(\w+)&ref=(\w+)/.to_s
(
  df.with_columns(
    captures: Polars.col("url").str.extract_groups(pattern)
  ).with_columns(name: Polars.col("captures").struct["1"].str.to_uppercase)
)
# =>
# shape: (3, 3)
# ┌─────────────────────────────────┬───────────────────────┬──────────┐
# │ url                             ┆ captures              ┆ name     │
# │ ---                             ┆ ---                   ┆ ---      │
# │ str                             ┆ struct[2]             ┆ str      │
# ╞═════════════════════════════════╪═══════════════════════╪══════════╡
# │ http://vote.com/ballon_dor?can… ┆ {"messi","python"}    ┆ MESSI    │
# │ http://vote.com/ballon_dor?can… ┆ {"weghorst","polars"} ┆ WEGHORST │
# │ http://vote.com/ballon_dor?err… ┆ {null,null}           ┆ null     │
# └─────────────────────────────────┴───────────────────────┴──────────┘

Parameters:

  • pattern (String) —

    A valid regular expression pattern containing at least one capture group, compatible with the regex crate.

Returns:



1032
1033
1034
 
# File 'lib/polars/string_expr.rb', line 1032

def extract_groups(pattern)
  Utils.wrap_expr(_rbexpr.str_extract_groups(pattern))
end

#join(delimiter = "-", ignore_nulls: true) ⇒ Expr Also known as: concat

Vertically concat the values in the Series to a single string value.

Examples:

df = Polars::DataFrame.new({"foo" => [1, nil, 2]})
df.select(Polars.col("foo").str.join("-"))
# =>
# shape: (1, 1)
# ┌─────┐
# │ foo │
# │ --- │
# │ str │
# ╞═════╡
# │ 1-2 │
# └─────┘
df = Polars::DataFrame.new({"foo" => [1, nil, 2]})
df.select(Polars.col("foo").str.join("-", ignore_nulls: false))
# =>
# shape: (1, 1)
# ┌──────┐
# │ foo  │
# │ ---  │
# │ str  │
# ╞══════╡
# │ null │
# └──────┘

Parameters:

  • delimiter (String) (defaults to: "-") —

    The delimiter to insert between consecutive string values.

  • ignore_nulls (Boolean) (defaults to: true) —

    Ignore null values (default).

Returns:



357
358
359
 
# File 'lib/polars/string_expr.rb', line 357

def join(delimiter = "-", ignore_nulls: true)
  Utils.wrap_expr(_rbexpr.str_join(delimiter, ignore_nulls))
end

#json_decode(dtype = nil, infer_schema_length: 100) ⇒ Expr Also known as: json_extract

Parse string values as JSON.

Throw errors if encounter invalid JSON strings.

Examples:

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_decode(dtype))
# =>
# shape: (3, 1)
# ┌─────────────┐
# │ json        │
# │ ---         │
# │ struct[2]   │
# ╞═════════════╡
# │ {1,true}    │
# │ {null,null} │
# │ {2,false}   │
# └─────────────┘

Parameters:

  • dtype (Object) (defaults to: nil) —

    The dtype to cast the extracted value to. If nil, the dtype will be inferred from the JSON value.

Returns:



804
805
806
807
808
809
 
# File 'lib/polars/string_expr.rb', line 804

def json_decode(dtype = nil, infer_schema_length: 100)
  if !dtype.nil?
    dtype = Utils.rb_type_to_dtype(dtype)
  end
  Utils.wrap_expr(_rbexpr.str_json_decode(dtype, infer_schema_length))
end

#json_path_match(json_path) ⇒ Expr

Extract the first match of json string with provided JSONPath expression.

Throw errors if encounter invalid json strings. All return value will be casted to Utf8 regardless of the original value.

Documentation on JSONPath standard can be found here.

Examples:

df = Polars::DataFrame.new(
  {"json_val" => ['{"a":"1"}', nil, '{"a":2}', '{"a":2.1}', '{"a":true}']}
)
df.select(Polars.col("json_val").str.json_path_match("$.a"))
# =>
# shape: (5, 1)
# ┌──────────┐
# │ json_val │
# │ ---      │
# │ str      │
# ╞══════════╡
# │ 1        │
# │ null     │
# │ 2        │
# │ 2.1      │
# │ true     │
# └──────────┘

Parameters:

  • json_path (String) —

    A valid JSON path query string.

Returns:



843
844
845
846
 
# File 'lib/polars/string_expr.rb', line 843

def json_path_match(json_path)
  json_path = Utils.parse_into_expression(json_path, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.str_json_path_match(json_path))
end

#len_bytes ⇒ Expr Also known as: lengths

Note:

The returned lengths are equal to the number of bytes in the UTF8 string. If you need the length in terms of the number of characters, use n_chars instead.

Get length of the strings as :u32 (as number of bytes).

Examples:

df = Polars::DataFrame.new({"s" => ["Café", nil, "345", "東京"]}).with_columns(
  [
    Polars.col("s").str.len_bytes.alias("length"),
    Polars.col("s").str.len_chars.alias("nchars")
  ]
)
df
# =>
# shape: (4, 3)
# ┌──────┬────────┬────────┐
# │ s    ┆ length ┆ nchars │
# │ ---  ┆ ---    ┆ ---    │
# │ str  ┆ u32    ┆ u32    │
# ╞══════╪════════╪════════╡
# │ Café ┆ 5      ┆ 4      │
# │ null ┆ null   ┆ null   │
# │ 345  ┆ 3      ┆ 3      │
# │ 東京 ┆ 6      ┆ 2      │
# └──────┴────────┴────────┘

Returns:



285
286
287
 
# File 'lib/polars/string_expr.rb', line 285

def len_bytes
  Utils.wrap_expr(_rbexpr.str_len_bytes)
end

#len_chars ⇒ Expr Also known as: n_chars

Note:

If you know that you are working with ASCII text, lengths will be equivalent, and faster (returns length in terms of the number of bytes).

Get length of the strings as :u32 (as number of chars).

Examples:

df = Polars::DataFrame.new({"s" => ["Café", nil, "345", "東京"]}).with_columns(
  [
    Polars.col("s").str.len_bytes.alias("length"),
    Polars.col("s").str.len_chars.alias("nchars")
  ]
)
df
# =>
# shape: (4, 3)
# ┌──────┬────────┬────────┐
# │ s    ┆ length ┆ nchars │
# │ ---  ┆ ---    ┆ ---    │
# │ str  ┆ u32    ┆ u32    │
# ╞══════╪════════╪════════╡
# │ Café ┆ 5      ┆ 4      │
# │ null ┆ null   ┆ null   │
# │ 345  ┆ 3      ┆ 3      │
# │ 東京 ┆ 6      ┆ 2      │
# └──────┴────────┴────────┘

Returns:



318
319
320
 
# File 'lib/polars/string_expr.rb', line 318

def len_chars
  Utils.wrap_expr(_rbexpr.str_len_chars)
end

#pad_end(length, fill_char = " ") ⇒ Expr Also known as: ljust

Pad the end of the string until it reaches the given length.

Examples:

df = Polars::DataFrame.new({"a": ["cow", "monkey", "hippopotamus", nil]})
df.with_columns(padded: Polars.col("a").str.pad_end(8, "*"))
# =>
# shape: (4, 2)
# ┌──────────────┬──────────────┐
# │ a            ┆ padded       │
# │ ---          ┆ ---          │
# │ str          ┆ str          │
# ╞══════════════╪══════════════╡
# │ cow          ┆ cow*****     │
# │ monkey       ┆ monkey**     │
# │ hippopotamus ┆ hippopotamus │
# │ null         ┆ null         │
# └──────────────┴──────────────┘

Parameters:

  • length (Integer) —

    Pad the string until it reaches this length. Strings with length equal to or greater than this value are returned as-is.

  • fill_char (String) (defaults to: " ") —

    The character to pad the string with.

Returns:



623
624
625
 
# File 'lib/polars/string_expr.rb', line 623

def pad_end(length, fill_char = " ")
  Utils.wrap_expr(_rbexpr.str_pad_end(length, fill_char))
end

#pad_start(length, fill_char = " ") ⇒ Expr Also known as: rjust

Pad the start of the string until it reaches the given length.

Examples:

df = Polars::DataFrame.new({"a": ["cow", "monkey", "hippopotamus", nil]})
df.with_columns(padded: Polars.col("a").str.pad_start(8, "*"))
# =>
# shape: (4, 2)
# ┌──────────────┬──────────────┐
# │ a            ┆ padded       │
# │ ---          ┆ ---          │
# │ str          ┆ str          │
# ╞══════════════╪══════════════╡
# │ cow          ┆ *****cow     │
# │ monkey       ┆ **monkey     │
# │ hippopotamus ┆ hippopotamus │
# │ null         ┆ null         │
# └──────────────┴──────────────┘

Parameters:

  • length (Integer) —

    Pad the string until it reaches this length. Strings with length equal to or greater than this value are returned as-is.

  • fill_char (String) (defaults to: " ") —

    The character to pad the string with.

Returns:



593
594
595
 
# File 'lib/polars/string_expr.rb', line 593

def pad_start(length, fill_char = " ")
  Utils.wrap_expr(_rbexpr.str_pad_start(length, fill_char))
end

#parse_int(radix = 2, strict: true) ⇒ Expr

Parse integers with base radix from strings.

By default base 2. ParseError/Overflows become Nulls.

Examples:

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 │
# └──────┘

Parameters:

  • radix (Integer) (defaults to: 2) —

    Positive integer which is the base of the string we are parsing. Default: 2.

  • strict (Boolean) (defaults to: true) —

    Bool, Default=true will raise any ParseError or overflow as ComputeError. False silently convert to Null.

Returns:



1365
1366
1367
 
# File 'lib/polars/string_expr.rb', line 1365

def parse_int(radix = 2, strict: true)
  to_integer(base: 2, strict: strict).cast(Int32, strict: strict)
end

#replace(pattern, value, literal: false, n: 1) ⇒ Expr

Replace first matching regex/literal substring with a new string value.

Examples:

df = Polars::DataFrame.new({"id" => [1, 2], "text" => ["123abc", "abc456"]})
df.with_column(
  Polars.col("text").str.replace('abc\b', "ABC")
)
# =>
# shape: (2, 2)
# ┌─────┬────────┐
# │ id  ┆ text   │
# │ --- ┆ ---    │
# │ i64 ┆ str    │
# ╞═════╪════════╡
# │ 1   ┆ 123ABC │
# │ 2   ┆ abc456 │
# └─────┴────────┘

Parameters:

  • pattern (String) —

    Regex pattern.

  • value (String) —

    Replacement string.

  • literal (Boolean) (defaults to: false) —

    Treat pattern as a literal string.

Returns:



1199
1200
1201
1202
1203
 
# File 'lib/polars/string_expr.rb', line 1199

def replace(pattern, value, literal: false, n: 1)
  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(pattern, value, literal: false) ⇒ Expr

Replace all matching regex/literal substrings with a new string value.

Examples:

df = Polars::DataFrame.new({"id" => [1, 2], "text" => ["abcabc", "123a123"]})
df.with_column(Polars.col("text").str.replace_all("a", "-"))
# =>
# shape: (2, 2)
# ┌─────┬─────────┐
# │ id  ┆ text    │
# │ --- ┆ ---     │
# │ i64 ┆ str     │
# ╞═════╪═════════╡
# │ 1   ┆ -bc-bc  │
# │ 2   ┆ 123-123 │
# └─────┴─────────┘

Parameters:

  • pattern (String) —

    Regex pattern.

  • value (String) —

    Replacement string.

  • literal (Boolean) (defaults to: false) —

    Treat pattern as a literal string.

Returns:



1229
1230
1231
1232
1233
 
# File 'lib/polars/string_expr.rb', line 1229

def replace_all(pattern, value, literal: false)
  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

#replace_many(patterns, replace_with, ascii_case_insensitive: false) ⇒ Expr

Use the aho-corasick algorithm to replace many matches.

Examples:

df = Polars::DataFrame.new(
  {
    "lyrics": [
      "Everybody wants to rule the world",
      "Tell me what you want, what you really really want",
      "Can you feel the love tonight"
    ]
  }
)
df.with_columns(
  Polars.col("lyrics")
  .str.replace_many(
    ["me", "you", "they"],
    ""
  )
  .alias("removes_pronouns")
)
# =>
# shape: (3, 2)
# ┌─────────────────────────────────┬─────────────────────────────────┐
# │ lyrics                          ┆ removes_pronouns                │
# │ ---                             ┆ ---                             │
# │ str                             ┆ str                             │
# ╞═════════════════════════════════╪═════════════════════════════════╡
# │ Everybody wants to rule the wo… ┆ Everybody wants to rule the wo… │
# │ Tell me what you want, what yo… ┆ Tell  what  want, what  really… │
# │ Can you feel the love tonight   ┆ Can  feel the love tonight      │
# └─────────────────────────────────┴─────────────────────────────────┘
df.with_columns(
  Polars.col("lyrics")
  .str.replace_many(
    ["me", "you"],
    ["you", "me"]
  )
  .alias("confusing")
)
# =>
# shape: (3, 2)
# ┌─────────────────────────────────┬─────────────────────────────────┐
# │ lyrics                          ┆ confusing                       │
# │ ---                             ┆ ---                             │
# │ str                             ┆ str                             │
# ╞═════════════════════════════════╪═════════════════════════════════╡
# │ Everybody wants to rule the wo… ┆ Everybody wants to rule the wo… │
# │ 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    │
# └─────────────────────────────────┴─────────────────────────────────┘

Parameters:

  • patterns (String) —

    String patterns to search and replace.

  • replace_with (String) —

    Strings to replace where a pattern was a match. This can be broadcasted. So it supports many:one and many:many.

  • ascii_case_insensitive (Boolean) (defaults to: false) —

    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.

Returns:



1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
 
# File 'lib/polars/string_expr.rb', line 1477

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
  )
  Utils.wrap_expr(
    _rbexpr.str_replace_many(
      patterns, replace_with, ascii_case_insensitive
    )
  )
end

#reverse ⇒ Expr

Returns string values in reversed order.

Examples:

df = Polars::DataFrame.new({"text" => ["foo", "bar", "man\u0303ana"]})
df.with_columns(Polars.col("text").str.reverse.alias("reversed"))
# =>
# shape: (3, 2)
# ┌────────┬──────────┐
# │ text   ┆ reversed │
# │ ---    ┆ ---      │
# │ str    ┆ str      │
# ╞════════╪══════════╡
# │ foo    ┆ oof      │
# │ bar    ┆ rab      │
# │ mañana ┆ anañam   │
# └────────┴──────────┘

Returns:



1253
1254
1255
 
# File 'lib/polars/string_expr.rb', line 1253

def reverse
  Utils.wrap_expr(_rbexpr.str_reverse)
end

#slice(offset, length = nil) ⇒ Expr

Create subslices of the string values of a Utf8 Series.

Examples:

df = Polars::DataFrame.new({"s" => ["pear", nil, "papaya", "dragonfruit"]})
df.with_column(
  Polars.col("s").str.slice(-3).alias("s_sliced")
)
# =>
# shape: (4, 2)
# ┌─────────────┬──────────┐
# │ s           ┆ s_sliced │
# │ ---         ┆ ---      │
# │ str         ┆ str      │
# ╞═════════════╪══════════╡
# │ pear        ┆ ear      │
# │ null        ┆ null     │
# │ papaya      ┆ aya      │
# │ dragonfruit ┆ uit      │
# └─────────────┴──────────┘

Parameters:

  • offset (Integer) —

    Start index. Negative indexing is supported.

  • length (Integer) (defaults to: nil) —

    Length of the slice. If set to nil (default), the slice is taken to the end of the string.

Returns:



1284
1285
1286
1287
1288
 
# File 'lib/polars/string_expr.rb', line 1284

def slice(offset, length = nil)
  offset = Utils.parse_into_expression(offset)
  length = Utils.parse_into_expression(length)
  Utils.wrap_expr(_rbexpr.str_slice(offset, length))
end

#split(by, inclusive: false) ⇒ Expr

Split the string by a substring.

Examples:

df = Polars::DataFrame.new({"s" => ["foo bar", "foo-bar", "foo bar baz"]})
df.select(Polars.col("s").str.split(" "))
# =>
# shape: (3, 1)
# ┌───────────────────────┐
# │ s                     │
# │ ---                   │
# │ list[str]             │
# ╞═══════════════════════╡
# │ ["foo", "bar"]        │
# │ ["foo-bar"]           │
# │ ["foo", "bar", "baz"] │
# └───────────────────────┘

Parameters:

  • by (String) —

    Substring to split by.

  • inclusive (Boolean) (defaults to: false) —

    If true, include the split character/string in the results.

Returns:



1089
1090
1091
1092
1093
1094
1095
 
# File 'lib/polars/string_expr.rb', line 1089

def split(by, inclusive: false)
  by = Utils.parse_into_expression(by, str_as_lit: true)
  if inclusive
    return Utils.wrap_expr(_rbexpr.str_split_inclusive(by))
  end
  Utils.wrap_expr(_rbexpr.str_split(by))
end

#split_exact(by, n, inclusive: false) ⇒ Expr

Split the string by a substring using n splits.

Results in a struct of n+1 fields.

If it cannot make n splits, the remaining field elements will be null.

Examples:

df = Polars::DataFrame.new({"x" => ["a_1", nil, "c", "d_4"]})
df.select(
  [
    Polars.col("x").str.split_exact("_", 1).alias("fields")
  ]
)
# =>
# shape: (4, 1)
# ┌─────────────┐
# │ fields      │
# │ ---         │
# │ struct[2]   │
# ╞═════════════╡
# │ {"a","1"}   │
# │ {null,null} │
# │ {"c",null}  │
# │ {"d","4"}   │
# └─────────────┘

Parameters:

  • by (String) —

    Substring to split by.

  • n (Integer) —

    Number of splits to make.

  • inclusive (Boolean) (defaults to: false) —

    If true, include the split character/string in the results.

Returns:



1131
1132
1133
1134
1135
1136
1137
1138
 
# File 'lib/polars/string_expr.rb', line 1131

def split_exact(by, n, inclusive: false)
  by = Utils.parse_into_expression(by, str_as_lit: true)
  if inclusive
    Utils.wrap_expr(_rbexpr.str_split_exact_inclusive(by, n))
  else
    Utils.wrap_expr(_rbexpr.str_split_exact(by, n))
  end
end

#splitn(by, n) ⇒ Expr

Split the string by a substring, restricted to returning at most n items.

If the number of possible splits is less than n-1, the remaining field elements will be null. If the number of possible splits is n-1 or greater, the last (nth) substring will contain the remainder of the string.

Examples:

df = Polars::DataFrame.new({"s" => ["foo bar", nil, "foo-bar", "foo bar baz"]})
df.select(Polars.col("s").str.splitn(" ", 2).alias("fields"))
# =>
# shape: (4, 1)
# ┌───────────────────┐
# │ fields            │
# │ ---               │
# │ struct[2]         │
# ╞═══════════════════╡
# │ {"foo","bar"}     │
# │ {null,null}       │
# │ {"foo-bar",null}  │
# │ {"foo","bar baz"} │
# └───────────────────┘

Parameters:

  • by (String) —

    Substring to split by.

  • n (Integer) —

    Max number of items to return.

Returns:



1168
1169
1170
1171
 
# File 'lib/polars/string_expr.rb', line 1168

def splitn(by, n)
  by = Utils.parse_into_expression(by, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.str_splitn(by, n))
end

#starts_with(sub) ⇒ Expr

Check if string values start with a substring.

Examples:

df = Polars::DataFrame.new({"fruits" => ["apple", "mango", nil]})
df.with_column(
  Polars.col("fruits").str.starts_with("app").alias("has_prefix")
)
# =>
# shape: (3, 2)
# ┌────────┬────────────┐
# │ fruits ┆ has_prefix │
# │ ---    ┆ ---        │
# │ str    ┆ bool       │
# ╞════════╪════════════╡
# │ apple  ┆ true       │
# │ mango  ┆ false      │
# │ null   ┆ null       │
# └────────┴────────────┘

Using starts_with as a filter condition:

df.filter(Polars.col("fruits").str.starts_with("app"))
# =>
# shape: (1, 1)
# ┌────────┐
# │ fruits │
# │ ---    │
# │ str    │
# ╞════════╡
# │ apple  │
# └────────┘

Parameters:

  • sub (String) —

    Prefix substring.

Returns:



772
773
774
775
 
# File 'lib/polars/string_expr.rb', line 772

def starts_with(sub)
  sub = Utils.parse_into_expression(sub, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.str_starts_with(sub))
end

#strip_chars(characters = nil) ⇒ Expr Also known as: strip

Remove leading and trailing whitespace.

Examples:

df = Polars::DataFrame.new({"foo" => [" lead", "trail ", " both "]})
df.select(Polars.col("foo").str.strip)
# =>
# shape: (3, 1)
# ┌───────┐
# │ foo   │
# │ ---   │
# │ str   │
# ╞═══════╡
# │ lead  │
# │ trail │
# │ both  │
# └───────┘

Parameters:

  • characters (String, nil) (defaults to: nil) —

    An optional single character that should be trimmed.

Returns:



449
450
451
452
 
# File 'lib/polars/string_expr.rb', line 449

def strip_chars(characters = nil)
  characters = Utils.parse_into_expression(characters, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.str_strip_chars(characters))
end

#strip_chars_end(characters = nil) ⇒ Expr Also known as: rstrip

Remove trailing whitespace.

Examples:

df = Polars::DataFrame.new({"foo" => [" lead", "trail ", " both "]})
df.select(Polars.col("foo").str.rstrip)
# =>
# shape: (3, 1)
# ┌───────┐
# │ foo   │
# │ ---   │
# │ str   │
# ╞═══════╡
# │  lead │
# │ trail │
# │  both │
# └───────┘

Parameters:

  • characters (String, nil) (defaults to: nil) —

    An optional single character that should be trimmed.

Returns:



503
504
505
506
 
# File 'lib/polars/string_expr.rb', line 503

def strip_chars_end(characters = nil)
  characters = Utils.parse_into_expression(characters, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.str_strip_chars_end(characters))
end

#strip_chars_start(characters = nil) ⇒ Expr Also known as: lstrip

Remove leading whitespace.

Examples:

df = Polars::DataFrame.new({"foo" => [" lead", "trail ", " both "]})
df.select(Polars.col("foo").str.lstrip)
# =>
# shape: (3, 1)
# ┌────────┐
# │ foo    │
# │ ---    │
# │ str    │
# ╞════════╡
# │ lead   │
# │ trail  │
# │ both   │
# └────────┘

Parameters:

  • characters (String, nil) (defaults to: nil) —

    An optional single character that should be trimmed.

Returns:



476
477
478
479
 
# File 'lib/polars/string_expr.rb', line 476

def strip_chars_start(characters = nil)
  characters = Utils.parse_into_expression(characters, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.str_strip_chars_start(characters))
end

#strip_prefix(prefix) ⇒ Expr

Remove prefix.

The prefix will be removed from the string exactly once, if found.

Examples:

df = Polars::DataFrame.new({"a" => ["foobar", "foofoobar", "foo", "bar"]})
df.with_columns(Polars.col("a").str.strip_prefix("foo").alias("stripped"))
# =>
# shape: (4, 2)
# ┌───────────┬──────────┐
# │ a         ┆ stripped │
# │ ---       ┆ ---      │
# │ str       ┆ str      │
# ╞═══════════╪══════════╡
# │ foobar    ┆ bar      │
# │ foofoobar ┆ foobar   │
# │ foo       ┆          │
# │ bar       ┆ bar      │
# └───────────┴──────────┘

Parameters:

  • prefix (String) —

    The prefix to be removed.

Returns:



533
534
535
536
 
# File 'lib/polars/string_expr.rb', line 533

def strip_prefix(prefix)
  prefix = Utils.parse_into_expression(prefix, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.str_strip_prefix(prefix))
end

#strip_suffix(suffix) ⇒ Expr

Remove suffix.

The suffix will be removed from the string exactly once, if found.

Examples:

df = Polars::DataFrame.new({"a" => ["foobar", "foobarbar", "foo", "bar"]})
df.with_columns(Polars.col("a").str.strip_suffix("bar").alias("stripped"))
# =>
# shape: (4, 2)
# ┌───────────┬──────────┐
# │ a         ┆ stripped │
# │ ---       ┆ ---      │
# │ str       ┆ str      │
# ╞═══════════╪══════════╡
# │ foobar    ┆ foo      │
# │ foobarbar ┆ foobar   │
# │ foo       ┆ foo      │
# │ bar       ┆          │
# └───────────┴──────────┘

Parameters:

  • suffix (String) —

    The suffix to be removed.

Returns:



563
564
565
566
 
# File 'lib/polars/string_expr.rb', line 563

def strip_suffix(suffix)
  suffix = Utils.parse_into_expression(suffix, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.str_strip_suffix(suffix))
end

#strptime(dtype, format = nil, strict: true, exact: true, cache: true, utc: false) ⇒ Expr

Note:

When parsing a Datetime the column precision will be inferred from the format string, if given, eg: "%F %T%.3f" => Datetime("ms"). If no fractional second component is found then the default is "us".

Parse a Utf8 expression to a Date/Datetime/Time type.

Examples:

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
# ]

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",
  ]
)
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,)
# Series: 'date' [date]
# [
#         2021-04-22
#         2022-01-04
#         2022-01-31
#         2001-07-08
# ]

Parameters:

  • dtype (Object) —

    The data type to convert into. Can be either Date, Datetime, or Time.

  • format (String) (defaults to: nil) —

    Format to use, refer to the chrono strftime documentation for specification. Example: "%y-%m-%d".

  • strict (Boolean) (defaults to: true) —

    Raise an error if any conversion fails.

  • exact (Boolean) (defaults to: true) —
    • If true, require an exact format match.
    • If false, allow the format to match anywhere in the target string.
  • utc (Boolean) (defaults to: false) —

    Parse timezone aware datetimes as UTC. This may be useful if you have data with mixed offsets.

Returns:



197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/polars/string_expr.rb', line 197

def strptime(dtype, format = nil, strict: true, exact: true, cache: true, utc: false)
  _validate_format_argument(format)

  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, Time}"
  end
end

#to_date(format = nil, strict: true, exact: true, cache: true) ⇒ Expr

Convert a Utf8 column into a Date column.

Examples:

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
# ]

Parameters:

  • format (String) (defaults to: nil) —

    Format to use for conversion. Refer to the chrono crate documentation for the full specification. Example: "%Y-%m-%d". If set to nil (default), the format is inferred from the data.

  • strict (Boolean) (defaults to: true) —

    Raise an error if any conversion fails.

  • exact (Boolean) (defaults to: true) —

    Require an exact format match. If false, allow the format to match anywhere in the target string.

  • cache (Boolean) (defaults to: true) —

    Use a cache of unique, converted dates to apply the conversion.

Returns:



40
41
42
43
 
# File 'lib/polars/string_expr.rb', line 40

def to_date(format = nil, strict: true, exact: true, cache: true)
  _validate_format_argument(format)
  Utils.wrap_expr(_rbexpr.str_to_date(format, strict, exact, cache))
end

#to_datetime(format = nil, time_unit: nil, time_zone: nil, strict: true, exact: true, cache: true, ambiguous: "raise") ⇒ Expr

Convert a Utf8 column into a Datetime column.

Examples:

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
# ]

Parameters:

  • format (String) (defaults to: nil) —

    Format to use for conversion. Refer to the chrono crate documentation for the full specification. Example: "%Y-%m-%d %H:%M:%S". If set to nil (default), the format is inferred from the data.

  • time_unit ("us", "ns", "ms") (defaults to: nil) —

    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".

  • time_zone (String) (defaults to: nil) —

    Time zone for the resulting Datetime column.

  • strict (Boolean) (defaults to: true) —

    Raise an error if any conversion fails.

  • exact (Boolean) (defaults to: true) —

    Require an exact format match. If false, allow the format to match anywhere in the target string.

  • cache (Boolean) (defaults to: true) —

    Use a cache of unique, converted datetimes to apply the conversion.

Returns:



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/polars/string_expr.rb', line 79

def to_datetime(
  format = nil,
  time_unit: nil,
  time_zone: nil,
  strict: true,
  exact: true,
  cache: true,
  ambiguous: "raise"
)
  _validate_format_argument(format)
  unless ambiguous.is_a?(Expr)
    ambiguous = Polars.lit(ambiguous)
  end
  Utils.wrap_expr(
    _rbexpr.str_to_datetime(
      format,
      time_unit,
      time_zone,
      strict,
      exact,
      cache,
      ambiguous._rbexpr
    )
  )
end

#to_decimal(inference_length = 100) ⇒ Expr

Convert a String column into a Decimal column.

This method infers the needed parameters precision and scale.

Examples:

df = Polars::DataFrame.new(
  {
    "numbers": [
      "40.12",
      "3420.13",
      "120134.19",
      "3212.98",
      "12.90",
      "143.09",
      "143.9"
    ]
  }
)
df.with_columns(numbers_decimal: Polars.col("numbers").str.to_decimal)
# =>
# shape: (7, 2)
# ┌───────────┬─────────────────┐
# │ numbers   ┆ numbers_decimal │
# │ ---       ┆ ---             │
# │ str       ┆ decimal[*,2]    │
# ╞═══════════╪═════════════════╡
# │ 40.12     ┆ 40.12           │
# │ 3420.13   ┆ 3420.13         │
# │ 120134.19 ┆ 120134.19       │
# │ 3212.98   ┆ 3212.98         │
# │ 12.90     ┆ 12.90           │
# │ 143.09    ┆ 143.09          │
# │ 143.9     ┆ 143.90          │
# └───────────┴─────────────────┘

Parameters:

  • inference_length (Integer) (defaults to: 100) —

    Number of elements to parse to determine the precision and scale.

Returns:



253
254
255
 
# File 'lib/polars/string_expr.rb', line 253

def to_decimal(inference_length = 100)
  Utils.wrap_expr(_rbexpr.str_to_decimal(inference_length))
end

#to_integer(base: 10, strict: true) ⇒ Expr

Convert an Utf8 column into an Int64 column with base radix.

Examples:

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   │
# └─────────┴────────┘
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   │
# └──────┴────────┘

Parameters:

  • base (Integer) (defaults to: 10) —

    Positive integer which is the base of the string we are parsing. Default: 10.

  • strict (Boolean) (defaults to: true) —

    Bool, default=true will raise any ParseError or overflow as ComputeError. false silently convert to Null.

Returns:



1332
1333
1334
1335
 
# File 'lib/polars/string_expr.rb', line 1332

def to_integer(base: 10, strict: true)
  base = Utils.parse_into_expression(base, str_as_lit: false)
  Utils.wrap_expr(_rbexpr.str_to_integer(base, strict))
end

#to_lowercase ⇒ Expr

Transform to lowercase variant.

Examples:

df = Polars::DataFrame.new({"foo" => ["CAT", "DOG"]})
df.select(Polars.col("foo").str.to_lowercase)
# =>
# shape: (2, 1)
# ┌─────┐
# │ foo │
# │ --- │
# │ str │
# ╞═════╡
# │ cat │
# │ dog │
# └─────┘

Returns:



400
401
402
 
# File 'lib/polars/string_expr.rb', line 400

def to_lowercase
  Utils.wrap_expr(_rbexpr.str_to_lowercase)
end

#to_time(format = nil, strict: true, cache: true) ⇒ Expr

Convert a Utf8 column into a Time column.

Examples:

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
# ]

Parameters:

  • format (String) (defaults to: nil) —

    Format to use for conversion. Refer to the chrono crate documentation for the full specification. Example: "%H:%M:%S". If set to nil (default), the format is inferred from the data.

  • strict (Boolean) (defaults to: true) —

    Raise an error if any conversion fails.

  • cache (Boolean) (defaults to: true) —

    Use a cache of unique, converted times to apply the conversion.

Returns:



130
131
132
133
 
# File 'lib/polars/string_expr.rb', line 130

def to_time(format = nil, strict: true, cache: true)
  _validate_format_argument(format)
  Utils.wrap_expr(_rbexpr.str_to_time(format, strict, cache))
end

#to_titlecase ⇒ Expr

Transform to titlecase variant.

Examples:

df = Polars::DataFrame.new(
  {"sing": ["welcome to my world", "THERE'S NO TURNING BACK"]}
)
df.with_columns(foo_title: Polars.col("sing").str.to_titlecase)
# =>
# shape: (2, 2)
# ┌─────────────────────────┬─────────────────────────┐
# │ sing                    ┆ foo_title               │
# │ ---                     ┆ ---                     │
# │ str                     ┆ str                     │
# ╞═════════════════════════╪═════════════════════════╡
# │ welcome to my world     ┆ Welcome To My World     │
# │ THERE'S NO TURNING BACK ┆ There's No Turning Back │
# └─────────────────────────┴─────────────────────────┘

Returns:

Raises:

  • (Todo) 


423
424
425
426
 
# File 'lib/polars/string_expr.rb', line 423

def to_titlecase
  raise Todo
  Utils.wrap_expr(_rbexpr.str_to_titlecase)
end

#to_uppercase ⇒ Expr

Transform to uppercase variant.

Examples:

df = Polars::DataFrame.new({"foo" => ["cat", "dog"]})
df.select(Polars.col("foo").str.to_uppercase)
# =>
# shape: (2, 1)
# ┌─────┐
# │ foo │
# │ --- │
# │ str │
# ╞═════╡
# │ CAT │
# │ DOG │
# └─────┘

Returns:



379
380
381
 
# File 'lib/polars/string_expr.rb', line 379

def to_uppercase
  Utils.wrap_expr(_rbexpr.str_to_uppercase)
end

#zfill(length) ⇒ Expr

Fills the string with zeroes.

Return a copy of the string left filled with ASCII '0' digits to make a string of length width.

A leading sign prefix ('+'/'-') is handled by inserting the padding after the sign character rather than before. The original string is returned if width is less than or equal to s.length.

Examples:

df = Polars::DataFrame.new({"a" => [-1, 123, 999999, nil]})
df.with_columns(Polars.col("a").cast(Polars::String).str.zfill(4).alias("zfill"))
# =>
# shape: (4, 2)
# ┌────────┬────────┐
# │ a      ┆ zfill  │
# │ ---    ┆ ---    │
# │ i64    ┆ str    │
# ╞════════╪════════╡
# │ -1     ┆ -001   │
# │ 123    ┆ 0123   │
# │ 999999 ┆ 999999 │
# │ null   ┆ null   │
# └────────┴────────┘

Parameters:

  • length (Integer) —

    Fill the value up to this length

Returns:



657
658
659
660
 
# File 'lib/polars/string_expr.rb', line 657

def zfill(length)
  length = Utils.parse_into_expression(length)
  Utils.wrap_expr(_rbexpr.str_zfill(length))
end