ascode/_documentation/starlark/built-in-methods.md

title	weight	toc
Built-in methods	10	true

Overview

This section lists the methods of built-in types. Methods are selected using dot expressions. For example, strings have a count method that counts occurrences of a substring; "banana".count("a") yields 3.

As with built-in functions, built-in methods accept only positional arguments except where noted. The parameter names serve merely as documentation.

dict·clear

D.clear() removes all the entries of dictionary D and returns None. It fails if the dictionary is frozen or if there are active iterators.

x = {"one": 1, "two": 2}
x.clear()                               # None
print(x)                                # {}

dict·get

D.get(key[, default]) returns the dictionary value corresponding to the given key. If the dictionary contains no such value, get returns None, or the value of the optional default parameter if present.

get fails if key is unhashable, or the dictionary is frozen or has active iterators.

x = {"one": 1, "two": 2}
x.get("one")                            # 1
x.get("three")                          # None
x.get("three", 0)                       # 0

dict·items

D.items() returns a new list of key/value pairs, one per element in dictionary D, in the same order as they would be returned by a for loop.

x = {"one": 1, "two": 2}
x.items()                               # [("one", 1), ("two", 2)]

dict·keys

D.keys() returns a new list containing the keys of dictionary D, in the same order as they would be returned by a for loop.

x = {"one": 1, "two": 2}
x.keys()                               # ["one", "two"]

dict·pop

D.pop(key[, default]) returns the value corresponding to the specified key, and removes it from the dictionary. If the dictionary contains no such value, and the optional default parameter is present, pop returns that value; otherwise, it fails.

pop fails if key is unhashable, or the dictionary is frozen or has active iterators.

x = {"one": 1, "two": 2}
x.pop("one")                            # 1
x                                       # {"two": 2}
x.pop("three", 0)                       # 0
x.pop("four")                           # error: missing key

dict·popitem

D.popitem() returns the first key/value pair, removing it from the dictionary.

popitem fails if the dictionary is empty, frozen, or has active iterators.

x = {"one": 1, "two": 2}
x.popitem()                             # ("one", 1)
x.popitem()                             # ("two", 2)
x.popitem()                             # error: empty dict

dict·setdefault

D.setdefault(key[, default]) returns the dictionary value corresponding to the given key. If the dictionary contains no such value, setdefault, like get, returns None or the value of the optional default parameter if present; setdefault additionally inserts the new key/value entry into the dictionary.

setdefault fails if the key is unhashable, or if the dictionary is frozen or has active iterators.

x = {"one": 1, "two": 2}
x.setdefault("one")                     # 1
x.setdefault("three", 0)                # 0
x                                       # {"one": 1, "two": 2, "three": 0}
x.setdefault("four")                    # None
x                                       # {"one": 1, "two": 2, "three": None}

dict·update

D.update([pairs][, name=value[, ...]) makes a sequence of key/value insertions into dictionary D, then returns None.

If the positional argument pairs is present, it must be None, another dict, or some other iterable. If it is another dict, then its key/value pairs are inserted into D. If it is an iterable, it must provide a sequence of pairs (or other iterables of length 2), each of which is treated as a key/value pair to be inserted into D.

For each name=value argument present, the name is converted to a string and used as the key for an insertion into D, with its corresponding value being value.

update fails if the dictionary is frozen or has active iterators.

x = {}
x.update([("a", 1), ("b", 2)], c=3)
x.update({"d": 4})
x.update(e=5)
x                                       # {"a": 1, "b": "2", "c": 3, "d": 4, "e": 5}

dict·values

D.values() returns a new list containing the dictionary's values, in the same order as they would be returned by a for loop over the dictionary.

x = {"one": 1, "two": 2}
x.values()                              # [1, 2]

list·append

L.append(x) appends x to the list L, and returns None.

append fails if the list is frozen or has active iterators.

x = []
x.append(1)                             # None
x.append(2)                             # None
x.append(3)                             # None
x                                       # [1, 2, 3]

list·clear

L.clear() removes all the elements of the list L and returns None. It fails if the list is frozen or if there are active iterators.

x = [1, 2, 3]
x.clear()                               # None
x                                       # []

list·extend

L.extend(x) appends the elements of x, which must be iterable, to the list L, and returns None.

extend fails if x is not iterable, or if the list L is frozen or has active iterators.

x = []
x.extend([1, 2, 3])                     # None
x.extend(["foo"])                       # None
x                                       # [1, 2, 3, "foo"]

list·index

L.index(x[, start[, end]]) finds x within the list L and returns its index.

The optional start and end parameters restrict the portion of list L that is inspected. If provided and not None, they must be list indices of type int. If an index is negative, len(L) is effectively added to it, then if the index is outside the range [0:len(L)], the nearest value within that range is used; see Indexing.

index fails if x is not found in L, or if start or end is not a valid index (int or None).

x = list("banana".codepoints())
x.index("a")                            # 1 (bAnana)
x.index("a", 2)                         # 3 (banAna)
x.index("a", -2)                        # 5 (bananA)

list·insert

L.insert(i, x) inserts the value x in the list L at index i, moving higher-numbered elements along by one. It returns None.

As usual, the index i must be an int. If its value is negative, the length of the list is added, then its value is clamped to the nearest value in the range [0:len(L)] to yield the effective index.

insert fails if the list is frozen or has active iterators.

x = ["b", "c", "e"]
x.insert(0, "a")                        # None
x.insert(-1, "d")                       # None
x                                       # ["a", "b", "c", "d", "e"]

list·pop

L.pop([index]) removes and returns the last element of the list L, or, if the optional index is provided, at that index.

pop fails if the index is not valid for L[i], or if the list is frozen or has active iterators.

x = [1, 2, 3, 4, 5]
x.pop()                                 # 5
x                                       # [1, 2, 3, 4]
x.pop(-2)                               # 3
x                                       # [1, 2, 4]
x.pop(-3)                               # 1
x                                       # [2, 4]
x.pop()                                 # 4
x                                       # [2]

list·remove

L.remove(x) removes the first occurrence of the value x from the list L, and returns None.

remove fails if the list does not contain x, is frozen, or has active iterators.

x = [1, 2, 3, 2]
x.remove(2)                             # None (x == [1, 3, 2])
x.remove(2)                             # None (x == [1, 3])
x.remove(2)                             # error: element not found

set·union

S.union(iterable) returns a new set into which have been inserted all the elements of set S and all the elements of the argument, which must be iterable.

union fails if any element of the iterable is not hashable.

x = set([1, 2])
y = set([2, 3])
x.union(y)                              # set([1, 2, 3])

string·elem_ords

S.elem_ords() returns an iterable value containing the sequence of numeric bytes values in the string S.

To materialize the entire sequence of bytes, apply list(...) to the result.

Example:

list("Hello, 世界".elem_ords())        # [72, 101, 108, 108, 111, 44, 32, 228, 184, 150, 231, 149, 140]

See also: string·elems.

Implementation note: elem_ords is not provided by the Java implementation.

string·capitalize

S.capitalize() returns a copy of string S with its first code point changed to its title case and all subsequent letters changed to their lower case.

"hello, world!".capitalize()		# "Hello, world!"
"hElLo, wOrLd!".capitalize()		# "Hello, world!"
"¿Por qué?".capitalize()		# "¿por qué?"

string·codepoint_ords

S.codepoint_ords() returns an iterable value containing the sequence of integer Unicode code points encoded by the string S. Each invalid code within the string is treated as if it encodes the Unicode replacement character, U+FFFD.

By returning an iterable, not a list, the cost of decoding the string is deferred until actually needed; apply list(...) to the result to materialize the entire sequence.

Example:

list("Hello, 世界".codepoint_ords())        # [72, 101, 108, 108, 111, 44, 32, 19990, 30028]

for cp in "Hello, 世界".codepoint_ords():
   print(chr(cp))  # prints 'H', 'e', 'l', 'l', 'o', ',', ' ', '世', '界'

See also: string·codepoints.

Implementation note: codepoint_ords is not provided by the Java implementation.

string·count

S.count(sub[, start[, end]]) returns the number of occcurences of sub within the string S, or, if the optional substring indices start and end are provided, within the designated substring of S. They are interpreted according to Starlark's indexing conventions.

"hello, world!".count("o")              # 2
"hello, world!".count("o", 7, 12)       # 1  (in "world")

string·endswith

S.endswith(suffix[, start[, end]]) reports whether the string S[start:end] has the specified suffix.

"filename.star".endswith(".star")         # True

The suffix argument may be a tuple of strings, in which case the function reports whether any one of them is a suffix.

'foo.cc'.endswith(('.cc', '.h'))         # True

string·find

S.find(sub[, start[, end]]) returns the index of the first occurrence of the substring sub within S.

If either or both of start or end are specified, they specify a subrange of S to which the search should be restricted. They are interpreted according to Starlark's indexing conventions.

If no occurrence is found, found returns -1.

"bonbon".find("on")             # 1
"bonbon".find("on", 2)          # 4
"bonbon".find("on", 2, 5)       # -1

string·format

S.format(*args, **kwargs) returns a version of the format string S in which bracketed portions {...} are replaced by arguments from args and kwargs.

Within the format string, a pair of braces {{ or }} is treated as a literal open or close brace. Each unpaired open brace must be matched by a close brace }. The optional text between corresponding open and close braces specifies which argument to use and how to format it, and consists of three components, all optional: a field name, a conversion preceded by '!', and a format specifier preceded by ':'.

{field}
{field:spec}
{field!conv}
{field!conv:spec}

The field name may be either a decimal number or a keyword. A number is interpreted as the index of a positional argument; a keyword specifies the value of a keyword argument. If all the numeric field names form the sequence 0, 1, 2, and so on, they may be omitted and those values will be implied; however, the explicit and implicit forms may not be mixed.

The conversion specifies how to convert an argument value x to a string. It may be either !r, which converts the value using repr(x), or !s, which converts the value using str(x) and is the default.

The format specifier, after a colon, specifies field width, alignment, padding, and numeric precision. Currently it must be empty, but it is reserved for future use.

"a{x}b{y}c{}".format(1, x=2, y=3)               # "a2b3c1"
"a{}b{}c".format(1, 2)                          # "a1b2c"
"({1}, {0})".format("zero", "one")              # "(one, zero)"
"Is {0!r} {0!s}?".format('heterological')       # 'is "heterological" heterological?'

string·index

S.index(sub[, start[, end]]) returns the index of the first occurrence of the substring sub within S, like S.find, except that if the substring is not found, the operation fails.

"bonbon".index("on")             # 1
"bonbon".index("on", 2)          # 4
"bonbon".index("on", 2, 5)       # error: substring not found  (in "nbo")

string·isalnum

S.isalnum() reports whether the string S is non-empty and consists only Unicode letters and digits.

"base64".isalnum()              # True
"Catch-22".isalnum()            # False

string·isalpha

S.isalpha() reports whether the string S is non-empty and consists only of Unicode letters.

"ABC".isalpha()                 # True
"Catch-22".isalpha()            # False
"".isalpha()                    # False

string·isdigit

S.isdigit() reports whether the string S is non-empty and consists only of Unicode digits.

"123".isdigit()                 # True
"Catch-22".isdigit()            # False
"".isdigit()                    # False

string·islower

S.islower() reports whether the string S contains at least one cased Unicode letter, and all such letters are lowercase.

"hello, world".islower()        # True
"Catch-22".islower()            # False
"123".islower()                 # False

string·isspace

S.isspace() reports whether the string S is non-empty and consists only of Unicode spaces.

"    ".isspace()                # True
"\r\t\n".isspace()              # True
"".isspace()                    # False

string·istitle

S.istitle() reports whether the string S contains at least one cased Unicode letter, and all such letters that begin a word are in title case.

"Hello, World!".istitle()       # True
"Catch-22".istitle()            # True
"HAL-9000".istitle()            # False
"Dženan".istitle()		# True
"DŽenan".istitle()		# False ("DŽ" is a single Unicode letter)
"123".istitle()                 # False

string·isupper

S.isupper() reports whether the string S contains at least one cased Unicode letter, and all such letters are uppercase.

"HAL-9000".isupper()            # True
"Catch-22".isupper()            # False
"123".isupper()                 # False

string·join

S.join(iterable) returns the string formed by concatenating each element of its argument, with a copy of the string S between successive elements. The argument must be an iterable whose elements are strings.

", ".join(["one", "two", "three"])      # "one, two, three"
"a".join("ctmrn".codepoints())          # "catamaran"

string·lower

S.lower() returns a copy of the string S with letters converted to lowercase.

"Hello, World!".lower()                 # "hello, world!"

string·lstrip

S.lstrip() returns a copy of the string S with leading whitespace removed.

Like strip, it accepts an optional string parameter that specifies an alternative set of Unicode code points to remove.

"  hello  ".lstrip()                    # "hello  "
"  hello  ".lstrip("h o")               # "ello  "

string·partition

S.partition(x) splits string S into three parts and returns them as a tuple: the portion before the first occurrence of string x, x itself, and the portion following it. If S does not contain x, partition returns (S, "", "").

partition fails if x is not a string, or is the empty string.

"one/two/three".partition("/")		# ("one", "/", "two/three")

string·replace

S.replace(old, new[, count]) returns a copy of string S with all occurrences of substring old replaced by new. If the optional argument count, which must be an int, is non-negative, it specifies a maximum number of occurrences to replace.

"banana".replace("a", "o")		# "bonono"
"banana".replace("a", "o", 2)		# "bonona"

string·rfind

S.rfind(sub[, start[, end]]) returns the index of the substring sub within S, like S.find, except that rfind returns the index of the substring's last occurrence.

"bonbon".rfind("on")             # 4
"bonbon".rfind("on", None, 5)    # 1
"bonbon".rfind("on", 2, 5)       # -1

string·rindex

S.rindex(sub[, start[, end]]) returns the index of the substring sub within S, like S.index, except that rindex returns the index of the substring's last occurrence.

"bonbon".rindex("on")             # 4
"bonbon".rindex("on", None, 5)    # 1                           (in "bonbo")
"bonbon".rindex("on", 2, 5)       # error: substring not found  (in "nbo")

string·rpartition

S.rpartition(x) is like partition, but splits S at the last occurrence of x.

"one/two/three".partition("/")		# ("one/two", "/", "three")

string·rsplit

S.rsplit([sep[, maxsplit]]) splits a string into substrings like S.split, except that when a maximum number of splits is specified, rsplit chooses the rightmost splits.

"banana".rsplit("n")                         # ["ba", "a", "a"]
"banana".rsplit("n", 1)                      # ["bana", "a"]
"one two  three".rsplit(None, 1)             # ["one two", "three"]
"".rsplit("n")                               # [""]

string·rstrip

S.rstrip() returns a copy of the string S with trailing whitespace removed.

Like strip, it accepts an optional string parameter that specifies an alternative set of Unicode code points to remove.

"  hello  ".rstrip()                    # "  hello"
"  hello  ".rstrip("h o")               # "  hell"

string·split

S.split([sep [, maxsplit]]) returns the list of substrings of S, splitting at occurrences of the delimiter string sep.

Consecutive occurrences of sep are considered to delimit empty strings, so 'food'.split('o') returns ['f', '', 'd']. Splitting an empty string with a specified separator returns ['']. If sep is the empty string, split fails.

If sep is not specified or is None, split uses a different algorithm: it removes all leading spaces from S (or trailing spaces in the case of rsplit), then splits the string around each consecutive non-empty sequence of Unicode white space characters. If S consists only of white space, S.split() returns the empty list.

If maxsplit is given and non-negative, it specifies a maximum number of splits.

"one two  three".split()                    # ["one", "two", "three"]
"one two  three".split(" ")                 # ["one", "two", "", "three"]
"one two  three".split(None, 1)             # ["one", "two  three"]
"banana".split("n")                         # ["ba", "a", "a"]
"banana".split("n", 1)                      # ["ba", "ana"]
"".split("n")                               # [""]

string·elems

S.elems() returns an iterable value containing successive 1-byte substrings of S. To materialize the entire sequence, apply list(...) to the result.

Example:

list('Hello, 世界'.elems())  # ["H", "e", "l", "l", "o", ",", " ", "\xe4", "\xb8", "\x96", "\xe7", "\x95", "\x8c"]

See also: string·elem_ords.

string·codepoints

S.codepoints() returns an iterable value containing the sequence of substrings of S that each encode a single Unicode code point. Each invalid code within the string is treated as if it encodes the Unicode replacement character, U+FFFD.

By returning an iterable, not a list, the cost of decoding the string is deferred until actually needed; apply list(...) to the result to materialize the entire sequence.

Example:

list('Hello, 世界'.codepoints())  # ['H', 'e', 'l', 'l', 'o', ',', ' ', '世', '界']

for cp in 'Hello, 世界'.codepoints():
   print(cp)  # prints 'H', 'e', 'l', 'l', 'o', ',', ' ', '世', '界'

See also: string·codepoint_ords.

Implementation note: codepoints is not provided by the Java implementation.

string·splitlines

S.splitlines([keepends]) returns a list whose elements are the successive lines of S, that is, the strings formed by splitting S at line terminators (currently assumed to be a single newline, \n, regardless of platform).

The optional argument, keepends, is interpreted as a Boolean. If true, line terminators are preserved in the result, though the final element does not necessarily end with a line terminator.

As a special case, if S is the empty string, splitlines returns the empty list.

"one\n\ntwo".splitlines()       # ["one", "", "two"]
"one\n\ntwo".splitlines(True)   # ["one\n", "\n", "two"]
"".splitlines()                 # [] -- a special case

string·startswith

S.startswith(prefix[, start[, end]]) reports whether the string S[start:end] has the specified prefix.

"filename.star".startswith("filename")         # True

The prefix argument may be a tuple of strings, in which case the function reports whether any one of them is a prefix.

'abc'.startswith(('a', 'A'))                  # True
'ABC'.startswith(('a', 'A'))                  # True
'def'.startswith(('a', 'A'))                  # False

string·strip

S.strip() returns a copy of the string S with leading and trailing whitespace removed.

It accepts an optional string argument: S.strip(cutset) instead removes all leading and trailing Unicode code points contained in cutset.

"  hello  ".strip()                     # "hello"
"  hello  ".strip("h o")                # "ell"

string·title

S.title() returns a copy of the string S with letters converted to title case.

Letters are converted to upper case at the start of words, lower case elsewhere.

"hElLo, WoRlD!".title()                 # "Hello, World!"
"dženan".title()                        # "Dženan" ("Dž" is a single Unicode letter)

string·upper

S.upper() returns a copy of the string S with letters converted to uppercase.

"Hello, World!".upper()                 # "HELLO, WORLD!"