polars-df 0.23.0 → 0.24.0

data/lib/polars/string_name_space.rb

@@ -126,9 +126,9 @@ module Polars
 
     # Parse a Series of dtype Utf8 to a Date/Datetime Series.
     #
-    # @param datatype [Symbol]
+    # @param dtype [Symbol]
     #   `:date`, `:datetime`, or `:time`.
-    # @param fmt [String]
+    # @param format [String]
     #   Format to use, refer to the
     #   [chrono strftime documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)
     #   for specification. Example: `"%y-%m-%d"`.
@@ -139,6 +139,13 @@ module Polars
     #   - If false, allow the format to match anywhere in the target string.
     # @param cache [Boolean]
     #   Use a cache of unique, converted dates to apply the 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 [Series]
     #
@@ -180,7 +187,7 @@ module Polars
     #   #         2022-01-31
     #   #         2001-07-08
     #   # ]
-    def strptime(datatype, fmt = nil, strict: true, exact: true, cache: true)
+    def strptime(dtype, format = nil, strict: true, exact: true, cache: true, ambiguous: "raise")
       super
     end
 
@@ -237,7 +244,6 @@ module Polars
     def len_bytes
       super
     end
-    alias_method :lengths, :len_bytes
 
     # Return the length of each string as the number of characters.
     #
@@ -258,7 +264,6 @@ module Polars
     def len_chars
       super
     end
-    alias_method :n_chars, :len_chars
 
     # Check if strings in Series contain a substring that matches a regex.
     #
@@ -266,6 +271,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 [Series]
     #
@@ -293,7 +301,7 @@ module Polars
     #   #         true
     #   #         null
     #   # ]
-    def contains(pattern, literal: false)
+    def contains(pattern, literal: false, strict: true)
       super
     end
 
@@ -358,7 +366,7 @@ module Polars
 
     # Check if string values end with a substring.
     #
-    # @param sub [String]
+    # @param suffix [String]
     #   Suffix substring.
     #
     # @return [Series]
@@ -374,13 +382,13 @@ module Polars
     #   #         true
     #   #         null
     #   # ]
-    def ends_with(sub)
+    def ends_with(suffix)
       super
     end
 
     # Check if string values start with a substring.
     #
-    # @param sub [String]
+    # @param prefix [String]
     #   Prefix substring.
     #
     # @return [Series]
@@ -396,7 +404,7 @@ module Polars
     #   #         false
     #   #         null
     #   # ]
-    def starts_with(sub)
+    def starts_with(prefix)
       super
     end
 
@@ -423,7 +431,7 @@ module Polars
     #   #         b"bar"
     #   #         null
     #   # ]
-    def decode(encoding, strict: false)
+    def decode(encoding, strict: true)
       super
     end
 
@@ -473,7 +481,7 @@ module Polars
     #   #         null
     #   #         {2,false}
     #   # ]
-    def json_decode(dtype = nil, infer_schema_length: 100)
+    def json_decode(dtype = nil, infer_schema_length: N_INFER_DEFAULT)
       if !dtype.nil?
         s = Utils.wrap_s(_s)
         return (
@@ -607,6 +615,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 [Series]
     #
@@ -620,10 +630,9 @@ module Polars
     #   #         5
     #   #         6
     #   # ]
-    def count_matches(pattern)
+    def count_matches(pattern, literal: false)
       super
     end
-    alias_method :count_match, :count_matches
 
     # Split the string by a substring.
     #
@@ -746,6 +755,8 @@ module Polars
     #   Substring to replace.
     # @param literal [Boolean]
     #   Treat pattern as a literal string.
+    # @param n [Integer]
+    #   Number of matches to replace.
     #
     # @return [Series]
     #
@@ -759,7 +770,7 @@ module Polars
     #   #         "123ABC"
     #   #         "abc456"
     #   # ]
-    def replace(pattern, value, literal: false)
+    def replace(pattern, value, literal: false, n: 1)
       super
     end
 
@@ -790,8 +801,10 @@ module Polars
 
     # Remove leading and trailing whitespace.
     #
-    # @param matches [String, nil]
-    #   An optional single character that should be trimmed
+    # @param characters [String]
+    #   The set of characters to be removed. All combinations of this set of
+    #   characters will be stripped from the start and end of the string. If set to
+    #   nil (default), all leading and trailing whitespace is removed instead.
     #
     # @return [Series]
     #
@@ -805,14 +818,16 @@ module Polars
     #   #         "hello"
     #   #         "world"
     #   # ]
-    def strip_chars(matches = nil)
+    def strip_chars(characters = nil)
       super
     end
 
     # Remove leading whitespace.
     #
-    # @param matches [String, nil]
-    #   An optional single character that should be trimmed
+    # @param characters [String]
+    #   The set of characters to be removed. All combinations of this set of
+    #   characters will be stripped from the start of the string. If set to
+    #   nil (default), all leading and trailing whitespace is removed instead.
     #
     # @return [Series]
     #
@@ -826,15 +841,16 @@ module Polars
     #   #         "hello "
     #   #         "world"
     #   # ]
-    def strip_chars_start(matches = nil)
+    def strip_chars_start(characters = nil)
       super
     end
-    alias_method :lstrip, :strip_chars_start
 
     # Remove trailing whitespace.
     #
-    # @param matches [String, nil]
-    #   An optional single character that should be trimmed
+    # @param characters [String]
+    #   The set of characters to be removed. All combinations of this set of
+    #   characters will be stripped from the end of the string. If set to
+    #   nil (default), all leading and trailing whitespace is removed instead.
     #
     # @return [Series]
     #
@@ -848,10 +864,9 @@ module Polars
     #   #         " hello"
     #   #         "world"
     #   # ]
-    def strip_chars_end(matches = nil)
+    def strip_chars_end(characters = nil)
       super
     end
-    alias_method :rstrip, :strip_chars_end
 
     # Remove prefix.
     #
@@ -985,62 +1000,6 @@ module Polars
       super
     end
 
-    # Return the string left justified in a string of length `width`.
-    #
-    # Padding is done using the specified `fillchar`. The original string is
-    # returned if `width` is less than or equal to `s.length`.
-    #
-    # @param width [Integer]
-    #   Justify left to this length.
-    # @param fillchar [String]
-    #   Fill with this ASCII character.
-    #
-    # @return [Series]
-    #
-    # @example
-    #   s = Polars::Series.new("a", ["cow", "monkey", nil, "hippopotamus"])
-    #   s.str.ljust(8, "*")
-    #   # =>
-    #   # shape: (4,)
-    #   # Series: 'a' [str]
-    #   # [
-    #   #         "cow*****"
-    #   #         "monkey**"
-    #   #         null
-    #   #         "hippopotamus"
-    #   # ]
-    def ljust(width, fillchar = " ")
-      super
-    end
-
-    # Return the string right justified in a string of length `width`.
-    #
-    # Padding is done using the specified `fillchar`. The original string is
-    # returned if `width` is less than or equal to `s.length`.
-    #
-    # @param width [Integer]
-    #   Justify right to this length.
-    # @param fillchar [String]
-    #   Fill with this ASCII character.
-    #
-    # @return [Series]
-    #
-    # @example
-    #   s = Polars::Series.new("a", ["cow", "monkey", nil, "hippopotamus"])
-    #   s.str.rjust(8, "*")
-    #   # =>
-    #   # shape: (4,)
-    #   # Series: 'a' [str]
-    #   # [
-    #   #         "*****cow"
-    #   #         "**monkey"
-    #   #         null
-    #   #         "hippopotamus"
-    #   # ]
-    def rjust(width, fillchar = " ")
-      super
-    end
-
     # Modify the strings to their lowercase equivalent.
     #
     # @return [Series]
@@ -1339,7 +1298,7 @@ module Polars
     #   #         "Can me feel the love tonight"
     #   # ]
     #
-    # @example Broadcast a replacement for many patterns by passing a sequence of length 1 to the `replace_with` parameter.
+    # @example Broadcast a replacement for many patterns by passing an array of length 1 to the `replace_with` parameter.
     #   s = Polars::Series.new(
     #     "lyrics",
     #     [
@@ -1379,7 +1338,7 @@ module Polars
     #   # ]
     def replace_many(
       patterns,
-      replace_with = Expr::NO_DEFAULT,
+      replace_with = NO_DEFAULT,
       ascii_case_insensitive: false
     )
       super
@@ -1496,7 +1455,7 @@ module Polars
     #   The delimiter to insert between consecutive string values.
     # @param ignore_nulls [Boolean]
     #   Ignore null values (default).
-    #   If set to `False`, null values will be propagated. This means that
+    #   If set to `false`, null values will be propagated. This means that
     #   if the column contains any null values, the output is null.
     #
     # @return [Series]
@@ -1518,10 +1477,15 @@ module Polars
     #   # [
     #   #         null
     #   # ]
-    def join(delimiter = "-", ignore_nulls: true)
+    def join(delimiter = nil, ignore_nulls: true)
+      # TODO update
+      if delimiter.nil?
+        warn "The default `delimiter` for `join` method will change from `-` to empty string in a future version"
+        delimiter = "-"
+      end
+
       super
     end
-    alias_method :concat, :join
 
     # Returns string values with all regular expression meta characters escaped.
     #

data/lib/polars/struct_expr.rb

@@ -26,34 +26,52 @@ module Polars
     #
     # @param name [String]
     #   Name of the field
+    # @param more_names [Array]
+    #   Additional struct field names.
     #
     # @return [Expr]
     #
     # @example
-    #   df = (
-    #     Polars::DataFrame.new(
-    #       {
-    #         "int" => [1, 2],
-    #         "str" => ["a", "b"],
-    #         "bool" => [true, nil],
-    #         "list" => [[1, 2], [3]]
-    #       }
-    #     )
-    #     .to_struct("my_struct")
-    #     .to_frame
-    #   )
-    #   df.select(Polars.col("my_struct").struct.field("str"))
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "aaa" => [1, 2],
+    #       "bbb" => ["ab", "cd"],
+    #       "ccc" => [true, nil],
+    #       "ddd" => [[1, 2], [3]]
+    #     }
+    #   ).select(Polars.struct("aaa", "bbb", "ccc", "ddd").alias("struct_col"))
+    #   df.select(Polars.col("struct_col").struct.field("bbb"))
     #   # =>
     #   # shape: (2, 1)
     #   # ┌─────┐
-    #   # │ str │
+    #   # │ bbb │
     #   # │ --- │
     #   # │ str │
     #   # ╞═════╡
-    #   # │ a   │
-    #   # │ b   │
+    #   # │ ab  │
+    #   # │ cd  │
     #   # └─────┘
-    def field(name)
+    #
+    # @example
+    #   df.select(Polars.col("struct_col").struct.field("aaa", "bbb"))
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌─────┬─────┐
+    #   # │ aaa ┆ bbb │
+    #   # │ --- ┆ --- │
+    #   # │ i64 ┆ str │
+    #   # ╞═════╪═════╡
+    #   # │ 1   ┆ ab  │
+    #   # │ 2   ┆ cd  │
+    #   # └─────┴─────┘
+    def field(name, *more_names)
+      if more_names.any?
+        name = (name.is_a?(::String) ? [name] : name) + more_names
+      end
+      if name.is_a?(::Array)
+        return Utils.wrap_expr(_rbexpr.struct_multiple_fields(name))
+      end
+
       Utils.wrap_expr(_rbexpr.struct_field_by_name(name))
     end
 
@@ -107,7 +125,7 @@ module Polars
     #     .to_struct("my_struct")
     #     .to_frame
     #   )
-    #   df = df.with_column(
+    #   df = df.with_columns(
     #     Polars.col("my_struct").struct.rename_fields(["INT", "STR", "BOOL", "LIST"])
     #   )
     #   df.select(Polars.col("my_struct").struct.field("INT"))