keylist

README

keylist

keylist implements an ordered list (slice) of items (Values), with a map from a Key (e.g., names) to indexes, to support fast lookup by name. There is also a Keys slice.

This is a different implementation of the ordmap package, and has the advantage of direct slice access to the values, instead of having to go through the KeyValue tuple struct in ordmap.

Documentation

Overview

Package keylist implements an ordered list (slice) of items, with a map from a key (e.g., names) to indexes, to support fast lookup by name. This is a different implementation of the [ordmap] package, that has separate slices for Values and Keys, instead of using a tuple list of both. The awkwardness of value access through the tuple is the major problem with ordmap.

Index

• type List
  • func New[K comparable, V any]() *List[K, V]
  • func (kl *List[K, V]) Add(key K, val V) error
  • func (kl *List[K, V]) At(key K) V
  • func (kl *List[K, V]) AtTry(key K) (V, bool)
  • func (kl *List[K, V]) Copy(from *List[K, V])
  • func (kl *List[K, V]) DeleteByIndex(i, j int)
  • func (kl *List[K, V]) DeleteByKey(key K) bool
  • func (kl *List[K, V]) IndexByKey(key K) int
  • func (kl *List[K, V]) IndexIsValid(idx int) error
  • func (kl *List[K, V]) Insert(idx int, key K, val V)
  • func (kl *List[K, V]) Len() int
  • func (kl *List[K, V]) RenameIndex(i int, key K)
  • func (kl *List[K, V]) Reset()
  • func (kl *List[K, V]) Set(key K, val V)
  • func (kl *List[K, V]) String() string
  • func (kl *List[K, V]) UpdateIndexes()

Types

type List

type List[K comparable, V any] struct {
	// List is the ordered slice of items.
	Values []V

	// Keys is the ordered list of keys, in same order as [List.Values]
	Keys []K
	// contains filtered or unexported fields
}

List implements an ordered list (slice) of Values, with a map from a key (e.g., names) to indexes, to support fast lookup by name.

func New

func New[K comparable, V any]() *List[K, V]

New returns a new List. The zero value is usable without initialization, so this is just a simple standard convenience method.

func (*List[K, V]) Add

func (kl *List[K, V]) Add(key K, val V) error

Add adds an item to the list with given key, An error is returned if the key is already on the list. See List.Set for a method that automatically replaces.

func (*List[K, V]) At

func (kl *List[K, V]) At(key K) V

At returns the value corresponding to the given key, with a zero value returned for a missing key. See List.AtTry for one that returns a bool for missing keys. For index-based access, use [List.Values] or [List.Keys] slices directly.

func (*List[K, V]) AtTry

func (kl *List[K, V]) AtTry(key K) (V, bool)

AtTry returns the value corresponding to the given key, with false returned for a missing key, in case the zero value is not diagnostic.

func (*List[K, V]) Copy

func (kl *List[K, V]) Copy(from *List[K, V])

Copy copies all of the entries from the given key list into this list. It keeps existing entries in this list unless they also exist in the given list, in which case they are overwritten. Use List.Reset first to get an exact copy.

func (*List[K, V]) DeleteByIndex

func (kl *List[K, V]) DeleteByIndex(i, j int)

DeleteByIndex deletes item(s) within the index range [i:j]. This is relatively slow because it needs to regenerate the index map.

func (*List[K, V]) DeleteByKey

func (kl *List[K, V]) DeleteByKey(key K) bool

DeleteByKey deletes the item with the given key, returning false if it does not find it. This is relatively slow because it needs to regenerate the index map.

func (*List[K, V]) IndexByKey

func (kl *List[K, V]) IndexByKey(key K) int

IndexByKey returns the index of the given key, with a -1 for missing key.

func (*List[K, V]) IndexIsValid

func (kl *List[K, V]) IndexIsValid(idx int) error

IndexIsValid returns an error if the given index is invalid.

func (*List[K, V]) Insert

func (kl *List[K, V]) Insert(idx int, key K, val V)

Insert inserts the given value with the given key at the given index. This is relatively slow because it needs regenerate the keys list. It panics if the key already exists because the behavior is undefined in that situation.

func (*List[K, V]) Len

func (kl *List[K, V]) Len() int

Len returns the number of items in the list.

func (*List[K, V]) RenameIndex

func (kl *List[K, V]) RenameIndex(i int, key K)

RenameIndex renames the item at given index to new key.

func (*List[K, V]) Reset

func (kl *List[K, V]) Reset()

Reset resets the list, removing any existing elements.

func (*List[K, V]) Set

func (kl *List[K, V]) Set(key K, val V)

Set sets given key to given value, adding to the end of the list if not already present, and otherwise replacing with this new value. This is the same semantics as a Go map. See List.Add for version that only adds and does not replace.

func (*List[K, V]) String

func (kl *List[K, V]) String() string

String returns a string representation of the list.

func (*List[K, V]) UpdateIndexes

func (kl *List[K, V]) UpdateIndexes()

UpdateIndexes updates the Indexes from Keys and Values. This must be called after loading Values from a file, for example, where Keys can be populated from Values or are also otherwise available.