Interface StringNamespace

namespace containing expr string functions

interface StringNamespace {
    concat(delimiter: string, ignoreNulls?: boolean): pl.Expr;
    contains(
        pat: string | RegExp | pl.Expr,
        literal?: boolean,
        strict?: boolean,
    ): pl.Expr;
    decode(encoding: "base64" | "hex", strict?: boolean): pl.Expr;
    decode(options: { encoding: "base64" | "hex"; strict?: boolean }): pl.Expr;
    encode(encoding: "base64" | "hex"): pl.Expr;
    extract(pat: any, groupIndex: number): pl.Expr;
    jsonDecode(dtype?: DataType, inferSchemaLength?: number): pl.Expr;
    jsonPathMatch(pat: string): pl.Expr;
    lengths(): pl.Expr;
    lstrip(): pl.Expr;
    padEnd(length: number, fillChar: string): pl.Expr;
    padStart(length: number, fillChar: string): pl.Expr;
    replace(pat: string | RegExp, val: string): pl.Expr;
    replaceAll(pat: string | RegExp, val: string): pl.Expr;
    rstrip(): pl.Expr;
    slice(start: number | pl.Expr, length?: number | pl.Expr): pl.Expr;
    split(by: string, options?: boolean | { inclusive?: boolean }): pl.Expr;
    strip(): pl.Expr;
    strptime(datatype: Date, fmt?: string): pl.Expr;
    strptime(datatype: Datetime, fmt?: string): pl.Expr;
    strptime(
        datatype: (
            timeUnit?: TimeUnit | "ms" | "ns" | "us",
            timeZone?: undefined | null | string,
        ) => Datetime,
        fmt?: string,
    ): pl.Expr;
    toLowerCase(): pl.Expr;
    toUpperCase(): pl.Expr;
    zFill(length: number | pl.Expr): pl.Expr;
}

Hierarchy

  • StringFunctions<pl.Expr>
    • StringNamespace

Methods

concat contains decode encode extract jsonDecode jsonPathMatch lengths lstrip padEnd padStart replace replaceAll rstrip slice split strip strptime toLowerCase toUpperCase zFill

Methods

concat

  • concat(delimiter: string, ignoreNulls?: boolean): pl.Expr

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

    Parameters

    • delimiter: string
    • OptionalignoreNulls: boolean

    Returns pl.Expr

    Example

    >>> df = pl.DataFrame({"foo": [1, null, 2]})
    >>> df = df.select(pl.col("foo").str.concat("-"))
    >>> df
    shape: (1, 1)
    ┌──────────┐
    │ foo      │
    │ ---      │
    │ str      │
    ╞══════════╡
    │ 1-null-2 │
    └──────────┘

contains

  • contains(
        pat: string | RegExp | pl.Expr,
        literal?: boolean,
        strict?: boolean,
    ): pl.Expr

    Check if strings in Series contain a substring that matches a pattern.

    Parameters

    • pat: string | RegExp | pl.Expr

      A valid regular expression pattern, compatible with the regex crate @param literal Treat pattern` as a literal string, not as a regular expression.

    • Optionalliteral: boolean
    • Optionalstrict: boolean

      Raise an error if the underlying pattern is not a valid regex, otherwise mask out with a null value.

    Returns pl.Expr

    Boolean mask

    Example

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

decode

  • decode(encoding: "base64" | "hex", strict?: boolean): pl.Expr

    Decodes a value using the provided encoding

    Parameters

    • encoding: "base64" | "hex"

      hex | base64

    • Optionalstrict: boolean

      how to handle invalid inputs

      - true: method will throw error if unable to decode a value
- false: unhandled values will be replaced with `null`

    Returns pl.Expr

    Example

    >>> df = pl.DataFrame({"strings": ["666f6f", "626172", null]})
    >>> df.select(col("strings").str.decode("hex"))
    shape: (3, 1)
    ┌─────────┐
    │ strings │
    │ ---     │
    │ str     │
    ╞═════════╡
    │ foo     │
    ├╌╌╌╌╌╌╌╌╌┤
    │ bar     │
    ├╌╌╌╌╌╌╌╌╌┤
    │ null    │
    └─────────┘
  • decode(options: { encoding: "base64" | "hex"; strict?: boolean }): pl.Expr

    Decodes a value using the provided encoding

    Parameters

    • options: { encoding: "base64" | "hex"; strict?: boolean }

    Returns pl.Expr

    Example

    > df = pl.DataFrame({"strings": ["666f6f", "626172", null]})
    > df.select(col("strings").str.decode("hex"))
    shape: (3, 1)
    ┌─────────┐
    │ strings │
    │ ---     │
    │ str     │
    ╞═════════╡
    │ foo     │
    ├╌╌╌╌╌╌╌╌╌┤
    │ bar     │
    ├╌╌╌╌╌╌╌╌╌┤
    │ null    │
    └─────────┘

encode

  • encode(encoding: "base64" | "hex"): pl.Expr

    Encodes a value using the provided encoding

    Parameters

    • encoding: "base64" | "hex"

      hex | base64

    Returns pl.Expr

    Example

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

extract

  • extract(pat: any, groupIndex: number): pl.Expr

    Extract the target capture group from provided patterns.

    Parameters

    • pat: any
    • groupIndex: number

      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 pl.Expr

    Utf8 array. Contain null if original value is null or regex capture nothing.

    Example

    > df = pl.DataFrame({
    ...   'a': [
    ...       'http://vote.com/ballon_dor?candidate=messi&ref=polars',
    ...       'http://vote.com/ballon_dor?candidat=jorginho&ref=polars',
    ...       'http://vote.com/ballon_dor?candidate=ronaldo&ref=polars'
    ...   ]})
    > df.select(pl.col('a').str.extract(/candidate=(\w+)/, 1))
    shape: (3, 1)
    ┌─────────┐
    │ a       │
    │ ---     │
    │ str     │
    ╞═════════╡
    │ messi   │
    ├╌╌╌╌╌╌╌╌╌┤
    │ null    │
    ├╌╌╌╌╌╌╌╌╌┤
    │ ronaldo │
    └─────────┘

jsonDecode

  • jsonDecode(dtype?: DataType, inferSchemaLength?: number): pl.Expr

    Parse string values as JSON. Throw errors if encounter invalid JSON strings.

    Parameters

    • Optionaldtype: DataType
    • OptionalinferSchemaLength: number

    Returns pl.Expr

    DF with struct

    Params

    Not implemented ATM

    Example

    >>> df = pl.DataFrame( {json: ['{"a":1, "b": true}', null, '{"a":2, "b": false}']} )
    >>> df.select(pl.col("json").str.jsonDecode())
    shape: (3, 1)
    ┌─────────────┐
    │ json        │
    │ ---         │
    │ struct[2]   │
    ╞═════════════╡
    │ {1,true}    │
    │ {null,null} │
    │ {2,false}   │
    └─────────────┘
    See Also
    ----------
    jsonPathMatch : Extract the first match of json string with provided JSONPath expression.

jsonPathMatch

  • jsonPathMatch(pat: string): pl.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.

    Parameters

    • pat: string

    Returns pl.Expr

    Utf8 array. Contain null if original value is null or the jsonPath return nothing.

    See

    https://goessner.net/articles/JsonPath/

    Example

    >>> df = pl.DataFrame({
    ...   'json_val': [
    ...     '{"a":"1"}',
    ...     null,
    ...     '{"a":2}',
    ...     '{"a":2.1}',
    ...     '{"a":true}'
    ...   ]
    ... })
    >>> df.select(pl.col('json_val').str.jsonPathMatch('$.a')
    shape: (5,)
    Series: 'json_val' [str]
    [
        "1"
        null
        "2"
        "2.1"
        "true"
    ]

lengths

lstrip

padEnd

  • padEnd(length: number, fillChar: string): pl.Expr

    Add a trailing fillChar to a string until string length is reached. If string is longer or equal to given length no modifications will be done

    Parameters

    • length: number

      of the final string

    • fillChar: string

      that will fill the string.

    Returns pl.Expr

    Note

    If a string longer than 1 character is provided only the first character will be used *

    Example

    > df = pl.DataFrame({
    ...   'foo': [
    ...       "a",
    ...       "b",
    ...       "LONG_WORD",
    ...       "cow"
    ...   ]})
    > df.select(pl.col('foo').str.padEnd("_", 3)
    shape: (4, 1)
    ┌──────────┐
    │ a        │
    │ -------- │
    │ str      │
    ╞══════════╡
    │ a__      │
    ├╌╌╌╌╌╌╌╌╌╌┤
    │ b__      │
    ├╌╌╌╌╌╌╌╌╌╌┤
    │ LONG_WORD│
    ├╌╌╌╌╌╌╌╌╌╌┤
    │ cow      │
    └──────────┘

padStart

  • padStart(length: number, fillChar: string): pl.Expr

    Add a leading fillChar to a string until string length is reached. If string is longer or equal to given length no modifications will be done

    Parameters

    • length: number

      of the final string

    • fillChar: string

      that will fill the string.

    Returns pl.Expr

    Note

    If a string longer than 1 character is provided only the first character will be used

    Example

    > df = pl.DataFrame({
    ...   'foo': [
    ...       "a",
    ...       "b",
    ...       "LONG_WORD",
    ...       "cow"
    ...   ]})
    > df.select(pl.col('foo').str.padStart("_", 3)
    shape: (4, 1)
    ┌──────────┐
    │ a        │
    │ -------- │
    │ str      │
    ╞══════════╡
    │ __a      │
    ├╌╌╌╌╌╌╌╌╌╌┤
    │ __b      │
    ├╌╌╌╌╌╌╌╌╌╌┤
    │ LONG_WORD│
    ├╌╌╌╌╌╌╌╌╌╌┤
    │ cow      │
    └──────────┘

replace

  • replace(pat: string | RegExp, val: string): pl.Expr

    Replace first regex match with a string value.

    Parameters

    • pat: string | RegExp
    • val: string

    Returns pl.Expr

replaceAll

  • replaceAll(pat: string | RegExp, val: string): pl.Expr

    Replace all regex matches with a string value.

    Parameters

    • pat: string | RegExp
    • val: string

    Returns pl.Expr

rstrip

slice

  • slice(start: number | pl.Expr, length?: number | pl.Expr): pl.Expr

    Create subslices of the string values of a Utf8 Series.

    Parameters

    • start: number | pl.Expr

      Start of the slice (negative indexing may be used).

    • Optionallength: number | pl.Expr

      Optional length of the slice.

    Returns pl.Expr

split

  • split(by: string, options?: boolean | { inclusive?: boolean }): pl.Expr

    Split a string into substrings using the specified separator and return them as a Series.

    Parameters

    • by: string
    • Optionaloptions: boolean | { inclusive?: boolean }

    Returns pl.Expr

strip

strptime

  • strptime(datatype: Date, fmt?: string): pl.Expr

    Parse a Series of dtype Utf8 to a Date/Datetime Series.

    Parameters

    • datatype: Date

      Date or Datetime.

    • Optionalfmt: string

      formatting syntax. Read more

    Returns pl.Expr

  • strptime(datatype: Datetime, fmt?: string): pl.Expr

    Parse a Series of dtype Utf8 to a Date/Datetime Series.

    Parameters

    • datatype: Datetime

      Date or Datetime.

    • Optionalfmt: string

      formatting syntax. Read more

    Returns pl.Expr

  • strptime(
        datatype: (
            timeUnit?: TimeUnit | "ms" | "ns" | "us",
            timeZone?: undefined | null | string,
        ) => Datetime,
        fmt?: string,
    ): pl.Expr

    Parse a Series of dtype Utf8 to a Date/Datetime Series.

    Parameters

    • datatype: (
          timeUnit?: TimeUnit | "ms" | "ns" | "us",
          timeZone?: undefined | null | string,
      ) => Datetime

      Date or Datetime.

        • (
              timeUnit?: TimeUnit | "ms" | "ns" | "us",
              timeZone?: undefined | null | string,
          ): Datetime

        • Calendar date and time type

          Parameters

          • OptionaltimeUnit: TimeUnit | "ms" | "ns" | "us"

            any of 'ms' | 'ns' | 'us'

          • timeZone: undefined | null | string = null

            timezone string as defined by Intl.DateTimeFormat America/New_York for example.

          Returns Datetime

    • Optionalfmt: string

      formatting syntax. Read more

    Returns pl.Expr

toLowerCase

toUpperCase

zFill

  • zFill(length: number | pl.Expr): pl.Expr

    Add leading "0" to a string until string length is reached. If string is longer or equal to given length no modifications will be done

    Parameters

    • length: number | pl.Expr

      of the final string

    Returns pl.Expr

    See

    padStart *

    Example

    > df = pl.DataFrame({
    ...   'foo': [
    ...       "a",
    ...       "b",
    ...       "LONG_WORD",
    ...       "cow"
    ...   ]})
    > df.select(pl.col('foo').str.justify(3)
    shape: (4, 1)
    ┌──────────┐
    │ a        │
    │ -------- │
    │ str      │
    ╞══════════╡
    │ 00a      │
    ├╌╌╌╌╌╌╌╌╌╌┤
    │ 00b      │
    ├╌╌╌╌╌╌╌╌╌╌┤
    │ LONG_WORD│
    ├╌╌╌╌╌╌╌╌╌╌┤
    │ cow      │
    └──────────┘

Settings

Member Visibility

On This Page

Methods