Method: Polars::StringExpr#strptime

Defined in:

lib/polars/string_expr.rb

#strptime(dtype, format = nil, strict: true, exact: true, cache: true, ambiguous: "raise") ⇒ 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.
• cache (Boolean) (defaults to: true) —

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

• ambiguous ('raise', 'earliest', 'latest', 'null') (defaults to: "raise") —

  Determine how to deal with ambiguous datetimes:

  • 'raise' (default): raise
  • 'earliest': use the earliest datetime
  • 'latest': use the latest datetime
  • 'null': set to null

Returns:

• (Expr)

# File 'lib/polars/string_expr.rb', line 210

def strptime(
  dtype,
  format = nil,
  strict: true,
  exact: true,
  cache: true,
  ambiguous: "raise"
)
  _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,
      ambiguous: ambiguous
    )
  elsif dtype == Time
    to_time(format, strict: strict, cache: cache)
  else
    raise ArgumentError, "dtype should be of type {Date, Datetime, Time}"
  end
end