tiny.preserves.Constructors

1/// Returns a namespace of constructors for `Value(D)`, the Preserves value whose embedded values2/// hold a `D`. A caller whose values hold embedded values of one type calls it once at compile3/// time, for every constructor over those values. The JSON decoder, the protocol record builders4/// and the pattern conversions each call it to build their records. `D` has to provide `eql`,5/// `order`, `deinit` and `clone`, or the call is a compile error.6pub fn Constructors(comptime D: type) type {7    domain_mod.assertIsDomain(D);8    const V = Value(D);9    return struct {10        /// Returns the boolean value `v`. The call allocates nothing.11        pub fn boolean(v: bool) V {12            return V.initBoolean(v);13        }1415        /// Returns an integer value holding `v`. The call widens `v` to 128 bits, so the value16        /// compares and encodes like any other integer. The call allocates nothing.17        pub fn integer(v: i64) V {18            return V.initI128(@as(i128, v));19        }2021        /// Returns the double value `v`. The call allocates nothing.22        pub fn float(v: f64) V {23            return V.initDouble(v);24        }2526        /// Returns a string value that borrows the bytes `s`. The value points into `s`, so `s` has27        /// to stay alive while the value is in use. The call checks nothing about `s`, including28        /// whether it is valid UTF-8.29        pub fn string(s: []const u8) V {30            return .{ .string = s };31        }3233        /// Returns a symbol value that borrows the bytes `name`. The value points into `name`, so34        /// `name` has to stay alive while the value is in use.35        pub fn symbol(name: []const u8) V {36            return .{ .symbol = name };37        }3839        /// Returns the discard pattern, which matches any value. The call allocates nothing.40        pub fn discard() V {41            return .{ .discard = {} };42        }4344        /// Returns the symbol `null`, the value the package uses for JSON's null. The symbol's45        /// bytes are a constant of the package, so the value is safe to keep. `isNull` recognizes46        /// the value.47        pub fn null_val() V {48            return .{ .symbol = symbols_mod.SYM_NULL.name };49        }5051        /// Returns a capture pattern, which matches what `inner` matches and records the matched52        /// value. The call allocates one cell for `inner` with `alloc` and moves `inner` into it.53        /// The only error is running out of memory.54        pub fn capture(alloc: Allocator, inner: V) !V {55            const p = try alloc.create(V);56            p.* = inner;57            return .{ .capture = p };58        }5960        /// Returns a pattern that matches what `inner` matches and records the matched value under61        /// `name`. The call allocates one cell for `inner` with `alloc` and borrows `name`. On62        /// failure the call frees its cell and leaves `inner` with the caller.63        pub fn bindVal(alloc: Allocator, name: []const u8, inner: V) !V {64            const p = try alloc.create(V);65            errdefer alloc.destroy(p);66            p.* = inner;67            return .{ .bind = .{ .name = name, .pattern = p } };68        }6970        /// Returns a pattern that matches a sequence whose first items match `prefix` and whose71        /// remaining items match `rest`. The call copies the `prefix` slice and allocates one cell72        /// for `rest`, both with `alloc`. The copy is shallow: the items it holds still point to73        /// whatever the caller's items pointed to. On failure the call frees what it allocated and74        /// leaves `prefix` and `rest` with the caller.75        pub fn restPattern(alloc: Allocator, prefix: []const V, rest: V) !V {76            const prefix_copy = try alloc.dupe(V, prefix);77            errdefer alloc.free(prefix_copy);78            const rest_ptr = try alloc.create(V);79            errdefer alloc.destroy(rest_ptr);80            rest_ptr.* = rest;81            return .{ .rest_pattern = .{ .prefix = prefix_copy, .rest = rest_ptr } };82        }8384        /// Returns an embedded value that holds the pointer `ptr`. The call is a compile error85        /// unless `D` is `AnyEmbedded`. The value carries no equality, cleanup or copy functions,86        /// so two such values are equal only when they hold the same pointer. Freeing the value87        /// leaves the pointed-to data alone.88        pub fn embedded(ptr: *anyopaque) V {89            if (D != AnyEmbedded) {90                @compileError("Constructors(" ++ @typeName(D) ++ ").embedded(ptr) requires D == AnyEmbedded");91            }92            return V{ .embedded = AnyEmbedded{ .value = ptr } };93        }9495        /// Returns a record with label `label` and fields `fields`. The call allocates one cell for96        /// the label and a copy of the `fields` slice, both with `alloc`. The copy is shallow: the97        /// new record holds the same field values the caller passed. `freeValue` frees exactly the98        /// cell and the slice this call allocated. On failure the call frees its cell and leaves99        /// `label` and `fields` with the caller.100        pub fn record(alloc: Allocator, label: V, fields: []const V) !V {101            const lp = try alloc.create(V);102            errdefer alloc.destroy(lp);103            lp.* = label;104            const fs = try alloc.dupe(V, fields);105            return .{ .record = .{ .label = lp, .fields = fs } };106        }107108        /// Returns a sequence holding a copy of the `items` slice, allocated with `alloc`. The copy109        /// is shallow: the new sequence holds the same item values the caller passed. `freeValue`110        /// frees exactly the slice this call allocated.111        pub fn sequence(alloc: Allocator, items: []const V) !V {112            const s = try alloc.dupe(V, items);113            return .{ .sequence = s };114        }115116        /// Returns a set holding a sorted copy of `items`, allocated with `alloc`. The copy is117        /// sorted by `compare`, the package's total order on values. The copy is shallow, and118        /// `freeValue` frees exactly the slice this call allocated. The duplicate check compares119        /// every pair of items, so its cost grows with the square of the count. The call returns120        /// `error.DuplicateSetElement` when two items are equal. That error allocates nothing. The121        /// duplicate check leaves `items` with the caller.122        pub fn set(alloc: Allocator, items: []const V) !V {123            if (!V.setElementsDistinct(items)) return error.DuplicateSetElement;124            const sorted = try alloc.dupe(V, items);125            const Cmp = struct {126                fn lt(_: void, a: V, b: V) bool {127                    return a.compare(b) == .lt;128                }129            };130            std.mem.sort(V, sorted, {}, Cmp.lt);131            return .{ .set = sorted };132        }133134        /// Returns a dictionary holding a copy of `entries` sorted by key, allocated with `alloc`.135        /// The keys are sorted by `compare`, the package's total order on values. The copy is136        /// shallow, and `freeValue` frees exactly the slice this call allocated. The duplicate137        /// check compares every pair of keys, so its cost grows with the square of the count. The138        /// call returns `error.DuplicateDictionaryKey` when two keys are equal. That error139        /// allocates nothing. The duplicate check leaves `entries` with the caller.140        pub fn dictionary(alloc: Allocator, entries: []const V.DictionaryEntry) !V {141            if (!V.dictionaryKeysDistinct(entries)) return error.DuplicateDictionaryKey;142            const sorted = try alloc.dupe(V.DictionaryEntry, entries);143            const Cmp = struct {144                fn lt(_: void, a: V.DictionaryEntry, b: V.DictionaryEntry) bool {145                    return a.key.compare(b.key) == .lt;146                }147            };148            std.mem.sort(V.DictionaryEntry, sorted, {}, Cmp.lt);149            return .{ .dictionary = sorted };150        }151    };152}

1pub const Constructors = constructors_mod.Constructors;