Search Apps Documentation Source Content File Folder Download Copy Actions Download State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

v0 source pure

Package flatmap is a sorted-vector map — the STL flat\_map / Abseil btree\_map trade — as a pure, reusable package.

Readme View source

gno.land/p/moul/x/daily/flatmap/v0

Sorted-vector map — New, Set, Get, Has, Delete, Keys, Values, At, Iterate, Range, Clone, Sorted, MaxEntries.

1import "gno.land/p/moul/x/daily/flatmap/v0"
2
3f := flatmap.New()
4f.Set("delta", "4"); f.Set("alpha", "1")
5f.Keys()                  // ["alpha" "delta"] — sorted by construction
6f.At(0)                   // "alpha", "1", true — indexed access
7f.Range("a", "c", fn)     // lo inclusive, hi exclusive

The STL flat_map trade. Keys and values live in two parallel sorted slices instead of a hash table or a tree of nodes:

operation cost
Get O(log n) binary search over contiguous memory
iteration O(n), already ordered, nothing to sort
Set in the middle O(n) — the tail shifts
Set at the end O(1) amortised — the fast path

Cheap reads and cheap ordered iteration, paid for at write time. That trade is stated rather than hidden.

On chain the ordering is the real draw: a built-in gno map iterates in an unspecified order, so a Render built from one can differ between nodes. A flat map is sorted by construction, so iteration is deterministic without a sort on every read.

Sorted storage also buys two things a hash map cannot offer: At(i) positional access, and Range(lo, hi) as two binary searches and a walk — including when the bounds are not themselves keys.

Sorted() is exported so callers can assert the invariant; it holds through the whole public API, including 200 worst-case head insertions.

Live demo: r/moul/x/daily/flatmapdemo · render it at /r/moul/x/daily/flatmapdemo/v0.

Part of moul/gno-contracts — moul's versioned gno.land contracts. See the repository for the full catalog, build/test tooling, and usage.

🧪 Highly experimental — potentially vibe-coded. Not audited; may break, change, or be removed at any time. Do not use with anything of value. Full disclaimer: DISCLAIMER.

Overview

Package flatmap is a sorted-vector map — the STL flat_map / Abseil btree_map trade — as a pure, reusable package.

Keys and values live in two parallel sorted slices instead of a hash table or a tree of nodes. Lookup is a binary search, O(log n) rather than O(1), but it touches contiguous memory instead of chasing pointers, iteration is already in key order with nothing to sort, and there is no per-entry node overhead. Insertion in the middle is O(n) because it shifts the tail. That is the whole bargain: cheap reads and cheap ordered iteration, paid for at write time.

On chain the ordering is the real draw. A built-in gno map iterates in an unspecified order, so a Render built from one can differ between nodes — a consensus bug rather than a cosmetic one. A flat map is sorted by construction, so iteration is deterministic without a sort on every read.

Appending in ascending key order is the fast path: it hits the end of the slice and shifts nothing.

A live demo of this package is at r/moul/x/daily/flatmapdemo(/r/moul/x/daily/flatmapdemo/v0).

Constants 1

const MaxEntries 

1const MaxEntries = 4096
source

MaxEntries bounds the map so gas stays predictable.

Functions 1

func New 

1func New() *FlatMap
source

New returns an empty FlatMap.

Types 1

type FlatMap

struct 
1type FlatMap struct {
2	keys []string
3	vals []string
4}
source

FlatMap is a string->string map backed by parallel sorted slices.

Methods on FlatMap

func At

method on FlatMap 
1func (f *FlatMap) At(i int) (key, value string, ok bool)
source

At returns the i-th entry in key order — the indexed access a hash map cannot offer, and one reason to pay for sorted storage.

func Clone

method on FlatMap 
1func (f *FlatMap) Clone() *FlatMap
source

Clone returns an independent copy.

func Delete

method on FlatMap 
1func (f *FlatMap) Delete(key string) bool
source

Delete removes key. Returns false when absent.

func Get

method on FlatMap 
1func (f *FlatMap) Get(key string) (string, bool)
source

Get returns the value for key.

func Has

method on FlatMap 
1func (f *FlatMap) Has(key string) bool
source

Has reports whether key is present.

func IsEmpty

method on FlatMap 
1func (f *FlatMap) IsEmpty() bool
source

IsEmpty reports whether the map holds nothing.

func Iterate

method on FlatMap 
1func (f *FlatMap) Iterate(fn func(key, value string) bool)
source

Iterate calls fn for each entry in key order. Returning true stops.

func Keys

method on FlatMap 
1func (f *FlatMap) Keys() []string
source

Keys returns the keys in sorted order, as a copy.

func Len

method on FlatMap 
1func (f *FlatMap) Len() int
source

Len returns the number of entries.

func Range

method on FlatMap 
1func (f *FlatMap) Range(lo, hi string, fn func(key, value string) bool)
source

Range calls fn for entries with lo <= key < hi, in key order. An empty hi means "to the end". This is the other thing sorted storage buys: a range query is two binary searches and a walk.

func Set

method on FlatMap 
1func (f *FlatMap) Set(key, value string) bool
source

Set inserts or updates key. Returns false only when the map is full and key is new — updating an existing key always succeeds.

func Sorted

method on FlatMap 
1func (f *FlatMap) Sorted() bool
source

Sorted reports whether the backing slice is in strictly ascending order. Always true through the public API; exported so callers can assert it.

func Values

method on FlatMap 
1func (f *FlatMap) Values() []string
source

Values returns the values ordered by their keys, as a copy.

Imports 1

  • sort stdlib

Source Files 3