Interface StringNamespace

namespace containing expr string functions

interface StringNamespace {
    concat(delimiter: string, ignoreNulls?: boolean): pl.Expr;
    contains(pat: string | RegExp): 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;
    jsonExtract(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 jsonExtract jsonPathMatch lengths lstrip padEnd padStart replace replaceAll rstrip slice split strip strptime toLowerCase toUpperCase zFill

Methods

concat

  • concat(delimiter, ignoreNulls?): 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): pl.Expr

  • Check if strings in Series contain regex pattern.

    Parameters

    • pat: string | RegExp

    Returns pl.Expr

decode

  • decode(encoding, strict?): 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): pl.Expr

  • Decodes a value using the provided encoding

    Parameters

    • options: {
          encoding: "base64" | "hex";
          strict?: boolean;
      }
      • encoding: "base64" | "hex"
      • Optionalstrict?: 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): 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, groupIndex): 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?, inferSchemaLength?): 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.

jsonExtract

  • jsonExtract(dtype?, inferSchemaLength?): 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

    Deprecated

    Since

    0.8.4

    Use

    jsonDecode

    Example

    >>> df = pl.DataFrame( {json: ['{"a":1, "b": true}', null, '{"a":2, "b": false}']} )
    >>> df.select(pl.col("json").str.jsonExtract())
    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): 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, fillChar): 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, fillChar): 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, val): pl.Expr

  • Replace first regex match with a string value.

    Parameters

    • pat: string | RegExp
    • val: string

    Returns pl.Expr

replaceAll

  • replaceAll(pat, val): pl.Expr

  • Replace all regex matches with a string value.

    Parameters

    • pat: string | RegExp
    • val: string

    Returns pl.Expr

rstrip

slice

  • slice(start, length?): 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, options?): 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, fmt?): 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, fmt?): 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, fmt?): 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?, timeZone?): 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): 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