Class: Polars::BinaryExpr

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

Overview

Namespace for binary related expressions.

Instance Method Summary collapse

Instance Method Details

#contains(literal) ⇒ Expr

Check if binaries in Series contain a binary substring.

Examples:

colors = Polars::DataFrame.new(
  {
    "name" => ["black", "yellow", "blue"],
    "code" => ["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b],
    "lit" => ["\x00".b, "\xff\x00".b, "\xff\xff".b]
  }
)
colors.select(
  "name",
  Polars.col("code").bin.contains("\xff".b).alias("contains_with_lit"),
  Polars.col("code").bin.contains(Polars.col("lit")).alias("contains_with_expr"),
)
# =>
# shape: (3, 3)
# ┌────────┬───────────────────┬────────────────────┐
# │ name   ┆ contains_with_lit ┆ contains_with_expr │
# │ ---    ┆ ---               ┆ ---                │
# │ str    ┆ bool              ┆ bool               │
# ╞════════╪═══════════════════╪════════════════════╡
# │ black  ┆ false             ┆ true               │
# │ yellow ┆ true              ┆ true               │
# │ blue   ┆ true              ┆ false              │
# └────────┴───────────────────┴────────────────────┘

Parameters:

  • literal (String) —

    The binary substring to look for

Returns:



43
44
45
46
 
# File 'lib/polars/binary_expr.rb', line 43

def contains(literal)
  literal = Utils.parse_into_expression(literal, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.binary_contains(literal))
end

#decode(encoding, strict: true) ⇒ Expr

Decode a value using the provided encoding.

Examples:

colors = Polars::DataFrame.new(
  {
    "name" => ["black", "yellow", "blue"],
    "encoded" => ["000000".b, "ffff00".b, "0000ff".b]
  }
)
colors.with_columns(
  Polars.col("encoded").bin.decode("hex").alias("code")
)
# =>
# shape: (3, 3)
# ┌────────┬───────────┬─────────────────┐
# │ name   ┆ encoded   ┆ code            │
# │ ---    ┆ ---       ┆ ---             │
# │ str    ┆ binary    ┆ binary          │
# ╞════════╪═══════════╪═════════════════╡
# │ black  ┆ b"000000" ┆ b"\x00\x00\x00" │
# │ yellow ┆ b"ffff00" ┆ b"\xff\xff\x00" │
# │ blue   ┆ b"0000ff" ┆ b"\x00\x00\xff" │
# └────────┴───────────┴─────────────────┘

Parameters:

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

    The encoding to use.

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

    Raise an error if the underlying value cannot be decoded, otherwise mask out with a null value.

Returns:



153
154
155
156
157
158
159
160
161
 
# File 'lib/polars/binary_expr.rb', line 153

def decode(encoding, strict: true)
  if encoding == "hex"
    Utils.wrap_expr(_rbexpr.binary_hex_decode(strict))
  elsif encoding == "base64"
    Utils.wrap_expr(_rbexpr.binary_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:

colors = Polars::DataFrame.new(
  {
    "color" => ["black", "yellow", "blue"],
    "code" => ["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b]
  }
)
colors.with_columns(
  Polars.col("code").bin.encode("hex").alias("encoded")
)
# =>
# shape: (3, 3)
# ┌────────┬─────────────────┬─────────┐
# │ color  ┆ code            ┆ encoded │
# │ ---    ┆ ---             ┆ ---     │
# │ str    ┆ binary          ┆ str     │
# ╞════════╪═════════════════╪═════════╡
# │ black  ┆ b"\x00\x00\x00" ┆ 000000  │
# │ yellow ┆ b"\xff\xff\x00" ┆ ffff00  │
# │ blue   ┆ b"\x00\x00\xff" ┆ 0000ff  │
# └────────┴─────────────────┴─────────┘

Parameters:

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

    The encoding to use.

Returns:



191
192
193
194
195
196
197
198
199
 
# File 'lib/polars/binary_expr.rb', line 191

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

#ends_with(suffix) ⇒ Expr

Check if string values end with a binary substring.

Examples:

colors = Polars::DataFrame.new(
  {
    "name" => ["black", "yellow", "blue"],
    "code" => ["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b],
    "suffix" => ["\x00".b, "\xff\x00".b, "\x00\x00".b]
  }
)
colors.select(
  "name",
  Polars.col("code").bin.ends_with("\xff".b).alias("ends_with_lit"),
  Polars.col("code").bin.ends_with(Polars.col("suffix")).alias("ends_with_expr")
)
# =>
# shape: (3, 3)
# ┌────────┬───────────────┬────────────────┐
# │ name   ┆ ends_with_lit ┆ ends_with_expr │
# │ ---    ┆ ---           ┆ ---            │
# │ str    ┆ bool          ┆ bool           │
# ╞════════╪═══════════════╪════════════════╡
# │ black  ┆ false         ┆ true           │
# │ yellow ┆ false         ┆ true           │
# │ blue   ┆ true          ┆ false          │
# └────────┴───────────────┴────────────────┘

Parameters:

  • suffix (String) —

    Suffix substring.

Returns:



79
80
81
82
 
# File 'lib/polars/binary_expr.rb', line 79

def ends_with(suffix)
  suffix = Utils.parse_into_expression(suffix, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.binary_ends_with(suffix))
end

#get(index, null_on_oob: false) ⇒ Expr

Get the byte value at the given index.

For example, index 0 would return the first byte of every binary value and index -1 would return the last byte of every binary value. If an index is out of bounds, it will return a None.

Examples:

df = Polars::DataFrame.new({"a" => ["\x01\x02\x03".b, "".b, "\x04\x05".b]})
df.with_columns(get: Polars.col("a").bin.get(0, null_on_oob: true))
# =>
# shape: (3, 2)
# ┌─────────────────┬──────┐
# │ a               ┆ get  │
# │ ---             ┆ ---  │
# │ binary          ┆ u8   │
# ╞═════════════════╪══════╡
# │ b"\x01\x02\x03" ┆ 1    │
# │ b""             ┆ null │
# │ b"\x04\x05"     ┆ 4    │
# └─────────────────┴──────┘

Parameters:

  • index (Object) —

    Index to return per binary value

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

    Behavior if an index is out of bounds:

    • true -> set as null
    • false -> raise an error

Returns:



413
414
415
416
 
# File 'lib/polars/binary_expr.rb', line 413

def get(index, null_on_oob: false)
  index_rbexpr = Utils.parse_into_expression(index)
  Utils.wrap_expr(_rbexpr.bin_get(index_rbexpr, null_on_oob))
end

#head(n = 5) ⇒ Expr

Note:

(1) A similar method exists for taking the last n bytes: :func:tail. (2) If n is negative, it is interpreted as "until the nth byte from the end", e.g., head(-3) returns all but the last three bytes.

Take the first n bytes of the binary values.

Examples:

colors = Polars::DataFrame.new(
  {
    "name" => ["black", "yellow", "blue"],
    "code" => ["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b]
  }
)
colors.with_columns(
  Polars.col("code").bin.head(2).alias("head")
)
# =>
# shape: (3, 3)
# ┌────────┬─────────────────┬─────────────┐
# │ name   ┆ code            ┆ head        │
# │ ---    ┆ ---             ┆ ---         │
# │ str    ┆ binary          ┆ binary      │
# ╞════════╪═════════════════╪═════════════╡
# │ black  ┆ b"\x00\x00\x00" ┆ b"\x00\x00" │
# │ yellow ┆ b"\xff\xff\x00" ┆ b"\xff\xff" │
# │ blue   ┆ b"\x00\x00\xff" ┆ b"\x00\x00" │
# └────────┴─────────────────┴─────────────┘

Parameters:

  • n (Object) (defaults to: 5) —

    Length of the slice (integer or expression). Negative indexing is supported; see note (2) below.

Returns:



339
340
341
342
 
# File 'lib/polars/binary_expr.rb', line 339

def head(n = 5)
  n_rbexpr = Utils.parse_into_expression(n, str_as_lit: false)
  Utils.wrap_expr(_rbexpr.bin_head(n_rbexpr))
end

#reinterpret(dtype:, endianness: "little") ⇒ Expr

Interpret a buffer as a numerical Polars type.

Examples:

df = Polars::DataFrame.new({"data" => ["\x05\x00\x00\x00".b, "\x10\x00\x01\x00".b]})
df.with_columns(
  bin2int: Polars.col("data").bin.reinterpret(
   dtype: Polars::Int32, endianness: "little"
  )
)
# =>
# shape: (2, 2)
# ┌─────────────────────┬─────────┐
# │ data                ┆ bin2int │
# │ ---                 ┆ ---     │
# │ binary              ┆ i32     │
# ╞═════════════════════╪═════════╡
# │ b"\x05\x00\x00\x00" ┆ 5       │
# │ b"\x10\x00\x01\x00" ┆ 65552   │
# └─────────────────────┴─────────┘

Parameters:

  • dtype (Object) —

    Which type to interpret binary column into.

  • endianness (defaults to: "little") —

    : ["big", "little"] Which endianness to use when interpreting bytes, by default "little".

Returns:



257
258
259
260
261
262
263
264
265
266
 
# File 'lib/polars/binary_expr.rb', line 257

def reinterpret(
  dtype:,
  endianness: "little"
)
  dtype = Utils.parse_into_datatype_expr(dtype)

  Utils.wrap_expr(
    _rbexpr.bin_reinterpret(dtype._rbdatatype_expr, endianness)
  )
end

#size(unit = "b") ⇒ Expr

Get the size of binary values in the given unit.

Examples:

df = Polars::DataFrame.new({"data" => [512, 256, 1024].map { |n| "\x00".b * n }})
df.with_columns(
  n_bytes: Polars.col("data").bin.size,
  n_kilobytes: Polars.col("data").bin.size("kb")
)
# =>
# shape: (3, 3)
# ┌─────────────────────────────────┬─────────┬─────────────┐
# │ data                            ┆ n_bytes ┆ n_kilobytes │
# │ ---                             ┆ ---     ┆ ---         │
# │ binary                          ┆ u32     ┆ f64         │
# ╞═════════════════════════════════╪═════════╪═════════════╡
# │ b"\x00\x00\x00\x00\x00\x00\x00… ┆ 512     ┆ 0.5         │
# │ b"\x00\x00\x00\x00\x00\x00\x00… ┆ 256     ┆ 0.25        │
# │ b"\x00\x00\x00\x00\x00\x00\x00… ┆ 1024    ┆ 1.0         │
# └─────────────────────────────────┴─────────┴─────────────┘

Parameters:

  • unit ('b', 'kb', 'mb', 'gb', 'tb') (defaults to: "b") —

    Scale the returned size to the given unit.

Returns:



225
226
227
228
229
 
# File 'lib/polars/binary_expr.rb', line 225

def size(unit = "b")
  sz = Utils.wrap_expr(_rbexpr.bin_size_bytes)
  sz = Utils.scale_bytes(sz, to: unit)
  sz
end

#slice(offset, length = nil) ⇒ Expr

Slice the binary values.

Examples:

colors = Polars::DataFrame.new(
  {
    "name" => ["black", "yellow", "blue"],
    "code" => ["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b]
  }
)
colors.with_columns(
  Polars.col("code").bin.slice(1, 2).alias("sliced")
)
# =>
# shape: (3, 3)
# ┌────────┬─────────────────┬─────────────┐
# │ name   ┆ code            ┆ sliced      │
# │ ---    ┆ ---             ┆ ---         │
# │ str    ┆ binary          ┆ binary      │
# ╞════════╪═════════════════╪═════════════╡
# │ black  ┆ b"\x00\x00\x00" ┆ b"\x00\x00" │
# │ yellow ┆ b"\xff\xff\x00" ┆ b"\xff\x00" │
# │ blue   ┆ b"\x00\x00\xff" ┆ b"\x00\xff" │
# └────────┴─────────────────┴─────────────┘

Parameters:

  • offset (Object) —

    Start index. Negative indexing is supported.

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

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

Returns:



299
300
301
302
303
 
# File 'lib/polars/binary_expr.rb', line 299

def slice(offset, length = nil)
  offset_rbexpr = Utils.parse_into_expression(offset)
  length_rbexpr = Utils.parse_into_expression(length)
  Utils.wrap_expr(_rbexpr.bin_slice(offset_rbexpr, length_rbexpr))
end

#starts_with(prefix) ⇒ Expr

Check if values start with a binary substring.

Examples:

colors = Polars::DataFrame.new(
  {
    "name": ["black", "yellow", "blue"],
    "code": ["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b],
    "prefix": ["\x00".b, "\xff\x00".b, "\x00\x00".b]
  }
)
colors.select(
  "name",
  Polars.col("code").bin.starts_with("\xff".b).alias("starts_with_lit"),
  Polars.col("code")
  .bin.starts_with(Polars.col("prefix"))
  .alias("starts_with_expr")
)
# =>
# shape: (3, 3)
# ┌────────┬─────────────────┬──────────────────┐
# │ name   ┆ starts_with_lit ┆ starts_with_expr │
# │ ---    ┆ ---             ┆ ---              │
# │ str    ┆ bool            ┆ bool             │
# ╞════════╪═════════════════╪══════════════════╡
# │ black  ┆ false           ┆ true             │
# │ yellow ┆ true            ┆ false            │
# │ blue   ┆ false           ┆ true             │
# └────────┴─────────────────┴──────────────────┘

Parameters:

  • prefix (String) —

    Prefix substring.

Returns:



117
118
119
120
 
# File 'lib/polars/binary_expr.rb', line 117

def starts_with(prefix)
  prefix = Utils.parse_into_expression(prefix, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.binary_starts_with(prefix))
end

#tail(n = 5) ⇒ Expr

Note:

(1) A similar method exists for taking the first n bytes: head. (2) If n is negative, it is interpreted as "starting at the nth byte", e.g., tail(-3) returns all but the first three bytes.

Take the last n bytes of the binary values.

Examples:

colors = Polars::DataFrame.new(
  {
    "name" => ["black", "yellow", "blue"],
    "code" => ["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b]
  }
)
colors.with_columns(
  Polars.col("code").bin.tail(2).alias("tail")
)
# =>
# shape: (3, 3)
# ┌────────┬─────────────────┬─────────────┐
# │ name   ┆ code            ┆ tail        │
# │ ---    ┆ ---             ┆ ---         │
# │ str    ┆ binary          ┆ binary      │
# ╞════════╪═════════════════╪═════════════╡
# │ black  ┆ b"\x00\x00\x00" ┆ b"\x00\x00" │
# │ yellow ┆ b"\xff\xff\x00" ┆ b"\xff\x00" │
# │ blue   ┆ b"\x00\x00\xff" ┆ b"\x00\xff" │
# └────────┴─────────────────┴─────────────┘

Parameters:

  • n (Object) (defaults to: 5) —

    Length of the slice (integer or expression). Negative indexing is supported; see note (2) below.

Returns:



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

def tail(n = 5)
  n_rbexpr = Utils.parse_into_expression(n, str_as_lit: false)
  Utils.wrap_expr(_rbexpr.bin_tail(n_rbexpr))
end