tiny.python.Value

1/// One Python value, as a tagged union of thirteen kinds. The virtual machine reads and writes2/// values in every operation, and `Result.value` is one. `None`, booleans and integers live in the3/// value itself, a string is a slice of bytes held elsewhere, and every other kind points to an4/// object held elsewhere. The objects that the virtual machine makes live on its heap. Copying a5/// value copies the pointer, so both copies refer to the same object.6pub const Value = union(enum) {7    /// Python's `None`, with no payload. `None` is false by Python's truth rules and equal only to8    /// `None`.9    none,10    /// Python's `True` or `False`. A boolean counts as the integer 1 or 0 in arithmetic, equality,11    /// ordering and hashing, so `True == 1` holds and a dictionary finds the key `1` under `True`.12    /// A boolean is never the same object as an integer under `is`.13    boolean: bool,14    /// A Python integer, stored in 128 signed bits. Arithmetic that leaves that range fails with15    /// `IntegerOverflow`.16    integer: i128,17    /// A Python string, as a slice of UTF-8 bytes that the value borrows. A string literal and its18    /// slices with step 1 point into the source text, and a string the run built points into the19    /// heap. Two strings are equal when their bytes are equal. Two strings are the same object20    /// under `is` when they start at the same address and have the same length.21    string: []const u8,22    /// A Python function, as the position of its body in the function table of the top-level chunk.23    /// The position names nothing once that chunk is freed.24    function: usize,25    /// One of the nine builtin functions, named by a `Builtin` tag.26    builtin: Builtin,27    /// A list or dictionary method bound to the object it was read from, as a pointer to a28    /// `NativeMethod` on the heap.29    method: *NativeMethod,30    /// A pointer to a Python list. When the virtual machine made the list, the machine's heap owns31    /// it.32    list: *List,33    /// A pointer to a Python tuple. When the virtual machine made the tuple, the machine's heap34    /// owns it.35    tuple: *Tuple,36    /// A pointer to a Python dictionary. When the virtual machine made the dictionary, the37    /// machine's heap owns it.38    dict: *Dict,39    /// A pointer to a view of a dictionary's keys, values or items.40    view: *DictView,41    /// A pointer to a Python range.42    range: *Range,43    /// A pointer to an iterator, whose position advances as it yields items.44    iterator: *Iterator,4546    /// Returns whether the value is true by Python's truth rules, for `if`, `while`, `and`, `or`47    /// and `not`. `None`, `False`, zero, and empty strings, lists, tuples, dictionaries, dictionary48    /// views and ranges are false. A dictionary view is false when its dictionary is empty.49    /// Functions, builtins, bound methods and iterators are always true.50    pub fn truthy(self: Value) bool {51        return switch (self) {52            .none => false,53            .boolean => |value| value,54            .integer => |value| value != 0,55            .string => |value| value.len != 0,56            .function => true,57            .builtin => true,58            .method => true,59            .list => |value| value.items.len != 0,60            .tuple => |value| value.items.len != 0,61            .dict => |value| value.entries.items.len != 0,62            .view => |value| value.dict.entries.items.len != 0,63            .range => |value| value.length != 0,64            .iterator => true,65        };66    }6768    /// Returns the integer a value stands for: an integer's own value, 1 for `True`, 0 for `False`,69    /// and `null` for every other kind. Arithmetic, indexing, `range`, `enumerate` and repetition70    /// read their integer inputs through it.71    pub fn integerLike(self: Value) ?i128 {72        return switch (self) {73            .integer => |value| value,74            .boolean => |value| if (value) 1 else 0,75            .none => null,76            .string => null,77            .function => null,78            .builtin => null,79            .method => null,80            .list => null,81            .tuple => null,82            .dict => null,83            .view => null,84            .range => null,85            .iterator => null,86        };87    }8889    /// Returns whether the value may be a dictionary key, so the virtual machine checks it before90    /// every dictionary lookup and insertion. `None`, booleans, integers, strings, functions,91    /// builtins, bound methods and ranges may be keys. A tuple may be a key when every item may.92    /// Lists, dictionaries, dictionary views and iterators may never be keys. The check walks a93    /// tuple item by item, so its cost grows with the tuple.94    pub fn hashable(self: Value) bool {95        return switch (self) {96            .none, .boolean, .integer, .string, .function, .builtin, .method, .range => true,97            .tuple => |value| sequenceHashable(value.items),98            .list, .dict, .view, .iterator => false,99        };100    }101102    /// Returns whether two values are equal by Python's rules, for `==`, `!=`, membership tests and103    /// dictionary lookups. Integers and booleans compare by their integer value. Strings compare104    /// their bytes, and lists and tuples compare item by item. Two dictionaries are equal when they105    /// hold equal values under the same keys, in any order. Two ranges are equal when they yield106    /// the same elements. Keys views compare their dictionaries' keys, items views compare their107    /// dictionaries, and a values view equals only itself. Two bound methods are equal when they108    /// have the same method and the same receiver. Functions and builtins compare their positions109    /// and tags, and iterators are equal only to themselves. Values of unrelated kinds are unequal,110    /// and the comparison returns no error. Comparing a list with itself returns true before111    /// comparing its items. Comparing a tuple with itself returns true before comparing its items.112    /// A list containing itself therefore equals itself, including when it holds a tuple containing113    /// that same list. Two distinct lists or dictionaries that each contain themselves recurse114    /// until the native stack overflows when comparison reaches those self-references because115    /// comparison has no depth bound.116    pub fn eql(self: Value, other: Value) bool {117        if (self.integerLike()) |left| {118            if (other.integerLike()) |right| return left == right;119        }120        return switch (self) {121            .none => other == .none,122            .boolean => false,123            .integer => false,124            .string => |left| switch (other) {125                .string => |right| std.mem.eql(u8, left, right),126                else => false,127            },128            .function => |left| switch (other) {129                .function => |right| left == right,130                else => false,131            },132            .builtin => |left| switch (other) {133                .builtin => |right| left == right,134                else => false,135            },136            .method => |left| switch (other) {137                .method => |right| nativeMethodsEqual(left, right),138                else => false,139            },140            .list => |left| switch (other) {141                .list => |right| listsEqual(left, right),142                else => false,143            },144            .tuple => |left| switch (other) {145                .tuple => |right| left == right or sequencesEqual(left.items, right.items),146                else => false,147            },148            .dict => |left| switch (other) {149                .dict => |right| dictsEqual(left, right),150                else => false,151            },152            .view => |left| switch (other) {153                .view => |right| dictViewsEqual(left, right),154                else => false,155            },156            .range => |left| switch (other) {157                .range => |right| rangesEqual(left, right),158                else => false,159            },160            .iterator => |left| switch (other) {161                .iterator => |right| left == right,162                else => false,163            },164        };165    }166167    /// Returns a 64-bit Wyhash of the value, with a fixed seed, so a value hashes the same in every168    /// run. The dictionary's hash table hashes keys with it. Equal values hash equally: an integer169    /// and the boolean with its value share a hash, and so do equal ranges and equal tuples. A170    /// bound method hashes its method and its receiver's address. The function asserts that the171    /// value is hashable, so the caller checks `hashable` first.172    pub fn hash(self: Value) u64 {173        std.debug.assert(self.hashable());174        var hasher = std.hash.Wyhash.init(0x5059_5448_4f4e_5641);175        hashInto(&hasher, self);176        return hasher.final();177    }178};

1pub const Value = object.Value;