Data Types

These are the main data types built in to the interpreter:

NoneType                     # the type of None
bool                         # True or False
int                          # a signed integer of arbitrary magnitude
float                        # an IEEE 754 double-precision floating point number
string                       # a byte string
list                         # a modifiable sequence of values
tuple                        # an unmodifiable sequence of values
dict                         # a mapping from values to values
set                          # a set of values
function                     # a function implemented in Starlark
builtin_function_or_method   # a function or method implemented by the interpreter or host application

Some functions, such as the iteration methods of string, or the range function, return instances of special-purpose types that don't appear in this list. Additional data types may be defined by the host application into which the interpreter is embedded, and those data types may participate in basic operations of the language such as arithmetic, comparison, indexing, and function calls.

Some operations can be applied to any Starlark value. For example, every value has a type string that can be obtained with the expression type(x), and any value may be converted to a string using the expression str(x), or to a Boolean truth value using the expression bool(x). Other operations apply only to certain types. For example, the indexing operation a[i] works only with strings, lists, and tuples, and any application-defined types that are indexable. The value concepts section explains the groupings of types by the operators they support.

None

None is a distinguished value used to indicate the absence of any other value. For example, the result of a call to a function that contains no return statement is None.

None is equal only to itself. Its type is "NoneType". The truth value of None is False.

Booleans

There are two Boolean values, True and False, representing the truth or falsehood of a predicate. The type of a Boolean is "bool".

Boolean values are typically used as conditions in if-statements, although any Starlark value used as a condition is implicitly interpreted as a Boolean. For example, the values None, 0, 0.0, and the empty sequences "", (), [], and {} have a truth value of False, whereas non-zero numbers and non-empty sequences have a truth value of True. Application-defined types determine their own truth value. Any value may be explicitly converted to a Boolean using the built-in bool function.

1 + 1 == 2                              # True
2 + 2 == 5                              # False
if 1 + 1:
        print("True")
else:
        print("False")

Integers

The Starlark integer type represents integers. Its type is "int".

Integers may be positive or negative, and arbitrarily large. Integer arithmetic is exact. Integers are totally ordered; comparisons follow mathematical tradition.

The + and - operators perform addition and subtraction, respectively. The * operator performs multiplication.

The // and % operations on integers compute floored division and remainder of floored division, respectively. If the signs of the operands differ, the sign of the remainder x % y matches that of the divisor, y. For all finite x and y (y ≠ 0), (x // y) * y + (x % y) == x. The / operator implements real division, and yields a float result even when its operands are both of type int.

Integers, including negative values, may be interpreted as bit vectors. The |, &, and ^ operators implement bitwise OR, AND, and XOR, respectively. The unary ~ operator yields the bitwise inversion of its integer argument. The << and >> operators shift the first argument to the left or right by the number of bits given by the second argument.

Any bool, number, or string may be interpreted as an integer by using the int built-in function.

An integer used in a Boolean context is considered true if it is non-zero.

100 // 5 * 9 + 32               # 212
3 // 2                          # 1
3 / 2                           # 1.5
111111111 * 111111111           # 12345678987654321
"0x%x" % (0x1234 & 0xf00f)      # "0x1004"
int("ffff", 16)                 # 65535, 0xffff

Floating-point numbers

The Starlark floating-point data type represents an IEEE 754 double-precision floating-point number. Its type is "float".

Arithmetic on floats using the +, -, *, /, //, and % operators follows the IEE 754 standard. However, computing the division or remainder of division by zero is a dynamic error.

An arithmetic operation applied to a mixture of float and int operands works as if the int operand is first converted to a float. For example, 3.141 + 1 is equivalent to 3.141 + float(1). There are two floating-point division operators: x / y yields the floating-point quotient of x and y, whereas x // y yields floor(x / y), that is, the largest integer value not greater than x / y. Although the resulting number is integral, it is represented as a float if either operand is a float.

The % operation computes the remainder of floored division. As with the corresponding operation on integers, if the signs of the operands differ, the sign of the remainder x % y matches that of the divisor, y.

The infinite float values +Inf and -Inf represent numbers greater/less than all finite float values.

The non-finite NaN value represents the result of dubious operations such as Inf/Inf. A NaN value compares neither less than, nor greater than, nor equal to any value, including itself.

All floats other than NaN are totally ordered, so they may be compared using operators such as == and <.

Any bool, number, or string may be interpreted as a floating-point number by using the float built-in function.

A float used in a Boolean context is considered true if it is non-zero.

1.23e45 * 1.23e45                               # 1.5129e+90
1.111111111111111 * 1.111111111111111           # 1.23457
3.0 / 2                                         # 1.5
3 / 2.0                                         # 1.5
float(3) / 2                                    # 1.5
3.0 // 2.0                                      # 1.0

Strings

A string represents an immutable sequence of bytes. The type of a string is "string".

Strings can represent arbitrary binary data, including zero bytes, but most strings contain text, encoded by convention using UTF-8.

The built-in len function returns the number of bytes in a string.

Strings may be concatenated with the + operator.

The substring expression s[i:j] returns the substring of s from index i up to index j. The index expression s[i] returns the 1-byte substring s[i:i+1].

Strings are hashable, and thus may be used as keys in a dictionary.

Strings are totally ordered lexicographically, so strings may be compared using operators such as == and <.

Strings are not iterable sequences, so they cannot be used as the operand of a for-loop, list comprehension, or any other operation than requires an iterable sequence. To obtain a view of a string as an iterable sequence of numeric byte values, 1-byte substrings, numeric Unicode code points, or 1-code point substrings, you must explicitly call one of its four methods: elems, elem_ords, codepoints, or codepoint_ords.

Any value may formatted as a string using the str or repr built-in functions, the str % tuple operator, or the str.format method.

A string used in a Boolean context is considered true if it is non-empty.

Strings have several built-in methods:

• capitalize
• codepoint_ords
• codepoints
• count
• elem_ords
• elems
• endswith
• find
• format
• index
• isalnum
• isalpha
• isdigit
• islower
• isspace
• istitle
• isupper
• join
• lower
• lstrip
• partition
• replace
• rfind
• rindex
• rpartition
• rsplit
• rstrip
• split
• splitlines
• startswith
• strip
• title
• upper

Implementation note:The type of a string element varies across implementations. There is agreement that byte strings, with text conventionally encoded using UTF-8, is the ideal choice, but the Java implementation treats strings as sequences of UTF-16 codes and changing it appears intractible; see Google Issue b/36360490.Implementation note:The Java implementation does not consistently treat strings as iterable; see `testdata/string.star` in the test suite and Google Issue b/34385336 for further details.

Lists

A list is a mutable sequence of values. The type of a list is "list".

Lists are indexable sequences: the elements of a list may be iterated over by for-loops, list comprehensions, and various built-in functions.

List may be constructed using bracketed list notation:

[]              # an empty list
[1]             # a 1-element list
[1, 2]          # a 2-element list

Lists can also be constructed from any iterable sequence by using the built-in list function.

The built-in len function applied to a list returns the number of elements. The index expression list[i] returns the element at index i, and the slice expression list[i:j] returns a new list consisting of the elements at indices from i to j.

List elements may be added using the append or extend methods, removed using the remove method, or reordered by assignments such as list[i] = list[j].

The concatenation operation x + y yields a new list containing all the elements of the two lists x and y.

For most types, x += y is equivalent to x = x + y, except that it evaluates x only once, that is, it allocates a new list to hold the concatenation of x and y. However, if x refers to a list, the statement does not allocate a new list but instead mutates the original list in place, similar to x.extend(y).

Lists are not hashable, so may not be used in the keys of a dictionary.

A list used in a Boolean context is considered true if it is non-empty.

A list comprehension creates a new list whose elements are the result of some expression applied to each element of another sequence.

[x*x for x in [1, 2, 3, 4]]      # [1, 4, 9, 16]

A list value has these methods:

• append
• clear
• extend
• index
• insert
• pop
• remove

Tuples

A tuple is an immutable sequence of values. The type of a tuple is "tuple".

Tuples are constructed using parenthesized list notation:

()                      # the empty tuple
(1,)                    # a 1-tuple
(1, 2)                  # a 2-tuple ("pair")
(1, 2, 3)               # a 3-tuple

Observe that for the 1-tuple, the trailing comma is necessary to distinguish it from the parenthesized expression (1). 1-tuples are seldom used.

Starlark, unlike Python, does not permit a trailing comma to appear in an unparenthesized tuple expression:

for k, v, in dict.items(): pass                 # syntax error at 'in'
_ = [(v, k) for k, v, in dict.items()]          # syntax error at 'in'
f = lambda a, b, : None                         # syntax error at ':'
sorted(3, 1, 4, 1,)                             # ok
[1, 2, 3, ]                                     # ok
{1: 2, 3:4, }                                   # ok

Any iterable sequence may be converted to a tuple by using the built-in tuple function.

Like lists, tuples are indexed sequences, so they may be indexed and sliced. The index expression tuple[i] returns the tuple element at index i, and the slice expression tuple[i:j] returns a sub-sequence of a tuple.

Tuples are iterable sequences, so they may be used as the operand of a for-loop, a list comprehension, or various built-in functions.

Unlike lists, tuples cannot be modified. However, the mutable elements of a tuple may be modified.

Tuples are hashable (assuming their elements are hashable), so they may be used as keys of a dictionary.

Tuples may be concatenated using the + operator.

A tuple used in a Boolean context is considered true if it is non-empty.

Dictionaries

A dictionary is a mutable mapping from keys to values. The type of a dictionary is "dict".

Dictionaries provide constant-time operations to insert an element, to look up the value for a key, or to remove an element. Dictionaries are implemented using hash tables, so keys must be hashable. Hashable values include None, Booleans, numbers, and strings, and tuples composed from hashable values. Most mutable values, such as lists, dictionaries, and sets, are not hashable, even when frozen. Attempting to use a non-hashable value as a key in a dictionary results in a dynamic error.

A dictionary expression specifies a dictionary as a set of key/value pairs enclosed in braces:

coins = {
  "penny": 1,
  "nickel": 5,
  "dime": 10,
  "quarter": 25,
}

The expression d[k], where d is a dictionary and k is a key, retrieves the value associated with the key. If the dictionary contains no such item, the operation fails:

coins["penny"]          # 1
coins["dime"]           # 10
coins["silver dollar"]  # error: key not found

The number of items in a dictionary d is given by len(d). A key/value item may be added to a dictionary, or updated if the key is already present, by using d[k] on the left side of an assignment:

len(coins)              # 4
coins["shilling"] = 20
len(coins)              # 5, item was inserted
coins["shilling"] = 5
len(coins)              # 5, existing item was updated

A dictionary can also be constructed using a dictionary comprehension, which evaluates a pair of expressions, the key and the value, for every element of another iterable such as a list. This example builds a mapping from each word to its length in bytes:

words = ["able", "baker", "charlie"]
{x: len(x) for x in words}  # {"charlie": 7, "baker": 5, "able": 4}

Dictionaries are iterable sequences, so they may be used as the operand of a for-loop, a list comprehension, or various built-in functions. Iteration yields the dictionary's keys in the order in which they were inserted; updating the value associated with an existing key does not affect the iteration order.

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

for name in coins:
  print(name, coins[name])  # prints "quarter 25", "dime 10", ...

Like all mutable values in Starlark, a dictionary can be frozen, and once frozen, all subsequent operations that attempt to update it will fail.

A dictionary used in a Boolean context is considered true if it is non-empty.

Dictionaries may be compared for equality using == and !=. Two dictionaries compare equal if they contain the same number of items and each key/value item (k, v) found in one dictionary is also present in the other. Dictionaries are not ordered; it is an error to compare two dictionaries with <.

A dictionary value has these methods:

• clear
• get
• items
• keys
• pop
• popitem
• setdefault
• update
• values

Sets

A set is a mutable set of values. The type of a set is "set".

Like dictionaries, sets are implemented using hash tables, so the elements of a set must be hashable.

Sets may be compared for equality or inequality using == and !=. Two sets compare equal if they contain the same elements.

Sets are iterable sequences, so they may be used as the operand of a for-loop, a list comprehension, or various built-in functions. Iteration yields the set's elements in the order in which they were inserted.

The binary | and & operators compute union and intersection when applied to sets. The right operand of the | operator may be any iterable value. The binary in operator performs a set membership test when its right operand is a set.

The binary ^ operator performs symmetric difference of two sets.

Sets are instantiated by calling the built-in set function, which returns a set containing all the elements of its optional argument, which must be an iterable sequence. Sets have no literal syntax.

The only method of a set is union, which is equivalent to the | operator.

A set used in a Boolean context is considered true if it is non-empty.

Implementation note:The Go implementation of Starlark requires the `-set` flag to enable support for sets. The Java implementation does not support sets.

Functions

A function value represents a function defined in Starlark. Its type is "function". A function value used in a Boolean context is always considered true.

Functions defined by a def statement are named; functions defined by a lambda expression are anonymous.

Function definitions may be nested, and an inner function may refer to a local variable of an outer function.

A function definition defines zero or more named parameters. Starlark has a rich mechanism for passing arguments to functions.

The example below shows a definition and call of a function of two required parameters, x and y.

def idiv(x, y):
  return x // y
idiv(6, 3)      # 2

A call may provide arguments to function parameters either by position, as in the example above, or by name, as in first two calls below, or by a mixture of the two forms, as in the third call below. All the positional arguments must precede all the named arguments. Named arguments may improve clarity, especially in functions of several parameters.

idiv(x=6, y=3)      # 2
idiv(y=3, x=6)      # 2
idiv(6, y=3)        # 2

Optional parameters: A parameter declaration may specify a default value using `name=value` syntax; such a parameter is _optional_. The default value expression is evaluated during execution of the `def` statement or evaluation of the `lambda` expression, and the default value forms part of the function value. All optional parameters must follow all non-optional parameters. A function call may omit arguments for any suffix of the optional parameters; the effective values of those arguments are supplied by the function's parameter defaults.

def f(x, y=3):
  return x, y
f(1, 2) # (1, 2)
f(1)    # (1, 3)

If a function parameter's default value is a mutable expression, modifications to the value during one call may be observed by subsequent calls. Beware of this when using lists or dicts as default values. If the function becomes frozen, its parameters' default values become frozen too.

export const _frontmatter = {"metaTitle":"Data Types","metaDescription":"Float, string, int, bool, None, etc"}