polars-df 0.15.0 → 0.26.0

data/lib/polars/binary_expr.rb

@@ -197,5 +197,222 @@ module Polars
         raise ArgumentError, "encoding must be one of {{'hex', 'base64'}}, got #{encoding}"
       end
     end
+
+    # Get the size of binary values in the given unit.
+    #
+    # @param unit ['b', 'kb', 'mb', 'gb', 'tb']
+    #   Scale the returned size to the given unit.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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         │
+    #   # └─────────────────────────────────┴─────────┴─────────────┘
+    def size(unit = "b")
+      sz = Utils.wrap_expr(_rbexpr.bin_size_bytes)
+      sz = Utils.scale_bytes(sz, to: unit)
+      sz
+    end
+
+    # Interpret a buffer as a numerical Polars type.
+    #
+    # @param dtype [Object]
+    #   Which type to interpret binary column into.
+    # @param endianness : ["big", "little"]
+    #   Which endianness to use when interpreting bytes, by default "little".
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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   │
+    #   # └─────────────────────┴─────────┘
+    def reinterpret(
+      dtype:,
+      endianness: "little"
+    )
+      dtype = Utils.parse_into_datatype_expr(dtype)
+
+      Utils.wrap_expr(
+        _rbexpr.bin_reinterpret(dtype._rbdatatype_expr, endianness)
+      )
+    end
+
+    # Slice the binary values.
+    #
+    # @param offset [Object]
+    #     Start index. Negative indexing is supported.
+    # @param length [Object]
+    #   Length of the slice. If set to `nil` (default), the slice is taken to the
+    #   end of the value.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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" │
+    #   # └────────┴─────────────────┴─────────────┘
+    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
+
+    # Take the first `n` bytes of the binary values.
+    #
+    # @param n [Object]
+    #   Length of the slice (integer or expression). Negative indexing is supported;
+    #   see note (2) below.
+    #
+    # @return [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.
+    #
+    # @example
+    #   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" │
+    #   # └────────┴─────────────────┴─────────────┘
+    def head(n = 5)
+      n_rbexpr = Utils.parse_into_expression(n, str_as_lit: false)
+      Utils.wrap_expr(_rbexpr.bin_head(n_rbexpr))
+    end
+
+    # Take the last `n` bytes of the binary values.
+    #
+    # @param n [Object]
+    #   Length of the slice (integer or expression). Negative indexing is supported;
+    #   see note (2) below.
+    #
+    # @return [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.
+    #
+    # @example
+    #   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" │
+    #   # └────────┴─────────────────┴─────────────┘
+    def tail(n = 5)
+      n_rbexpr = Utils.parse_into_expression(n, str_as_lit: false)
+      Utils.wrap_expr(_rbexpr.bin_tail(n_rbexpr))
+    end
+
+    # 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`.
+    #
+    # @param index [Object]
+    #   Index to return per binary value
+    # @param null_on_oob [Boolean]
+    #   Behavior if an index is out of bounds:
+    #
+    #   * true -> set as null
+    #   * false -> raise an error
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   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    │
+    #   # └─────────────────┴──────┘
+    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
   end
 end

data/lib/polars/binary_name_space.rb

@@ -110,7 +110,7 @@ module Polars
     #   #         b"\x00\x00\xff"
     #   # ]
     #
-    # @example Set `strict=False` to set invalid values to null instead of raising an error.
+    # @example Set `strict: false` to set invalid values to null instead of raising an error.
     #   s = Polars::Series.new("colors", ["000000".b, "ffff00".b, "invalid_value".b])
     #   s.bin.decode("hex", strict: false)
     #   # =>
@@ -157,5 +157,159 @@ module Polars
     def encode(encoding)
       super
     end
+
+    # Get the size of the binary values in a Series in the given unit.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("data", [512, 256, 2560, 1024].map { |n| "\x00".b * n })
+    #   s.bin.size("kb")
+    #   # =>
+    #   # shape: (4,)
+    #   # Series: 'data' [f64]
+    #   # [
+    #   #         0.5
+    #   #         0.25
+    #   #         2.5
+    #   #         1.0
+    #   # ]
+    def size(unit = "b")
+      super
+    end
+
+    # Interpret a buffer as a numerical polars type.
+    #
+    # @param dtype [Object]
+    #   Which type to interpret binary column into.
+    # @param endianness ["big", "little"]
+    #   Which endianness to use when interpreting bytes, by default "little".
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("data", ["\x05\x00\x00\x00".b, "\x10\x00\x01\x00".b])
+    #   s.bin.reinterpret(dtype: Polars::Int32, endianness: "little")
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'data' [i32]
+    #   # [
+    #   #         5
+    #   #         65552
+    #   # ]
+    def reinterpret(dtype:, endianness: "little")
+      super
+    end
+
+    # Slice the binary values.
+    #
+    # @param offset [Object]
+    #   Start index. Negative indexing is supported.
+    # @param length [Object]
+    #   Length of the slice. If set to `nil` (default), the slice is taken to the
+    #   end of the value.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   colors = Polars::Series.new(["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b])
+    #   colors.bin.slice(1, 2)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [binary]
+    #   # [
+    #   #         b"\x00\x00"
+    #   #         b"\xff\x00"
+    #   #         b"\x00\xff"
+    #   # ]
+    def slice(offset, length = nil)
+      super
+    end
+
+    # 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.
+    # The behavior if an index is out of bounds is determined by the argument
+    # `null_on_oob`.
+    #
+    # @param index [Object]
+    #   Index to return per binary value
+    # @param null_on_oob [Boolean]
+    #   Behavior if an index is out of bounds:
+    #
+    #   * true -> set as null
+    #   * false -> raise an error
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", ["\x01\x02\x03".b, "".b, "\x04\x05".b])
+    #   s.bin.get(0, null_on_oob: true)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [u8]
+    #   # [
+    #   #         1
+    #   #         null
+    #   #         4
+    #   # ]
+    def get(index, null_on_oob: false)
+      super
+    end
+
+    # Take the first `n` bytes of the binary values.
+    #
+    # @param n [Object]
+    #   Length of the slice. Negative indexing is supported; see note (2) below.
+    #
+    # @return [Series]
+    #
+    # @note
+    #   (1) A similar method exists for taking the last `n` bytes: `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.
+    #
+    # @example
+    #   colors = Polars::Series.new(["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b])
+    #   colors.bin.head(2)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [binary]
+    #   # [
+    #   #         b"\x00\x00"
+    #   #         b"\xff\xff"
+    #   #         b"\x00\x00"
+    #   # ]
+    def head(n = 5)
+      super
+    end
+
+    # Take the last `n` bytes of the binary values.
+    #
+    # @param n [Object]
+    #   Length of the slice. Negative indexing is supported; see note (2) below.
+    #
+    # @return [Series]
+    #
+    # @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.
+    #
+    # @example
+    #   colors = Polars::Series.new(["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b])
+    #   colors.bin.tail(2)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [binary]
+    #   # [
+    #   #         b"\x00\x00"
+    #   #         b"\xff\x00"
+    #   #         b"\x00\xff"
+    #   # ]
+    def tail(n = 5)
+      super
+    end
   end
 end

data/lib/polars/cat_expr.rb

@@ -32,5 +32,229 @@ module Polars
     def get_categories
       Utils.wrap_expr(_rbexpr.cat_get_categories)
     end
+
+    # Return the byte-length of the string representation of each value.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   When working with non-ASCII text, the length in bytes is not the same as the
+    #   length in characters. You may want to use `len_chars` instead.
+    #   Note that `len_bytes` is much more performant (_O(1)_) than
+    #   `len_chars` (_O(n)_).
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"a" => Polars::Series.new(["Café", "345", "東京", nil], dtype: Polars::Categorical)}
+    #   )
+    #   df.with_columns(
+    #     Polars.col("a").cat.len_bytes.alias("n_bytes"),
+    #     Polars.col("a").cat.len_chars.alias("n_chars")
+    #   )
+    #   # =>
+    #   # shape: (4, 3)
+    #   # ┌──────┬─────────┬─────────┐
+    #   # │ a    ┆ n_bytes ┆ n_chars │
+    #   # │ ---  ┆ ---     ┆ ---     │
+    #   # │ cat  ┆ u32     ┆ u32     │
+    #   # ╞══════╪═════════╪═════════╡
+    #   # │ Café ┆ 5       ┆ 4       │
+    #   # │ 345  ┆ 3       ┆ 3       │
+    #   # │ 東京 ┆ 6       ┆ 2       │
+    #   # │ null ┆ null    ┆ null    │
+    #   # └──────┴─────────┴─────────┘
+    def len_bytes
+      Utils.wrap_expr(_rbexpr.cat_len_bytes)
+    end
+
+    # Return the number of characters of the string representation of each value.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   When working with ASCII text, use `len_bytes` instead to achieve
+    #   equivalent output with much better performance:
+    #   `len_bytes` runs in _O(1)_, while `len_chars` runs in (_O(n)_).
+    #
+    #   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.
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"a" => Polars::Series.new(["Café", "345", "東京", nil], dtype: Polars::Categorical)}
+    #   )
+    #   df.with_columns(
+    #     Polars.col("a").cat.len_chars.alias("n_chars"),
+    #     Polars.col("a").cat.len_bytes.alias("n_bytes")
+    #   )
+    #   # =>
+    #   # shape: (4, 3)
+    #   # ┌──────┬─────────┬─────────┐
+    #   # │ a    ┆ n_chars ┆ n_bytes │
+    #   # │ ---  ┆ ---     ┆ ---     │
+    #   # │ cat  ┆ u32     ┆ u32     │
+    #   # ╞══════╪═════════╪═════════╡
+    #   # │ Café ┆ 4       ┆ 5       │
+    #   # │ 345  ┆ 3       ┆ 3       │
+    #   # │ 東京 ┆ 2       ┆ 6       │
+    #   # │ null ┆ null    ┆ null    │
+    #   # └──────┴─────────┴─────────┘
+    def len_chars
+      Utils.wrap_expr(_rbexpr.cat_len_chars)
+    end
+
+    # Check if string representations of values start with a substring.
+    #
+    # @param prefix [String]
+    #   Prefix substring.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   Whereas `str.starts_with` allows expression inputs, `cat.starts_with` requires
+    #   a literal string value.
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"fruits" => Polars::Series.new(["apple", "mango", nil], dtype: Polars::Categorical)}
+    #   )
+    #   df.with_columns(
+    #     Polars.col("fruits").cat.starts_with("app").alias("has_prefix")
+    #   )
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌────────┬────────────┐
+    #   # │ fruits ┆ has_prefix │
+    #   # │ ---    ┆ ---        │
+    #   # │ cat    ┆ bool       │
+    #   # ╞════════╪════════════╡
+    #   # │ apple  ┆ true       │
+    #   # │ mango  ┆ false      │
+    #   # │ null   ┆ null       │
+    #   # └────────┴────────────┘
+    #
+    # @example Using `starts_with` as a filter condition:
+    #   df.filter(Polars.col("fruits").cat.starts_with("app"))
+    #   # =>
+    #   # shape: (1, 1)
+    #   # ┌────────┐
+    #   # │ fruits │
+    #   # │ ---    │
+    #   # │ cat    │
+    #   # ╞════════╡
+    #   # │ apple  │
+    #   # └────────┘
+    def starts_with(prefix)
+      if !prefix.is_a?(::String)
+        msg = "'prefix' must be a string; found #{prefix.inspect}"
+        raise TypeError, msg
+      end
+      Utils.wrap_expr(_rbexpr.cat_starts_with(prefix))
+    end
+
+    # Check if string representations of values end with a substring.
+    #
+    # @param suffix [String]
+    #   Suffix substring.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   Whereas `str.ends_with` allows expression inputs, `cat.ends_with` requires a
+    #   literal string value.
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {"fruits" => Polars::Series.new(["apple", "mango", nil], dtype: Polars::Categorical)}
+    #   )
+    #   df.with_columns(Polars.col("fruits").cat.ends_with("go").alias("has_suffix"))
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌────────┬────────────┐
+    #   # │ fruits ┆ has_suffix │
+    #   # │ ---    ┆ ---        │
+    #   # │ cat    ┆ bool       │
+    #   # ╞════════╪════════════╡
+    #   # │ apple  ┆ false      │
+    #   # │ mango  ┆ true       │
+    #   # │ null   ┆ null       │
+    #   # └────────┴────────────┘
+    #
+    # @example Using `ends_with` as a filter condition:
+    #   df.filter(Polars.col("fruits").cat.ends_with("go"))
+    #   # =>
+    #   # shape: (1, 1)
+    #   # ┌────────┐
+    #   # │ fruits │
+    #   # │ ---    │
+    #   # │ cat    │
+    #   # ╞════════╡
+    #   # │ mango  │
+    #   # └────────┘
+    def ends_with(suffix)
+      if !suffix.is_a?(::String)
+        msg = "'suffix' must be a string; found #{suffix.inspect}"
+        raise TypeError, msg
+      end
+      Utils.wrap_expr(_rbexpr.cat_ends_with(suffix))
+    end
+
+    # Extract a substring from the string representation of each value.
+    #
+    # @param offset [Integer]
+    #   Start index. Negative indexing is supported.
+    # @param length [Integer]
+    #   Length of the slice. If set to `nil` (default), the slice is taken to the
+    #   end of the string.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   Both the `offset` and `length` inputs are 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.
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "s" => Polars::Series.new(
+    #         ["pear", nil, "papaya", "dragonfruit"],
+    #         dtype: Polars::Categorical
+    #       )
+    #     }
+    #   )
+    #   df.with_columns(Polars.col("s").cat.slice(-3).alias("slice"))
+    #   # =>
+    #   # shape: (4, 2)
+    #   # ┌─────────────┬───────┐
+    #   # │ s           ┆ slice │
+    #   # │ ---         ┆ ---   │
+    #   # │ cat         ┆ str   │
+    #   # ╞═════════════╪═══════╡
+    #   # │ pear        ┆ ear   │
+    #   # │ null        ┆ null  │
+    #   # │ papaya      ┆ aya   │
+    #   # │ dragonfruit ┆ uit   │
+    #   # └─────────────┴───────┘
+    #
+    # @example Using the optional `length` parameter
+    #   df.with_columns(Polars.col("s").cat.slice(4, 3).alias("slice"))
+    #   # =>
+    #   # shape: (4, 2)
+    #   # ┌─────────────┬───────┐
+    #   # │ s           ┆ slice │
+    #   # │ ---         ┆ ---   │
+    #   # │ cat         ┆ str   │
+    #   # ╞═════════════╪═══════╡
+    #   # │ pear        ┆       │
+    #   # │ null        ┆ null  │
+    #   # │ papaya      ┆ ya    │
+    #   # │ dragonfruit ┆ onf   │
+    #   # └─────────────┴───────┘
+    def slice(offset, length = nil)
+      Utils.wrap_expr(_rbexpr.cat_slice(offset, length))
+    end
   end
 end