Compiler-shipped collection families

These APIs ship in the compiler’s embedded first-party BASIL library. No import, generated Integer/String variant, or application .blib dependency is required. The algorithms use ordinary specialized records, checked borrows and storage exchange; they are not separate opaque runtime implementations. See core lists/sets/dictionaries and generic records .

Construction and ownership

DIM jobs AS Deque[STRING]=NewDeque()
PushBack(BYREF jobs,"build")
PushFront(BYREF jobs,"check")
PRINT PopFront(BYREF jobs)

cache=NewCache(100) AS Cache[STRING,LIST OF INTEGER]
CachePut(BYREF cache,"numbers",[1,2,3])

Empty factories need their type arguments from a typed destination or AS result annotation. Later mutations do not infer an earlier declaration’s type. Length is the logical element count for these records; LEN remains the core sequence/ hash-container operation. Reset(BYREF collection) empties a collection; it does not change its configuration. Ordinary parameters borrow, BYREF excludes other access, and copying copyable containers/snapshots creates independent values.

Insertion takes a BYVAL payload: it copies a borrowed copyable value once, adopts a fresh value, or adopts an explicitly transferred named owner. There is no last-use resource transfer. Resource payloads make their containing collection noncopyable. Pop, extraction and bounded-deque eviction return owned values; resource Front/Back/Peek/Lookup/Find/Get return checked read-only views. A view excludes mutation, transfer and relocation of its whole owner until consumption finishes, including suspension. Store a snapshot only for copyable payloads.

DIM files AS Deque[File]=NewDeque()
PushBack(BYREF files,OpenFile("/dev/null"))
PRINT GetFileInfo(Front(files)).Size
file=PopFront(BYREF files)   ' transfer out; normal scope cleanup closes it

Keys must be copyable and support the existing canonical equality/hash/order rules. Structural NaN keys are rejected with InvalidKeyError; signed zero is one key. Sorted containers use Compare and existing NaN-last ordering, after key validation. Custom Equal/Hash/Compare must agree. Resource keys and stored task/channel capabilities remain unsupported.

Opaque container fields are private implementation state. Automatic JSON/shared serialization cannot expose or manufacture that state: it raises JsonError code4. Encode a logical snapshot, or configure a concrete formatter that decodes through the public factories/operations. This also applies to other opaque types without declared formatters. Generic OPERATOR declarations remain unsupported; do not treat derived representation equality/hash as abstract sequence/cache equality. For logical deque/queue comparison, compare their copyable snapshots explicitly.

Sequences and priority queues

Deque/queue/heap empty reads and removals raise EmptyCollection. Bounded-deque construction rejects nonpositive capacity with CollectionError; its pushes also declare CollectionError/EmptyCollection. Snapshots preserve logical sequence order and require copyable payloads. Priorities include INT64_MIN/MAX without negation. Heap payloads need no comparison operation. Growth and sifting exchange complete values rather than cloning their managed fields or resources.

Ordered keys and counting

Existing SET/DICT preserve insertion order; NewOrderedSet() and NewOrderedDictionary() are contextual factories for those same native types.

Sorted keys use binary search, O(log n) lookup and O(n) insertion/removal in a sorted vector. Ranges are half-open [first,finish); reversed ranges are empty. Sorted-set algebra merges in O(n+m). InsertValue/SetValue return TRUE for a new key, FALSE for an existing one. Lookup returns OPTIONAL; LookupRequired raises MissingKey. At and editing APIs use nonnegative checked indices and IndexError. Key/order errors remain in specialized FAILS contracts.

Counter counts are positive; missing keys read as zero and zero counts remove the key. Add/RemoveValue require nonnegative amounts. Removal returns the amount removed, bounded by the current count. Length counts distinct keys; TotalCount counts occurrences. Overflow/invalid amounts raise CollectionError before mutation.

Multimaps retain duplicate values and per-key insertion order. Length counts keys, TotalCount counts all values; removing the last value removes the key. Get raises MissingKey; GetAll returns an independent list or an empty list and requires copyable values. Find/Get can borrow resource buckets. RemoveOne uses equality and requires copyable values; RemoveKey destroys all values and returns their count. Extract returns an owned optional bucket; ExtractAt removes one owned value. Key snapshots retain native insertion order; sorted-dictionary snapshots are sorted. ValueSnapshot is copyable-only; Values on a resource sorted dictionary is a view.

Bitsets

NewBitSet(size) creates a packed UINT64 fixed universe [0,size). Capacity is the universe size; Length counts included bits. Has/Include/Exclude/Flip use checked nonnegative indices and IndexError. Members returns ascending INTEGER indices. Reset clears bits without changing the universe. BitUnion, BitIntersection, BitDifference, BitSymmetricDifference and Complement return independent bitsets. Binary operations require equal universes (CollectionError). Complement masks unused padding bits. There is no arbitrary 100-million-bit cap; negative sizes are checked, while ordinary allocation/representability limits retain the fatal allocation policy. Storage is ceil(size/64)*8 payload bytes, plus ordinary list/record headers.

Bounded caches

DIM cache AS Cache[STRING,STRING]=NewCache(100,CachePolicy.LRUWithTTL,SOME(Seconds(60)))
result=CachePut(BYREF cache,"key","value",weight=2)
IF LET value=CacheFind(BYREF cache,"key") THEN
    PRINT value
END IF

Every timed operation has an At counterpart with now AS MonotonicInstant after key/value and before optional weight. An externally timed cache requires At operations; ordinary caches reject them. LRU reads no clock. Other ordinary caches sample the system monotonic clock. Caller-owned Clock values can supply samples for active/boot/test time without transferring or copying clock authority.

TTL expires at age >= expireAfter, measured since the most recent write. Find does not extend TTL. TTL evicts oldest writes; LRU policies evict least recently used entries. Expiry order and recency have separate linked indexes; lookups/edits are amortized O(1), plus entries pruned/evicted. Freed slots are reused. Weights are caller accounting units, not measured memory usage.

Accepted mutating samples must be nondecreasing and from the same clock domain. Wrong domains, backwards samples, invalid mode/weights and weight-total overflow produce checked errors. A Peek validates time but does not advance LastObserved. Expired entries can be pruned before a later rejected write; this is not a full rollback transaction. APIs declare CollectionError/DateTimeError/IoError and key-dependent errors; plain LRU construction itself only declares CollectionError.

These are ordinary exclusive mutable values: no implicit locks, worker thread, timer task, asynchronous loader or request coalescing. Cancellation follows structured scope exit and cleans retained/temporary owners; a cancelled edit is not a recoverable transaction that resumes the same invocation.