StringValue

StringValue(arg)

Methods

Name	Description
as_date	Parse a string and return a date.
as_timestamp	Parse a string and return a timestamp.
ascii_str	Return the numeric ASCII code of the first character of a string.
authority	Parse a URL and extract authority.
capitalize	Uppercase the first letter, lowercase the rest.
concat	Concatenate strings.
contains	Return whether the expression contains substr.
convert_base	Convert a string representing an integer from one base to another.
endswith	Determine if self ends with end.
file	Parse a URL and extract file.
find	Return the position of the first occurrence of substring.
find_in_set	Find the first occurrence of str_list within a list of strings.
fragment	Parse a URL and extract fragment identifier.
hashbytes	Compute the binary hash value of the input.
hexdigest	Return the hash digest of the input as a hex encoded string.
host	Parse a URL and extract host.
ilike	Match patterns against self, case-insensitive.
initcap	Deprecated. Use capitalize instead.
join	Join a list of strings using self as the separator.
left	Return the nchars left-most characters.
length	Compute the length of a string.
levenshtein	Return the Levenshtein distance between two strings.
like	Match patterns against self, case-sensitive.
lower	Convert string to all lowercase.
lpad	Pad arg by truncating on the right or padding on the left.
lstrip	Remove whitespace from the left side of string.
path	Parse a URL and extract path.
protocol	Parse a URL and extract protocol.
query	Parse a URL and returns query string or query string parameter.
re_extract	Return the specified match at index from a regex pattern.
re_replace	Replace all matches found by regex pattern with replacement.
re_search	Return whether the values match pattern.
re_split	Split a string by a regular expression pattern.
repeat	Repeat a string n times.
replace	Replace each exact match of pattern with replacement.
reverse	Reverse the characters of a string.
right	Return up to nchars from the end of each string.
rpad	Pad self by truncating or padding on the right.
rstrip	Remove whitespace from the right side of string.
split	Split as string on delimiter.
startswith	Determine whether self starts with start.
strip	Remove whitespace from left and right sides of a string.
substr	Extract a substring.
translate	Replace from_str characters in self characters in to_str.
upper	Convert string to all uppercase.
userinfo	Parse a URL and extract user info.

as_date

as_date(format_str)

Parse a string and return a date.

Parameters

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

Returns

Name	Type	Description
	DateValue	Parsed date value

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"ts": ["20170206"]})
>>> t.ts.as_date("%Y%m%d")

as_timestamp

as_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

Name	Type	Description
	TimestampValue	Parsed timestamp value

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"ts": ["20170206"]})
>>> t.ts.as_timestamp("%Y%m%d")

ascii_str

ascii_str()

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

Returns

Name	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()

authority

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

Name	Type	Description
	StringValue	Extracted string value

capitalize

capitalize()

Uppercase the first letter, lowercase the rest.

This API matches the semantics of the Python method.

Returns

Name	Type	Description
	StringValue	Capitalized string

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["aBC", " abc", "ab cd", None]})
>>> t.s.capitalize()

concat

concat(other, *args)

Concatenate strings.

NULLs are propagated. This methods is equivalent to using the + operator.

Parameters

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

Returns

Name	Type	Description
	StringValue	All strings concatenated

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", None]})
>>> t.s.concat("xyz", "123")

>>> t.s + "xyz"

contains

contains(substr)

Return whether the expression contains substr.

Parameters

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

Returns

Name	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")

convert_base

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

Name	Type	Description
	IntegerValue	Converted expression

endswith

endswith(end)

Determine if self ends with end.

Parameters

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

Returns

Name	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")

file

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.file()  # docs/books/tutorial/index.html?name=networking

Returns

Name	Type	Description
	StringValue	Extracted string value

find

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

Return the position of the first occurrence 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

Name	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")

>>> t.s.find("z")

find_in_set

find_in_set(str_list)

Find the first occurrence 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

Name	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

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

Name	Type	Description
	StringValue	Extracted string value

hashbytes

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

Name	Type	Description
	BinaryValue	Binary expression

hexdigest

hexdigest(how='sha256')

Return the hash digest of the input as a hex encoded string.

Parameters

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

Returns

Name	Type	Description
	StringValue	Hexadecimal representation of the hash as a string

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"species": ["Adelie", "Chinstrap", "Gentoo"]})
>>> t.species.hexdigest()

host

host()

Parse a URL and extract host.

Examples

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

Returns

Name	Type	Description
	StringValue	Extracted string value

ilike

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

Name	Type	Description
	BooleanValue	Column indicating matches

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["Ibis project", "GitHub"]})
>>> t.s.ilike("%PROJect")

initcap

initcap()

Deprecated. Use capitalize instead.

join

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

Name	Type	Description
	StringValue	Joined string

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"arr": [["a", "b", "c"], None, [], ["b", None]]})
>>> t

>>> ibis.literal("|").join(t.arr)

See Also

ArrayValue.join

left

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

Name	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)

length

length()

Compute the length of a string.

Returns

Name	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()

levenshtein

levenshtein(other)

Return the Levenshtein distance between two strings.

Parameters

Name	Type	Description	Default
other	StringValue	String to compare to	required

Returns

Name	Type	Description
	IntegerValue	The edit distance between the two strings

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> s = ibis.literal("kitten")
>>> s.levenshtein("sitting")

like

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

Name	Type	Description
	BooleanValue	Column indicating matches

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["Ibis project", "GitHub"]})
>>> t.s.like("%project")

lower

lower()

Convert string to all lowercase.

Returns

Name	Type	Description
	StringValue	Lowercase string

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["AAA", "a", "AA"]})
>>> t

>>> t.s.lower()

lpad

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

Name	Type	Description
	StringValue	Left-padded string

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "def", "ghij"]})
>>> t.s.lpad(5, "-")

lstrip

lstrip()

Remove whitespace from the left side of string.

Returns

Name	Type	Description
	StringValue	Left-stripped string

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["\ta\t", "\nb\n", "\vc\t"]})
>>> t

>>> t.s.lstrip()

path

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.path()  # docs/books/tutorial/index.html

Returns

Name	Type	Description
	StringValue	Extracted string value

protocol

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

Name	Type	Description
	StringValue	Extracted string value

query

query(key=None)

Parse a URL and returns query string 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

Name	Type	Description
	StringValue	Extracted string value

re_extract

re_extract(pattern, index)

Return the specified match at index from a regex pattern.

Parameters

Name	Type	Description	Default
pattern	str | StringValue	Regular 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 match objects: when index is zero and there’s a match, return the entire match, otherwise return the content of the index-th match group.	required

Returns

Name	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)

Extract the entire match

>>> t.s.re_extract(r"^(a)bc", 0)

re_replace

re_replace(pattern, replacement)

Replace all matches 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

Name	Type	Description
	StringValue	Modified string

Examples

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

Replace all “a”s that are at the beginning of the string with “b”:

>>> s.re_replace("^a", "b")

Double up any “a”s or “b”s, using capture groups and backreferences:

>>> s.re_replace("([ab])", r"\0\0")

Normalize all whitespace to a single space:

>>> s.re_replace(r"\s+", " ")

re_search

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

Name	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")

re_split

re_split(pattern)

Split a string by a regular expression pattern.

Parameters

Name	Type	Description	Default
pattern	str | StringValue	Regular expression string to split by	required

Returns

Name	Type	Description
	ArrayValue	Array of strings from splitting by pattern

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable(dict(s=["a.b", "b.....c", "c.........a", "def"]))
>>> t.s

>>> t.s.re_split(r"\.+").name("splits")

repeat

repeat(n)

Repeat a string n times.

Parameters

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

Returns

Name	Type	Description
	StringValue	Repeated string

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["a", "bb", "c"]})
>>> t.s.repeat(5)

replace

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

Name	Type	Description
	StringValue	Replaced string

Examples

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

reverse

reverse()

Reverse the characters of a string.

Returns

Name	Type	Description
	StringValue	Reversed string

Examples

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

>>> t.s.reverse()

right

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

Name	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)

rpad

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

Name	Type	Description
	StringValue	Right-padded string

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "def", "ghij"]})
>>> t.s.rpad(5, "-")

rstrip

rstrip()

Remove whitespace from the right side of string.

Returns

Name	Type	Description
	StringValue	Right-stripped string

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["\ta\t", "\nb\n", "\vc\t"]})
>>> t

>>> t.s.rstrip()

split

split(delimiter)

Split as string on delimiter.

NoteThis API only works on backends with array support.

Parameters

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

Returns

Name	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

>>> t.col.split(",")

startswith

startswith(start)

Determine whether self starts with start.

Parameters

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

Returns

Name	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")

strip

strip()

Remove whitespace from left and right sides of a string.

Returns

Name	Type	Description
	StringValue	Stripped string

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["\ta\t", "\nb\n", "\vc\t"]})
>>> t

>>> t.s.strip()

substr

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

Name	Type	Description
	StringValue	Found substring

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["abc", "defg", "hijlk"]})
>>> t.s.substr(2)

translate

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

Name	Type	Description
	StringValue	Translated string

Examples

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

upper

upper()

Convert string to all uppercase.

Returns

Name	Type	Description
	StringValue	Uppercase string

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"s": ["aaa", "A", "aa"]})
>>> t

>>> t.s.upper()

userinfo

userinfo()

Parse a URL and extract user info.

Examples

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

Returns

Name	Type	Description
	StringValue	Extracted string value