String Expressions¶

All string operations are valid for both scalars and columns.

`StringValue` ¶

Bases: Value

Functions¶

`add(other)` ¶

Concatenate strings.

Parameters:

Name	Type	Description	Default
`other`	`str \| StringValue`	String to concatenate	required

Returns:

Type	Description
`StringValue`	All strings concatenated

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "bac", "bca"]})
>>> t
┏━━━━━━━━┓
┃ s      ┃
┡━━━━━━━━┩
│ string │
├────────┤
│ abc    │
│ bac    │
│ bca    │
└────────┘
>>> t.s + "z"
┏━━━━━━━━━━━━━━━━┓
┃ StringConcat() ┃
┡━━━━━━━━━━━━━━━━┩
│ string         │
├────────────────┤
│ abcz           │
│ bacz           │
│ bcaz           │
└────────────────┘
>>> t.s + t.s
┏━━━━━━━━━━━━━━━━┓
┃ StringConcat() ┃
┡━━━━━━━━━━━━━━━━┩
│ string         │
├────────────────┤
│ abcabc         │
│ bacbac         │
│ bcabca         │
└────────────────┘

`getitem(key)` ¶

Index or slice a string expression.

Parameters:

Name	Type	Description	Default
`key`	`slice \| int \| ir.IntegerScalar`	`int`, `slice` or integer scalar expression	required

Returns:

Type	Description
`StringValue`	Indexed or sliced string value

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"food": ["bread", "cheese", "rice"], "idx": [1, 2, 4]})
>>> t
┏━━━━━━━━┳━━━━━━━┓
┃ food   ┃ idx   ┃
┡━━━━━━━━╇━━━━━━━┩
│ string │ int64 │
├────────┼───────┤
│ bread  │     1 │
│ cheese │     2 │
│ rice   │     4 │
└────────┴───────┘
>>> t.food[0]
┏━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Substring(food, 0, 1) ┃
┡━━━━━━━━━━━━━━━━━━━━━━━┩
│ string                │
├───────────────────────┤
│ b                     │
│ c                     │
│ r                     │
└───────────────────────┘
>>> t.food[:3]
┏━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Substring(food, 0, 3) ┃
┡━━━━━━━━━━━━━━━━━━━━━━━┩
│ string                │
├───────────────────────┤
│ bre                   │
│ che                   │
│ ric                   │
└───────────────────────┘
>>> t.food[3:5]
┏━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Substring(food, 3, 2) ┃
┡━━━━━━━━━━━━━━━━━━━━━━━┩
│ string                │
├───────────────────────┤
│ ad                    │
│ es                    │
│ e                     │
└───────────────────────┘
>>> t.food[7]
┏━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Substring(food, 7, 1) ┃
┡━━━━━━━━━━━━━━━━━━━━━━━┩
│ string                │
├───────────────────────┤
│ ~                     │
│ ~                     │
│ ~                     │
└───────────────────────┘

`radd(other)` ¶

Concatenate strings.

Parameters:

Name	Type	Description	Default
`other`	`str \| StringValue`	String to concatenate	required

Returns:

Type	Description
`StringValue`	All strings concatenated

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "bac", "bca"]})
>>> t
┏━━━━━━━━┓
┃ s      ┃
┡━━━━━━━━┩
│ string │
├────────┤
│ abc    │
│ bac    │
│ bca    │
└────────┘
>>> "z" + t.s
┏━━━━━━━━━━━━━━━━┓
┃ StringConcat() ┃
┡━━━━━━━━━━━━━━━━┩
│ string         │
├────────────────┤
│ zabc           │
│ zbac           │
│ zbca           │
└────────────────┘

`ascii_str()` ¶

Return the numeric ASCII code of the first character of a string.

Returns:

Type	Description
`IntegerValue`	ASCII code of the first character of the input

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "def", "ghi"]})
>>> t.s.ascii_str()
┏━━━━━━━━━━━━━━━━┓
┃ StringAscii(s) ┃
┡━━━━━━━━━━━━━━━━┩
│ int32          │
├────────────────┤
│             97 │
│            100 │
│            103 │
└────────────────┘

`authority()` ¶

Parse a URL and extract authority.

Examples:

>>> import ibis
>>> url = ibis.literal("https://user:pass@example.com:80/docs/books")
>>> result = url.authority()  # user:pass@example.com:80

Returns:

Type	Description
`StringValue`	Extracted string value

`capitalize()` ¶

Capitalize the input string.

Returns:

Type	Description
`StringValue`	Capitalized string

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "def", "ghi"]})
>>> t.s.capitalize()
┏━━━━━━━━━━━━━━━┓
┃ Capitalize(s) ┃
┡━━━━━━━━━━━━━━━┩
│ string        │
├───────────────┤
│ Abc           │
│ Def           │
│ Ghi           │
└───────────────┘

`concat(other, *args)` ¶

Concatenate strings.

Parameters:

Name	Type	Description	Default
`other`	`str \| StringValue`	String to concatenate	required
`args`	`str \| StringValue`	Additional strings to concatenate	`()`

Returns:

Type	Description
`StringValue`	All strings concatenated

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "bac", "bca"]})
>>> t.s.concat("xyz")
┏━━━━━━━━━━━━━━━━┓
┃ StringConcat() ┃
┡━━━━━━━━━━━━━━━━┩
│ string         │
├────────────────┤
│ abcxyz         │
│ bacxyz         │
│ bcaxyz         │
└────────────────┘

`contains(substr)` ¶

Return whether the expression contains substr.

Parameters:

Name	Type	Description	Default
`substr`	`str \| StringValue`	Substring for which to check	required

Returns:

Type	Description
`BooleanValue`	Boolean indicating the presence of `substr` in the expression

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["bab", "ddd", "eaf"]})
>>> t.s.contains("a")
┏━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ StringContains(s, 'a') ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━┩
│ boolean                │
├────────────────────────┤
│ True                   │
│ False                  │
│ True                   │
└────────────────────────┘

`convert_base(from_base, to_base)` ¶

Convert a string representing an integer from one base to another.

Parameters:

Name	Type	Description	Default
`from_base`	`int \| ir.IntegerValue`	Numeric base of the expression	required
`to_base`	`int \| ir.IntegerValue`	New base	required

Returns:

Type	Description
`IntegerValue`	Converted expression

`endswith(end)` ¶

Determine if self ends with end.

Parameters:

Name	Type	Description	Default
`end`	`str \| StringValue`	Suffix to check for	required

Returns:

Type	Description
`BooleanValue`	Boolean indicating whether `self` ends with `end`

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["Ibis project", "GitHub"]})
>>> t.s.endswith("project")
┏━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ EndsWith(s, 'project') ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━┩
│ boolean                │
├────────────────────────┤
│ True                   │
│ False                  │
└────────────────────────┘

`file()` ¶

Parse a URL and extract file.

Examples:

>>> import ibis
>>> url = ibis.literal("https://example.com:80/docs/books/tutorial/index.html?name=networking")
>>> result = url.authority()  # docs/books/tutorial/index.html?name=networking

Returns:

Type	Description
`StringValue`	Extracted string value

`find(substr, start=None, end=None)` ¶

Return the position of the first occurence of substring.

Parameters:

Name	Type	Description	Default
`substr`	`str \| StringValue`	Substring to search for	required
`start`	`int \| ir.IntegerValue \| None`	Zero based index of where to start the search	`None`
`end`	`int \| ir.IntegerValue \| None`	Zero based index of where to stop the search. Currently not implemented.	`None`

Returns:

Type	Description
`IntegerValue`	Position of `substr` in `arg` starting from `start`

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "bac", "bca"]})
>>> t.s.find("a")
┏━━━━━━━━━━━━━━━━━━━━┓
┃ StringFind(s, 'a') ┃
┡━━━━━━━━━━━━━━━━━━━━┩
│ int64              │
├────────────────────┤
│                  0 │
│                  1 │
│                  2 │
└────────────────────┘
>>> t.s.find("z")
┏━━━━━━━━━━━━━━━━━━━━┓
┃ StringFind(s, 'z') ┃
┡━━━━━━━━━━━━━━━━━━━━┩
│ int64              │
├────────────────────┤
│                 -1 │
│                 -1 │
│                 -1 │
└────────────────────┘

`find_in_set(str_list)` ¶

Find the first occurence of str_list within a list of strings.

No string in str_list can have a comma.

Parameters:

Name	Type	Description	Default
`str_list`	`Sequence[str]`	Sequence of strings	required

Returns:

Type	Description
`IntegerValue`	Position of `str_list` in `self`. Returns -1 if `self` isn't found or if `self` contains `','`.

Examples:

>>> import ibis
>>> table = ibis.table(dict(string_col='string'))
>>> result = table.string_col.find_in_set(['a', 'b'])

`fragment()` ¶

Parse a URL and extract fragment identifier.

Examples:

>>> import ibis
>>> url = ibis.literal("https://example.com:80/docs/#DOWNLOADING")
>>> result = url.fragment()  # DOWNLOADING

Returns:

Type	Description
`StringValue`	Extracted string value

`hashbytes(how='sha256')` ¶

Compute the binary hash value of the input.

Parameters:

Name	Type	Description	Default
`how`	`Literal['md5', 'sha1', 'sha256', 'sha512']`	Hash algorithm to use	`'sha256'`

Returns:

Type	Description
`BinaryValue`	Binary expression

`host()` ¶

Parse a URL and extract host.

Examples:

>>> import ibis
>>> url = ibis.literal("https://user:pass@example.com:80/docs/books")
>>> result = url.authority()  # example.com

Returns:

Type	Description
`StringValue`	Extracted string value

`ilike(patterns)` ¶

Match patterns against self, case-insensitive.

This function is modeled after SQL's ILIKE directive. Use % as a multiple-character wildcard or _ as a single-character wildcard.

Use re_search or rlike for regular expression-based matching.

Parameters:

Name	Type	Description	Default
`patterns`	`str \| StringValue \| Iterable[str \| StringValue]`	If `pattern` is a list, then if any pattern matches the input then the corresponding row in the output is `True`.	required

Returns:

Type	Description
`BooleanValue`	Column indicating matches

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["Ibis project", "GitHub"]})
>>> t.s.ilike("%PROJect")
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ StringSQLILike(s, '%PROJect') ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ boolean                       │
├───────────────────────────────┤
│ True                          │
│ False                         │
└───────────────────────────────┘

`join(strings)` ¶

Join a list of strings using self as the separator.

Parameters:

Name	Type	Description	Default
`strings`	`Sequence[str \| StringValue] \| ir.ArrayValue`	Strings to join with `arg`	required

Returns:

Type	Description
`StringValue`	Joined string

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"arr": [["a", "b", "c"], None, [], ["b", None]]})
>>> t
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ arr                  ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<string>        │
├──────────────────────┤
│ ['a', 'b', ... +1]   │
│ ∅                    │
│ []                   │
│ ['b', None]          │
└──────────────────────┘
>>> ibis.literal("|").join(t.arr)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ArrayStringJoin('|', arr) ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ string                    │
├───────────────────────────┤
│ a|b|c                     │
│ ∅                         │
│ ∅                         │
│ b                         │
└───────────────────────────┘

`left(nchars)` ¶

Return the nchars left-most characters.

Parameters:

Name	Type	Description	Default
`nchars`	`int \| ir.IntegerValue`	Maximum number of characters to return	required

Returns:

Type	Description
`StringValue`	Characters from the start

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "defg", "hijlk"]})
>>> t.s.left(2)
┏━━━━━━━━━━━━━━━━━━━━┓
┃ Substring(s, 0, 2) ┃
┡━━━━━━━━━━━━━━━━━━━━┩
│ string             │
├────────────────────┤
│ ab                 │
│ de                 │
│ hi                 │
└────────────────────┘

`length()` ¶

Compute the length of a string.

Returns:

Type	Description
`IntegerValue`	The length of each string in the expression

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["aaa", "a", "aa"]})
>>> t.s.length()
┏━━━━━━━━━━━━━━━━━┓
┃ StringLength(s) ┃
┡━━━━━━━━━━━━━━━━━┩
│ int32           │
├─────────────────┤
│               3 │
│               1 │
│               2 │
└─────────────────┘

`like(patterns)` ¶

Match patterns against self, case-sensitive.

This function is modeled after the SQL LIKE directive. Use % as a multiple-character wildcard or _ as a single-character wildcard.

Use re_search or rlike for regular expression-based matching.

Parameters:

Name	Type	Description	Default
`patterns`	`str \| StringValue \| Iterable[str \| StringValue]`	If `pattern` is a list, then if any pattern matches the input then the corresponding row in the output is `True`.	required

Returns:

Type	Description
`BooleanValue`	Column indicating matches

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["Ibis project", "GitHub"]})
>>> t.s.like("%project")
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ StringSQLLike(s, '%project') ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ boolean                      │
├──────────────────────────────┤
│ True                         │
│ False                        │
└──────────────────────────────┘

`lower()` ¶

Convert string to all lowercase.

Returns:

Type	Description
`StringValue`	Lowercase string

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["AAA", "a", "AA"]})
>>> t
┏━━━━━━━━┓
┃ s      ┃
┡━━━━━━━━┩
│ string │
├────────┤
│ AAA    │
│ a      │
│ AA     │
└────────┘
>>> t.s.lower()
┏━━━━━━━━━━━━━━┓
┃ Lowercase(s) ┃
┡━━━━━━━━━━━━━━┩
│ string       │
├──────────────┤
│ aaa          │
│ a            │
│ aa           │
└──────────────┘

`lpad(length, pad=' ')` ¶

Pad arg by truncating on the right or padding on the left.

Parameters:

Name	Type	Description	Default
`length`	`int \| ir.IntegerValue`	Length of output string	required
`pad`	`str \| StringValue`	Pad character	`' '`

Returns:

Type	Description
`StringValue`	Left-padded string

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "def", "ghij"]})
>>> t.s.lpad(5, "-")
┏━━━━━━━━━━━━━━━━━┓
┃ LPad(s, 5, '-') ┃
┡━━━━━━━━━━━━━━━━━┩
│ string          │
├─────────────────┤
│ --abc           │
│ --def           │
│ -ghij           │
└─────────────────┘

`lstrip()` ¶

Remove whitespace from the left side of string.

Returns:

Type	Description
`StringValue`	Left-stripped string

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["\ta\t", "\nb\n", "\vc\t"]})
>>> t
┏━━━━━━━━┓
┃ s      ┃
┡━━━━━━━━┩
│ string │
├────────┤
│ \ta\t  │
│ \nb\n  │
│ \vc\t  │
└────────┘
>>> t.s.lstrip()
┏━━━━━━━━━━━┓
┃ LStrip(s) ┃
┡━━━━━━━━━━━┩
│ string    │
├───────────┤
│ a\t       │
│ b\n       │
│ c\t       │
└───────────┘

`path()` ¶

Parse a URL and extract path.

Examples:

>>> import ibis
>>> url = ibis.literal("https://example.com:80/docs/books/tutorial/index.html?name=networking")
>>> result = url.authority()  # docs/books/tutorial/index.html

Returns:

Type	Description
`StringValue`	Extracted string value

`protocol()` ¶

Parse a URL and extract protocol.

Examples:

>>> import ibis
>>> url = ibis.literal("https://user:pass@example.com:80/docs/books")
>>> result = url.protocol()  # https

Returns:

Type	Description
`StringValue`	Extracted string value

`query(key=None)` ¶

Parse a URL and returns query strring or query string parameter.

If key is passed, return the value of the query string parameter named. If key is absent, return the query string.

Parameters:

Name	Type	Description	Default
`key`	`str \| StringValue \| None`	Query component to extract	`None`

Examples:

>>> import ibis
>>> url = ibis.literal("https://example.com:80/docs/books/tutorial/index.html?name=networking")
>>> result = url.query()  # name=networking
>>> query_name = url.query('name')  # networking

Returns:

Type	Description
`StringValue`	Extracted string value

`re_extract(pattern, index)` ¶

Return the specified match at index from a regex pattern.

Parameters:

Name Type Description Default

pattern

str | StringValue

Reguar expression pattern string

required

index

int | ir.IntegerValue

The index of the match group to return.

The behavior of this function follows the behavior of Python's re.match: when index is zero and there's a match, return the entire string, otherwise return the content of the index-th match group.

required

Returns:

Type	Description
`StringValue`	Extracted match or whole string if `index` is zero

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "bac", "bca"]})

Extract a specific group

>>> t.s.re_extract(r"^(a)bc", 1)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ RegexExtract(s, '^(a)bc', 1) ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ string                       │
├──────────────────────────────┤
│ a                            │
│ ~                            │
│ ~                            │
└──────────────────────────────┘

Extract the entire match

>>> t.s.re_extract(r"^(a)bc", 0)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ RegexExtract(s, '^(a)bc', 0) ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ string                       │
├──────────────────────────────┤
│ abc                          │
│ ~                            │
│ ~                            │
└──────────────────────────────┘

`re_replace(pattern, replacement)` ¶

Replace match found by regex pattern with replacement.

Parameters:

Name	Type	Description	Default
`pattern`	`str \| StringValue`	Regular expression string	required
`replacement`	`str \| StringValue`	Replacement string or regular expression	required

Returns:

Type	Description
`StringValue`	Modified string

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "bac", "bca"]})
>>> t.s.re_replace("^(a)", "b")
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ RegexReplace(s, '^(a)', 'b') ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ string                       │
├──────────────────────────────┤
│ bbc                          │
│ bac                          │
│ bca                          │
└──────────────────────────────┘

`re_search(pattern)` ¶

Return whether the values match pattern.

Returns True if the regex matches a string and False otherwise.

Parameters:

Name	Type	Description	Default
`pattern`	`str \| StringValue`	Regular expression use for searching	required

Returns:

Type	Description
`BooleanValue`	Indicator of matches

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["Ibis project", "GitHub"]})
>>> t.s.re_search(".+Hub")
┏━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ RegexSearch(s, '.+Hub') ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ boolean                 │
├─────────────────────────┤
│ False                   │
│ True                    │
└─────────────────────────┘

`repeat(n)` ¶

Repeat a string n times.

Parameters:

Name	Type	Description	Default
`n`	`int \| ir.IntegerValue`	Number of repetitions	required

Returns:

Type	Description
`StringValue`	Repeated string

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["a", "bb", "c"]})
>>> t.s.repeat(5)
┏━━━━━━━━━━━━━━┓
┃ Repeat(s, 5) ┃
┡━━━━━━━━━━━━━━┩
│ string       │
├──────────────┤
│ aaaaa        │
│ bbbbbbbbbb   │
│ ccccc        │
└──────────────┘

`replace(pattern, replacement)` ¶

Replace each exact match of pattern with replacement.

Parameters:

Name	Type	Description	Default
`pattern`	`StringValue`	String pattern	required
`replacement`	`StringValue`	String replacement	required

Returns:

Type	Description
`StringValue`	Replaced string

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "bac", "bca"]})
>>> t.s.replace("b", "z")
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ StringReplace(s, 'b', 'z') ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ string                     │
├────────────────────────────┤
│ azc                        │
│ zac                        │
│ zca                        │
└────────────────────────────┘

`reverse()` ¶

Reverse the characters of a string.

Returns:

Type	Description
`StringValue`	Reversed string

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "def", "ghi"]})
>>> t
┏━━━━━━━━┓
┃ s      ┃
┡━━━━━━━━┩
│ string │
├────────┤
│ abc    │
│ def    │
│ ghi    │
└────────┘
>>> t.s.reverse()
┏━━━━━━━━━━━━┓
┃ Reverse(s) ┃
┡━━━━━━━━━━━━┩
│ string     │
├────────────┤
│ cba        │
│ fed        │
│ ihg        │
└────────────┘

`right(nchars)` ¶

Return up to nchars from the end of each string.

Parameters:

Name	Type	Description	Default
`nchars`	`int \| ir.IntegerValue`	Maximum number of characters to return	required

Returns:

Type	Description
`StringValue`	Characters from the end

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "defg", "hijlk"]})
>>> t.s.right(2)
┏━━━━━━━━━━━━━━━━┓
┃ StrRight(s, 2) ┃
┡━━━━━━━━━━━━━━━━┩
│ string         │
├────────────────┤
│ bc             │
│ fg             │
│ lk             │
└────────────────┘

`rpad(length, pad=' ')` ¶

Pad self by truncating or padding on the right.

Parameters:

Name	Type	Description	Default
`self`		String to pad	required
`length`	`int \| ir.IntegerValue`	Length of output string	required
`pad`	`str \| StringValue`	Pad character	`' '`

Returns:

Type	Description
`StringValue`	Right-padded string

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "def", "ghij"]})
>>> t.s.rpad(5, "-")
┏━━━━━━━━━━━━━━━━━┓
┃ RPad(s, 5, '-') ┃
┡━━━━━━━━━━━━━━━━━┩
│ string          │
├─────────────────┤
│ abc--           │
│ def--           │
│ ghij-           │
└─────────────────┘

`rstrip()` ¶

Remove whitespace from the right side of string.

Returns:

Type	Description
`StringValue`	Right-stripped string

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["\ta\t", "\nb\n", "\vc\t"]})
>>> t
┏━━━━━━━━┓
┃ s      ┃
┡━━━━━━━━┩
│ string │
├────────┤
│ \ta\t  │
│ \nb\n  │
│ \vc\t  │
└────────┘
>>> t.s.rstrip()
┏━━━━━━━━━━━┓
┃ RStrip(s) ┃
┡━━━━━━━━━━━┩
│ string    │
├───────────┤
│ \ta       │
│ \nb       │
│ \vc       │
└───────────┘

`split(delimiter)` ¶

Split as string on delimiter.

This API only works on backends with array support.

Parameters:

Name	Type	Description	Default
`delimiter`	`str \| StringValue`	Value to split by	required

Returns:

Type	Description
`ArrayValue`	The string split by `delimiter`

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"col": ["a,b,c", "d,e", "f"]})
>>> t
┏━━━━━━━━┓
┃ col    ┃
┡━━━━━━━━┩
│ string │
├────────┤
│ a,b,c  │
│ d,e    │
│ f      │
└────────┘
>>> t.col.split(",")
┏━━━━━━━━━━━━━━━━━━━━━━━┓
┃ StringSplit(col, ',') ┃
┡━━━━━━━━━━━━━━━━━━━━━━━┩
│ array<string>         │
├───────────────────────┤
│ ['a', 'b', ... +1]    │
│ ['d', 'e']            │
│ ['f']                 │
└───────────────────────┘

`startswith(start)` ¶

Determine whether self starts with end.

Parameters:

Name	Type	Description	Default
`start`	`str \| StringValue`	prefix to check for	required

Returns:

Type	Description
`BooleanValue`	Boolean indicating whether `self` starts with `start`

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["Ibis project", "GitHub"]})
>>> t.s.startswith("Ibis")
┏━━━━━━━━━━━━━━━━━━━━━━━┓
┃ StartsWith(s, 'Ibis') ┃
┡━━━━━━━━━━━━━━━━━━━━━━━┩
│ boolean               │
├───────────────────────┤
│ True                  │
│ False                 │
└───────────────────────┘

`strip()` ¶

Remove whitespace from left and right sides of a string.

Returns:

Type	Description
`StringValue`	Stripped string

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["\ta\t", "\nb\n", "\vc\t"]})
>>> t
┏━━━━━━━━┓
┃ s      ┃
┡━━━━━━━━┩
│ string │
├────────┤
│ \ta\t  │
│ \nb\n  │
│ \vc\t  │
└────────┘
>>> t.s.strip()
┏━━━━━━━━━━┓
┃ Strip(s) ┃
┡━━━━━━━━━━┩
│ string   │
├──────────┤
│ a        │
│ b        │
│ c        │
└──────────┘

`substr(start, length=None)` ¶

Extract a substring.

Parameters:

Name	Type	Description	Default
`start`	`int \| ir.IntegerValue`	First character to start splitting, indices start at 0	required
`length`	`int \| ir.IntegerValue \| None`	Maximum length of each substring. If not supplied, searches the entire string	`None`

Returns:

Type	Description
`StringValue`	Found substring

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "defg", "hijlk"]})
>>> t.s.substr(2)
┏━━━━━━━━━━━━━━━━━┓
┃ Substring(s, 2) ┃
┡━━━━━━━━━━━━━━━━━┩
│ string          │
├─────────────────┤
│ c               │
│ fg              │
│ jlk             │
└─────────────────┘

`to_timestamp(format_str)` ¶

Parse a string and return a timestamp.

Parameters:

Name	Type	Description	Default
`format_str`	`str`	Format string in `strptime` format	required

Returns:

Type	Description
`TimestampValue`	Parsed timestamp value

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"ts": ["20170206"]})
>>> t.ts.to_timestamp("%Y%m%d")
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ StringToTimestamp(ts, '%Y%m%d') ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ timestamp('UTC')                │
├─────────────────────────────────┤
│ 2017-02-06 00:00:00+00:00       │
└─────────────────────────────────┘

`translate(from_str, to_str)` ¶

Replace from_str characters in self characters in to_str.

To avoid unexpected behavior, from_str should be shorter than to_str.

Parameters:

Name	Type	Description	Default
`from_str`	`StringValue`	Characters in `arg` to replace	required
`to_str`	`StringValue`	Characters to use for replacement	required

Returns:

Type	Description
`StringValue`	Translated string

Examples:

>>> import ibis
>>> table = ibis.table(dict(string_col='string'))
>>> result = table.string_col.translate('a', 'b')

`upper()` ¶

Convert string to all uppercase.

Returns:

Type	Description
`StringValue`	Uppercase string

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["aaa", "A", "aa"]})
>>> t
┏━━━━━━━━┓
┃ s      ┃
┡━━━━━━━━┩
│ string │
├────────┤
│ aaa    │
│ A      │
│ aa     │
└────────┘
>>> t.s.upper()
┏━━━━━━━━━━━━━━┓
┃ Uppercase(s) ┃
┡━━━━━━━━━━━━━━┩
│ string       │
├──────────────┤
│ AAA          │
│ A            │
│ AA           │
└──────────────┘

`userinfo()` ¶

Parse a URL and extract user info.

Examples:

>>> import ibis
>>> url = ibis.literal("https://user:pass@example.com:80/docs/books")
>>> result = url.authority()  # user:pass

Returns:

Type	Description
`StringValue`	Extracted string value

Last update: August 5, 2022

String Expressions¶

StringValue ¶

Functions¶

__add__(other) ¶

__getitem__(key) ¶

__radd__(other) ¶

ascii_str() ¶

authority() ¶

capitalize() ¶

concat(other, *args) ¶

contains(substr) ¶

convert_base(from_base, to_base) ¶

endswith(end) ¶

file() ¶

find(substr, start=None, end=None) ¶

find_in_set(str_list) ¶

fragment() ¶

hashbytes(how='sha256') ¶

host() ¶

ilike(patterns) ¶

join(strings) ¶

See Also¶

left(nchars) ¶

length() ¶

like(patterns) ¶

lower() ¶

lpad(length, pad=' ') ¶

lstrip() ¶

path() ¶

protocol() ¶

query(key=None) ¶

re_extract(pattern, index) ¶

re_replace(pattern, replacement) ¶

re_search(pattern) ¶

repeat(n) ¶

replace(pattern, replacement) ¶

reverse() ¶

right(nchars) ¶

rpad(length, pad=' ') ¶

rstrip() ¶

split(delimiter) ¶

startswith(start) ¶

strip() ¶

substr(start, length=None) ¶

to_timestamp(format_str) ¶

translate(from_str, to_str) ¶

upper() ¶

userinfo() ¶

`StringValue` ¶

`add(other)` ¶

`getitem(key)` ¶

`radd(other)` ¶

`ascii_str()` ¶

`authority()` ¶

`capitalize()` ¶

`concat(other, *args)` ¶

`contains(substr)` ¶

`convert_base(from_base, to_base)` ¶

`endswith(end)` ¶

`file()` ¶

`find(substr, start=None, end=None)` ¶

`find_in_set(str_list)` ¶

`fragment()` ¶

`hashbytes(how='sha256')` ¶

`host()` ¶

`ilike(patterns)` ¶

`join(strings)` ¶

`left(nchars)` ¶

`length()` ¶

`like(patterns)` ¶

`lower()` ¶

`lpad(length, pad=' ')` ¶

`lstrip()` ¶

`path()` ¶

`protocol()` ¶

`query(key=None)` ¶

`re_extract(pattern, index)` ¶

`re_replace(pattern, replacement)` ¶

`re_search(pattern)` ¶

`repeat(n)` ¶

`replace(pattern, replacement)` ¶

`reverse()` ¶

`right(nchars)` ¶

`rpad(length, pad=' ')` ¶

`rstrip()` ¶

`split(delimiter)` ¶

`startswith(start)` ¶

`strip()` ¶

`substr(start, length=None)` ¶

`to_timestamp(format_str)` ¶

`translate(from_str, to_str)` ¶

`upper()` ¶

`userinfo()` ¶