emap

Enhanced Golang Map

EMap implements an enhanced map in Golang. The main enhancement of emap over original golang map is the support of searching index.

• Values in the emap can have one or more indices which can be used to search or delete.
• Key in the emap must be unique as same as the key in the golang map.
• Index in the emap is an N to M relation which mean a value can have multi indices and multi values can have one same index.

##Several Choices #####Generic EMap

• The generic emap has no restrict for the type of its key, value and index.
• The generic emap has a read-write locker inside so it is concurrent safe.

#####Expirable EMap

• The expirable emap has no restrict for the type of its key, value and index.
• The expirable emap has a read-write locker inside so it is concurrent safe.
• The expirable emap will check all the values in the emap with the period of input interval(milliseconds). If a value is expired, it will be deleted automatically.

#####Strict EMap

• The types of key, value and index used in the strict emap are determined during initialization by the sample inputs.
• All methods of the strict emap must use the same type of the sample inputs otherwise an error will be returned.
• The strict emap has a read-write locker inside so it is concurrent safe.

#####Unlock EMap

• The unlock emap has no restrict for the type of its key, value and index.
• The unlock emap has no locker or mutex inside, so it is not concurrent safe.
• It is only suitable for those models like Event Loop to achieve better performance.

##Requirements #####Download this package

go get github.com/starwander/emap

#####Implements ExpirableValue interface of this package for all values if ExpirableEmap is chosen

// ExpirableValue is the interface which must be implemented by all the value in the expirable EMap.
type ExpirableValue interface {
	// IsExpired returns if the value is expired.
	// If true, the value will be deleted automatically.
	IsExpired() bool
}

Basic Operations

• Insert: pushes a new value into emap with input key and indices.
• FetchByKey: gets the value in the emap by input key.
• FetchByIndex: gets the all values in the emap by input index.
• DeleteByKey: deletes the value in the emap by input key.
• DeleteByIndex: deletes all the values in the emap by input index.
• AddIndex: add the input index to the value in the emap of the input key.
• RemoveIndex: remove the input index from the value in the emap of the input key.
• KeyNum: returns the total key number in the emap.
• KeyNumOfIndex: returns the total key number of the input index in the emap.
• IndexNum: returns the total index number in the emap.
• IndexNumOfKey: returns the total index number of the input key in the emap.
• HasKey: returns if the input key exists in the emap.
• HasIndex: returns if the input index exists in the emap.

Higher-order Operations

• Transform:

• Transform is a higher-order operation which apply the input callback function to each key-value pair in the emap.
• Any error returned by the callback function will interrupt the transforming and the error will be returned.
• If transform successfully, a new golang map is created with each key-value pair returned by the input callback function.

• Foreach:

• Foreach is a higher-order operation which apply the input callback function to each key-value pair in the emap.
• Since the callback function has no return, the foreach procedure will never be interrupted.
• A typical usage of Foreach is apply a closure.

Example

package main

import (
	"fmt"
	"github.com/starwander/emap"
	"time"
)

type employee struct {
	name       string
	gender     string
	department string
	retired    bool
	//hobby      []string
}

type emplyeeByDept struct {
	name       string
	department string
}

func (e *employee) IsExpired() bool {
	return e.retired
}

func main() {
	emap := emap.NewExpirableEMap(1000)

	emap.Insert("Tom", &employee{"Tom", "Male", "R&D", false}, "R&D", "swimming", "hiking")
	emap.Insert("Jerry", &employee{"Jerry", "Male", "Sales", false}, "Sales", "football", "hiking")
	emap.Insert("Carol", &employee{"Carol", "Female", "HR", false}, "HR", "movie")
	emap.Insert("Jessie", &employee{"Jessie", "Female", "Sales", false}, "Sales", "hiking", "cycling")

	fmt.Println(emap.KeyNum())                //4
	fmt.Println(emap.IndexNum())              //8
	fmt.Println(emap.IndexNumOfKey("Tom"))    //3
	fmt.Println(emap.KeyNumOfIndex("hiking")) //3

	fmt.Println(emap.FetchByKey("Carol")) // &{Carol Female HR false} <nil>
	allSales, _ := emap.FetchByIndex("Sales")
	for _, each := range allSales {
		//&{Jerry Male Sales false}
		//&{Jessie Female Sales false}
		fmt.Println(each.(*employee))
	}

	emap.RemoveIndex("Jerry", "hiking")
	allHiking, _ := emap.FetchByIndex("hiking")
	for _, each := range allHiking {
		//&{Tom Male R&D false}
		//&{Jessie Female Sales false}
		fmt.Println(each.(*employee))
	}
	emap.AddIndex("Jessie", "movie")
	allMovie, _ := emap.FetchByIndex("movie")
	for _, each := range allMovie {
		//&{Carol Female HR false}
		//&{Jessie Female Sales false}
		fmt.Println(each.(*employee))
	}

	emap.DeleteByKey("Jerry")
	fmt.Println(emap.KeyNum()) //3

	nameAndDept, _ := emap.Transform(func(n interface{}, e interface{}) (interface{}, error) {
		return &emplyeeByDept{n.(string), e.(*employee).department}, nil
	})
	for _, each := range nameAndDept {
		//&{Jessie Sales}
		//&{Tom R&D}
		//&{Carol HR}
		fmt.Println(each.(*emplyeeByDept))
	}

	var totalMaleNum, totalFemalNum int
	emap.Foreach(func(n interface{}, e interface{}) {
		if e.(*employee).gender == "Male" {
			totalMaleNum++
		} else {
			totalFemalNum++
		}
	})
	fmt.Println("Total male number:", totalMaleNum, "Total female number:", totalFemalNum) //Total male number: 1 Total female number: 2

	carol, _ := emap.FetchByKey("Carol")
	carol.(*employee).retired = true
	time.Sleep(1100 * time.Millisecond)
	fmt.Println(emap.FetchByKey("Carol")) //<nil> key not exist
}

Reference

GoDoc

LICENSE

EMap source code is licensed under the Apache Licence, Version 2.0.