initial commit

Author: umpc

LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2017 Justin Lowery
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,75 @@
+# SortedMap
+
+Sorted Map is a small library that provides a value-sorted ```map[string]interface``` type and methods combined from Go 1 map and slice primitives.
+
+This data structure allows for roughly constant-time reads and for efficiently iterating over only a subsection of the stored values. While this works for the project it was built for, because of the structure's reliance on a sorted slice of keys, worst-case delete operations are roughly ```O(n)```, where ```n``` is the number of items in the collection.
+
+## Example Usage
+
+```go
+package main
+
+import (
+	"fmt"
+	"time"
+	mrand "math/rand"
+
+	"github.com/umpc/sortedmap"
+)
+
+func main() {
+	mrand.Seed(time.Now().UTC().UnixNano())
+
+	// Example records:
+	records := make([]*sortedmap.Record, 5)
+	for i := range records {
+		year := mrand.Intn(2018)
+		if year < 1970 {
+			year = 1970
+		}
+		mth := time.Month(mrand.Intn(12))
+		if mth < 1 {
+			mth++
+		}
+		day := mrand.Intn(28)
+		if day < 1 {
+			day++
+		}
+
+		hour := mrand.Intn(23)
+		min := mrand.Intn(59)
+		sec := mrand.Intn(59)
+	
+		t := time.Date(year, mth, day, hour, min, sec, 0, time.UTC)
+		records[i] = &sortedmap.Record{
+			Key: t.Format(time.RFC3339),
+// 			Val: mrand.Intn(34334534561),
+			Val: t,
+		}
+	}
+
+	// Only one type can be used at a time, though handling for multiple types is still shown here:
+	sm := sortedmap.New(func(idx map[string]interface{}, sorted []string, i int, val interface{}) bool {
+		switch val.(type) {
+//		case int:
+//			return val.(int) < idx[sorted[i]].(int)
+		case time.Time:
+			return val.(time.Time).Before(idx[sorted[i]].(time.Time))
+		default:
+			return false
+		}
+	})
+
+	// Insert:
+	sm.BatchReplace(records...)
+
+	// Ordered iteration up until a given time:
+	for rec := range sm.IterBefore(time.Now()) {
+		fmt.Printf("%+v\n", rec)
+	}
+}
+```
+
+## License
+
+The source code is available under the [MIT License](https://opensource.org/licenses/MIT).

defaults.go

@@ -0,0 +1,14 @@
+package sortedmap
+
+import "time"
+
+func defaultSortLessFn(idx map[string]interface{}, sorted []string, i int, val interface{}) bool {
+	return idx[sorted[i]].(time.Time).Before(val.(time.Time))
+}
+
+func setDefaults(lessFn SortLessFunc) SortLessFunc {
+	if lessFn == nil {
+		lessFn = defaultSortLessFn
+	}
+	return lessFn
+}

delete.go

@@ -0,0 +1,35 @@
+package sortedmap
+
+func (sm *SortedMap) delete(key string) bool {
+	if _, ok := sm.idx[key]; ok {
+		delete(sm.idx, key)
+
+		smLen := len(sm.sorted)
+		deleted := 0
+
+		for i := 0; i < smLen - deleted; i++ {
+			if sm.sorted[i] == key {
+				sm.sorted = deleteString(sm.sorted, i)
+				deleted++
+			}
+		}
+
+		return true
+	}
+	return false
+}
+
+// Delete removes a value from the collection, using the given key.
+// Because the index position of each sorted key changes on each insert and a simpler structure was ideal, deletes can have a worse-case complexity of O(n), meaning the goroutine must loop through the sorted slice to find and delete the given key.
+func (sm *SortedMap) Delete(key string) bool {
+	return sm.delete(key)
+}
+
+// BatchDelete removes values from the collection, using the given keys, returning a slice of the results.
+func (sm *SortedMap) BatchDelete(keys ...string) []bool {
+	results := make([]bool, len(keys))
+	for i, key := range keys {
+		results[i] = sm.delete(key)
+	}
+	return results
+}

get.go

@@ -0,0 +1,19 @@
+package sortedmap
+
+// Get retrieves a value from the collection, using the given key.
+func (sm *SortedMap) Get(key string) (interface{}, bool) {
+	val, ok := sm.idx[key]
+	return val, ok
+}
+
+// BatchGet retrieves values with their read statuses from the collection, using the given keys.
+func (sm *SortedMap) BatchGet(keys ...string) ([]interface{}, []bool) {
+	vals := make([]interface{}, len(keys))
+	results := make([]bool, len(keys))
+
+	for i, key := range keys {
+		vals[i], results[i] = sm.idx[key]
+	}
+
+	return vals, results
+}

has.go

@@ -0,0 +1,16 @@
+package sortedmap
+
+// Has checks if the key exists in the collection.
+func (sm *SortedMap) Has(key string) bool {
+	_, ok := sm.idx[key]
+	return ok
+}
+
+// Has checks if the keys exist in the collection and returns a slice containing the results.
+func (sm *SortedMap) BatchHas(keys ...string) []bool {
+	results := make([]bool, len(keys))
+	for i, key := range keys {
+		_, results[i] = sm.idx[key]
+	}
+	return results
+}

insert.go

@@ -0,0 +1,26 @@
+package sortedmap
+
+func (sm *SortedMap) insert(key string, val interface{}) bool {
+	if _, ok := sm.idx[key]; !ok {
+		sm.idx[key] = val
+		sm.sorted = sm.insertSort(key, val)
+	    return true
+    }
+    return false
+}
+
+// Insert uses the provided 'less than' function to insert sort and add the value to the collection and returns a value containing the record's insert status.
+// If the key already exists, the value will not be inserted. Use Replace for the alternative functionality.
+func (sm *SortedMap) Insert(key string, val interface{}) bool {
+	return sm.insert(key, val)
+}
+
+// BatchInsert adds all given records to the collection and returns a slice containing each record's insert status.
+// If a key already exists, the value will not be inserted. Use BatchReplace for the alternative functionality.
+func (sm *SortedMap) BatchInsert(recs ...*Record) []bool {
+	results := make([]bool, len(recs))
+	for i, rec := range recs {
+		results[i] = sm.insert(rec.Key, rec.Val)
+	}
+	return results
+}

insertsort.go

@@ -0,0 +1,14 @@
+package sortedmap
+
+import "sort"
+
+func (sm *SortedMap) insertSort(key string, val interface{}) []string {
+	smLen := len(sm.sorted)
+	if smLen == 0 {
+		return []string{key}
+	}
+	i := sort.Search(smLen, func(i int) bool {
+		return sm.lessFn(sm.idx, sm.sorted, i, val)
+	})
+	return insertString(sm.sorted, i, key)
+}

iter.go

@@ -0,0 +1,106 @@
+package sortedmap
+
+import "sort"
+
+func (sm *SortedMap) iter(bufSize int) <-chan Record {
+	ch := make(chan Record, bufSize)
+
+	go func(ch chan Record) {
+		var (
+			key string
+			smLen = len(sm.sorted)
+		)
+		for i := 0; i < smLen; i++ {
+			key = sm.sorted[i]
+			ch <- Record{
+				Key: key,
+				Val: sm.idx[key],
+			}
+		}
+		close(ch)
+	}(ch)
+
+	return ch
+}
+
+func (sm *SortedMap) iterUntil(bufSize int, val interface{}) <-chan Record {
+	ch := make(chan Record, bufSize)
+
+	go func(ch chan Record) {
+		var (
+			key string
+			smLen = len(sm.sorted)
+		)
+		for i := 0; i < smLen; i++ {
+			if sm.lessFn(sm.idx, sm.sorted, i, val) {
+				break
+			}
+			key = sm.sorted[i]
+			ch <- Record{
+				Key: key,
+				Val: sm.idx[key],
+			}
+		}
+		close(ch)
+	}(ch)
+
+	return ch
+}
+
+func (sm *SortedMap) iterAfter(bufSize int, val interface{}) <-chan Record {
+	ch := make(chan Record, bufSize)
+
+	go func(ch chan Record) {
+		var (
+			key string
+			smLen = len(sm.sorted)
+		)
+		i := sort.Search(smLen, func(i int) bool {
+			return sm.lessFn(sm.idx, sm.sorted, i, val)
+		})
+		for; i < smLen; i++ {
+			key = sm.sorted[i]
+			ch <- Record{
+				Key: key,
+				Val: sm.idx[key],
+			}
+		}
+		close(ch)
+	}(ch)
+
+	return ch
+}
+
+// Iter returns an unbuffered channel that sorted records can be read from and processed.
+func (sm *SortedMap) Iter() <-chan Record {
+	return sm.iter(0)
+}
+
+// IterUntil returns an unbuffered channel that sorted records can be read from and processed.
+// IterUntil starts at the lowest value in the collection and sends all values until reaching the given value.
+func (sm *SortedMap) IterUntil(val interface{}) <-chan Record {
+	return sm.iterUntil(0, val)
+}
+
+// IterAfter returns an unbuffered channel that sorted records can be read from and processed.
+// IterAfter starts at the given value and sends all values until reaching the end of the collection.
+func (sm *SortedMap) IterAfter(val interface{}) <-chan Record {
+	return sm.iterAfter(0, val)
+}
+
+// BufferedIter returns a buffered channel that sorted records can be read from and processed.
+func (sm *SortedMap) BufferedIter(bufSize int) <-chan Record {
+	return sm.iter(bufSize)
+}
+
+// BufferedIterUntil returns a buffered channel that sorted records can be read from and processed.
+// BufferedIterUntil starts at the lowest value in the collection and sends all values until reaching the given value.
+func (sm *SortedMap) BufferedIterUntil(bufSize int, val interface{}) <-chan Record {
+	return sm.iterUntil(bufSize, val)
+}
+
+// BufferedIterAfter returns a buffered channel that sorted records can be read from and processed.
+// BufferedIterAfter starts at the given value and sends all values until reaching the end of the collection.
+func (sm *SortedMap) BufferedIterAfter(bufSize int, val interface{}) <-chan Record {
+	return sm.iterAfter(bufSize, val)
+}

replace.go

@@ -0,0 +1,31 @@
+package sortedmap
+
+func (sm *SortedMap) replace(key string, val interface{}) {
+	if _, ok := sm.idx[key]; ok {
+	    sm.delete(key)
+    }
+	sm.idx[key] = val
+	sm.sorted = sm.insertSort(key, val)
+}
+
+// Replace uses the provided 'less than' function to insert sort.
+// Even if the key already exists, the value will be inserted. Use Insert for the alternative functionality.
+func (sm *SortedMap) Replace(key string, val interface{}) {
+	sm.replace(key, val)
+}
+
+// BatchReplace adds all given records to the collection.
+// Even if a key already exists, the value will be inserted. Use BatchInsert for the alternative functionality.	
+func (sm *SortedMap) BatchReplace(recs ...*Record) {
+	for _, rec := range recs {
+		sm.replace(rec.Key, rec.Val)
+	}
+}
+
+// ChReplace reads records from a channel and adds all given records to the collection.
+// Even if a key already exists, the value will be inserted. If a clearly efficient alternative to this function is proposed, it will likely be accepted and merged.
+func (sm *SortedMap) ChReplace(ch <-chan *Record) {
+	for rec := range ch {
+		sm.replace(rec.Key, rec.Val)
+	}
+}