diff --git a/container/glist/glist.go b/container/glist/glist.go index 94319e50e..1df70e4a9 100644 --- a/container/glist/glist.go +++ b/container/glist/glist.go @@ -36,8 +36,8 @@ func New(safe ...bool) *List { } } -// NewFrom creates and returns a list from a copy of given slice . -// The parameter is used to specify whether using list in concurrent-safety, +// NewFrom creates and returns a list from a copy of given slice `array`. +// The parameter `safe` is used to specify whether using list in concurrent-safety, // which is false in default. func NewFrom(array []interface{}, safe ...bool) *List { l := list.New() @@ -50,7 +50,7 @@ func NewFrom(array []interface{}, safe ...bool) *List { } } -// PushFront inserts a new element with value at the front of list and returns . +// PushFront inserts a new element with value at the front of list and returns `e`. func (l *List) PushFront(v interface{}) (e *Element) { l.mu.Lock() if l.list == nil { @@ -61,7 +61,7 @@ func (l *List) PushFront(v interface{}) (e *Element) { return } -// PushBack inserts a new element with value at the back of list and returns . +// PushBack inserts a new element with value at the back of list and returns `e`. func (l *List) PushBack(v interface{}) (e *Element) { l.mu.Lock() if l.list == nil { @@ -72,7 +72,7 @@ func (l *List) PushBack(v interface{}) (e *Element) { return } -// PushFronts inserts multiple new elements with values at the front of list . +// PushFronts inserts multiple new elements with values at the front of list `l`. func (l *List) PushFronts(values []interface{}) { l.mu.Lock() if l.list == nil { @@ -84,7 +84,7 @@ func (l *List) PushFronts(values []interface{}) { l.mu.Unlock() } -// PushBacks inserts multiple new elements with values at the back of list . +// PushBacks inserts multiple new elements with values at the back of list `l`. func (l *List) PushBacks(values []interface{}) { l.mu.Lock() if l.list == nil { @@ -96,7 +96,7 @@ func (l *List) PushBacks(values []interface{}) { l.mu.Unlock() } -// PopBack removes the element from back of and returns the value of the element. +// PopBack removes the element from back of `l` and returns the value of the element. func (l *List) PopBack() (value interface{}) { l.mu.Lock() defer l.mu.Unlock() @@ -110,7 +110,7 @@ func (l *List) PopBack() (value interface{}) { return } -// PopFront removes the element from front of and returns the value of the element. +// PopFront removes the element from front of `l` and returns the value of the element. func (l *List) PopFront() (value interface{}) { l.mu.Lock() defer l.mu.Unlock() @@ -124,7 +124,7 @@ func (l *List) PopFront() (value interface{}) { return } -// PopBacks removes elements from back of +// PopBacks removes elements from back of `l` // and returns values of the removed elements as slice. func (l *List) PopBacks(max int) (values []interface{}) { l.mu.Lock() @@ -146,7 +146,7 @@ func (l *List) PopBacks(max int) (values []interface{}) { return } -// PopFronts removes elements from front of +// PopFronts removes elements from front of `l` // and returns values of the removed elements as slice. func (l *List) PopFronts(max int) (values []interface{}) { l.mu.Lock() @@ -168,19 +168,19 @@ func (l *List) PopFronts(max int) (values []interface{}) { return } -// PopBackAll removes all elements from back of +// PopBackAll removes all elements from back of `l` // and returns values of the removed elements as slice. func (l *List) PopBackAll() []interface{} { return l.PopBacks(-1) } -// PopFrontAll removes all elements from front of +// PopFrontAll removes all elements from front of `l` // and returns values of the removed elements as slice. func (l *List) PopFrontAll() []interface{} { return l.PopFronts(-1) } -// FrontAll copies and returns values of all elements from front of as slice. +// FrontAll copies and returns values of all elements from front of `l` as slice. func (l *List) FrontAll() (values []interface{}) { l.mu.RLock() defer l.mu.RUnlock() @@ -197,7 +197,7 @@ func (l *List) FrontAll() (values []interface{}) { return } -// BackAll copies and returns values of all elements from back of as slice. +// BackAll copies and returns values of all elements from back of `l` as slice. func (l *List) BackAll() (values []interface{}) { l.mu.RLock() defer l.mu.RUnlock() @@ -214,7 +214,7 @@ func (l *List) BackAll() (values []interface{}) { return } -// FrontValue returns value of the first element of or nil if the list is empty. +// FrontValue returns value of the first element of `l` or nil if the list is empty. func (l *List) FrontValue() (value interface{}) { l.mu.RLock() defer l.mu.RUnlock() @@ -227,7 +227,7 @@ func (l *List) FrontValue() (value interface{}) { return } -// BackValue returns value of the last element of or nil if the list is empty. +// BackValue returns value of the last element of `l` or nil if the list is empty. func (l *List) BackValue() (value interface{}) { l.mu.RLock() defer l.mu.RUnlock() @@ -240,7 +240,7 @@ func (l *List) BackValue() (value interface{}) { return } -// Front returns the first element of list or nil if the list is empty. +// Front returns the first element of list `l` or nil if the list is empty. func (l *List) Front() (e *Element) { l.mu.RLock() defer l.mu.RUnlock() @@ -251,7 +251,7 @@ func (l *List) Front() (e *Element) { return } -// Back returns the last element of list or nil if the list is empty. +// Back returns the last element of list `l` or nil if the list is empty. func (l *List) Back() (e *Element) { l.mu.RLock() defer l.mu.RUnlock() @@ -262,7 +262,7 @@ func (l *List) Back() (e *Element) { return } -// Len returns the number of elements of list . +// Len returns the number of elements of list `l`. // The complexity is O(1). func (l *List) Len() (length int) { l.mu.RLock() @@ -279,9 +279,9 @@ func (l *List) Size() int { return l.Len() } -// MoveBefore moves element to its new position before

. -// If or

is not an element of , or ==

, the list is not modified. -// The element and

must not be nil. +// MoveBefore moves element to its new position before `p`. +// If or

is not an element of , or == `p`, the list is not modified. +// The element and `p` must not be nil. func (l *List) MoveBefore(e, p *Element) { l.mu.Lock() defer l.mu.Unlock() @@ -291,9 +291,9 @@ func (l *List) MoveBefore(e, p *Element) { l.list.MoveBefore(e, p) } -// MoveAfter moves element to its new position after

. -// If or

is not an element of , or ==

, the list is not modified. -// The element and

must not be nil. +// MoveAfter moves element to its new position after `p`. +// If or

is not an element of , or == `p`, the list is not modified. +// The element and `p` must not be nil. func (l *List) MoveAfter(e, p *Element) { l.mu.Lock() defer l.mu.Unlock() @@ -303,8 +303,8 @@ func (l *List) MoveAfter(e, p *Element) { l.list.MoveAfter(e, p) } -// MoveToFront moves element to the front of list . -// If is not an element of , the list is not modified. +// MoveToFront moves element to the front of list `l`. +// If is not an element of `l`, the list is not modified. // The element must not be nil. func (l *List) MoveToFront(e *Element) { l.mu.Lock() @@ -315,8 +315,8 @@ func (l *List) MoveToFront(e *Element) { l.list.MoveToFront(e) } -// MoveToBack moves element to the back of list . -// If is not an element of , the list is not modified. +// MoveToBack moves element to the back of list `l`. +// If is not an element of `l`, the list is not modified. // The element must not be nil. func (l *List) MoveToBack(e *Element) { l.mu.Lock() @@ -327,8 +327,8 @@ func (l *List) MoveToBack(e *Element) { l.list.MoveToBack(e) } -// PushBackList inserts a copy of an other list at the back of list . -// The lists and may be the same, but they must not be nil. +// PushBackList inserts a copy of an other list at the back of list `l`. +// The lists and `other` may be the same, but they must not be nil. func (l *List) PushBackList(other *List) { if l != other { other.mu.RLock() @@ -342,8 +342,8 @@ func (l *List) PushBackList(other *List) { l.list.PushBackList(other.list) } -// PushFrontList inserts a copy of an other list at the front of list . -// The lists and may be the same, but they must not be nil. +// PushFrontList inserts a copy of an other list at the front of list `l`. +// The lists and `other` may be the same, but they must not be nil. func (l *List) PushFrontList(other *List) { if l != other { other.mu.RLock() @@ -357,9 +357,9 @@ func (l *List) PushFrontList(other *List) { l.list.PushFrontList(other.list) } -// InsertAfter inserts a new element with value immediately after

and returns . -// If

is not an element of , the list is not modified. -// The

must not be nil. +// InsertAfter inserts a new element with value immediately after

and returns `e`. +// If

is not an element of `l`, the list is not modified. +// The `p` must not be nil. func (l *List) InsertAfter(p *Element, v interface{}) (e *Element) { l.mu.Lock() defer l.mu.Unlock() @@ -370,9 +370,9 @@ func (l *List) InsertAfter(p *Element, v interface{}) (e *Element) { return } -// InsertBefore inserts a new element with value immediately before

and returns . -// If

is not an element of , the list is not modified. -// The

must not be nil. +// InsertBefore inserts a new element with value immediately before

and returns `e`. +// If

is not an element of `l`, the list is not modified. +// The `p` must not be nil. func (l *List) InsertBefore(p *Element, v interface{}) (e *Element) { l.mu.Lock() defer l.mu.Unlock() @@ -383,7 +383,7 @@ func (l *List) InsertBefore(p *Element, v interface{}) (e *Element) { return } -// Remove removes from if is an element of list . +// Remove removes from if is an element of list `l`. // It returns the element value e.Value. // The element must not be nil. func (l *List) Remove(e *Element) (value interface{}) { @@ -396,7 +396,7 @@ func (l *List) Remove(e *Element) (value interface{}) { return } -// Removes removes multiple elements from if are elements of list . +// Removes removes multiple elements from if are elements of list `l`. func (l *List) Removes(es []*Element) { l.mu.Lock() defer l.mu.Unlock() @@ -409,7 +409,7 @@ func (l *List) Removes(es []*Element) { return } -// RemoveAll removes all elements from list . +// RemoveAll removes all elements from list `l`. func (l *List) RemoveAll() { l.mu.Lock() l.list = list.New() @@ -421,7 +421,7 @@ func (l *List) Clear() { l.RemoveAll() } -// RLockFunc locks reading with given callback function within RWMutex.RLock. +// RLockFunc locks reading with given callback function `f` within RWMutex.RLock. func (l *List) RLockFunc(f func(list *list.List)) { l.mu.RLock() defer l.mu.RUnlock() @@ -430,7 +430,7 @@ func (l *List) RLockFunc(f func(list *list.List)) { } } -// LockFunc locks writing with given callback function within RWMutex.Lock. +// LockFunc locks writing with given callback function `f` within RWMutex.Lock. func (l *List) LockFunc(f func(list *list.List)) { l.mu.Lock() defer l.mu.Unlock() @@ -445,8 +445,8 @@ func (l *List) Iterator(f func(e *Element) bool) { l.IteratorAsc(f) } -// IteratorAsc iterates the list readonly in ascending order with given callback function . -// If returns true, then it continues iterating; or false to stop. +// IteratorAsc iterates the list readonly in ascending order with given callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (l *List) IteratorAsc(f func(e *Element) bool) { l.mu.RLock() defer l.mu.RUnlock() @@ -463,8 +463,8 @@ func (l *List) IteratorAsc(f func(e *Element) bool) { } } -// IteratorDesc iterates the list readonly in descending order with given callback function . -// If returns true, then it continues iterating; or false to stop. +// IteratorDesc iterates the list readonly in descending order with given callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (l *List) IteratorDesc(f func(e *Element) bool) { l.mu.RLock() defer l.mu.RUnlock() @@ -481,7 +481,7 @@ func (l *List) IteratorDesc(f func(e *Element) bool) { } } -// Join joins list elements with a string . +// Join joins list elements with a string `glue`. func (l *List) Join(glue string) string { l.mu.RLock() defer l.mu.RUnlock() diff --git a/container/gmap/gmap.go b/container/gmap/gmap.go index b5e887e62..4cff99d3a 100644 --- a/container/gmap/gmap.go +++ b/container/gmap/gmap.go @@ -13,32 +13,32 @@ type ( ) // New creates and returns an empty hash map. -// The parameter is used to specify whether using map in concurrent-safety, +// The parameter `safe` is used to specify whether using map in concurrent-safety, // which is false in default. func New(safe ...bool) *Map { return NewAnyAnyMap(safe...) } -// NewFrom creates and returns a hash map from given map . -// Note that, the param map will be set as the underlying data map(no deep copy), +// NewFrom creates and returns a hash map from given map `data`. +// Note that, the param `data` map will be set as the underlying data map(no deep copy), // there might be some concurrent-safe issues when changing the map outside. -// The parameter is used to specify whether using tree in concurrent-safety, +// The parameter `safe` is used to specify whether using tree in concurrent-safety, // which is false in default. func NewFrom(data map[interface{}]interface{}, safe ...bool) *Map { return NewAnyAnyMapFrom(data, safe...) } // NewHashMap creates and returns an empty hash map. -// The parameter is used to specify whether using map in concurrent-safety, +// The parameter `safe` is used to specify whether using map in concurrent-safety, // which is false in default. func NewHashMap(safe ...bool) *Map { return NewAnyAnyMap(safe...) } -// NewHashMapFrom creates and returns a hash map from given map . -// Note that, the param map will be set as the underlying data map(no deep copy), +// NewHashMapFrom creates and returns a hash map from given map `data`. +// Note that, the param `data` map will be set as the underlying data map(no deep copy), // there might be some concurrent-safe issues when changing the map outside. -// The parameter is used to specify whether using tree in concurrent-safety, +// The parameter `safe` is used to specify whether using tree in concurrent-safety, // which is false in default. func NewHashMapFrom(data map[interface{}]interface{}, safe ...bool) *Map { return NewAnyAnyMapFrom(data, safe...) diff --git a/container/gmap/gmap_hash_any_any_map.go b/container/gmap/gmap_hash_any_any_map.go index 3544d0648..ea56aed8c 100644 --- a/container/gmap/gmap_hash_any_any_map.go +++ b/container/gmap/gmap_hash_any_any_map.go @@ -23,7 +23,7 @@ type AnyAnyMap struct { } // NewAnyAnyMap creates and returns an empty hash map. -// The parameter is used to specify whether using map in concurrent-safety, +// The parameter `safe` is used to specify whether using map in concurrent-safety, // which is false in default. func NewAnyAnyMap(safe ...bool) *AnyAnyMap { return &AnyAnyMap{ @@ -32,8 +32,8 @@ func NewAnyAnyMap(safe ...bool) *AnyAnyMap { } } -// NewAnyAnyMapFrom creates and returns a hash map from given map . -// Note that, the param map will be set as the underlying data map(no deep copy), +// NewAnyAnyMapFrom creates and returns a hash map from given map `data`. +// Note that, the param `data` map will be set as the underlying data map(no deep copy), // there might be some concurrent-safe issues when changing the map outside. func NewAnyAnyMapFrom(data map[interface{}]interface{}, safe ...bool) *AnyAnyMap { return &AnyAnyMap{ @@ -42,8 +42,8 @@ func NewAnyAnyMapFrom(data map[interface{}]interface{}, safe ...bool) *AnyAnyMap } } -// Iterator iterates the hash map readonly with custom callback function . -// If returns true, then it continues iterating; or false to stop. +// Iterator iterates the hash map readonly with custom callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (m *AnyAnyMap) Iterator(f func(k interface{}, v interface{}) bool) { m.mu.RLock() defer m.mu.RUnlock() @@ -143,8 +143,8 @@ func (m *AnyAnyMap) Sets(data map[interface{}]interface{}) { m.mu.Unlock() } -// Search searches the map with given . -// Second return parameter is true if key was found, otherwise false. +// Search searches the map with given `key`. +// Second return parameter `found` is true if key was found, otherwise false. func (m *AnyAnyMap) Search(key interface{}) (value interface{}, found bool) { m.mu.RLock() if m.data != nil { @@ -154,7 +154,7 @@ func (m *AnyAnyMap) Search(key interface{}) (value interface{}, found bool) { return } -// Get returns the value by given . +// Get returns the value by given `key`. func (m *AnyAnyMap) Get(key interface{}) (value interface{}) { m.mu.RLock() if m.data != nil { @@ -175,7 +175,7 @@ func (m *AnyAnyMap) Pop() (key, value interface{}) { return } -// Pops retrieves and deletes items from the map. +// Pops retrieves and deletes `size` items from the map. // It returns all items if size == -1. func (m *AnyAnyMap) Pops(size int) map[interface{}]interface{} { m.mu.Lock() @@ -202,14 +202,14 @@ func (m *AnyAnyMap) Pops(size int) map[interface{}]interface{} { } // doSetWithLockCheck checks whether value of the key exists with mutex.Lock, -// if not exists, set value to the map with given , +// if not exists, set value to the map with given `key`, // or else just return the existing value. // -// When setting value, if is type of , +// When setting value, if `value` is type of , // it will be executed with mutex.Lock of the hash map, -// and its return value will be set to the map with . +// and its return value will be set to the map with `key`. // -// It returns value with given . +// It returns value with given `key`. func (m *AnyAnyMap) doSetWithLockCheck(key interface{}, value interface{}) interface{} { m.mu.Lock() defer m.mu.Unlock() @@ -229,7 +229,7 @@ func (m *AnyAnyMap) doSetWithLockCheck(key interface{}, value interface{}) inter } // GetOrSet returns the value by key, -// or sets value with given if it does not exist and then returns this value. +// or sets value with given `value` if it does not exist and then returns this value. func (m *AnyAnyMap) GetOrSet(key interface{}, value interface{}) interface{} { if v, ok := m.Search(key); !ok { return m.doSetWithLockCheck(key, value) @@ -239,7 +239,7 @@ func (m *AnyAnyMap) GetOrSet(key interface{}, value interface{}) interface{} { } // GetOrSetFunc returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. func (m *AnyAnyMap) GetOrSetFunc(key interface{}, f func() interface{}) interface{} { if v, ok := m.Search(key); !ok { @@ -250,10 +250,10 @@ func (m *AnyAnyMap) GetOrSetFunc(key interface{}, f func() interface{}) interfac } // GetOrSetFuncLock returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. // -// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function +// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function `f` // with mutex.Lock of the hash map. func (m *AnyAnyMap) GetOrSetFuncLock(key interface{}, f func() interface{}) interface{} { if v, ok := m.Search(key); !ok { @@ -263,7 +263,7 @@ func (m *AnyAnyMap) GetOrSetFuncLock(key interface{}, f func() interface{}) inte } } -// GetVar returns a Var with the value by given . +// GetVar returns a Var with the value by given `key`. // The returned Var is un-concurrent safe. func (m *AnyAnyMap) GetVar(key interface{}) *gvar.Var { return gvar.New(m.Get(key)) @@ -287,8 +287,8 @@ func (m *AnyAnyMap) GetVarOrSetFuncLock(key interface{}, f func() interface{}) * return gvar.New(m.GetOrSetFuncLock(key, f)) } -// SetIfNotExist sets to the map if the does not exist, and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExist sets to the map if the `key` does not exist, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *AnyAnyMap) SetIfNotExist(key interface{}, value interface{}) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, value) @@ -297,8 +297,8 @@ func (m *AnyAnyMap) SetIfNotExist(key interface{}, value interface{}) bool { return false } -// SetIfNotExistFunc sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFunc sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *AnyAnyMap) SetIfNotExistFunc(key interface{}, f func() interface{}) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, f()) @@ -307,11 +307,11 @@ func (m *AnyAnyMap) SetIfNotExistFunc(key interface{}, f func() interface{}) boo return false } -// SetIfNotExistFuncLock sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFuncLock sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. // // SetIfNotExistFuncLock differs with SetIfNotExistFunc function is that -// it executes function with mutex.Lock of the hash map. +// it executes function `f` with mutex.Lock of the hash map. func (m *AnyAnyMap) SetIfNotExistFuncLock(key interface{}, f func() interface{}) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, f) @@ -320,7 +320,7 @@ func (m *AnyAnyMap) SetIfNotExistFuncLock(key interface{}, f func() interface{}) return false } -// Remove deletes value from map by given , and return this deleted value. +// Remove deletes value from map by given `key`, and return this deleted value. func (m *AnyAnyMap) Remove(key interface{}) (value interface{}) { m.mu.Lock() if m.data != nil { @@ -375,7 +375,7 @@ func (m *AnyAnyMap) Values() []interface{} { } // Contains checks whether a key exists. -// It returns true if the exists, or else false. +// It returns true if the `key` exists, or else false. func (m *AnyAnyMap) Contains(key interface{}) bool { var ok bool m.mu.RLock() @@ -407,21 +407,21 @@ func (m *AnyAnyMap) Clear() { m.mu.Unlock() } -// Replace the data of the map with given . +// Replace the data of the map with given `data`. func (m *AnyAnyMap) Replace(data map[interface{}]interface{}) { m.mu.Lock() m.data = data m.mu.Unlock() } -// LockFunc locks writing with given callback function within RWMutex.Lock. +// LockFunc locks writing with given callback function `f` within RWMutex.Lock. func (m *AnyAnyMap) LockFunc(f func(m map[interface{}]interface{})) { m.mu.Lock() defer m.mu.Unlock() f(m.data) } -// RLockFunc locks reading with given callback function within RWMutex.RLock. +// RLockFunc locks reading with given callback function `f` within RWMutex.RLock. func (m *AnyAnyMap) RLockFunc(f func(m map[interface{}]interface{})) { m.mu.RLock() defer m.mu.RUnlock() @@ -440,7 +440,7 @@ func (m *AnyAnyMap) Flip() { } // Merge merges two hash maps. -// The map will be merged into the map . +// The map will be merged into the map `m`. func (m *AnyAnyMap) Merge(other *AnyAnyMap) { m.mu.Lock() defer m.mu.Unlock() diff --git a/container/gmap/gmap_hash_int_any_map.go b/container/gmap/gmap_hash_int_any_map.go index 5ced8024f..1a53a8b63 100644 --- a/container/gmap/gmap_hash_int_any_map.go +++ b/container/gmap/gmap_hash_int_any_map.go @@ -23,7 +23,7 @@ type IntAnyMap struct { } // NewIntAnyMap returns an empty IntAnyMap object. -// The parameter is used to specify whether using map in concurrent-safety, +// The parameter `safe` is used to specify whether using map in concurrent-safety, // which is false in default. func NewIntAnyMap(safe ...bool) *IntAnyMap { return &IntAnyMap{ @@ -32,8 +32,8 @@ func NewIntAnyMap(safe ...bool) *IntAnyMap { } } -// NewIntAnyMapFrom creates and returns a hash map from given map . -// Note that, the param map will be set as the underlying data map(no deep copy), +// NewIntAnyMapFrom creates and returns a hash map from given map `data`. +// Note that, the param `data` map will be set as the underlying data map(no deep copy), // there might be some concurrent-safe issues when changing the map outside. func NewIntAnyMapFrom(data map[int]interface{}, safe ...bool) *IntAnyMap { return &IntAnyMap{ @@ -42,8 +42,8 @@ func NewIntAnyMapFrom(data map[int]interface{}, safe ...bool) *IntAnyMap { } } -// Iterator iterates the hash map readonly with custom callback function . -// If returns true, then it continues iterating; or false to stop. +// Iterator iterates the hash map readonly with custom callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (m *IntAnyMap) Iterator(f func(k int, v interface{}) bool) { m.mu.RLock() defer m.mu.RUnlock() @@ -143,8 +143,8 @@ func (m *IntAnyMap) Sets(data map[int]interface{}) { m.mu.Unlock() } -// Search searches the map with given . -// Second return parameter is true if key was found, otherwise false. +// Search searches the map with given `key`. +// Second return parameter `found` is true if key was found, otherwise false. func (m *IntAnyMap) Search(key int) (value interface{}, found bool) { m.mu.RLock() if m.data != nil { @@ -154,7 +154,7 @@ func (m *IntAnyMap) Search(key int) (value interface{}, found bool) { return } -// Get returns the value by given . +// Get returns the value by given `key`. func (m *IntAnyMap) Get(key int) (value interface{}) { m.mu.RLock() if m.data != nil { @@ -175,7 +175,7 @@ func (m *IntAnyMap) Pop() (key int, value interface{}) { return } -// Pops retrieves and deletes items from the map. +// Pops retrieves and deletes `size` items from the map. // It returns all items if size == -1. func (m *IntAnyMap) Pops(size int) map[int]interface{} { m.mu.Lock() @@ -202,14 +202,14 @@ func (m *IntAnyMap) Pops(size int) map[int]interface{} { } // doSetWithLockCheck checks whether value of the key exists with mutex.Lock, -// if not exists, set value to the map with given , +// if not exists, set value to the map with given `key`, // or else just return the existing value. // -// When setting value, if is type of , +// When setting value, if `value` is type of , // it will be executed with mutex.Lock of the hash map, -// and its return value will be set to the map with . +// and its return value will be set to the map with `key`. // -// It returns value with given . +// It returns value with given `key`. func (m *IntAnyMap) doSetWithLockCheck(key int, value interface{}) interface{} { m.mu.Lock() defer m.mu.Unlock() @@ -229,7 +229,7 @@ func (m *IntAnyMap) doSetWithLockCheck(key int, value interface{}) interface{} { } // GetOrSet returns the value by key, -// or sets value with given if it does not exist and then returns this value. +// or sets value with given `value` if it does not exist and then returns this value. func (m *IntAnyMap) GetOrSet(key int, value interface{}) interface{} { if v, ok := m.Search(key); !ok { return m.doSetWithLockCheck(key, value) @@ -239,7 +239,7 @@ func (m *IntAnyMap) GetOrSet(key int, value interface{}) interface{} { } // GetOrSetFunc returns the value by key, -// or sets value with returned value of callback function if it does not exist and returns this value. +// or sets value with returned value of callback function `f` if it does not exist and returns this value. func (m *IntAnyMap) GetOrSetFunc(key int, f func() interface{}) interface{} { if v, ok := m.Search(key); !ok { return m.doSetWithLockCheck(key, f()) @@ -249,9 +249,9 @@ func (m *IntAnyMap) GetOrSetFunc(key int, f func() interface{}) interface{} { } // GetOrSetFuncLock returns the value by key, -// or sets value with returned value of callback function if it does not exist and returns this value. +// or sets value with returned value of callback function `f` if it does not exist and returns this value. // -// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function +// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function `f` // with mutex.Lock of the hash map. func (m *IntAnyMap) GetOrSetFuncLock(key int, f func() interface{}) interface{} { if v, ok := m.Search(key); !ok { @@ -261,7 +261,7 @@ func (m *IntAnyMap) GetOrSetFuncLock(key int, f func() interface{}) interface{} } } -// GetVar returns a Var with the value by given . +// GetVar returns a Var with the value by given `key`. // The returned Var is un-concurrent safe. func (m *IntAnyMap) GetVar(key int) *gvar.Var { return gvar.New(m.Get(key)) @@ -285,8 +285,8 @@ func (m *IntAnyMap) GetVarOrSetFuncLock(key int, f func() interface{}) *gvar.Var return gvar.New(m.GetOrSetFuncLock(key, f)) } -// SetIfNotExist sets to the map if the does not exist, and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExist sets to the map if the `key` does not exist, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *IntAnyMap) SetIfNotExist(key int, value interface{}) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, value) @@ -295,8 +295,8 @@ func (m *IntAnyMap) SetIfNotExist(key int, value interface{}) bool { return false } -// SetIfNotExistFunc sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFunc sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *IntAnyMap) SetIfNotExistFunc(key int, f func() interface{}) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, f()) @@ -305,11 +305,11 @@ func (m *IntAnyMap) SetIfNotExistFunc(key int, f func() interface{}) bool { return false } -// SetIfNotExistFuncLock sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFuncLock sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. // // SetIfNotExistFuncLock differs with SetIfNotExistFunc function is that -// it executes function with mutex.Lock of the hash map. +// it executes function `f` with mutex.Lock of the hash map. func (m *IntAnyMap) SetIfNotExistFuncLock(key int, f func() interface{}) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, f) @@ -329,7 +329,7 @@ func (m *IntAnyMap) Removes(keys []int) { m.mu.Unlock() } -// Remove deletes value from map by given , and return this deleted value. +// Remove deletes value from map by given `key`, and return this deleted value. func (m *IntAnyMap) Remove(key int) (value interface{}) { m.mu.Lock() if m.data != nil { @@ -373,7 +373,7 @@ func (m *IntAnyMap) Values() []interface{} { } // Contains checks whether a key exists. -// It returns true if the exists, or else false. +// It returns true if the `key` exists, or else false. func (m *IntAnyMap) Contains(key int) bool { var ok bool m.mu.RLock() @@ -405,21 +405,21 @@ func (m *IntAnyMap) Clear() { m.mu.Unlock() } -// Replace the data of the map with given . +// Replace the data of the map with given `data`. func (m *IntAnyMap) Replace(data map[int]interface{}) { m.mu.Lock() m.data = data m.mu.Unlock() } -// LockFunc locks writing with given callback function within RWMutex.Lock. +// LockFunc locks writing with given callback function `f` within RWMutex.Lock. func (m *IntAnyMap) LockFunc(f func(m map[int]interface{})) { m.mu.Lock() defer m.mu.Unlock() f(m.data) } -// RLockFunc locks reading with given callback function within RWMutex.RLock. +// RLockFunc locks reading with given callback function `f` within RWMutex.RLock. func (m *IntAnyMap) RLockFunc(f func(m map[int]interface{})) { m.mu.RLock() defer m.mu.RUnlock() @@ -438,7 +438,7 @@ func (m *IntAnyMap) Flip() { } // Merge merges two hash maps. -// The map will be merged into the map . +// The map will be merged into the map `m`. func (m *IntAnyMap) Merge(other *IntAnyMap) { m.mu.Lock() defer m.mu.Unlock() diff --git a/container/gmap/gmap_hash_int_int_map.go b/container/gmap/gmap_hash_int_int_map.go index 5ca359630..404ad6f70 100644 --- a/container/gmap/gmap_hash_int_int_map.go +++ b/container/gmap/gmap_hash_int_int_map.go @@ -21,7 +21,7 @@ type IntIntMap struct { } // NewIntIntMap returns an empty IntIntMap object. -// The parameter is used to specify whether using map in concurrent-safety, +// The parameter `safe` is used to specify whether using map in concurrent-safety, // which is false in default. func NewIntIntMap(safe ...bool) *IntIntMap { return &IntIntMap{ @@ -30,8 +30,8 @@ func NewIntIntMap(safe ...bool) *IntIntMap { } } -// NewIntIntMapFrom creates and returns a hash map from given map . -// Note that, the param map will be set as the underlying data map(no deep copy), +// NewIntIntMapFrom creates and returns a hash map from given map `data`. +// Note that, the param `data` map will be set as the underlying data map(no deep copy), // there might be some concurrent-safe issues when changing the map outside. func NewIntIntMapFrom(data map[int]int, safe ...bool) *IntIntMap { return &IntIntMap{ @@ -40,8 +40,8 @@ func NewIntIntMapFrom(data map[int]int, safe ...bool) *IntIntMap { } } -// Iterator iterates the hash map readonly with custom callback function . -// If returns true, then it continues iterating; or false to stop. +// Iterator iterates the hash map readonly with custom callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (m *IntIntMap) Iterator(f func(k int, v int) bool) { m.mu.RLock() defer m.mu.RUnlock() @@ -130,8 +130,8 @@ func (m *IntIntMap) Sets(data map[int]int) { m.mu.Unlock() } -// Search searches the map with given . -// Second return parameter is true if key was found, otherwise false. +// Search searches the map with given `key`. +// Second return parameter `found` is true if key was found, otherwise false. func (m *IntIntMap) Search(key int) (value int, found bool) { m.mu.RLock() if m.data != nil { @@ -141,7 +141,7 @@ func (m *IntIntMap) Search(key int) (value int, found bool) { return } -// Get returns the value by given . +// Get returns the value by given `key`. func (m *IntIntMap) Get(key int) (value int) { m.mu.RLock() if m.data != nil { @@ -162,7 +162,7 @@ func (m *IntIntMap) Pop() (key, value int) { return } -// Pops retrieves and deletes items from the map. +// Pops retrieves and deletes `size` items from the map. // It returns all items if size == -1. func (m *IntIntMap) Pops(size int) map[int]int { m.mu.Lock() @@ -189,10 +189,10 @@ func (m *IntIntMap) Pops(size int) map[int]int { } // doSetWithLockCheck checks whether value of the key exists with mutex.Lock, -// if not exists, set value to the map with given , +// if not exists, set value to the map with given `key`, // or else just return the existing value. // -// It returns value with given . +// It returns value with given `key`. func (m *IntIntMap) doSetWithLockCheck(key int, value int) int { m.mu.Lock() defer m.mu.Unlock() @@ -207,7 +207,7 @@ func (m *IntIntMap) doSetWithLockCheck(key int, value int) int { } // GetOrSet returns the value by key, -// or sets value with given if it does not exist and then returns this value. +// or sets value with given `value` if it does not exist and then returns this value. func (m *IntIntMap) GetOrSet(key int, value int) int { if v, ok := m.Search(key); !ok { return m.doSetWithLockCheck(key, value) @@ -217,7 +217,7 @@ func (m *IntIntMap) GetOrSet(key int, value int) int { } // GetOrSetFunc returns the value by key, -// or sets value with returned value of callback function if it does not exist and returns this value. +// or sets value with returned value of callback function `f` if it does not exist and returns this value. func (m *IntIntMap) GetOrSetFunc(key int, f func() int) int { if v, ok := m.Search(key); !ok { return m.doSetWithLockCheck(key, f()) @@ -227,9 +227,9 @@ func (m *IntIntMap) GetOrSetFunc(key int, f func() int) int { } // GetOrSetFuncLock returns the value by key, -// or sets value with returned value of callback function if it does not exist and returns this value. +// or sets value with returned value of callback function `f` if it does not exist and returns this value. // -// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function +// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function `f` // with mutex.Lock of the hash map. func (m *IntIntMap) GetOrSetFuncLock(key int, f func() int) int { if v, ok := m.Search(key); !ok { @@ -249,8 +249,8 @@ func (m *IntIntMap) GetOrSetFuncLock(key int, f func() int) int { } } -// SetIfNotExist sets to the map if the does not exist, and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExist sets to the map if the `key` does not exist, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *IntIntMap) SetIfNotExist(key int, value int) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, value) @@ -259,8 +259,8 @@ func (m *IntIntMap) SetIfNotExist(key int, value int) bool { return false } -// SetIfNotExistFunc sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFunc sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *IntIntMap) SetIfNotExistFunc(key int, f func() int) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, f()) @@ -269,11 +269,11 @@ func (m *IntIntMap) SetIfNotExistFunc(key int, f func() int) bool { return false } -// SetIfNotExistFuncLock sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFuncLock sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. // // SetIfNotExistFuncLock differs with SetIfNotExistFunc function is that -// it executes function with mutex.Lock of the hash map. +// it executes function `f` with mutex.Lock of the hash map. func (m *IntIntMap) SetIfNotExistFuncLock(key int, f func() int) bool { if !m.Contains(key) { m.mu.Lock() @@ -300,7 +300,7 @@ func (m *IntIntMap) Removes(keys []int) { m.mu.Unlock() } -// Remove deletes value from map by given , and return this deleted value. +// Remove deletes value from map by given `key`, and return this deleted value. func (m *IntIntMap) Remove(key int) (value int) { m.mu.Lock() if m.data != nil { @@ -344,7 +344,7 @@ func (m *IntIntMap) Values() []int { } // Contains checks whether a key exists. -// It returns true if the exists, or else false. +// It returns true if the `key` exists, or else false. func (m *IntIntMap) Contains(key int) bool { var ok bool m.mu.RLock() @@ -376,21 +376,21 @@ func (m *IntIntMap) Clear() { m.mu.Unlock() } -// Replace the data of the map with given . +// Replace the data of the map with given `data`. func (m *IntIntMap) Replace(data map[int]int) { m.mu.Lock() m.data = data m.mu.Unlock() } -// LockFunc locks writing with given callback function within RWMutex.Lock. +// LockFunc locks writing with given callback function `f` within RWMutex.Lock. func (m *IntIntMap) LockFunc(f func(m map[int]int)) { m.mu.Lock() defer m.mu.Unlock() f(m.data) } -// RLockFunc locks reading with given callback function within RWMutex.RLock. +// RLockFunc locks reading with given callback function `f` within RWMutex.RLock. func (m *IntIntMap) RLockFunc(f func(m map[int]int)) { m.mu.RLock() defer m.mu.RUnlock() @@ -409,7 +409,7 @@ func (m *IntIntMap) Flip() { } // Merge merges two hash maps. -// The map will be merged into the map . +// The map will be merged into the map `m`. func (m *IntIntMap) Merge(other *IntIntMap) { m.mu.Lock() defer m.mu.Unlock() diff --git a/container/gmap/gmap_hash_int_str_map.go b/container/gmap/gmap_hash_int_str_map.go index df5a655d8..9e6dc6c34 100644 --- a/container/gmap/gmap_hash_int_str_map.go +++ b/container/gmap/gmap_hash_int_str_map.go @@ -21,7 +21,7 @@ type IntStrMap struct { } // NewIntStrMap returns an empty IntStrMap object. -// The parameter is used to specify whether using map in concurrent-safety, +// The parameter `safe` is used to specify whether using map in concurrent-safety, // which is false in default. func NewIntStrMap(safe ...bool) *IntStrMap { return &IntStrMap{ @@ -30,8 +30,8 @@ func NewIntStrMap(safe ...bool) *IntStrMap { } } -// NewIntStrMapFrom creates and returns a hash map from given map . -// Note that, the param map will be set as the underlying data map(no deep copy), +// NewIntStrMapFrom creates and returns a hash map from given map `data`. +// Note that, the param `data` map will be set as the underlying data map(no deep copy), // there might be some concurrent-safe issues when changing the map outside. func NewIntStrMapFrom(data map[int]string, safe ...bool) *IntStrMap { return &IntStrMap{ @@ -40,8 +40,8 @@ func NewIntStrMapFrom(data map[int]string, safe ...bool) *IntStrMap { } } -// Iterator iterates the hash map readonly with custom callback function . -// If returns true, then it continues iterating; or false to stop. +// Iterator iterates the hash map readonly with custom callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (m *IntStrMap) Iterator(f func(k int, v string) bool) { m.mu.RLock() defer m.mu.RUnlock() @@ -130,8 +130,8 @@ func (m *IntStrMap) Sets(data map[int]string) { m.mu.Unlock() } -// Search searches the map with given . -// Second return parameter is true if key was found, otherwise false. +// Search searches the map with given `key`. +// Second return parameter `found` is true if key was found, otherwise false. func (m *IntStrMap) Search(key int) (value string, found bool) { m.mu.RLock() if m.data != nil { @@ -141,7 +141,7 @@ func (m *IntStrMap) Search(key int) (value string, found bool) { return } -// Get returns the value by given . +// Get returns the value by given `key`. func (m *IntStrMap) Get(key int) (value string) { m.mu.RLock() if m.data != nil { @@ -162,7 +162,7 @@ func (m *IntStrMap) Pop() (key int, value string) { return } -// Pops retrieves and deletes items from the map. +// Pops retrieves and deletes `size` items from the map. // It returns all items if size == -1. func (m *IntStrMap) Pops(size int) map[int]string { m.mu.Lock() @@ -189,10 +189,10 @@ func (m *IntStrMap) Pops(size int) map[int]string { } // doSetWithLockCheck checks whether value of the key exists with mutex.Lock, -// if not exists, set value to the map with given , +// if not exists, set value to the map with given `key`, // or else just return the existing value. // -// It returns value with given . +// It returns value with given `key`. func (m *IntStrMap) doSetWithLockCheck(key int, value string) string { m.mu.Lock() defer m.mu.Unlock() @@ -207,7 +207,7 @@ func (m *IntStrMap) doSetWithLockCheck(key int, value string) string { } // GetOrSet returns the value by key, -// or sets value with given if it does not exist and then returns this value. +// or sets value with given `value` if it does not exist and then returns this value. func (m *IntStrMap) GetOrSet(key int, value string) string { if v, ok := m.Search(key); !ok { return m.doSetWithLockCheck(key, value) @@ -217,7 +217,7 @@ func (m *IntStrMap) GetOrSet(key int, value string) string { } // GetOrSetFunc returns the value by key, -// or sets value with returned value of callback function if it does not exist and returns this value. +// or sets value with returned value of callback function `f` if it does not exist and returns this value. func (m *IntStrMap) GetOrSetFunc(key int, f func() string) string { if v, ok := m.Search(key); !ok { return m.doSetWithLockCheck(key, f()) @@ -227,9 +227,9 @@ func (m *IntStrMap) GetOrSetFunc(key int, f func() string) string { } // GetOrSetFuncLock returns the value by key, -// or sets value with returned value of callback function if it does not exist and returns this value. +// or sets value with returned value of callback function `f` if it does not exist and returns this value. // -// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function +// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function `f` // with mutex.Lock of the hash map. func (m *IntStrMap) GetOrSetFuncLock(key int, f func() string) string { if v, ok := m.Search(key); !ok { @@ -249,8 +249,8 @@ func (m *IntStrMap) GetOrSetFuncLock(key int, f func() string) string { } } -// SetIfNotExist sets to the map if the does not exist, and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExist sets to the map if the `key` does not exist, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *IntStrMap) SetIfNotExist(key int, value string) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, value) @@ -259,8 +259,8 @@ func (m *IntStrMap) SetIfNotExist(key int, value string) bool { return false } -// SetIfNotExistFunc sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFunc sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *IntStrMap) SetIfNotExistFunc(key int, f func() string) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, f()) @@ -269,11 +269,11 @@ func (m *IntStrMap) SetIfNotExistFunc(key int, f func() string) bool { return false } -// SetIfNotExistFuncLock sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFuncLock sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. // // SetIfNotExistFuncLock differs with SetIfNotExistFunc function is that -// it executes function with mutex.Lock of the hash map. +// it executes function `f` with mutex.Lock of the hash map. func (m *IntStrMap) SetIfNotExistFuncLock(key int, f func() string) bool { if !m.Contains(key) { m.mu.Lock() @@ -300,7 +300,7 @@ func (m *IntStrMap) Removes(keys []int) { m.mu.Unlock() } -// Remove deletes value from map by given , and return this deleted value. +// Remove deletes value from map by given `key`, and return this deleted value. func (m *IntStrMap) Remove(key int) (value string) { m.mu.Lock() if m.data != nil { @@ -344,7 +344,7 @@ func (m *IntStrMap) Values() []string { } // Contains checks whether a key exists. -// It returns true if the exists, or else false. +// It returns true if the `key` exists, or else false. func (m *IntStrMap) Contains(key int) bool { var ok bool m.mu.RLock() @@ -376,21 +376,21 @@ func (m *IntStrMap) Clear() { m.mu.Unlock() } -// Replace the data of the map with given . +// Replace the data of the map with given `data`. func (m *IntStrMap) Replace(data map[int]string) { m.mu.Lock() m.data = data m.mu.Unlock() } -// LockFunc locks writing with given callback function within RWMutex.Lock. +// LockFunc locks writing with given callback function `f` within RWMutex.Lock. func (m *IntStrMap) LockFunc(f func(m map[int]string)) { m.mu.Lock() defer m.mu.Unlock() f(m.data) } -// RLockFunc locks reading with given callback function within RWMutex.RLock. +// RLockFunc locks reading with given callback function `f` within RWMutex.RLock. func (m *IntStrMap) RLockFunc(f func(m map[int]string)) { m.mu.RLock() defer m.mu.RUnlock() @@ -409,7 +409,7 @@ func (m *IntStrMap) Flip() { } // Merge merges two hash maps. -// The map will be merged into the map . +// The map will be merged into the map `m`. func (m *IntStrMap) Merge(other *IntStrMap) { m.mu.Lock() defer m.mu.Unlock() diff --git a/container/gmap/gmap_hash_str_any_map.go b/container/gmap/gmap_hash_str_any_map.go index 802cd09db..609ebc026 100644 --- a/container/gmap/gmap_hash_str_any_map.go +++ b/container/gmap/gmap_hash_str_any_map.go @@ -23,7 +23,7 @@ type StrAnyMap struct { } // NewStrAnyMap returns an empty StrAnyMap object. -// The parameter is used to specify whether using map in concurrent-safety, +// The parameter `safe` is used to specify whether using map in concurrent-safety, // which is false in default. func NewStrAnyMap(safe ...bool) *StrAnyMap { return &StrAnyMap{ @@ -32,8 +32,8 @@ func NewStrAnyMap(safe ...bool) *StrAnyMap { } } -// NewStrAnyMapFrom creates and returns a hash map from given map . -// Note that, the param map will be set as the underlying data map(no deep copy), +// NewStrAnyMapFrom creates and returns a hash map from given map `data`. +// Note that, the param `data` map will be set as the underlying data map(no deep copy), // there might be some concurrent-safe issues when changing the map outside. func NewStrAnyMapFrom(data map[string]interface{}, safe ...bool) *StrAnyMap { return &StrAnyMap{ @@ -42,8 +42,8 @@ func NewStrAnyMapFrom(data map[string]interface{}, safe ...bool) *StrAnyMap { } } -// Iterator iterates the hash map readonly with custom callback function . -// If returns true, then it continues iterating; or false to stop. +// Iterator iterates the hash map readonly with custom callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (m *StrAnyMap) Iterator(f func(k string, v interface{}) bool) { m.mu.RLock() defer m.mu.RUnlock() @@ -137,8 +137,8 @@ func (m *StrAnyMap) Sets(data map[string]interface{}) { m.mu.Unlock() } -// Search searches the map with given . -// Second return parameter is true if key was found, otherwise false. +// Search searches the map with given `key`. +// Second return parameter `found` is true if key was found, otherwise false. func (m *StrAnyMap) Search(key string) (value interface{}, found bool) { m.mu.RLock() if m.data != nil { @@ -148,7 +148,7 @@ func (m *StrAnyMap) Search(key string) (value interface{}, found bool) { return } -// Get returns the value by given . +// Get returns the value by given `key`. func (m *StrAnyMap) Get(key string) (value interface{}) { m.mu.RLock() if m.data != nil { @@ -169,7 +169,7 @@ func (m *StrAnyMap) Pop() (key string, value interface{}) { return } -// Pops retrieves and deletes items from the map. +// Pops retrieves and deletes `size` items from the map. // It returns all items if size == -1. func (m *StrAnyMap) Pops(size int) map[string]interface{} { m.mu.Lock() @@ -196,14 +196,14 @@ func (m *StrAnyMap) Pops(size int) map[string]interface{} { } // doSetWithLockCheck checks whether value of the key exists with mutex.Lock, -// if not exists, set value to the map with given , +// if not exists, set value to the map with given `key`, // or else just return the existing value. // -// When setting value, if is type of , +// When setting value, if `value` is type of , // it will be executed with mutex.Lock of the hash map, -// and its return value will be set to the map with . +// and its return value will be set to the map with `key`. // -// It returns value with given . +// It returns value with given `key`. func (m *StrAnyMap) doSetWithLockCheck(key string, value interface{}) interface{} { m.mu.Lock() defer m.mu.Unlock() @@ -223,7 +223,7 @@ func (m *StrAnyMap) doSetWithLockCheck(key string, value interface{}) interface{ } // GetOrSet returns the value by key, -// or sets value with given if it does not exist and then returns this value. +// or sets value with given `value` if it does not exist and then returns this value. func (m *StrAnyMap) GetOrSet(key string, value interface{}) interface{} { if v, ok := m.Search(key); !ok { return m.doSetWithLockCheck(key, value) @@ -233,7 +233,7 @@ func (m *StrAnyMap) GetOrSet(key string, value interface{}) interface{} { } // GetOrSetFunc returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. func (m *StrAnyMap) GetOrSetFunc(key string, f func() interface{}) interface{} { if v, ok := m.Search(key); !ok { @@ -244,10 +244,10 @@ func (m *StrAnyMap) GetOrSetFunc(key string, f func() interface{}) interface{} { } // GetOrSetFuncLock returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. // -// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function +// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function `f` // with mutex.Lock of the hash map. func (m *StrAnyMap) GetOrSetFuncLock(key string, f func() interface{}) interface{} { if v, ok := m.Search(key); !ok { @@ -257,7 +257,7 @@ func (m *StrAnyMap) GetOrSetFuncLock(key string, f func() interface{}) interface } } -// GetVar returns a Var with the value by given . +// GetVar returns a Var with the value by given `key`. // The returned Var is un-concurrent safe. func (m *StrAnyMap) GetVar(key string) *gvar.Var { return gvar.New(m.Get(key)) @@ -281,8 +281,8 @@ func (m *StrAnyMap) GetVarOrSetFuncLock(key string, f func() interface{}) *gvar. return gvar.New(m.GetOrSetFuncLock(key, f)) } -// SetIfNotExist sets to the map if the does not exist, and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExist sets to the map if the `key` does not exist, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *StrAnyMap) SetIfNotExist(key string, value interface{}) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, value) @@ -291,8 +291,8 @@ func (m *StrAnyMap) SetIfNotExist(key string, value interface{}) bool { return false } -// SetIfNotExistFunc sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFunc sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *StrAnyMap) SetIfNotExistFunc(key string, f func() interface{}) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, f()) @@ -301,11 +301,11 @@ func (m *StrAnyMap) SetIfNotExistFunc(key string, f func() interface{}) bool { return false } -// SetIfNotExistFuncLock sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFuncLock sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. // // SetIfNotExistFuncLock differs with SetIfNotExistFunc function is that -// it executes function with mutex.Lock of the hash map. +// it executes function `f` with mutex.Lock of the hash map. func (m *StrAnyMap) SetIfNotExistFuncLock(key string, f func() interface{}) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, f) @@ -325,7 +325,7 @@ func (m *StrAnyMap) Removes(keys []string) { m.mu.Unlock() } -// Remove deletes value from map by given , and return this deleted value. +// Remove deletes value from map by given `key`, and return this deleted value. func (m *StrAnyMap) Remove(key string) (value interface{}) { m.mu.Lock() if m.data != nil { @@ -369,7 +369,7 @@ func (m *StrAnyMap) Values() []interface{} { } // Contains checks whether a key exists. -// It returns true if the exists, or else false. +// It returns true if the `key` exists, or else false. func (m *StrAnyMap) Contains(key string) bool { var ok bool m.mu.RLock() @@ -401,21 +401,21 @@ func (m *StrAnyMap) Clear() { m.mu.Unlock() } -// Replace the data of the map with given . +// Replace the data of the map with given `data`. func (m *StrAnyMap) Replace(data map[string]interface{}) { m.mu.Lock() m.data = data m.mu.Unlock() } -// LockFunc locks writing with given callback function within RWMutex.Lock. +// LockFunc locks writing with given callback function `f` within RWMutex.Lock. func (m *StrAnyMap) LockFunc(f func(m map[string]interface{})) { m.mu.Lock() defer m.mu.Unlock() f(m.data) } -// RLockFunc locks reading with given callback function within RWMutex.RLock. +// RLockFunc locks reading with given callback function `f` within RWMutex.RLock. func (m *StrAnyMap) RLockFunc(f func(m map[string]interface{})) { m.mu.RLock() defer m.mu.RUnlock() @@ -434,7 +434,7 @@ func (m *StrAnyMap) Flip() { } // Merge merges two hash maps. -// The map will be merged into the map . +// The map will be merged into the map `m`. func (m *StrAnyMap) Merge(other *StrAnyMap) { m.mu.Lock() defer m.mu.Unlock() diff --git a/container/gmap/gmap_hash_str_int_map.go b/container/gmap/gmap_hash_str_int_map.go index f01fcaa8d..129694f86 100644 --- a/container/gmap/gmap_hash_str_int_map.go +++ b/container/gmap/gmap_hash_str_int_map.go @@ -21,7 +21,7 @@ type StrIntMap struct { } // NewStrIntMap returns an empty StrIntMap object. -// The parameter is used to specify whether using map in concurrent-safety, +// The parameter `safe` is used to specify whether using map in concurrent-safety, // which is false in default. func NewStrIntMap(safe ...bool) *StrIntMap { return &StrIntMap{ @@ -30,8 +30,8 @@ func NewStrIntMap(safe ...bool) *StrIntMap { } } -// NewStrIntMapFrom creates and returns a hash map from given map . -// Note that, the param map will be set as the underlying data map(no deep copy), +// NewStrIntMapFrom creates and returns a hash map from given map `data`. +// Note that, the param `data` map will be set as the underlying data map(no deep copy), // there might be some concurrent-safe issues when changing the map outside. func NewStrIntMapFrom(data map[string]int, safe ...bool) *StrIntMap { return &StrIntMap{ @@ -40,8 +40,8 @@ func NewStrIntMapFrom(data map[string]int, safe ...bool) *StrIntMap { } } -// Iterator iterates the hash map readonly with custom callback function . -// If returns true, then it continues iterating; or false to stop. +// Iterator iterates the hash map readonly with custom callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (m *StrIntMap) Iterator(f func(k string, v int) bool) { m.mu.RLock() defer m.mu.RUnlock() @@ -130,8 +130,8 @@ func (m *StrIntMap) Sets(data map[string]int) { m.mu.Unlock() } -// Search searches the map with given . -// Second return parameter is true if key was found, otherwise false. +// Search searches the map with given `key`. +// Second return parameter `found` is true if key was found, otherwise false. func (m *StrIntMap) Search(key string) (value int, found bool) { m.mu.RLock() if m.data != nil { @@ -141,7 +141,7 @@ func (m *StrIntMap) Search(key string) (value int, found bool) { return } -// Get returns the value by given . +// Get returns the value by given `key`. func (m *StrIntMap) Get(key string) (value int) { m.mu.RLock() if m.data != nil { @@ -162,7 +162,7 @@ func (m *StrIntMap) Pop() (key string, value int) { return } -// Pops retrieves and deletes items from the map. +// Pops retrieves and deletes `size` items from the map. // It returns all items if size == -1. func (m *StrIntMap) Pops(size int) map[string]int { m.mu.Lock() @@ -189,10 +189,10 @@ func (m *StrIntMap) Pops(size int) map[string]int { } // doSetWithLockCheck checks whether value of the key exists with mutex.Lock, -// if not exists, set value to the map with given , +// if not exists, set value to the map with given `key`, // or else just return the existing value. // -// It returns value with given . +// It returns value with given `key`. func (m *StrIntMap) doSetWithLockCheck(key string, value int) int { m.mu.Lock() if m.data == nil { @@ -208,7 +208,7 @@ func (m *StrIntMap) doSetWithLockCheck(key string, value int) int { } // GetOrSet returns the value by key, -// or sets value with given if it does not exist and then returns this value. +// or sets value with given `value` if it does not exist and then returns this value. func (m *StrIntMap) GetOrSet(key string, value int) int { if v, ok := m.Search(key); !ok { return m.doSetWithLockCheck(key, value) @@ -218,7 +218,7 @@ func (m *StrIntMap) GetOrSet(key string, value int) int { } // GetOrSetFunc returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. func (m *StrIntMap) GetOrSetFunc(key string, f func() int) int { if v, ok := m.Search(key); !ok { @@ -229,10 +229,10 @@ func (m *StrIntMap) GetOrSetFunc(key string, f func() int) int { } // GetOrSetFuncLock returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. // -// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function +// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function `f` // with mutex.Lock of the hash map. func (m *StrIntMap) GetOrSetFuncLock(key string, f func() int) int { if v, ok := m.Search(key); !ok { @@ -252,8 +252,8 @@ func (m *StrIntMap) GetOrSetFuncLock(key string, f func() int) int { } } -// SetIfNotExist sets to the map if the does not exist, and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExist sets to the map if the `key` does not exist, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *StrIntMap) SetIfNotExist(key string, value int) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, value) @@ -262,8 +262,8 @@ func (m *StrIntMap) SetIfNotExist(key string, value int) bool { return false } -// SetIfNotExistFunc sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFunc sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *StrIntMap) SetIfNotExistFunc(key string, f func() int) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, f()) @@ -272,11 +272,11 @@ func (m *StrIntMap) SetIfNotExistFunc(key string, f func() int) bool { return false } -// SetIfNotExistFuncLock sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFuncLock sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. // // SetIfNotExistFuncLock differs with SetIfNotExistFunc function is that -// it executes function with mutex.Lock of the hash map. +// it executes function `f` with mutex.Lock of the hash map. func (m *StrIntMap) SetIfNotExistFuncLock(key string, f func() int) bool { if !m.Contains(key) { m.mu.Lock() @@ -303,7 +303,7 @@ func (m *StrIntMap) Removes(keys []string) { m.mu.Unlock() } -// Remove deletes value from map by given , and return this deleted value. +// Remove deletes value from map by given `key`, and return this deleted value. func (m *StrIntMap) Remove(key string) (value int) { m.mu.Lock() if m.data != nil { @@ -347,7 +347,7 @@ func (m *StrIntMap) Values() []int { } // Contains checks whether a key exists. -// It returns true if the exists, or else false. +// It returns true if the `key` exists, or else false. func (m *StrIntMap) Contains(key string) bool { var ok bool m.mu.RLock() @@ -379,21 +379,21 @@ func (m *StrIntMap) Clear() { m.mu.Unlock() } -// Replace the data of the map with given . +// Replace the data of the map with given `data`. func (m *StrIntMap) Replace(data map[string]int) { m.mu.Lock() m.data = data m.mu.Unlock() } -// LockFunc locks writing with given callback function within RWMutex.Lock. +// LockFunc locks writing with given callback function `f` within RWMutex.Lock. func (m *StrIntMap) LockFunc(f func(m map[string]int)) { m.mu.Lock() defer m.mu.Unlock() f(m.data) } -// RLockFunc locks reading with given callback function within RWMutex.RLock. +// RLockFunc locks reading with given callback function `f` within RWMutex.RLock. func (m *StrIntMap) RLockFunc(f func(m map[string]int)) { m.mu.RLock() defer m.mu.RUnlock() @@ -412,7 +412,7 @@ func (m *StrIntMap) Flip() { } // Merge merges two hash maps. -// The map will be merged into the map . +// The map will be merged into the map `m`. func (m *StrIntMap) Merge(other *StrIntMap) { m.mu.Lock() defer m.mu.Unlock() diff --git a/container/gmap/gmap_hash_str_str_map.go b/container/gmap/gmap_hash_str_str_map.go index cfbc945b2..ce90c7820 100644 --- a/container/gmap/gmap_hash_str_str_map.go +++ b/container/gmap/gmap_hash_str_str_map.go @@ -22,7 +22,7 @@ type StrStrMap struct { } // NewStrStrMap returns an empty StrStrMap object. -// The parameter is used to specify whether using map in concurrent-safety, +// The parameter `safe` is used to specify whether using map in concurrent-safety, // which is false in default. func NewStrStrMap(safe ...bool) *StrStrMap { return &StrStrMap{ @@ -31,8 +31,8 @@ func NewStrStrMap(safe ...bool) *StrStrMap { } } -// NewStrStrMapFrom creates and returns a hash map from given map . -// Note that, the param map will be set as the underlying data map(no deep copy), +// NewStrStrMapFrom creates and returns a hash map from given map `data`. +// Note that, the param `data` map will be set as the underlying data map(no deep copy), // there might be some concurrent-safe issues when changing the map outside. func NewStrStrMapFrom(data map[string]string, safe ...bool) *StrStrMap { return &StrStrMap{ @@ -41,8 +41,8 @@ func NewStrStrMapFrom(data map[string]string, safe ...bool) *StrStrMap { } } -// Iterator iterates the hash map readonly with custom callback function . -// If returns true, then it continues iterating; or false to stop. +// Iterator iterates the hash map readonly with custom callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (m *StrStrMap) Iterator(f func(k string, v string) bool) { m.mu.RLock() defer m.mu.RUnlock() @@ -131,8 +131,8 @@ func (m *StrStrMap) Sets(data map[string]string) { m.mu.Unlock() } -// Search searches the map with given . -// Second return parameter is true if key was found, otherwise false. +// Search searches the map with given `key`. +// Second return parameter `found` is true if key was found, otherwise false. func (m *StrStrMap) Search(key string) (value string, found bool) { m.mu.RLock() if m.data != nil { @@ -142,7 +142,7 @@ func (m *StrStrMap) Search(key string) (value string, found bool) { return } -// Get returns the value by given . +// Get returns the value by given `key`. func (m *StrStrMap) Get(key string) (value string) { m.mu.RLock() if m.data != nil { @@ -163,7 +163,7 @@ func (m *StrStrMap) Pop() (key, value string) { return } -// Pops retrieves and deletes items from the map. +// Pops retrieves and deletes `size` items from the map. // It returns all items if size == -1. func (m *StrStrMap) Pops(size int) map[string]string { m.mu.Lock() @@ -190,10 +190,10 @@ func (m *StrStrMap) Pops(size int) map[string]string { } // doSetWithLockCheck checks whether value of the key exists with mutex.Lock, -// if not exists, set value to the map with given , +// if not exists, set value to the map with given `key`, // or else just return the existing value. // -// It returns value with given . +// It returns value with given `key`. func (m *StrStrMap) doSetWithLockCheck(key string, value string) string { m.mu.Lock() defer m.mu.Unlock() @@ -208,7 +208,7 @@ func (m *StrStrMap) doSetWithLockCheck(key string, value string) string { } // GetOrSet returns the value by key, -// or sets value with given if it does not exist and then returns this value. +// or sets value with given `value` if it does not exist and then returns this value. func (m *StrStrMap) GetOrSet(key string, value string) string { if v, ok := m.Search(key); !ok { return m.doSetWithLockCheck(key, value) @@ -218,7 +218,7 @@ func (m *StrStrMap) GetOrSet(key string, value string) string { } // GetOrSetFunc returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. func (m *StrStrMap) GetOrSetFunc(key string, f func() string) string { if v, ok := m.Search(key); !ok { @@ -229,10 +229,10 @@ func (m *StrStrMap) GetOrSetFunc(key string, f func() string) string { } // GetOrSetFuncLock returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. // -// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function +// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function `f` // with mutex.Lock of the hash map. func (m *StrStrMap) GetOrSetFuncLock(key string, f func() string) string { if v, ok := m.Search(key); !ok { @@ -252,8 +252,8 @@ func (m *StrStrMap) GetOrSetFuncLock(key string, f func() string) string { } } -// SetIfNotExist sets to the map if the does not exist, and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExist sets to the map if the `key` does not exist, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *StrStrMap) SetIfNotExist(key string, value string) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, value) @@ -262,8 +262,8 @@ func (m *StrStrMap) SetIfNotExist(key string, value string) bool { return false } -// SetIfNotExistFunc sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFunc sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *StrStrMap) SetIfNotExistFunc(key string, f func() string) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, f()) @@ -272,11 +272,11 @@ func (m *StrStrMap) SetIfNotExistFunc(key string, f func() string) bool { return false } -// SetIfNotExistFuncLock sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFuncLock sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. // // SetIfNotExistFuncLock differs with SetIfNotExistFunc function is that -// it executes function with mutex.Lock of the hash map. +// it executes function `f` with mutex.Lock of the hash map. func (m *StrStrMap) SetIfNotExistFuncLock(key string, f func() string) bool { if !m.Contains(key) { m.mu.Lock() @@ -303,7 +303,7 @@ func (m *StrStrMap) Removes(keys []string) { m.mu.Unlock() } -// Remove deletes value from map by given , and return this deleted value. +// Remove deletes value from map by given `key`, and return this deleted value. func (m *StrStrMap) Remove(key string) (value string) { m.mu.Lock() if m.data != nil { @@ -347,7 +347,7 @@ func (m *StrStrMap) Values() []string { } // Contains checks whether a key exists. -// It returns true if the exists, or else false. +// It returns true if the `key` exists, or else false. func (m *StrStrMap) Contains(key string) bool { var ok bool m.mu.RLock() @@ -379,21 +379,21 @@ func (m *StrStrMap) Clear() { m.mu.Unlock() } -// Replace the data of the map with given . +// Replace the data of the map with given `data`. func (m *StrStrMap) Replace(data map[string]string) { m.mu.Lock() m.data = data m.mu.Unlock() } -// LockFunc locks writing with given callback function within RWMutex.Lock. +// LockFunc locks writing with given callback function `f` within RWMutex.Lock. func (m *StrStrMap) LockFunc(f func(m map[string]string)) { m.mu.Lock() defer m.mu.Unlock() f(m.data) } -// RLockFunc locks reading with given callback function within RWMutex.RLock. +// RLockFunc locks reading with given callback function `f` within RWMutex.RLock. func (m *StrStrMap) RLockFunc(f func(m map[string]string)) { m.mu.RLock() defer m.mu.RUnlock() @@ -412,7 +412,7 @@ func (m *StrStrMap) Flip() { } // Merge merges two hash maps. -// The map will be merged into the map . +// The map will be merged into the map `m`. func (m *StrStrMap) Merge(other *StrStrMap) { m.mu.Lock() defer m.mu.Unlock() diff --git a/container/gmap/gmap_list_map.go b/container/gmap/gmap_list_map.go index 805b565f1..5ca38d3f8 100644 --- a/container/gmap/gmap_list_map.go +++ b/container/gmap/gmap_list_map.go @@ -31,7 +31,7 @@ type gListMapNode struct { // NewListMap returns an empty link map. // ListMap is backed by a hash table to store values and doubly-linked list to store ordering. -// The parameter is used to specify whether using map in concurrent-safety, +// The parameter `safe` is used to specify whether using map in concurrent-safety, // which is false in default. func NewListMap(safe ...bool) *ListMap { return &ListMap{ @@ -41,8 +41,8 @@ func NewListMap(safe ...bool) *ListMap { } } -// NewListMapFrom returns a link map from given map . -// Note that, the param map will be set as the underlying data map(no deep copy), +// NewListMapFrom returns a link map from given map `data`. +// Note that, the param `data` map will be set as the underlying data map(no deep copy), // there might be some concurrent-safe issues when changing the map outside. func NewListMapFrom(data map[interface{}]interface{}, safe ...bool) *ListMap { m := NewListMap(safe...) @@ -55,8 +55,8 @@ func (m *ListMap) Iterator(f func(key, value interface{}) bool) { m.IteratorAsc(f) } -// IteratorAsc iterates the map readonly in ascending order with given callback function . -// If returns true, then it continues iterating; or false to stop. +// IteratorAsc iterates the map readonly in ascending order with given callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (m *ListMap) IteratorAsc(f func(key interface{}, value interface{}) bool) { m.mu.RLock() defer m.mu.RUnlock() @@ -69,8 +69,8 @@ func (m *ListMap) IteratorAsc(f func(key interface{}, value interface{}) bool) { } } -// IteratorDesc iterates the map readonly in descending order with given callback function . -// If returns true, then it continues iterating; or false to stop. +// IteratorDesc iterates the map readonly in descending order with given callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (m *ListMap) IteratorDesc(f func(key interface{}, value interface{}) bool) { m.mu.RLock() defer m.mu.RUnlock() @@ -96,7 +96,7 @@ func (m *ListMap) Clear() { m.mu.Unlock() } -// Replace the data of the map with given . +// Replace the data of the map with given `data`. func (m *ListMap) Replace(data map[interface{}]interface{}) { m.mu.Lock() m.data = make(map[interface{}]*glist.Element) @@ -202,8 +202,8 @@ func (m *ListMap) Sets(data map[interface{}]interface{}) { m.mu.Unlock() } -// Search searches the map with given . -// Second return parameter is true if key was found, otherwise false. +// Search searches the map with given `key`. +// Second return parameter `found` is true if key was found, otherwise false. func (m *ListMap) Search(key interface{}) (value interface{}, found bool) { m.mu.RLock() if m.data != nil { @@ -216,7 +216,7 @@ func (m *ListMap) Search(key interface{}) (value interface{}, found bool) { return } -// Get returns the value by given . +// Get returns the value by given `key`. func (m *ListMap) Get(key interface{}) (value interface{}) { m.mu.RLock() if m.data != nil { @@ -241,7 +241,7 @@ func (m *ListMap) Pop() (key, value interface{}) { return } -// Pops retrieves and deletes items from the map. +// Pops retrieves and deletes `size` items from the map. // It returns all items if size == -1. func (m *ListMap) Pops(size int) map[interface{}]interface{} { m.mu.Lock() @@ -268,14 +268,14 @@ func (m *ListMap) Pops(size int) map[interface{}]interface{} { } // doSetWithLockCheck checks whether value of the key exists with mutex.Lock, -// if not exists, set value to the map with given , +// if not exists, set value to the map with given `key`, // or else just return the existing value. // -// When setting value, if is type of , +// When setting value, if `value` is type of , // it will be executed with mutex.Lock of the map, -// and its return value will be set to the map with . +// and its return value will be set to the map with `key`. // -// It returns value with given . +// It returns value with given `key`. func (m *ListMap) doSetWithLockCheck(key interface{}, value interface{}) interface{} { m.mu.Lock() defer m.mu.Unlock() @@ -296,7 +296,7 @@ func (m *ListMap) doSetWithLockCheck(key interface{}, value interface{}) interfa } // GetOrSet returns the value by key, -// or sets value with given if it does not exist and then returns this value. +// or sets value with given `value` if it does not exist and then returns this value. func (m *ListMap) GetOrSet(key interface{}, value interface{}) interface{} { if v, ok := m.Search(key); !ok { return m.doSetWithLockCheck(key, value) @@ -306,7 +306,7 @@ func (m *ListMap) GetOrSet(key interface{}, value interface{}) interface{} { } // GetOrSetFunc returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. func (m *ListMap) GetOrSetFunc(key interface{}, f func() interface{}) interface{} { if v, ok := m.Search(key); !ok { @@ -317,10 +317,10 @@ func (m *ListMap) GetOrSetFunc(key interface{}, f func() interface{}) interface{ } // GetOrSetFuncLock returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. // -// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function +// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function `f` // with mutex.Lock of the map. func (m *ListMap) GetOrSetFuncLock(key interface{}, f func() interface{}) interface{} { if v, ok := m.Search(key); !ok { @@ -330,7 +330,7 @@ func (m *ListMap) GetOrSetFuncLock(key interface{}, f func() interface{}) interf } } -// GetVar returns a Var with the value by given . +// GetVar returns a Var with the value by given `key`. // The returned Var is un-concurrent safe. func (m *ListMap) GetVar(key interface{}) *gvar.Var { return gvar.New(m.Get(key)) @@ -354,8 +354,8 @@ func (m *ListMap) GetVarOrSetFuncLock(key interface{}, f func() interface{}) *gv return gvar.New(m.GetOrSetFuncLock(key, f)) } -// SetIfNotExist sets to the map if the does not exist, and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExist sets to the map if the `key` does not exist, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *ListMap) SetIfNotExist(key interface{}, value interface{}) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, value) @@ -364,8 +364,8 @@ func (m *ListMap) SetIfNotExist(key interface{}, value interface{}) bool { return false } -// SetIfNotExistFunc sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFunc sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. func (m *ListMap) SetIfNotExistFunc(key interface{}, f func() interface{}) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, f()) @@ -374,11 +374,11 @@ func (m *ListMap) SetIfNotExistFunc(key interface{}, f func() interface{}) bool return false } -// SetIfNotExistFuncLock sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFuncLock sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. // // SetIfNotExistFuncLock differs with SetIfNotExistFunc function is that -// it executes function with mutex.Lock of the map. +// it executes function `f` with mutex.Lock of the map. func (m *ListMap) SetIfNotExistFuncLock(key interface{}, f func() interface{}) bool { if !m.Contains(key) { m.doSetWithLockCheck(key, f) @@ -387,7 +387,7 @@ func (m *ListMap) SetIfNotExistFuncLock(key interface{}, f func() interface{}) b return false } -// Remove deletes value from map by given , and return this deleted value. +// Remove deletes value from map by given `key`, and return this deleted value. func (m *ListMap) Remove(key interface{}) (value interface{}) { m.mu.Lock() if m.data != nil { @@ -452,7 +452,7 @@ func (m *ListMap) Values() []interface{} { } // Contains checks whether a key exists. -// It returns true if the exists, or else false. +// It returns true if the `key` exists, or else false. func (m *ListMap) Contains(key interface{}) (ok bool) { m.mu.RLock() if m.data != nil { @@ -486,7 +486,7 @@ func (m *ListMap) Flip() { } // Merge merges two link maps. -// The map will be merged into the map . +// The map will be merged into the map `m`. func (m *ListMap) Merge(other *ListMap) { m.mu.Lock() defer m.mu.Unlock() diff --git a/container/gmap/gmap_tree_map.go b/container/gmap/gmap_tree_map.go index 1b9f02783..694fc10d7 100644 --- a/container/gmap/gmap_tree_map.go +++ b/container/gmap/gmap_tree_map.go @@ -14,16 +14,16 @@ import ( type TreeMap = gtree.RedBlackTree // NewTreeMap instantiates a tree map with the custom comparator. -// The parameter is used to specify whether using tree in concurrent-safety, +// The parameter `safe` is used to specify whether using tree in concurrent-safety, // which is false in default. func NewTreeMap(comparator func(v1, v2 interface{}) int, safe ...bool) *TreeMap { return gtree.NewRedBlackTree(comparator, safe...) } -// NewTreeMapFrom instantiates a tree map with the custom comparator and map. -// Note that, the param map will be set as the underlying data map(no deep copy), +// NewTreeMapFrom instantiates a tree map with the custom comparator and `data` map. +// Note that, the param `data` map will be set as the underlying data map(no deep copy), // there might be some concurrent-safe issues when changing the map outside. -// The parameter is used to specify whether using tree in concurrent-safety, +// The parameter `safe` is used to specify whether using tree in concurrent-safety, // which is false in default. func NewTreeMapFrom(comparator func(v1, v2 interface{}) int, data map[interface{}]interface{}, safe ...bool) *TreeMap { return gtree.NewRedBlackTreeFrom(comparator, data, safe...) diff --git a/container/gpool/gpool.go b/container/gpool/gpool.go index 4b7e5e583..0c32deb15 100644 --- a/container/gpool/gpool.go +++ b/container/gpool/gpool.go @@ -126,7 +126,7 @@ func (p *Pool) Size() int { return p.list.Len() } -// Close closes the pool. If

has ExpireFunc, +// Close closes the pool. If `p` has ExpireFunc, // then it automatically closes all items using this function before it's closed. // Commonly you do not need call this function manually. func (p *Pool) Close() { diff --git a/container/gqueue/gqueue.go b/container/gqueue/gqueue.go index b8a2dfbaa..bb7affe72 100644 --- a/container/gqueue/gqueue.go +++ b/container/gqueue/gqueue.go @@ -40,8 +40,8 @@ const ( ) // New returns an empty queue object. -// Optional parameter is used to limit the size of the queue, which is unlimited in default. -// When is given, the queue will be static and high performance which is comparable with stdlib channel. +// Optional parameter `limit` is used to limit the size of the queue, which is unlimited in default. +// When `limit` is given, the queue will be static and high performance which is comparable with stdlib channel. func New(limit ...int) *Queue { q := &Queue{ closed: gtype.NewBool(), @@ -87,12 +87,12 @@ func (q *Queue) asyncLoopFromListToChannel() { <-q.events } } - // It should be here to close q.C if is unlimited size. + // It should be here to close q.C if `q` is unlimited size. // It's the sender's responsibility to close channel when it should be closed. close(q.C) } -// Push pushes the data into the queue. +// Push pushes the data `v` into the queue. // Note that it would panics if Push is called after the queue is closed. func (q *Queue) Push(v interface{}) { if q.limit > 0 { diff --git a/container/gring/gring.go b/container/gring/gring.go index 9114558c4..464f99f65 100644 --- a/container/gring/gring.go +++ b/container/gring/gring.go @@ -28,8 +28,8 @@ type internalRingItem struct { Value interface{} } -// New creates and returns a Ring structure of elements. -// The optional parameter specifies whether using this structure in concurrent safety, +// New creates and returns a Ring structure of `cap` elements. +// The optional parameter `safe` specifies whether using this structure in concurrent safety, // which is false in default. func New(cap int, safe ...bool) *Ring { return &Ring{ diff --git a/container/gset/gset_any_set.go b/container/gset/gset_any_set.go index 9db79a47a..8e222a8cc 100644 --- a/container/gset/gset_any_set.go +++ b/container/gset/gset_any_set.go @@ -21,7 +21,7 @@ type Set struct { } // New create and returns a new set, which contains un-repeated items. -// The parameter is used to specify whether using set in concurrent-safety, +// The parameter `safe` is used to specify whether using set in concurrent-safety, // which is false in default. func New(safe ...bool) *Set { return NewSet(safe...) @@ -35,8 +35,8 @@ func NewSet(safe ...bool) *Set { } } -// NewFrom returns a new set from . -// Parameter can be either a variable of any type, or a slice. +// NewFrom returns a new set from `items`. +// Parameter `items` can be either a variable of any type, or a slice. func NewFrom(items interface{}, safe ...bool) *Set { m := make(map[interface{}]struct{}) for _, v := range gconv.Interfaces(items) { @@ -48,8 +48,8 @@ func NewFrom(items interface{}, safe ...bool) *Set { } } -// Iterator iterates the set readonly with given callback function , -// if returns true then continue iterating; or false to stop. +// Iterator iterates the set readonly with given callback function `f`, +// if `f` returns true then continue iterating; or false to stop. func (set *Set) Iterator(f func(v interface{}) bool) { set.mu.RLock() defer set.mu.RUnlock() @@ -76,7 +76,7 @@ func (set *Set) Add(items ...interface{}) { // it adds the item to set and returns true if it does not exists in the set, // or else it does nothing and returns false. // -// Note that, if is nil, it does nothing and returns false. +// Note that, if `item` is nil, it does nothing and returns false. func (set *Set) AddIfNotExist(item interface{}) bool { if item == nil { return false @@ -97,9 +97,9 @@ func (set *Set) AddIfNotExist(item interface{}) bool { // AddIfNotExistFunc checks whether item exists in the set, // it adds the item to set and returns true if it does not exists in the set and -// function returns true, or else it does nothing and returns false. +// function `f` returns true, or else it does nothing and returns false. // -// Note that, if is nil, it does nothing and returns false. The function +// Note that, if is nil, it does nothing and returns false. The function `f` // is executed without writing lock. func (set *Set) AddIfNotExistFunc(item interface{}, f func() bool) bool { if item == nil { @@ -123,9 +123,9 @@ func (set *Set) AddIfNotExistFunc(item interface{}, f func() bool) bool { // AddIfNotExistFunc checks whether item exists in the set, // it adds the item to set and returns true if it does not exists in the set and -// function returns true, or else it does nothing and returns false. +// function `f` returns true, or else it does nothing and returns false. // -// Note that, if is nil, it does nothing and returns false. The function +// Note that, if is nil, it does nothing and returns false. The function `f` // is executed within writing lock. func (set *Set) AddIfNotExistFuncLock(item interface{}, f func() bool) bool { if item == nil { @@ -147,7 +147,7 @@ func (set *Set) AddIfNotExistFuncLock(item interface{}, f func() bool) bool { return false } -// Contains checks whether the set contains . +// Contains checks whether the set contains `item`. func (set *Set) Contains(item interface{}) bool { var ok bool set.mu.RLock() @@ -158,7 +158,7 @@ func (set *Set) Contains(item interface{}) bool { return ok } -// Remove deletes from set. +// Remove deletes `item` from set. func (set *Set) Remove(item interface{}) { set.mu.Lock() if set.data != nil { @@ -197,7 +197,7 @@ func (set *Set) Slice() []interface{} { return ret } -// Join joins items with a string . +// Join joins items with a string `glue`. func (set *Set) Join(glue string) string { set.mu.RLock() defer set.mu.RUnlock() @@ -246,14 +246,14 @@ func (set *Set) String() string { return buffer.String() } -// LockFunc locks writing with callback function . +// LockFunc locks writing with callback function `f`. func (set *Set) LockFunc(f func(m map[interface{}]struct{})) { set.mu.Lock() defer set.mu.Unlock() f(set.data) } -// RLockFunc locks reading with callback function . +// RLockFunc locks reading with callback function `f`. func (set *Set) RLockFunc(f func(m map[interface{}]struct{})) { set.mu.RLock() defer set.mu.RUnlock() @@ -280,7 +280,7 @@ func (set *Set) Equal(other *Set) bool { return true } -// IsSubsetOf checks whether the current set is a sub-set of . +// IsSubsetOf checks whether the current set is a sub-set of `other`. func (set *Set) IsSubsetOf(other *Set) bool { if set == other { return true @@ -297,8 +297,8 @@ func (set *Set) IsSubsetOf(other *Set) bool { return true } -// Union returns a new set which is the union of and . -// Which means, all the items in are in or in . +// Union returns a new set which is the union of and `others`. +// Which means, all the items in are in or in `others`. func (set *Set) Union(others ...*Set) (newSet *Set) { newSet = NewSet() set.mu.RLock() @@ -323,8 +323,8 @@ func (set *Set) Union(others ...*Set) (newSet *Set) { return } -// Diff returns a new set which is the difference set from to . -// Which means, all the items in are in but not in . +// Diff returns a new set which is the difference set from to `others`. +// Which means, all the items in are in but not in `others`. func (set *Set) Diff(others ...*Set) (newSet *Set) { newSet = NewSet() set.mu.RLock() @@ -344,8 +344,8 @@ func (set *Set) Diff(others ...*Set) (newSet *Set) { return } -// Intersect returns a new set which is the intersection from to . -// Which means, all the items in are in and also in . +// Intersect returns a new set which is the intersection from to `others`. +// Which means, all the items in are in and also in `others`. func (set *Set) Intersect(others ...*Set) (newSet *Set) { newSet = NewSet() set.mu.RLock() @@ -366,11 +366,11 @@ func (set *Set) Intersect(others ...*Set) (newSet *Set) { return } -// Complement returns a new set which is the complement from to . -// Which means, all the items in are in and not in . +// Complement returns a new set which is the complement from to `full`. +// Which means, all the items in are in and not in `set`. // -// It returns the difference between and -// if the given set is not the full set of . +// It returns the difference between and `set` +// if the given set is not the full set of `set`. func (set *Set) Complement(full *Set) (newSet *Set) { newSet = NewSet() set.mu.RLock() @@ -387,7 +387,7 @@ func (set *Set) Complement(full *Set) (newSet *Set) { return } -// Merge adds items from sets into . +// Merge adds items from sets into `set`. func (set *Set) Merge(others ...*Set) *Set { set.mu.Lock() defer set.mu.Unlock() @@ -428,7 +428,7 @@ func (set *Set) Pop() interface{} { return nil } -// Pops randomly pops items from set. +// Pops randomly pops `size` items from set. // It returns all items if size == -1. func (set *Set) Pops(size int) []interface{} { set.mu.Lock() @@ -452,7 +452,7 @@ func (set *Set) Pops(size int) []interface{} { return array } -// Walk applies a user supplied function to every item of set. +// Walk applies a user supplied function `f` to every item of set. func (set *Set) Walk(f func(item interface{}) interface{}) *Set { set.mu.Lock() defer set.mu.Unlock() diff --git a/container/gset/gset_int_set.go b/container/gset/gset_int_set.go index 39a98d9f3..2fead63dc 100644 --- a/container/gset/gset_int_set.go +++ b/container/gset/gset_int_set.go @@ -20,7 +20,7 @@ type IntSet struct { } // New create and returns a new set, which contains un-repeated items. -// The parameter is used to specify whether using set in concurrent-safety, +// The parameter `safe` is used to specify whether using set in concurrent-safety, // which is false in default. func NewIntSet(safe ...bool) *IntSet { return &IntSet{ @@ -29,7 +29,7 @@ func NewIntSet(safe ...bool) *IntSet { } } -// NewIntSetFrom returns a new set from . +// NewIntSetFrom returns a new set from `items`. func NewIntSetFrom(items []int, safe ...bool) *IntSet { m := make(map[int]struct{}) for _, v := range items { @@ -41,8 +41,8 @@ func NewIntSetFrom(items []int, safe ...bool) *IntSet { } } -// Iterator iterates the set readonly with given callback function , -// if returns true then continue iterating; or false to stop. +// Iterator iterates the set readonly with given callback function `f`, +// if `f` returns true then continue iterating; or false to stop. func (set *IntSet) Iterator(f func(v int) bool) { set.mu.RLock() defer set.mu.RUnlock() @@ -69,7 +69,7 @@ func (set *IntSet) Add(item ...int) { // it adds the item to set and returns true if it does not exists in the set, // or else it does nothing and returns false. // -// Note that, if is nil, it does nothing and returns false. +// Note that, if `item` is nil, it does nothing and returns false. func (set *IntSet) AddIfNotExist(item int) bool { if !set.Contains(item) { set.mu.Lock() @@ -87,9 +87,9 @@ func (set *IntSet) AddIfNotExist(item int) bool { // AddIfNotExistFunc checks whether item exists in the set, // it adds the item to set and returns true if it does not exists in the set and -// function returns true, or else it does nothing and returns false. +// function `f` returns true, or else it does nothing and returns false. // -// Note that, the function is executed without writing lock. +// Note that, the function `f` is executed without writing lock. func (set *IntSet) AddIfNotExistFunc(item int, f func() bool) bool { if !set.Contains(item) { if f() { @@ -109,9 +109,9 @@ func (set *IntSet) AddIfNotExistFunc(item int, f func() bool) bool { // AddIfNotExistFunc checks whether item exists in the set, // it adds the item to set and returns true if it does not exists in the set and -// function returns true, or else it does nothing and returns false. +// function `f` returns true, or else it does nothing and returns false. // -// Note that, the function is executed without writing lock. +// Note that, the function `f` is executed without writing lock. func (set *IntSet) AddIfNotExistFuncLock(item int, f func() bool) bool { if !set.Contains(item) { set.mu.Lock() @@ -129,7 +129,7 @@ func (set *IntSet) AddIfNotExistFuncLock(item int, f func() bool) bool { return false } -// Contains checks whether the set contains . +// Contains checks whether the set contains `item`. func (set *IntSet) Contains(item int) bool { var ok bool set.mu.RLock() @@ -140,7 +140,7 @@ func (set *IntSet) Contains(item int) bool { return ok } -// Remove deletes from set. +// Remove deletes `item` from set. func (set *IntSet) Remove(item int) { set.mu.Lock() if set.data != nil { @@ -179,7 +179,7 @@ func (set *IntSet) Slice() []int { return ret } -// Join joins items with a string . +// Join joins items with a string `glue`. func (set *IntSet) Join(glue string) string { set.mu.RLock() defer set.mu.RUnlock() @@ -206,14 +206,14 @@ func (set *IntSet) String() string { return "[" + set.Join(",") + "]" } -// LockFunc locks writing with callback function . +// LockFunc locks writing with callback function `f`. func (set *IntSet) LockFunc(f func(m map[int]struct{})) { set.mu.Lock() defer set.mu.Unlock() f(set.data) } -// RLockFunc locks reading with callback function . +// RLockFunc locks reading with callback function `f`. func (set *IntSet) RLockFunc(f func(m map[int]struct{})) { set.mu.RLock() defer set.mu.RUnlock() @@ -240,7 +240,7 @@ func (set *IntSet) Equal(other *IntSet) bool { return true } -// IsSubsetOf checks whether the current set is a sub-set of . +// IsSubsetOf checks whether the current set is a sub-set of `other`. func (set *IntSet) IsSubsetOf(other *IntSet) bool { if set == other { return true @@ -257,8 +257,8 @@ func (set *IntSet) IsSubsetOf(other *IntSet) bool { return true } -// Union returns a new set which is the union of and . -// Which means, all the items in are in or in . +// Union returns a new set which is the union of and `other`. +// Which means, all the items in are in or in `other`. func (set *IntSet) Union(others ...*IntSet) (newSet *IntSet) { newSet = NewIntSet() set.mu.RLock() @@ -283,8 +283,8 @@ func (set *IntSet) Union(others ...*IntSet) (newSet *IntSet) { return } -// Diff returns a new set which is the difference set from to . -// Which means, all the items in are in but not in . +// Diff returns a new set which is the difference set from to `other`. +// Which means, all the items in are in but not in `other`. func (set *IntSet) Diff(others ...*IntSet) (newSet *IntSet) { newSet = NewIntSet() set.mu.RLock() @@ -304,8 +304,8 @@ func (set *IntSet) Diff(others ...*IntSet) (newSet *IntSet) { return } -// Intersect returns a new set which is the intersection from to . -// Which means, all the items in are in and also in . +// Intersect returns a new set which is the intersection from to `other`. +// Which means, all the items in are in and also in `other`. func (set *IntSet) Intersect(others ...*IntSet) (newSet *IntSet) { newSet = NewIntSet() set.mu.RLock() @@ -326,11 +326,11 @@ func (set *IntSet) Intersect(others ...*IntSet) (newSet *IntSet) { return } -// Complement returns a new set which is the complement from to . -// Which means, all the items in are in and not in . +// Complement returns a new set which is the complement from to `full`. +// Which means, all the items in are in and not in `set`. // -// It returns the difference between and -// if the given set is not the full set of . +// It returns the difference between and `set` +// if the given set is not the full set of `set`. func (set *IntSet) Complement(full *IntSet) (newSet *IntSet) { newSet = NewIntSet() set.mu.RLock() @@ -347,7 +347,7 @@ func (set *IntSet) Complement(full *IntSet) (newSet *IntSet) { return } -// Merge adds items from sets into . +// Merge adds items from sets into `set`. func (set *IntSet) Merge(others ...*IntSet) *IntSet { set.mu.Lock() defer set.mu.Unlock() @@ -388,7 +388,7 @@ func (set *IntSet) Pop() int { return 0 } -// Pops randomly pops items from set. +// Pops randomly pops `size` items from set. // It returns all items if size == -1. func (set *IntSet) Pops(size int) []int { set.mu.Lock() @@ -412,7 +412,7 @@ func (set *IntSet) Pops(size int) []int { return array } -// Walk applies a user supplied function to every item of set. +// Walk applies a user supplied function `f` to every item of set. func (set *IntSet) Walk(f func(item int) int) *IntSet { set.mu.Lock() defer set.mu.Unlock() diff --git a/container/gset/gset_str_set.go b/container/gset/gset_str_set.go index 24323c3e7..dea06ff17 100644 --- a/container/gset/gset_str_set.go +++ b/container/gset/gset_str_set.go @@ -22,7 +22,7 @@ type StrSet struct { } // NewStrSet create and returns a new set, which contains un-repeated items. -// The parameter is used to specify whether using set in concurrent-safety, +// The parameter `safe` is used to specify whether using set in concurrent-safety, // which is false in default. func NewStrSet(safe ...bool) *StrSet { return &StrSet{ @@ -31,7 +31,7 @@ func NewStrSet(safe ...bool) *StrSet { } } -// NewStrSetFrom returns a new set from . +// NewStrSetFrom returns a new set from `items`. func NewStrSetFrom(items []string, safe ...bool) *StrSet { m := make(map[string]struct{}) for _, v := range items { @@ -43,8 +43,8 @@ func NewStrSetFrom(items []string, safe ...bool) *StrSet { } } -// Iterator iterates the set readonly with given callback function , -// if returns true then continue iterating; or false to stop. +// Iterator iterates the set readonly with given callback function `f`, +// if `f` returns true then continue iterating; or false to stop. func (set *StrSet) Iterator(f func(v string) bool) { set.mu.RLock() defer set.mu.RUnlock() @@ -87,9 +87,9 @@ func (set *StrSet) AddIfNotExist(item string) bool { // AddIfNotExistFunc checks whether item exists in the set, // it adds the item to set and returns true if it does not exists in the set and -// function returns true, or else it does nothing and returns false. +// function `f` returns true, or else it does nothing and returns false. // -// Note that, the function is executed without writing lock. +// Note that, the function `f` is executed without writing lock. func (set *StrSet) AddIfNotExistFunc(item string, f func() bool) bool { if !set.Contains(item) { if f() { @@ -109,9 +109,9 @@ func (set *StrSet) AddIfNotExistFunc(item string, f func() bool) bool { // AddIfNotExistFunc checks whether item exists in the set, // it adds the item to set and returns true if it does not exists in the set and -// function returns true, or else it does nothing and returns false. +// function `f` returns true, or else it does nothing and returns false. // -// Note that, the function is executed without writing lock. +// Note that, the function `f` is executed without writing lock. func (set *StrSet) AddIfNotExistFuncLock(item string, f func() bool) bool { if !set.Contains(item) { set.mu.Lock() @@ -129,7 +129,7 @@ func (set *StrSet) AddIfNotExistFuncLock(item string, f func() bool) bool { return false } -// Contains checks whether the set contains . +// Contains checks whether the set contains `item`. func (set *StrSet) Contains(item string) bool { var ok bool set.mu.RLock() @@ -153,7 +153,7 @@ func (set *StrSet) ContainsI(item string) bool { return false } -// Remove deletes from set. +// Remove deletes `item` from set. func (set *StrSet) Remove(item string) { set.mu.Lock() if set.data != nil { @@ -193,7 +193,7 @@ func (set *StrSet) Slice() []string { return ret } -// Join joins items with a string . +// Join joins items with a string `glue`. func (set *StrSet) Join(glue string) string { set.mu.RLock() defer set.mu.RUnlock() @@ -234,14 +234,14 @@ func (set *StrSet) String() string { return buffer.String() } -// LockFunc locks writing with callback function . +// LockFunc locks writing with callback function `f`. func (set *StrSet) LockFunc(f func(m map[string]struct{})) { set.mu.Lock() defer set.mu.Unlock() f(set.data) } -// RLockFunc locks reading with callback function . +// RLockFunc locks reading with callback function `f`. func (set *StrSet) RLockFunc(f func(m map[string]struct{})) { set.mu.RLock() defer set.mu.RUnlock() @@ -268,7 +268,7 @@ func (set *StrSet) Equal(other *StrSet) bool { return true } -// IsSubsetOf checks whether the current set is a sub-set of . +// IsSubsetOf checks whether the current set is a sub-set of `other`. func (set *StrSet) IsSubsetOf(other *StrSet) bool { if set == other { return true @@ -285,8 +285,8 @@ func (set *StrSet) IsSubsetOf(other *StrSet) bool { return true } -// Union returns a new set which is the union of and . -// Which means, all the items in are in or in . +// Union returns a new set which is the union of and `other`. +// Which means, all the items in are in or in `other`. func (set *StrSet) Union(others ...*StrSet) (newSet *StrSet) { newSet = NewStrSet() set.mu.RLock() @@ -311,8 +311,8 @@ func (set *StrSet) Union(others ...*StrSet) (newSet *StrSet) { return } -// Diff returns a new set which is the difference set from to . -// Which means, all the items in are in but not in . +// Diff returns a new set which is the difference set from to `other`. +// Which means, all the items in are in but not in `other`. func (set *StrSet) Diff(others ...*StrSet) (newSet *StrSet) { newSet = NewStrSet() set.mu.RLock() @@ -332,8 +332,8 @@ func (set *StrSet) Diff(others ...*StrSet) (newSet *StrSet) { return } -// Intersect returns a new set which is the intersection from to . -// Which means, all the items in are in and also in . +// Intersect returns a new set which is the intersection from to `other`. +// Which means, all the items in are in and also in `other`. func (set *StrSet) Intersect(others ...*StrSet) (newSet *StrSet) { newSet = NewStrSet() set.mu.RLock() @@ -354,11 +354,11 @@ func (set *StrSet) Intersect(others ...*StrSet) (newSet *StrSet) { return } -// Complement returns a new set which is the complement from to . -// Which means, all the items in are in and not in . +// Complement returns a new set which is the complement from to `full`. +// Which means, all the items in are in and not in `set`. // -// It returns the difference between and -// if the given set is not the full set of . +// It returns the difference between and `set` +// if the given set is not the full set of `set`. func (set *StrSet) Complement(full *StrSet) (newSet *StrSet) { newSet = NewStrSet() set.mu.RLock() @@ -375,7 +375,7 @@ func (set *StrSet) Complement(full *StrSet) (newSet *StrSet) { return } -// Merge adds items from sets into . +// Merge adds items from sets into `set`. func (set *StrSet) Merge(others ...*StrSet) *StrSet { set.mu.Lock() defer set.mu.Unlock() @@ -416,7 +416,7 @@ func (set *StrSet) Pop() string { return "" } -// Pops randomly pops items from set. +// Pops randomly pops `size` items from set. // It returns all items if size == -1. func (set *StrSet) Pops(size int) []string { set.mu.Lock() @@ -440,7 +440,7 @@ func (set *StrSet) Pops(size int) []string { return array } -// Walk applies a user supplied function to every item of set. +// Walk applies a user supplied function `f` to every item of set. func (set *StrSet) Walk(f func(item string) string) *StrSet { set.mu.Lock() defer set.mu.Unlock() diff --git a/container/gtree/gtree_avltree.go b/container/gtree/gtree_avltree.go index b5ee031dd..deaad2b75 100644 --- a/container/gtree/gtree_avltree.go +++ b/container/gtree/gtree_avltree.go @@ -34,7 +34,7 @@ type AVLTreeNode struct { } // NewAVLTree instantiates an AVL tree with the custom key comparator. -// The parameter is used to specify whether using tree in concurrent-safety, +// The parameter `safe` is used to specify whether using tree in concurrent-safety, // which is false in default. func NewAVLTree(comparator func(v1, v2 interface{}) int, safe ...bool) *AVLTree { return &AVLTree{ @@ -44,7 +44,7 @@ func NewAVLTree(comparator func(v1, v2 interface{}) int, safe ...bool) *AVLTree } // NewAVLTreeFrom instantiates an AVL tree with the custom key comparator and data map. -// The parameter is used to specify whether using tree in concurrent-safety, +// The parameter `safe` is used to specify whether using tree in concurrent-safety, // which is false in default. func NewAVLTreeFrom(comparator func(v1, v2 interface{}) int, data map[interface{}]interface{}, safe ...bool) *AVLTree { tree := NewAVLTree(comparator, safe...) @@ -77,8 +77,8 @@ func (tree *AVLTree) Sets(data map[interface{}]interface{}) { } } -// Search searches the tree with given . -// Second return parameter is true if key was found, otherwise false. +// Search searches the tree with given `key`. +// Second return parameter `found` is true if key was found, otherwise false. func (tree *AVLTree) Search(key interface{}) (value interface{}, found bool) { tree.mu.RLock() defer tree.mu.RUnlock() @@ -88,8 +88,8 @@ func (tree *AVLTree) Search(key interface{}) (value interface{}, found bool) { return nil, false } -// doSearch searches the tree with given . -// Second return parameter is true if key was found, otherwise false. +// doSearch searches the tree with given `key`. +// Second return parameter `found` is true if key was found, otherwise false. func (tree *AVLTree) doSearch(key interface{}) (node *AVLTreeNode, found bool) { node = tree.root for node != nil { @@ -106,21 +106,21 @@ func (tree *AVLTree) doSearch(key interface{}) (node *AVLTreeNode, found bool) { return nil, false } -// Get searches the node in the tree by and returns its value or nil if key is not found in tree. +// Get searches the node in the tree by `key` and returns its value or nil if key is not found in tree. func (tree *AVLTree) Get(key interface{}) (value interface{}) { value, _ = tree.Search(key) return } // doSetWithLockCheck checks whether value of the key exists with mutex.Lock, -// if not exists, set value to the map with given , +// if not exists, set value to the map with given `key`, // or else just return the existing value. // -// When setting value, if is type of , +// When setting value, if `value` is type of , // it will be executed with mutex.Lock of the hash map, -// and its return value will be set to the map with . +// and its return value will be set to the map with `key`. // -// It returns value with given . +// It returns value with given `key`. func (tree *AVLTree) doSetWithLockCheck(key interface{}, value interface{}) interface{} { tree.mu.Lock() defer tree.mu.Unlock() @@ -137,7 +137,7 @@ func (tree *AVLTree) doSetWithLockCheck(key interface{}, value interface{}) inte } // GetOrSet returns the value by key, -// or sets value with given if it does not exist and then returns this value. +// or sets value with given `value` if it does not exist and then returns this value. func (tree *AVLTree) GetOrSet(key interface{}, value interface{}) interface{} { if v, ok := tree.Search(key); !ok { return tree.doSetWithLockCheck(key, value) @@ -147,7 +147,7 @@ func (tree *AVLTree) GetOrSet(key interface{}, value interface{}) interface{} { } // GetOrSetFunc returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. func (tree *AVLTree) GetOrSetFunc(key interface{}, f func() interface{}) interface{} { if v, ok := tree.Search(key); !ok { @@ -158,10 +158,10 @@ func (tree *AVLTree) GetOrSetFunc(key interface{}, f func() interface{}) interfa } // GetOrSetFuncLock returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. // -// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function +// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function `f` // with mutex.Lock of the hash map. func (tree *AVLTree) GetOrSetFuncLock(key interface{}, f func() interface{}) interface{} { if v, ok := tree.Search(key); !ok { @@ -171,7 +171,7 @@ func (tree *AVLTree) GetOrSetFuncLock(key interface{}, f func() interface{}) int } } -// GetVar returns a gvar.Var with the value by given . +// GetVar returns a gvar.Var with the value by given `key`. // The returned gvar.Var is un-concurrent safe. func (tree *AVLTree) GetVar(key interface{}) *gvar.Var { return gvar.New(tree.Get(key)) @@ -195,8 +195,8 @@ func (tree *AVLTree) GetVarOrSetFuncLock(key interface{}, f func() interface{}) return gvar.New(tree.GetOrSetFuncLock(key, f)) } -// SetIfNotExist sets to the map if the does not exist, and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExist sets to the map if the `key` does not exist, and then returns true. +// It returns false if exists, and `value` would be ignored. func (tree *AVLTree) SetIfNotExist(key interface{}, value interface{}) bool { if !tree.Contains(key) { tree.doSetWithLockCheck(key, value) @@ -205,8 +205,8 @@ func (tree *AVLTree) SetIfNotExist(key interface{}, value interface{}) bool { return false } -// SetIfNotExistFunc sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFunc sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. func (tree *AVLTree) SetIfNotExistFunc(key interface{}, f func() interface{}) bool { if !tree.Contains(key) { tree.doSetWithLockCheck(key, f()) @@ -215,11 +215,11 @@ func (tree *AVLTree) SetIfNotExistFunc(key interface{}, f func() interface{}) bo return false } -// SetIfNotExistFuncLock sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFuncLock sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. // // SetIfNotExistFuncLock differs with SetIfNotExistFunc function is that -// it executes function with mutex.Lock of the hash map. +// it executes function `f` with mutex.Lock of the hash map. func (tree *AVLTree) SetIfNotExistFuncLock(key interface{}, f func() interface{}) bool { if !tree.Contains(key) { tree.doSetWithLockCheck(key, f) @@ -228,7 +228,7 @@ func (tree *AVLTree) SetIfNotExistFuncLock(key interface{}, f func() interface{} return false } -// Contains checks whether exists in the tree. +// Contains checks whether `key` exists in the tree. func (tree *AVLTree) Contains(key interface{}) bool { _, ok := tree.Search(key) return ok @@ -243,7 +243,7 @@ func (tree *AVLTree) Remove(key interface{}) (value interface{}) { return } -// Removes batch deletes values of the tree by . +// Removes batch deletes values of the tree by `keys`. func (tree *AVLTree) Removes(keys []interface{}) { tree.mu.Lock() defer tree.mu.Unlock() @@ -386,7 +386,7 @@ func (tree *AVLTree) Clear() { tree.size = 0 } -// Replace the data of the tree with given . +// Replace the data of the tree with given `data`. func (tree *AVLTree) Replace(data map[interface{}]interface{}) { tree.mu.Lock() defer tree.mu.Unlock() @@ -437,7 +437,7 @@ func (tree *AVLTree) MapStrAny() map[string]interface{} { // Note that you should guarantee the value is the same type as key, // or else the comparator would panic. // -// If the type of value is different with key, you pass the new . +// If the type of value is different with key, you pass the new `comparator`. func (tree *AVLTree) Flip(comparator ...func(v1, v2 interface{}) int) { t := (*AVLTree)(nil) if len(comparator) > 0 { @@ -465,18 +465,18 @@ func (tree *AVLTree) IteratorFrom(key interface{}, match bool, f func(key, value tree.IteratorAscFrom(key, match, f) } -// IteratorAsc iterates the tree readonly in ascending order with given callback function . -// If returns true, then it continues iterating; or false to stop. +// IteratorAsc iterates the tree readonly in ascending order with given callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (tree *AVLTree) IteratorAsc(f func(key, value interface{}) bool) { tree.mu.RLock() defer tree.mu.RUnlock() tree.doIteratorAsc(tree.bottom(0), f) } -// IteratorAscFrom iterates the tree readonly in ascending order with given callback function . -// The parameter specifies the start entry for iterating. The specifies whether -// starting iterating if the is fully matched, or else using index searching iterating. -// If returns true, then it continues iterating; or false to stop. +// IteratorAscFrom iterates the tree readonly in ascending order with given callback function `f`. +// The parameter specifies the start entry for iterating. The `match` specifies whether +// starting iterating if the `key` is fully matched, or else using index searching iterating. +// If `f` returns true, then it continues iterating; or false to stop. func (tree *AVLTree) IteratorAscFrom(key interface{}, match bool, f func(key, value interface{}) bool) { tree.mu.RLock() defer tree.mu.RUnlock() @@ -499,18 +499,18 @@ func (tree *AVLTree) doIteratorAsc(node *AVLTreeNode, f func(key, value interfac } } -// IteratorDesc iterates the tree readonly in descending order with given callback function . -// If returns true, then it continues iterating; or false to stop. +// IteratorDesc iterates the tree readonly in descending order with given callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (tree *AVLTree) IteratorDesc(f func(key, value interface{}) bool) { tree.mu.RLock() defer tree.mu.RUnlock() tree.doIteratorDesc(tree.bottom(1), f) } -// IteratorDescFrom iterates the tree readonly in descending order with given callback function . -// The parameter specifies the start entry for iterating. The specifies whether -// starting iterating if the is fully matched, or else using index searching iterating. -// If returns true, then it continues iterating; or false to stop. +// IteratorDescFrom iterates the tree readonly in descending order with given callback function `f`. +// The parameter specifies the start entry for iterating. The `match` specifies whether +// starting iterating if the `key` is fully matched, or else using index searching iterating. +// If `f` returns true, then it continues iterating; or false to stop. func (tree *AVLTree) IteratorDescFrom(key interface{}, match bool, f func(key, value interface{}) bool) { tree.mu.RLock() defer tree.mu.RUnlock() diff --git a/container/gtree/gtree_btree.go b/container/gtree/gtree_btree.go index 45a3068b9..f26783366 100644 --- a/container/gtree/gtree_btree.go +++ b/container/gtree/gtree_btree.go @@ -40,10 +40,10 @@ type BTreeEntry struct { Value interface{} } -// NewBTree instantiates a B-tree with (maximum number of children) and a custom key comparator. -// The parameter is used to specify whether using tree in concurrent-safety, +// NewBTree instantiates a B-tree with `m` (maximum number of children) and a custom key comparator. +// The parameter `safe` is used to specify whether using tree in concurrent-safety, // which is false in default. -// Note that the must be greater or equal than 3, or else it panics. +// Note that the `m` must be greater or equal than 3, or else it panics. func NewBTree(m int, comparator func(v1, v2 interface{}) int, safe ...bool) *BTree { if m < 3 { panic("Invalid order, should be at least 3") @@ -55,8 +55,8 @@ func NewBTree(m int, comparator func(v1, v2 interface{}) int, safe ...bool) *BTr } } -// NewBTreeFrom instantiates a B-tree with (maximum number of children), a custom key comparator and data map. -// The parameter is used to specify whether using tree in concurrent-safety, +// NewBTreeFrom instantiates a B-tree with `m` (maximum number of children), a custom key comparator and data map. +// The parameter `safe` is used to specify whether using tree in concurrent-safety, // which is false in default. func NewBTreeFrom(m int, comparator func(v1, v2 interface{}) int, data map[interface{}]interface{}, safe ...bool) *BTree { tree := NewBTree(m, comparator, safe...) @@ -104,21 +104,21 @@ func (tree *BTree) Sets(data map[interface{}]interface{}) { } } -// Get searches the node in the tree by and returns its value or nil if key is not found in tree. +// Get searches the node in the tree by `key` and returns its value or nil if key is not found in tree. func (tree *BTree) Get(key interface{}) (value interface{}) { value, _ = tree.Search(key) return } // doSetWithLockCheck checks whether value of the key exists with mutex.Lock, -// if not exists, set value to the map with given , +// if not exists, set value to the map with given `key`, // or else just return the existing value. // -// When setting value, if is type of , +// When setting value, if `value` is type of , // it will be executed with mutex.Lock of the hash map, -// and its return value will be set to the map with . +// and its return value will be set to the map with `key`. // -// It returns value with given . +// It returns value with given `key`. func (tree *BTree) doSetWithLockCheck(key interface{}, value interface{}) interface{} { tree.mu.Lock() defer tree.mu.Unlock() @@ -135,7 +135,7 @@ func (tree *BTree) doSetWithLockCheck(key interface{}, value interface{}) interf } // GetOrSet returns the value by key, -// or sets value with given if it does not exist and then returns this value. +// or sets value with given `value` if it does not exist and then returns this value. func (tree *BTree) GetOrSet(key interface{}, value interface{}) interface{} { if v, ok := tree.Search(key); !ok { return tree.doSetWithLockCheck(key, value) @@ -145,7 +145,7 @@ func (tree *BTree) GetOrSet(key interface{}, value interface{}) interface{} { } // GetOrSetFunc returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. func (tree *BTree) GetOrSetFunc(key interface{}, f func() interface{}) interface{} { if v, ok := tree.Search(key); !ok { @@ -156,10 +156,10 @@ func (tree *BTree) GetOrSetFunc(key interface{}, f func() interface{}) interface } // GetOrSetFuncLock returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. // -// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function +// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function `f` // with mutex.Lock of the hash map. func (tree *BTree) GetOrSetFuncLock(key interface{}, f func() interface{}) interface{} { if v, ok := tree.Search(key); !ok { @@ -169,7 +169,7 @@ func (tree *BTree) GetOrSetFuncLock(key interface{}, f func() interface{}) inter } } -// GetVar returns a gvar.Var with the value by given . +// GetVar returns a gvar.Var with the value by given `key`. // The returned gvar.Var is un-concurrent safe. func (tree *BTree) GetVar(key interface{}) *gvar.Var { return gvar.New(tree.Get(key)) @@ -193,8 +193,8 @@ func (tree *BTree) GetVarOrSetFuncLock(key interface{}, f func() interface{}) *g return gvar.New(tree.GetOrSetFuncLock(key, f)) } -// SetIfNotExist sets to the map if the does not exist, and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExist sets to the map if the `key` does not exist, and then returns true. +// It returns false if exists, and `value` would be ignored. func (tree *BTree) SetIfNotExist(key interface{}, value interface{}) bool { if !tree.Contains(key) { tree.doSetWithLockCheck(key, value) @@ -203,8 +203,8 @@ func (tree *BTree) SetIfNotExist(key interface{}, value interface{}) bool { return false } -// SetIfNotExistFunc sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFunc sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. func (tree *BTree) SetIfNotExistFunc(key interface{}, f func() interface{}) bool { if !tree.Contains(key) { tree.doSetWithLockCheck(key, f()) @@ -213,11 +213,11 @@ func (tree *BTree) SetIfNotExistFunc(key interface{}, f func() interface{}) bool return false } -// SetIfNotExistFuncLock sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFuncLock sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. // // SetIfNotExistFuncLock differs with SetIfNotExistFunc function is that -// it executes function with mutex.Lock of the hash map. +// it executes function `f` with mutex.Lock of the hash map. func (tree *BTree) SetIfNotExistFuncLock(key interface{}, f func() interface{}) bool { if !tree.Contains(key) { tree.doSetWithLockCheck(key, f) @@ -226,7 +226,7 @@ func (tree *BTree) SetIfNotExistFuncLock(key interface{}, f func() interface{}) return false } -// Contains checks whether exists in the tree. +// Contains checks whether `key` exists in the tree. func (tree *BTree) Contains(key interface{}) bool { _, ok := tree.Search(key) return ok @@ -244,14 +244,14 @@ func (tree *BTree) doRemove(key interface{}) (value interface{}) { return } -// Remove removes the node from the tree by . +// Remove removes the node from the tree by `key`. func (tree *BTree) Remove(key interface{}) (value interface{}) { tree.mu.Lock() defer tree.mu.Unlock() return tree.doRemove(key) } -// Removes batch deletes values of the tree by . +// Removes batch deletes values of the tree by `keys`. func (tree *BTree) Removes(keys []interface{}) { tree.mu.Lock() defer tree.mu.Unlock() @@ -324,7 +324,7 @@ func (tree *BTree) Clear() { tree.size = 0 } -// Replace the data of the tree with given . +// Replace the data of the tree with given `data`. func (tree *BTree) Replace(data map[interface{}]interface{}) { tree.mu.Lock() defer tree.mu.Unlock() @@ -369,8 +369,8 @@ func (tree *BTree) String() string { return buffer.String() } -// Search searches the tree with given . -// Second return parameter is true if key was found, otherwise false. +// Search searches the tree with given `key`. +// Second return parameter `found` is true if key was found, otherwise false. func (tree *BTree) Search(key interface{}) (value interface{}, found bool) { tree.mu.RLock() defer tree.mu.RUnlock() @@ -381,7 +381,7 @@ func (tree *BTree) Search(key interface{}) (value interface{}, found bool) { return nil, false } -// Search searches the tree with given without mutex. +// Search searches the tree with given `key` without mutex. // It returns the entry if found or otherwise nil. func (tree *BTree) doSearch(key interface{}) *BTreeEntry { node, index, found := tree.searchRecursively(tree.root, key) @@ -406,8 +406,8 @@ func (tree *BTree) IteratorFrom(key interface{}, match bool, f func(key, value i tree.IteratorAscFrom(key, match, f) } -// IteratorAsc iterates the tree readonly in ascending order with given callback function . -// If returns true, then it continues iterating; or false to stop. +// IteratorAsc iterates the tree readonly in ascending order with given callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (tree *BTree) IteratorAsc(f func(key, value interface{}) bool) { tree.mu.RLock() defer tree.mu.RUnlock() @@ -418,10 +418,10 @@ func (tree *BTree) IteratorAsc(f func(key, value interface{}) bool) { tree.doIteratorAsc(node, node.Entries[0], 0, f) } -// IteratorAscFrom iterates the tree readonly in ascending order with given callback function . -// The parameter specifies the start entry for iterating. The specifies whether -// starting iterating if the is fully matched, or else using index searching iterating. -// If returns true, then it continues iterating; or false to stop. +// IteratorAscFrom iterates the tree readonly in ascending order with given callback function `f`. +// The parameter specifies the start entry for iterating. The `match` specifies whether +// starting iterating if the `key` is fully matched, or else using index searching iterating. +// If `f` returns true, then it continues iterating; or false to stop. func (tree *BTree) IteratorAscFrom(key interface{}, match bool, f func(key, value interface{}) bool) { tree.mu.RLock() defer tree.mu.RUnlock() @@ -479,8 +479,8 @@ loop: } } -// IteratorDesc iterates the tree readonly in descending order with given callback function . -// If returns true, then it continues iterating; or false to stop. +// IteratorDesc iterates the tree readonly in descending order with given callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (tree *BTree) IteratorDesc(f func(key, value interface{}) bool) { tree.mu.RLock() defer tree.mu.RUnlock() @@ -493,10 +493,10 @@ func (tree *BTree) IteratorDesc(f func(key, value interface{}) bool) { tree.doIteratorDesc(node, entry, index, f) } -// IteratorDescFrom iterates the tree readonly in descending order with given callback function . -// The parameter specifies the start entry for iterating. The specifies whether -// starting iterating if the is fully matched, or else using index searching iterating. -// If returns true, then it continues iterating; or false to stop. +// IteratorDescFrom iterates the tree readonly in descending order with given callback function `f`. +// The parameter specifies the start entry for iterating. The `match` specifies whether +// starting iterating if the `key` is fully matched, or else using index searching iterating. +// If `f` returns true, then it continues iterating; or false to stop. func (tree *BTree) IteratorDescFrom(key interface{}, match bool, f func(key, value interface{}) bool) { tree.mu.RLock() defer tree.mu.RUnlock() @@ -510,8 +510,8 @@ func (tree *BTree) IteratorDescFrom(key interface{}, match bool, f func(key, val } } -// IteratorDesc iterates the tree readonly in descending order with given callback function . -// If returns true, then it continues iterating; or false to stop. +// IteratorDesc iterates the tree readonly in descending order with given callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (tree *BTree) doIteratorDesc(node *BTreeNode, entry *BTreeEntry, index int, f func(key, value interface{}) bool) { first := true loop: diff --git a/container/gtree/gtree_redblacktree.go b/container/gtree/gtree_redblacktree.go index 7ccf0fd1c..e75d04ffd 100644 --- a/container/gtree/gtree_redblacktree.go +++ b/container/gtree/gtree_redblacktree.go @@ -41,7 +41,7 @@ type RedBlackTreeNode struct { } // NewRedBlackTree instantiates a red-black tree with the custom key comparator. -// The parameter is used to specify whether using tree in concurrent-safety, +// The parameter `safe` is used to specify whether using tree in concurrent-safety, // which is false in default. func NewRedBlackTree(comparator func(v1, v2 interface{}) int, safe ...bool) *RedBlackTree { return &RedBlackTree{ @@ -50,8 +50,8 @@ func NewRedBlackTree(comparator func(v1, v2 interface{}) int, safe ...bool) *Red } } -// NewRedBlackTreeFrom instantiates a red-black tree with the custom key comparator and map. -// The parameter is used to specify whether using tree in concurrent-safety, +// NewRedBlackTreeFrom instantiates a red-black tree with the custom key comparator and `data` map. +// The parameter `safe` is used to specify whether using tree in concurrent-safety, // which is false in default. func NewRedBlackTreeFrom(comparator func(v1, v2 interface{}) int, data map[interface{}]interface{}, safe ...bool) *RedBlackTree { tree := NewRedBlackTree(comparator, safe...) @@ -146,21 +146,21 @@ func (tree *RedBlackTree) doSet(key interface{}, value interface{}) { tree.size++ } -// Get searches the node in the tree by and returns its value or nil if key is not found in tree. +// Get searches the node in the tree by `key` and returns its value or nil if key is not found in tree. func (tree *RedBlackTree) Get(key interface{}) (value interface{}) { value, _ = tree.Search(key) return } // doSetWithLockCheck checks whether value of the key exists with mutex.Lock, -// if not exists, set value to the map with given , +// if not exists, set value to the map with given `key`, // or else just return the existing value. // -// When setting value, if is type of , +// When setting value, if `value` is type of , // it will be executed with mutex.Lock of the hash map, -// and its return value will be set to the map with . +// and its return value will be set to the map with `key`. // -// It returns value with given . +// It returns value with given `key`. func (tree *RedBlackTree) doSetWithLockCheck(key interface{}, value interface{}) interface{} { tree.mu.Lock() defer tree.mu.Unlock() @@ -177,7 +177,7 @@ func (tree *RedBlackTree) doSetWithLockCheck(key interface{}, value interface{}) } // GetOrSet returns the value by key, -// or sets value with given if it does not exist and then returns this value. +// or sets value with given `value` if it does not exist and then returns this value. func (tree *RedBlackTree) GetOrSet(key interface{}, value interface{}) interface{} { if v, ok := tree.Search(key); !ok { return tree.doSetWithLockCheck(key, value) @@ -187,7 +187,7 @@ func (tree *RedBlackTree) GetOrSet(key interface{}, value interface{}) interface } // GetOrSetFunc returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. func (tree *RedBlackTree) GetOrSetFunc(key interface{}, f func() interface{}) interface{} { if v, ok := tree.Search(key); !ok { @@ -198,10 +198,10 @@ func (tree *RedBlackTree) GetOrSetFunc(key interface{}, f func() interface{}) in } // GetOrSetFuncLock returns the value by key, -// or sets value with returned value of callback function if it does not exist +// or sets value with returned value of callback function `f` if it does not exist // and then returns this value. // -// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function +// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function `f` // with mutex.Lock of the hash map. func (tree *RedBlackTree) GetOrSetFuncLock(key interface{}, f func() interface{}) interface{} { if v, ok := tree.Search(key); !ok { @@ -211,7 +211,7 @@ func (tree *RedBlackTree) GetOrSetFuncLock(key interface{}, f func() interface{} } } -// GetVar returns a gvar.Var with the value by given . +// GetVar returns a gvar.Var with the value by given `key`. // The returned gvar.Var is un-concurrent safe. func (tree *RedBlackTree) GetVar(key interface{}) *gvar.Var { return gvar.New(tree.Get(key)) @@ -235,8 +235,8 @@ func (tree *RedBlackTree) GetVarOrSetFuncLock(key interface{}, f func() interfac return gvar.New(tree.GetOrSetFuncLock(key, f)) } -// SetIfNotExist sets to the map if the does not exist, and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExist sets to the map if the `key` does not exist, and then returns true. +// It returns false if exists, and `value` would be ignored. func (tree *RedBlackTree) SetIfNotExist(key interface{}, value interface{}) bool { if !tree.Contains(key) { tree.doSetWithLockCheck(key, value) @@ -245,8 +245,8 @@ func (tree *RedBlackTree) SetIfNotExist(key interface{}, value interface{}) bool return false } -// SetIfNotExistFunc sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFunc sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. func (tree *RedBlackTree) SetIfNotExistFunc(key interface{}, f func() interface{}) bool { if !tree.Contains(key) { tree.doSetWithLockCheck(key, f()) @@ -255,11 +255,11 @@ func (tree *RedBlackTree) SetIfNotExistFunc(key interface{}, f func() interface{ return false } -// SetIfNotExistFuncLock sets value with return value of callback function , and then returns true. -// It returns false if exists, and would be ignored. +// SetIfNotExistFuncLock sets value with return value of callback function `f`, and then returns true. +// It returns false if exists, and `value` would be ignored. // // SetIfNotExistFuncLock differs with SetIfNotExistFunc function is that -// it executes function with mutex.Lock of the hash map. +// it executes function `f` with mutex.Lock of the hash map. func (tree *RedBlackTree) SetIfNotExistFuncLock(key interface{}, f func() interface{}) bool { if !tree.Contains(key) { tree.doSetWithLockCheck(key, f) @@ -268,13 +268,13 @@ func (tree *RedBlackTree) SetIfNotExistFuncLock(key interface{}, f func() interf return false } -// Contains checks whether exists in the tree. +// Contains checks whether `key` exists in the tree. func (tree *RedBlackTree) Contains(key interface{}) bool { _, ok := tree.Search(key) return ok } -// doRemove removes the node from the tree by without mutex. +// doRemove removes the node from the tree by `key` without mutex. func (tree *RedBlackTree) doRemove(key interface{}) (value interface{}) { child := (*RedBlackTreeNode)(nil) node, found := tree.doSearch(key) @@ -307,14 +307,14 @@ func (tree *RedBlackTree) doRemove(key interface{}) (value interface{}) { return } -// Remove removes the node from the tree by . +// Remove removes the node from the tree by `key`. func (tree *RedBlackTree) Remove(key interface{}) (value interface{}) { tree.mu.Lock() defer tree.mu.Unlock() return tree.doRemove(key) } -// Removes batch deletes values of the tree by . +// Removes batch deletes values of the tree by `keys`. func (tree *RedBlackTree) Removes(keys []interface{}) { tree.mu.Lock() defer tree.mu.Unlock() @@ -436,7 +436,7 @@ func (tree *RedBlackTree) rightNode() *RedBlackTreeNode { // Floor Finds floor node of the input key, return the floor node or nil if no floor node is found. // Second return parameter is true if floor was found, otherwise false. // -// Floor node is defined as the largest node that its key is smaller than or equal to the given . +// Floor node is defined as the largest node that its key is smaller than or equal to the given `key`. // A floor node may not be found, either because the tree is empty, or because // all nodes in the tree are larger than the given node. func (tree *RedBlackTree) Floor(key interface{}) (floor *RedBlackTreeNode, found bool) { @@ -464,7 +464,7 @@ func (tree *RedBlackTree) Floor(key interface{}) (floor *RedBlackTreeNode, found // Ceiling finds ceiling node of the input key, return the ceiling node or nil if no ceiling node is found. // Second return parameter is true if ceiling was found, otherwise false. // -// Ceiling node is defined as the smallest node that its key is larger than or equal to the given . +// Ceiling node is defined as the smallest node that its key is larger than or equal to the given `key`. // A ceiling node may not be found, either because the tree is empty, or because // all nodes in the tree are smaller than the given node. func (tree *RedBlackTree) Ceiling(key interface{}) (ceiling *RedBlackTreeNode, found bool) { @@ -499,18 +499,18 @@ func (tree *RedBlackTree) IteratorFrom(key interface{}, match bool, f func(key, tree.IteratorAscFrom(key, match, f) } -// IteratorAsc iterates the tree readonly in ascending order with given callback function . -// If returns true, then it continues iterating; or false to stop. +// IteratorAsc iterates the tree readonly in ascending order with given callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (tree *RedBlackTree) IteratorAsc(f func(key, value interface{}) bool) { tree.mu.RLock() defer tree.mu.RUnlock() tree.doIteratorAsc(tree.leftNode(), f) } -// IteratorAscFrom iterates the tree readonly in ascending order with given callback function . -// The parameter specifies the start entry for iterating. The specifies whether -// starting iterating if the is fully matched, or else using index searching iterating. -// If returns true, then it continues iterating; or false to stop. +// IteratorAscFrom iterates the tree readonly in ascending order with given callback function `f`. +// The parameter specifies the start entry for iterating. The `match` specifies whether +// starting iterating if the `key` is fully matched, or else using index searching iterating. +// If `f` returns true, then it continues iterating; or false to stop. func (tree *RedBlackTree) IteratorAscFrom(key interface{}, match bool, f func(key, value interface{}) bool) { tree.mu.RLock() defer tree.mu.RUnlock() @@ -550,18 +550,18 @@ loop: } } -// IteratorDesc iterates the tree readonly in descending order with given callback function . -// If returns true, then it continues iterating; or false to stop. +// IteratorDesc iterates the tree readonly in descending order with given callback function `f`. +// If `f` returns true, then it continues iterating; or false to stop. func (tree *RedBlackTree) IteratorDesc(f func(key, value interface{}) bool) { tree.mu.RLock() defer tree.mu.RUnlock() tree.doIteratorDesc(tree.rightNode(), f) } -// IteratorDescFrom iterates the tree readonly in descending order with given callback function . -// The parameter specifies the start entry for iterating. The specifies whether -// starting iterating if the is fully matched, or else using index searching iterating. -// If returns true, then it continues iterating; or false to stop. +// IteratorDescFrom iterates the tree readonly in descending order with given callback function `f`. +// The parameter specifies the start entry for iterating. The `match` specifies whether +// starting iterating if the `key` is fully matched, or else using index searching iterating. +// If `f` returns true, then it continues iterating; or false to stop. func (tree *RedBlackTree) IteratorDescFrom(key interface{}, match bool, f func(key, value interface{}) bool) { tree.mu.RLock() defer tree.mu.RUnlock() @@ -609,7 +609,7 @@ func (tree *RedBlackTree) Clear() { tree.size = 0 } -// Replace the data of the tree with given . +// Replace the data of the tree with given `data`. func (tree *RedBlackTree) Replace(data map[interface{}]interface{}) { tree.mu.Lock() defer tree.mu.Unlock() @@ -636,8 +636,8 @@ func (tree *RedBlackTree) Print() { fmt.Println(tree.String()) } -// Search searches the tree with given . -// Second return parameter is true if key was found, otherwise false. +// Search searches the tree with given `key`. +// Second return parameter `found` is true if key was found, otherwise false. func (tree *RedBlackTree) Search(key interface{}) (value interface{}, found bool) { tree.mu.RLock() defer tree.mu.RUnlock() @@ -652,7 +652,7 @@ func (tree *RedBlackTree) Search(key interface{}) (value interface{}, found bool // Note that you should guarantee the value is the same type as key, // or else the comparator would panic. // -// If the type of value is different with key, you pass the new . +// If the type of value is different with key, you pass the new `comparator`. func (tree *RedBlackTree) Flip(comparator ...func(v1, v2 interface{}) int) { t := (*RedBlackTree)(nil) if len(comparator) > 0 { @@ -698,7 +698,7 @@ func (tree *RedBlackTree) output(node *RedBlackTreeNode, prefix string, isTail b } } -// doSearch searches the tree with given without mutex. +// doSearch searches the tree with given `key` without mutex. // It returns the node if found or otherwise nil. func (tree *RedBlackTree) doSearch(key interface{}) (node *RedBlackTreeNode, found bool) { node = tree.root diff --git a/container/gtype/bool.go b/container/gtype/gtype_bool.go similarity index 94% rename from container/gtype/bool.go rename to container/gtype/gtype_bool.go index adb49db20..4b7e45909 100644 --- a/container/gtype/bool.go +++ b/container/gtype/gtype_bool.go @@ -23,7 +23,7 @@ var ( ) // NewBool creates and returns a concurrent-safe object for bool type, -// with given initial value . +// with given initial value `value`. func NewBool(value ...bool) *Bool { t := &Bool{} if len(value) > 0 { @@ -41,7 +41,7 @@ func (v *Bool) Clone() *Bool { return NewBool(v.Val()) } -// Set atomically stores into t.value and returns the previous value of t.value. +// Set atomically stores `value` into t.value and returns the previous value of t.value. func (v *Bool) Set(value bool) (old bool) { if value { old = atomic.SwapInt32(&v.value, 1) == 1 @@ -91,7 +91,7 @@ func (v *Bool) UnmarshalJSON(b []byte) error { return nil } -// UnmarshalValue is an interface implement which sets any type of value for . +// UnmarshalValue is an interface implement which sets any type of value for `v`. func (v *Bool) UnmarshalValue(value interface{}) error { v.Set(gconv.Bool(value)) return nil diff --git a/container/gtype/byte.go b/container/gtype/gtype_byte.go similarity index 91% rename from container/gtype/byte.go rename to container/gtype/gtype_byte.go index 14fcafe1d..9315e529c 100644 --- a/container/gtype/byte.go +++ b/container/gtype/gtype_byte.go @@ -18,7 +18,7 @@ type Byte struct { } // NewByte creates and returns a concurrent-safe object for byte type, -// with given initial value . +// with given initial value `value`. func NewByte(value ...byte) *Byte { if len(value) > 0 { return &Byte{ @@ -33,7 +33,7 @@ func (v *Byte) Clone() *Byte { return NewByte(v.Val()) } -// Set atomically stores into t.value and returns the previous value of t.value. +// Set atomically stores `value` into t.value and returns the previous value of t.value. func (v *Byte) Set(value byte) (old byte) { return byte(atomic.SwapInt32(&v.value, int32(value))) } @@ -43,7 +43,7 @@ func (v *Byte) Val() byte { return byte(atomic.LoadInt32(&v.value)) } -// Add atomically adds to t.value and returns the new value. +// Add atomically adds `delta` to t.value and returns the new value. func (v *Byte) Add(delta byte) (new byte) { return byte(atomic.AddInt32(&v.value, int32(delta))) } @@ -69,7 +69,7 @@ func (v *Byte) UnmarshalJSON(b []byte) error { return nil } -// UnmarshalValue is an interface implement which sets any type of value for . +// UnmarshalValue is an interface implement which sets any type of value for `v`. func (v *Byte) UnmarshalValue(value interface{}) error { v.Set(gconv.Byte(value)) return nil diff --git a/container/gtype/bytes.go b/container/gtype/gtype_bytes.go similarity index 92% rename from container/gtype/bytes.go rename to container/gtype/gtype_bytes.go index eae89a722..9f91254ee 100644 --- a/container/gtype/bytes.go +++ b/container/gtype/gtype_bytes.go @@ -19,7 +19,7 @@ type Bytes struct { } // NewBytes creates and returns a concurrent-safe object for []byte type, -// with given initial value . +// with given initial value `value`. func NewBytes(value ...[]byte) *Bytes { t := &Bytes{} if len(value) > 0 { @@ -33,8 +33,8 @@ func (v *Bytes) Clone() *Bytes { return NewBytes(v.Val()) } -// Set atomically stores into t.value and returns the previous value of t.value. -// Note: The parameter cannot be nil. +// Set atomically stores `value` into t.value and returns the previous value of t.value. +// Note: The parameter `value` cannot be nil. func (v *Bytes) Set(value []byte) (old []byte) { old = v.Val() v.value.Store(value) @@ -73,7 +73,7 @@ func (v *Bytes) UnmarshalJSON(b []byte) error { return nil } -// UnmarshalValue is an interface implement which sets any type of value for . +// UnmarshalValue is an interface implement which sets any type of value for `v`. func (v *Bytes) UnmarshalValue(value interface{}) error { v.Set(gconv.Bytes(value)) return nil diff --git a/container/gtype/float32.go b/container/gtype/gtype_float32.go similarity index 92% rename from container/gtype/float32.go rename to container/gtype/gtype_float32.go index 5c2ffea03..7da59ce87 100644 --- a/container/gtype/float32.go +++ b/container/gtype/gtype_float32.go @@ -20,7 +20,7 @@ type Float32 struct { } // NewFloat32 creates and returns a concurrent-safe object for float32 type, -// with given initial value . +// with given initial value `value`. func NewFloat32(value ...float32) *Float32 { if len(value) > 0 { return &Float32{ @@ -35,7 +35,7 @@ func (v *Float32) Clone() *Float32 { return NewFloat32(v.Val()) } -// Set atomically stores into t.value and returns the previous value of t.value. +// Set atomically stores `value` into t.value and returns the previous value of t.value. func (v *Float32) Set(value float32) (old float32) { return math.Float32frombits(atomic.SwapUint32(&v.value, math.Float32bits(value))) } @@ -45,7 +45,7 @@ func (v *Float32) Val() float32 { return math.Float32frombits(atomic.LoadUint32(&v.value)) } -// Add atomically adds to t.value and returns the new value. +// Add atomically adds `delta` to t.value and returns the new value. func (v *Float32) Add(delta float32) (new float32) { for { old := math.Float32frombits(v.value) @@ -82,7 +82,7 @@ func (v *Float32) UnmarshalJSON(b []byte) error { return nil } -// UnmarshalValue is an interface implement which sets any type of value for . +// UnmarshalValue is an interface implement which sets any type of value for `v`. func (v *Float32) UnmarshalValue(value interface{}) error { v.Set(gconv.Float32(value)) return nil diff --git a/container/gtype/float64.go b/container/gtype/gtype_float64.go similarity index 92% rename from container/gtype/float64.go rename to container/gtype/gtype_float64.go index 9a7de8c32..340bdef00 100644 --- a/container/gtype/float64.go +++ b/container/gtype/gtype_float64.go @@ -20,7 +20,7 @@ type Float64 struct { } // NewFloat64 creates and returns a concurrent-safe object for float64 type, -// with given initial value . +// with given initial value `value`. func NewFloat64(value ...float64) *Float64 { if len(value) > 0 { return &Float64{ @@ -35,7 +35,7 @@ func (v *Float64) Clone() *Float64 { return NewFloat64(v.Val()) } -// Set atomically stores into t.value and returns the previous value of t.value. +// Set atomically stores `value` into t.value and returns the previous value of t.value. func (v *Float64) Set(value float64) (old float64) { return math.Float64frombits(atomic.SwapUint64(&v.value, math.Float64bits(value))) } @@ -45,7 +45,7 @@ func (v *Float64) Val() float64 { return math.Float64frombits(atomic.LoadUint64(&v.value)) } -// Add atomically adds to t.value and returns the new value. +// Add atomically adds `delta` to t.value and returns the new value. func (v *Float64) Add(delta float64) (new float64) { for { old := math.Float64frombits(v.value) @@ -82,7 +82,7 @@ func (v *Float64) UnmarshalJSON(b []byte) error { return nil } -// UnmarshalValue is an interface implement which sets any type of value for . +// UnmarshalValue is an interface implement which sets any type of value for `v`. func (v *Float64) UnmarshalValue(value interface{}) error { v.Set(gconv.Float64(value)) return nil diff --git a/container/gtype/int.go b/container/gtype/gtype_int.go similarity index 91% rename from container/gtype/int.go rename to container/gtype/gtype_int.go index 7c9ea774a..ca420e945 100644 --- a/container/gtype/int.go +++ b/container/gtype/gtype_int.go @@ -18,7 +18,7 @@ type Int struct { } // NewInt creates and returns a concurrent-safe object for int type, -// with given initial value . +// with given initial value `value`. func NewInt(value ...int) *Int { if len(value) > 0 { return &Int{ @@ -33,7 +33,7 @@ func (v *Int) Clone() *Int { return NewInt(v.Val()) } -// Set atomically stores into t.value and returns the previous value of t.value. +// Set atomically stores `value` into t.value and returns the previous value of t.value. func (v *Int) Set(value int) (old int) { return int(atomic.SwapInt64(&v.value, int64(value))) } @@ -43,7 +43,7 @@ func (v *Int) Val() int { return int(atomic.LoadInt64(&v.value)) } -// Add atomically adds to t.value and returns the new value. +// Add atomically adds `delta` to t.value and returns the new value. func (v *Int) Add(delta int) (new int) { return int(atomic.AddInt64(&v.value, int64(delta))) } @@ -69,7 +69,7 @@ func (v *Int) UnmarshalJSON(b []byte) error { return nil } -// UnmarshalValue is an interface implement which sets any type of value for . +// UnmarshalValue is an interface implement which sets any type of value for `v`. func (v *Int) UnmarshalValue(value interface{}) error { v.Set(gconv.Int(value)) return nil diff --git a/container/gtype/int32.go b/container/gtype/gtype_int32.go similarity index 91% rename from container/gtype/int32.go rename to container/gtype/gtype_int32.go index 07ac0acf3..7c74a5b95 100644 --- a/container/gtype/int32.go +++ b/container/gtype/gtype_int32.go @@ -18,7 +18,7 @@ type Int32 struct { } // NewInt32 creates and returns a concurrent-safe object for int32 type, -// with given initial value . +// with given initial value `value`. func NewInt32(value ...int32) *Int32 { if len(value) > 0 { return &Int32{ @@ -33,7 +33,7 @@ func (v *Int32) Clone() *Int32 { return NewInt32(v.Val()) } -// Set atomically stores into t.value and returns the previous value of t.value. +// Set atomically stores `value` into t.value and returns the previous value of t.value. func (v *Int32) Set(value int32) (old int32) { return atomic.SwapInt32(&v.value, value) } @@ -43,7 +43,7 @@ func (v *Int32) Val() int32 { return atomic.LoadInt32(&v.value) } -// Add atomically adds to t.value and returns the new value. +// Add atomically adds `delta` to t.value and returns the new value. func (v *Int32) Add(delta int32) (new int32) { return atomic.AddInt32(&v.value, delta) } @@ -69,7 +69,7 @@ func (v *Int32) UnmarshalJSON(b []byte) error { return nil } -// UnmarshalValue is an interface implement which sets any type of value for . +// UnmarshalValue is an interface implement which sets any type of value for `v`. func (v *Int32) UnmarshalValue(value interface{}) error { v.Set(gconv.Int32(value)) return nil diff --git a/container/gtype/int64.go b/container/gtype/gtype_int64.go similarity index 91% rename from container/gtype/int64.go rename to container/gtype/gtype_int64.go index ed2a65d06..92610455c 100644 --- a/container/gtype/int64.go +++ b/container/gtype/gtype_int64.go @@ -18,7 +18,7 @@ type Int64 struct { } // NewInt64 creates and returns a concurrent-safe object for int64 type, -// with given initial value . +// with given initial value `value`. func NewInt64(value ...int64) *Int64 { if len(value) > 0 { return &Int64{ @@ -33,7 +33,7 @@ func (v *Int64) Clone() *Int64 { return NewInt64(v.Val()) } -// Set atomically stores into t.value and returns the previous value of t.value. +// Set atomically stores `value` into t.value and returns the previous value of t.value. func (v *Int64) Set(value int64) (old int64) { return atomic.SwapInt64(&v.value, value) } @@ -43,7 +43,7 @@ func (v *Int64) Val() int64 { return atomic.LoadInt64(&v.value) } -// Add atomically adds to t.value and returns the new value. +// Add atomically adds `delta` to t.value and returns the new value. func (v *Int64) Add(delta int64) (new int64) { return atomic.AddInt64(&v.value, delta) } @@ -69,7 +69,7 @@ func (v *Int64) UnmarshalJSON(b []byte) error { return nil } -// UnmarshalValue is an interface implement which sets any type of value for . +// UnmarshalValue is an interface implement which sets any type of value for `v`. func (v *Int64) UnmarshalValue(value interface{}) error { v.Set(gconv.Int64(value)) return nil diff --git a/container/gtype/interface.go b/container/gtype/gtype_interface.go similarity index 91% rename from container/gtype/interface.go rename to container/gtype/gtype_interface.go index 8cd554dde..a58ba9031 100644 --- a/container/gtype/interface.go +++ b/container/gtype/gtype_interface.go @@ -18,7 +18,7 @@ type Interface struct { } // NewInterface creates and returns a concurrent-safe object for interface{} type, -// with given initial value . +// with given initial value `value`. func NewInterface(value ...interface{}) *Interface { t := &Interface{} if len(value) > 0 && value[0] != nil { @@ -32,8 +32,8 @@ func (v *Interface) Clone() *Interface { return NewInterface(v.Val()) } -// Set atomically stores into t.value and returns the previous value of t.value. -// Note: The parameter cannot be nil. +// Set atomically stores `value` into t.value and returns the previous value of t.value. +// Note: The parameter `value` cannot be nil. func (v *Interface) Set(value interface{}) (old interface{}) { old = v.Val() v.value.Store(value) @@ -66,7 +66,7 @@ func (v *Interface) UnmarshalJSON(b []byte) error { return nil } -// UnmarshalValue is an interface implement which sets any type of value for . +// UnmarshalValue is an interface implement which sets any type of value for `v`. func (v *Interface) UnmarshalValue(value interface{}) error { v.Set(value) return nil diff --git a/container/gtype/string.go b/container/gtype/gtype_string.go similarity index 93% rename from container/gtype/string.go rename to container/gtype/gtype_string.go index f0b89f4ca..02803a09c 100644 --- a/container/gtype/string.go +++ b/container/gtype/gtype_string.go @@ -18,7 +18,7 @@ type String struct { } // NewString creates and returns a concurrent-safe object for string type, -// with given initial value . +// with given initial value `value`. func NewString(value ...string) *String { t := &String{} if len(value) > 0 { @@ -32,7 +32,7 @@ func (v *String) Clone() *String { return NewString(v.Val()) } -// Set atomically stores into t.value and returns the previous value of t.value. +// Set atomically stores `value` into t.value and returns the previous value of t.value. func (v *String) Set(value string) (old string) { old = v.Val() v.value.Store(value) @@ -64,7 +64,7 @@ func (v *String) UnmarshalJSON(b []byte) error { return nil } -// UnmarshalValue is an interface implement which sets any type of value for . +// UnmarshalValue is an interface implement which sets any type of value for `v`. func (v *String) UnmarshalValue(value interface{}) error { v.Set(gconv.String(value)) return nil diff --git a/container/gtype/uint.go b/container/gtype/gtype_uint.go similarity index 91% rename from container/gtype/uint.go rename to container/gtype/gtype_uint.go index a6e35996f..613e09488 100644 --- a/container/gtype/uint.go +++ b/container/gtype/gtype_uint.go @@ -18,7 +18,7 @@ type Uint struct { } // NewUint creates and returns a concurrent-safe object for uint type, -// with given initial value . +// with given initial value `value`. func NewUint(value ...uint) *Uint { if len(value) > 0 { return &Uint{ @@ -33,7 +33,7 @@ func (v *Uint) Clone() *Uint { return NewUint(v.Val()) } -// Set atomically stores into t.value and returns the previous value of t.value. +// Set atomically stores `value` into t.value and returns the previous value of t.value. func (v *Uint) Set(value uint) (old uint) { return uint(atomic.SwapUint64(&v.value, uint64(value))) } @@ -43,7 +43,7 @@ func (v *Uint) Val() uint { return uint(atomic.LoadUint64(&v.value)) } -// Add atomically adds to t.value and returns the new value. +// Add atomically adds `delta` to t.value and returns the new value. func (v *Uint) Add(delta uint) (new uint) { return uint(atomic.AddUint64(&v.value, uint64(delta))) } @@ -69,7 +69,7 @@ func (v *Uint) UnmarshalJSON(b []byte) error { return nil } -// UnmarshalValue is an interface implement which sets any type of value for . +// UnmarshalValue is an interface implement which sets any type of value for `v`. func (v *Uint) UnmarshalValue(value interface{}) error { v.Set(gconv.Uint(value)) return nil diff --git a/container/gtype/uint32.go b/container/gtype/gtype_uint32.go similarity index 91% rename from container/gtype/uint32.go rename to container/gtype/gtype_uint32.go index d1f4ea736..d42133d75 100644 --- a/container/gtype/uint32.go +++ b/container/gtype/gtype_uint32.go @@ -18,7 +18,7 @@ type Uint32 struct { } // NewUint32 creates and returns a concurrent-safe object for uint32 type, -// with given initial value . +// with given initial value `value`. func NewUint32(value ...uint32) *Uint32 { if len(value) > 0 { return &Uint32{ @@ -33,7 +33,7 @@ func (v *Uint32) Clone() *Uint32 { return NewUint32(v.Val()) } -// Set atomically stores into t.value and returns the previous value of t.value. +// Set atomically stores `value` into t.value and returns the previous value of t.value. func (v *Uint32) Set(value uint32) (old uint32) { return atomic.SwapUint32(&v.value, value) } @@ -43,7 +43,7 @@ func (v *Uint32) Val() uint32 { return atomic.LoadUint32(&v.value) } -// Add atomically adds to t.value and returns the new value. +// Add atomically adds `delta` to t.value and returns the new value. func (v *Uint32) Add(delta uint32) (new uint32) { return atomic.AddUint32(&v.value, delta) } @@ -69,7 +69,7 @@ func (v *Uint32) UnmarshalJSON(b []byte) error { return nil } -// UnmarshalValue is an interface implement which sets any type of value for . +// UnmarshalValue is an interface implement which sets any type of value for `v`. func (v *Uint32) UnmarshalValue(value interface{}) error { v.Set(gconv.Uint32(value)) return nil diff --git a/container/gtype/uint64.go b/container/gtype/gtype_uint64.go similarity index 91% rename from container/gtype/uint64.go rename to container/gtype/gtype_uint64.go index 7791eeac3..01a4a3346 100644 --- a/container/gtype/uint64.go +++ b/container/gtype/gtype_uint64.go @@ -18,7 +18,7 @@ type Uint64 struct { } // NewUint64 creates and returns a concurrent-safe object for uint64 type, -// with given initial value . +// with given initial value `value`. func NewUint64(value ...uint64) *Uint64 { if len(value) > 0 { return &Uint64{ @@ -33,7 +33,7 @@ func (v *Uint64) Clone() *Uint64 { return NewUint64(v.Val()) } -// Set atomically stores into t.value and returns the previous value of t.value. +// Set atomically stores `value` into t.value and returns the previous value of t.value. func (v *Uint64) Set(value uint64) (old uint64) { return atomic.SwapUint64(&v.value, value) } @@ -43,7 +43,7 @@ func (v *Uint64) Val() uint64 { return atomic.LoadUint64(&v.value) } -// Add atomically adds to t.value and returns the new value. +// Add atomically adds `delta` to t.value and returns the new value. func (v *Uint64) Add(delta uint64) (new uint64) { return atomic.AddUint64(&v.value, delta) } @@ -69,7 +69,7 @@ func (v *Uint64) UnmarshalJSON(b []byte) error { return nil } -// UnmarshalValue is an interface implement which sets any type of value for . +// UnmarshalValue is an interface implement which sets any type of value for `v`. func (v *Uint64) UnmarshalValue(value interface{}) error { v.Set(gconv.Uint64(value)) return nil diff --git a/container/gtype/z_bench_basic_test.go b/container/gtype/gtype_z_bench_basic_test.go similarity index 100% rename from container/gtype/z_bench_basic_test.go rename to container/gtype/gtype_z_bench_basic_test.go diff --git a/container/gtype/z_bench_json_test.go b/container/gtype/gtype_z_bench_json_test.go similarity index 100% rename from container/gtype/z_bench_json_test.go rename to container/gtype/gtype_z_bench_json_test.go diff --git a/container/gtype/z_unit_bool_test.go b/container/gtype/gtype_z_unit_bool_test.go similarity index 100% rename from container/gtype/z_unit_bool_test.go rename to container/gtype/gtype_z_unit_bool_test.go diff --git a/container/gtype/z_unit_byte_test.go b/container/gtype/gtype_z_unit_byte_test.go similarity index 100% rename from container/gtype/z_unit_byte_test.go rename to container/gtype/gtype_z_unit_byte_test.go diff --git a/container/gtype/z_unit_bytes_test.go b/container/gtype/gtype_z_unit_bytes_test.go similarity index 100% rename from container/gtype/z_unit_bytes_test.go rename to container/gtype/gtype_z_unit_bytes_test.go diff --git a/container/gtype/z_unit_float32_test.go b/container/gtype/gtype_z_unit_float32_test.go similarity index 100% rename from container/gtype/z_unit_float32_test.go rename to container/gtype/gtype_z_unit_float32_test.go diff --git a/container/gtype/z_unit_float64_test.go b/container/gtype/gtype_z_unit_float64_test.go similarity index 100% rename from container/gtype/z_unit_float64_test.go rename to container/gtype/gtype_z_unit_float64_test.go diff --git a/container/gtype/z_unit_int32_test.go b/container/gtype/gtype_z_unit_int32_test.go similarity index 100% rename from container/gtype/z_unit_int32_test.go rename to container/gtype/gtype_z_unit_int32_test.go diff --git a/container/gtype/z_unit_int64_test.go b/container/gtype/gtype_z_unit_int64_test.go similarity index 100% rename from container/gtype/z_unit_int64_test.go rename to container/gtype/gtype_z_unit_int64_test.go diff --git a/container/gtype/z_unit_int_test.go b/container/gtype/gtype_z_unit_int_test.go similarity index 100% rename from container/gtype/z_unit_int_test.go rename to container/gtype/gtype_z_unit_int_test.go diff --git a/container/gtype/z_unit_interface_test.go b/container/gtype/gtype_z_unit_interface_test.go similarity index 100% rename from container/gtype/z_unit_interface_test.go rename to container/gtype/gtype_z_unit_interface_test.go diff --git a/container/gtype/z_unit_string_test.go b/container/gtype/gtype_z_unit_string_test.go similarity index 100% rename from container/gtype/z_unit_string_test.go rename to container/gtype/gtype_z_unit_string_test.go diff --git a/container/gtype/z_unit_uint32_test.go b/container/gtype/gtype_z_unit_uint32_test.go similarity index 100% rename from container/gtype/z_unit_uint32_test.go rename to container/gtype/gtype_z_unit_uint32_test.go diff --git a/container/gtype/z_unit_uint64_test.go b/container/gtype/gtype_z_unit_uint64_test.go similarity index 100% rename from container/gtype/z_unit_uint64_test.go rename to container/gtype/gtype_z_unit_uint64_test.go diff --git a/container/gtype/z_unit_uint_test.go b/container/gtype/gtype_z_unit_uint_test.go similarity index 100% rename from container/gtype/z_unit_uint_test.go rename to container/gtype/gtype_z_unit_uint_test.go diff --git a/crypto/gaes/gaes.go b/crypto/gaes/gaes.go index 43bc0600a..4048311f4 100644 --- a/crypto/gaes/gaes.go +++ b/crypto/gaes/gaes.go @@ -31,9 +31,9 @@ func Decrypt(cipherText []byte, key []byte, iv ...[]byte) ([]byte, error) { return DecryptCBC(cipherText, key, iv...) } -// EncryptCBC encrypts

using CBC mode. +// EncryptCBC encrypts `plainText` using CBC mode. // Note that the key must be 16/24/32 bit length. -// The parameter <iv> initialization vector is unnecessary. +// The parameter `iv` initialization vector is unnecessary. func EncryptCBC(plainText []byte, key []byte, iv ...[]byte) ([]byte, error) { block, err := aes.NewCipher(key) if err != nil { @@ -54,9 +54,9 @@ func EncryptCBC(plainText []byte, key []byte, iv ...[]byte) ([]byte, error) { return cipherText, nil } -// DecryptCBC decrypts <cipherText> using CBC mode. +// DecryptCBC decrypts `cipherText` using CBC mode. // Note that the key must be 16/24/32 bit length. -// The parameter <iv> initialization vector is unnecessary. +// The parameter `iv` initialization vector is unnecessary. func DecryptCBC(cipherText []byte, key []byte, iv ...[]byte) ([]byte, error) { block, err := aes.NewCipher(key) if err != nil { @@ -116,9 +116,9 @@ func PKCS5UnPadding(src []byte, blockSize int) ([]byte, error) { return src[:(length - unpadding)], nil } -// EncryptCFB encrypts <plainText> using CFB mode. +// EncryptCFB encrypts `plainText` using CFB mode. // Note that the key must be 16/24/32 bit length. -// The parameter <iv> initialization vector is unnecessary. +// The parameter `iv` initialization vector is unnecessary. func EncryptCFB(plainText []byte, key []byte, padding *int, iv ...[]byte) ([]byte, error) { block, err := aes.NewCipher(key) if err != nil { @@ -138,9 +138,9 @@ func EncryptCFB(plainText []byte, key []byte, padding *int, iv ...[]byte) ([]byt return cipherText, nil } -// DecryptCFB decrypts <plainText> using CFB mode. +// DecryptCFB decrypts `plainText` using CFB mode. // Note that the key must be 16/24/32 bit length. -// The parameter <iv> initialization vector is unnecessary. +// The parameter `iv` initialization vector is unnecessary. func DecryptCFB(cipherText []byte, key []byte, unPadding int, iv ...[]byte) ([]byte, error) { block, err := aes.NewCipher(key) if err != nil { diff --git a/crypto/gcrc32/gcrc32.go b/crypto/gcrc32/gcrc32.go index 59b193bd2..64ed4f4a4 100644 --- a/crypto/gcrc32/gcrc32.go +++ b/crypto/gcrc32/gcrc32.go @@ -14,7 +14,7 @@ import ( ) // Encrypt encrypts any type of variable using CRC32 algorithms. -// It uses gconv package to convert <v> to its bytes type. +// It uses gconv package to convert `v` to its bytes type. func Encrypt(v interface{}) uint32 { return crc32.ChecksumIEEE(gconv.Bytes(v)) } diff --git a/crypto/gdes/gdes.go b/crypto/gdes/gdes.go index 8b00e1a7c..ff7a358e2 100644 --- a/crypto/gdes/gdes.go +++ b/crypto/gdes/gdes.go @@ -20,7 +20,7 @@ const ( PKCS5PADDING ) -// EncryptECB encrypts <plainText> using ECB mode. +// EncryptECB encrypts `plainText` using ECB mode. func EncryptECB(plainText []byte, key []byte, padding int) ([]byte, error) { text, err := Padding(plainText, padding) if err != nil { @@ -42,7 +42,7 @@ func EncryptECB(plainText []byte, key []byte, padding int) ([]byte, error) { return cipherText, nil } -// DecryptECB decrypts <cipherText> using ECB mode. +// DecryptECB decrypts `cipherText` using ECB mode. func DecryptECB(cipherText []byte, key []byte, padding int) ([]byte, error) { text := make([]byte, len(cipherText)) block, err := des.NewCipher(key) @@ -63,8 +63,8 @@ func DecryptECB(cipherText []byte, key []byte, padding int) ([]byte, error) { return plainText, nil } -// EncryptECBTriple encrypts <plainText> using TripleDES and ECB mode. -// The length of the <key> should be either 16 or 24 bytes. +// EncryptECBTriple encrypts `plainText` using TripleDES and ECB mode. +// The length of the `key` should be either 16 or 24 bytes. func EncryptECBTriple(plainText []byte, key []byte, padding int) ([]byte, error) { if len(key) != 16 && len(key) != 24 { return nil, gerror.NewCode(gcode.CodeInvalidParameter, "key length error") @@ -97,8 +97,8 @@ func EncryptECBTriple(plainText []byte, key []byte, padding int) ([]byte, error) return cipherText, nil } -// DecryptECBTriple decrypts <cipherText> using TripleDES and ECB mode. -// The length of the <key> should be either 16 or 24 bytes. +// DecryptECBTriple decrypts `cipherText` using TripleDES and ECB mode. +// The length of the `key` should be either 16 or 24 bytes. func DecryptECBTriple(cipherText []byte, key []byte, padding int) ([]byte, error) { if len(key) != 16 && len(key) != 24 { return nil, gerror.NewCode(gcode.CodeInvalidParameter, "key length error") @@ -131,7 +131,7 @@ func DecryptECBTriple(cipherText []byte, key []byte, padding int) ([]byte, error return plainText, nil } -// EncryptCBC encrypts <plainText> using CBC mode. +// EncryptCBC encrypts `plainText` using CBC mode. func EncryptCBC(plainText []byte, key []byte, iv []byte, padding int) ([]byte, error) { block, err := des.NewCipher(key) if err != nil { @@ -154,7 +154,7 @@ func EncryptCBC(plainText []byte, key []byte, iv []byte, padding int) ([]byte, e return cipherText, nil } -// DecryptCBC decrypts <cipherText> using CBC mode. +// DecryptCBC decrypts `cipherText` using CBC mode. func DecryptCBC(cipherText []byte, key []byte, iv []byte, padding int) ([]byte, error) { block, err := des.NewCipher(key) if err != nil { @@ -177,7 +177,7 @@ func DecryptCBC(cipherText []byte, key []byte, iv []byte, padding int) ([]byte, return plainText, nil } -// EncryptCBCTriple encrypts <plainText> using TripleDES and CBC mode. +// EncryptCBCTriple encrypts `plainText` using TripleDES and CBC mode. func EncryptCBCTriple(plainText []byte, key []byte, iv []byte, padding int) ([]byte, error) { if len(key) != 16 && len(key) != 24 { return nil, gerror.NewCode(gcode.CodeInvalidParameter, "key length invalid") @@ -212,7 +212,7 @@ func EncryptCBCTriple(plainText []byte, key []byte, iv []byte, padding int) ([]b return cipherText, nil } -// DecryptCBCTriple decrypts <cipherText> using TripleDES and CBC mode. +// DecryptCBCTriple decrypts `cipherText` using TripleDES and CBC mode. func DecryptCBCTriple(cipherText []byte, key []byte, iv []byte, padding int) ([]byte, error) { if len(key) != 16 && len(key) != 24 { return nil, gerror.NewCode(gcode.CodeInvalidParameter, "key length invalid") diff --git a/crypto/gmd5/gmd5.go b/crypto/gmd5/gmd5.go index ab16f1cf7..9f35b87d5 100644 --- a/crypto/gmd5/gmd5.go +++ b/crypto/gmd5/gmd5.go @@ -17,13 +17,13 @@ import ( ) // Encrypt encrypts any type of variable using MD5 algorithms. -// It uses gconv package to convert <v> to its bytes type. +// It uses gconv package to convert `v` to its bytes type. func Encrypt(data interface{}) (encrypt string, err error) { return EncryptBytes(gconv.Bytes(data)) } // MustEncrypt encrypts any type of variable using MD5 algorithms. -// It uses gconv package to convert <v> to its bytes type. +// It uses gconv package to convert `v` to its bytes type. // It panics if any error occurs. func MustEncrypt(data interface{}) string { result, err := Encrypt(data) @@ -33,7 +33,7 @@ func MustEncrypt(data interface{}) string { return result } -// EncryptBytes encrypts <data> using MD5 algorithms. +// EncryptBytes encrypts `data` using MD5 algorithms. func EncryptBytes(data []byte) (encrypt string, err error) { h := md5.New() if _, err = h.Write([]byte(data)); err != nil { @@ -42,7 +42,7 @@ func EncryptBytes(data []byte) (encrypt string, err error) { return fmt.Sprintf("%x", h.Sum(nil)), nil } -// MustEncryptBytes encrypts <data> using MD5 algorithms. +// MustEncryptBytes encrypts `data` using MD5 algorithms. // It panics if any error occurs. func MustEncryptBytes(data []byte) string { result, err := EncryptBytes(data) @@ -52,12 +52,12 @@ func MustEncryptBytes(data []byte) string { return result } -// EncryptBytes encrypts string <data> using MD5 algorithms. +// EncryptBytes encrypts string `data` using MD5 algorithms. func EncryptString(data string) (encrypt string, err error) { return EncryptBytes([]byte(data)) } -// MustEncryptString encrypts string <data> using MD5 algorithms. +// MustEncryptString encrypts string `data` using MD5 algorithms. // It panics if any error occurs. func MustEncryptString(data string) string { result, err := EncryptString(data) @@ -67,7 +67,7 @@ func MustEncryptString(data string) string { return result } -// EncryptFile encrypts file content of <path> using MD5 algorithms. +// EncryptFile encrypts file content of `path` using MD5 algorithms. func EncryptFile(path string) (encrypt string, err error) { f, err := os.Open(path) if err != nil { @@ -82,7 +82,7 @@ func EncryptFile(path string) (encrypt string, err error) { return fmt.Sprintf("%x", h.Sum(nil)), nil } -// MustEncryptFile encrypts file content of <path> using MD5 algorithms. +// MustEncryptFile encrypts file content of `path` using MD5 algorithms. // It panics if any error occurs. func MustEncryptFile(path string) string { result, err := EncryptFile(path) diff --git a/crypto/gsha1/gsha1.go b/crypto/gsha1/gsha1.go index 7f8b6347f..50beeeb58 100644 --- a/crypto/gsha1/gsha1.go +++ b/crypto/gsha1/gsha1.go @@ -17,13 +17,13 @@ import ( ) // Encrypt encrypts any type of variable using SHA1 algorithms. -// It uses gconv package to convert <v> to its bytes type. +// It uses package gconv to convert `v` to its bytes type. func Encrypt(v interface{}) string { r := sha1.Sum(gconv.Bytes(v)) return hex.EncodeToString(r[:]) } -// EncryptFile encrypts file content of <path> using SHA1 algorithms. +// EncryptFile encrypts file content of `path` using SHA1 algorithms. func EncryptFile(path string) (encrypt string, err error) { f, err := os.Open(path) if err != nil { @@ -38,7 +38,7 @@ func EncryptFile(path string) (encrypt string, err error) { return hex.EncodeToString(h.Sum(nil)), nil } -// MustEncryptFile encrypts file content of <path> using SHA1 algorithms. +// MustEncryptFile encrypts file content of `path` using SHA1 algorithms. // It panics if any error occurs. func MustEncryptFile(path string) string { result, err := EncryptFile(path) diff --git a/database/gredis/gredis.go b/database/gredis/gredis.go index 8de774e15..4bd6f3702 100644 --- a/database/gredis/gredis.go +++ b/database/gredis/gredis.go @@ -140,7 +140,7 @@ func New(config *Config) *Redis { // NewFromStr creates a redis client object with given configuration string. // Redis client maintains a connection pool automatically. -// The parameter <str> like: +// The parameter `str` like: // 127.0.0.1:6379,0 // 127.0.0.1:6379,0,password func NewFromStr(str string) (*Redis, error) { diff --git a/database/gredis/gredis_config.go b/database/gredis/gredis_config.go index e6fcae37e..310c113da 100644 --- a/database/gredis/gredis_config.go +++ b/database/gredis/gredis_config.go @@ -29,7 +29,7 @@ var ( ) // SetConfig sets the global configuration for specified group. -// If <name> is not passed, it sets configuration for the default group name. +// If `name` is not passed, it sets configuration for the default group name. func SetConfig(config *Config, name ...string) { group := DefaultGroupName if len(name) > 0 { @@ -42,7 +42,7 @@ func SetConfig(config *Config, name ...string) { } // SetConfigByStr sets the global configuration for specified group with string. -// If <name> is not passed, it sets configuration for the default group name. +// If `name` is not passed, it sets configuration for the default group name. func SetConfigByStr(str string, name ...string) error { group := DefaultGroupName if len(name) > 0 { @@ -58,7 +58,7 @@ func SetConfigByStr(str string, name ...string) error { } // GetConfig returns the global configuration with specified group name. -// If <name> is not passed, it returns configuration of the default group name. +// If `name` is not passed, it returns configuration of the default group name. func GetConfig(name ...string) (config *Config, ok bool) { group := DefaultGroupName if len(name) > 0 { @@ -71,7 +71,7 @@ func GetConfig(name ...string) (config *Config, ok bool) { } // RemoveConfig removes the global configuration with specified group. -// If <name> is not passed, it removes configuration of the default group name. +// If `name` is not passed, it removes configuration of the default group name. func RemoveConfig(name ...string) { group := DefaultGroupName if len(name) > 0 { diff --git a/database/gredis/gredis_instance.go b/database/gredis/gredis_instance.go index 4a5afcd25..9e8049180 100644 --- a/database/gredis/gredis_instance.go +++ b/database/gredis/gredis_instance.go @@ -14,7 +14,7 @@ var ( ) // Instance returns an instance of redis client with specified group. -// The <name> param is unnecessary, if <name> is not passed, +// The <name> param is unnecessary, if `name` is not passed, // it returns a redis instance with default configuration group. func Instance(name ...string) *Redis { group := DefaultGroupName diff --git a/errors/gerror/gerror.go b/errors/gerror/gerror.go index 8249dddcd..4a607ae99 100644 --- a/errors/gerror/gerror.go +++ b/errors/gerror/gerror.go @@ -64,7 +64,7 @@ func Newf(format string, args ...interface{}) error { } // NewSkip creates and returns an error which is formatted from given text. -// The parameter <skip> specifies the stack callers skipped amount. +// The parameter `skip` specifies the stack callers skipped amount. func NewSkip(skip int, text string) error { return &Error{ stack: callers(skip), @@ -74,7 +74,7 @@ func NewSkip(skip int, text string) error { } // NewSkipf returns an error that formats as the given format and args. -// The parameter <skip> specifies the stack callers skipped amount. +// The parameter `skip` specifies the stack callers skipped amount. func NewSkipf(skip int, format string, args ...interface{}) error { return &Error{ stack: callers(skip), @@ -99,7 +99,7 @@ func Wrap(err error, text string) error { // Wrapf returns an error annotating err with a stack trace // at the point Wrapf is called, and the format specifier. -// It returns nil if given <err> is nil. +// It returns nil if given `err` is nil. func Wrapf(err error, format string, args ...interface{}) error { if err == nil { return nil @@ -114,7 +114,7 @@ func Wrapf(err error, format string, args ...interface{}) error { // WrapSkip wraps error with text. // It returns nil if given err is nil. -// The parameter <skip> specifies the stack callers skipped amount. +// The parameter `skip` specifies the stack callers skipped amount. func WrapSkip(skip int, err error, text string) error { if err == nil { return nil @@ -129,7 +129,7 @@ func WrapSkip(skip int, err error, text string) error { // WrapSkipf wraps error with text that is formatted with given format and args. // It returns nil if given err is nil. -// The parameter <skip> specifies the stack callers skipped amount. +// The parameter `skip` specifies the stack callers skipped amount. func WrapSkipf(skip int, err error, format string, args ...interface{}) error { if err == nil { return nil @@ -165,7 +165,7 @@ func NewCodef(code gcode.Code, format string, args ...interface{}) error { } // NewCodeSkip creates and returns an error which has error code and is formatted from given text. -// The parameter <skip> specifies the stack callers skipped amount. +// The parameter `skip` specifies the stack callers skipped amount. func NewCodeSkip(code gcode.Code, skip int, text ...string) error { errText := "" if len(text) > 0 { @@ -179,7 +179,7 @@ func NewCodeSkip(code gcode.Code, skip int, text ...string) error { } // NewCodeSkipf returns an error that has error code and formats as the given format and args. -// The parameter <skip> specifies the stack callers skipped amount. +// The parameter `skip` specifies the stack callers skipped amount. func NewCodeSkipf(code gcode.Code, skip int, format string, args ...interface{}) error { return &Error{ stack: callers(skip), @@ -207,7 +207,7 @@ func WrapCode(code gcode.Code, err error, text ...string) error { } // WrapCodef wraps error with code and format specifier. -// It returns nil if given <err> is nil. +// It returns nil if given `err` is nil. func WrapCodef(code gcode.Code, err error, format string, args ...interface{}) error { if err == nil { return nil @@ -222,7 +222,7 @@ func WrapCodef(code gcode.Code, err error, format string, args ...interface{}) e // WrapCodeSkip wraps error with code and text. // It returns nil if given err is nil. -// The parameter <skip> specifies the stack callers skipped amount. +// The parameter `skip` specifies the stack callers skipped amount. func WrapCodeSkip(code gcode.Code, skip int, err error, text ...string) error { if err == nil { return nil @@ -241,7 +241,7 @@ func WrapCodeSkip(code gcode.Code, skip int, err error, text ...string) error { // WrapCodeSkipf wraps error with code and text that is formatted with given format and args. // It returns nil if given err is nil. -// The parameter <skip> specifies the stack callers skipped amount. +// The parameter `skip` specifies the stack callers skipped amount. func WrapCodeSkipf(code gcode.Code, skip int, err error, format string, args ...interface{}) error { if err == nil { return nil @@ -265,7 +265,7 @@ func Code(err error) gcode.Code { return gcode.CodeNil } -// Cause returns the root cause error of <err>. +// Cause returns the root cause error of `err`. func Cause(err error) error { if err != nil { if e, ok := err.(apiCause); ok { @@ -276,7 +276,7 @@ func Cause(err error) error { } // Stack returns the stack callers as string. -// It returns the error string directly if the <err> does not support stacks. +// It returns the error string directly if the `err` does not support stacks. func Stack(err error) string { if err == nil { return "" diff --git a/errors/gerror/gerror_error.go b/errors/gerror/gerror_error.go index bbc00bdf1..602005461 100644 --- a/errors/gerror/gerror_error.go +++ b/errors/gerror/gerror_error.go @@ -124,7 +124,7 @@ func (err *Error) Format(s fmt.State, verb rune) { } // Stack returns the stack callers as string. -// It returns an empty string if the <err> does not support stacks. +// It returns an empty string if the `err` does not support stacks. func (err *Error) Stack() string { if err == nil { return "" @@ -202,7 +202,7 @@ func formatSubStack(st stack, buffer *bytes.Buffer) { continue } } - // Avoid stack string like "<autogenerated>" + // Avoid stack string like "`autogenerated`" if strings.Contains(file, "<") { continue } diff --git a/frame/g/g_func.go b/frame/g/g_func.go index 5034a8f08..10981ea8d 100644 --- a/frame/g/g_func.go +++ b/frame/g/g_func.go @@ -21,7 +21,7 @@ func NewVar(i interface{}, safe ...bool) *Var { } // Wait is an alias of ghttp.Wait, which blocks until all the web servers shutdown. -// It's commonly used in multiple servers situation. +// It's commonly used in multiple servers' situation. func Wait() { ghttp.Wait() } @@ -43,8 +43,7 @@ func Export(i ...interface{}) string { return gutil.Export(i...) } -// Throw throws a exception, which can be caught by TryCatch function. -// It always be used in TryCatch function. +// Throw throws an exception, which can be caught by TryCatch function. func Throw(exception interface{}) { gutil.Throw(exception) } @@ -56,22 +55,22 @@ func Try(try func()) (err error) { } // TryCatch implements try...catch... logistics using internal panic...recover. -// It automatically calls function <catch> if any exception occurs ans passes the exception as an error. +// It automatically calls function `catch` if any exception occurs ans passes the exception as an error. func TryCatch(try func(), catch ...func(exception error)) { gutil.TryCatch(try, catch...) } -// IsNil checks whether given <value> is nil. -// Parameter <traceSource> is used for tracing to the source variable if given <value> is type -// of a pinter that also points to a pointer. It returns nil if the source is nil when <traceSource> +// IsNil checks whether given `value` is nil. +// Parameter <traceSource> is used for tracing to the source variable if given `value` is type +// of pinter that also points to a pointer. It returns nil if the source is nil when `traceSource` // is true. -// Note that it might use reflect feature which affects performance a little bit. +// Note that it might use reflect feature which affects performance a little. func IsNil(value interface{}, traceSource ...bool) bool { return empty.IsNil(value, traceSource...) } -// IsEmpty checks whether given <value> empty. -// It returns true if <value> is in: 0, nil, false, "", len(slice/map/chan) == 0. +// IsEmpty checks whether given `value` empty. +// It returns true if `value` is in: 0, nil, false, "", len(slice/map/chan) == 0. // Or else it returns true. func IsEmpty(value interface{}) bool { return empty.IsEmpty(value) diff --git a/frame/g/g_object.go b/frame/g/g_object.go index c75247b57..4776fd9f9 100644 --- a/frame/g/g_object.go +++ b/frame/g/g_object.go @@ -58,13 +58,13 @@ func Cfg(name ...string) *gcfg.Config { } // Resource returns an instance of Resource. -// The parameter <name> is the name for the instance. +// The parameter `name` is the name for the instance. func Resource(name ...string) *gres.Resource { return gins.Resource(name...) } // I18n returns an instance of gi18n.Manager. -// The parameter <name> is the name for the instance. +// The parameter `name` is the name for the instance. func I18n(name ...string) *gi18n.Manager { return gins.I18n(name...) } @@ -76,7 +76,7 @@ func Res(name ...string) *gres.Resource { } // Log returns an instance of glog.Logger. -// The parameter <name> is the name for the instance. +// The parameter `name` is the name for the instance. func Log(name ...string) *glog.Logger { return gins.Log(name...) } diff --git a/frame/gins/gins.go b/frame/gins/gins.go index af822b0f6..719cf9bba 100644 --- a/frame/gins/gins.go +++ b/frame/gins/gins.go @@ -33,24 +33,24 @@ func GetOrSet(name string, instance interface{}) interface{} { } // GetOrSetFunc returns the instance by name, -// or sets instance with returned value of callback function <f> if it does not exist +// or sets instance with returned value of callback function `f` if it does not exist // and then returns this instance. func GetOrSetFunc(name string, f func() interface{}) interface{} { return instances.GetOrSetFunc(name, f) } // GetOrSetFuncLock returns the instance by name, -// or sets instance with returned value of callback function <f> if it does not exist +// or sets instance with returned value of callback function `f` if it does not exist // and then returns this instance. // -// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function <f> +// GetOrSetFuncLock differs with GetOrSetFunc function is that it executes function `f` // with mutex.Lock of the hash map. func GetOrSetFuncLock(name string, f func() interface{}) interface{} { return instances.GetOrSetFuncLock(name, f) } -// SetIfNotExist sets <instance> to the map if the <name> does not exist, then returns true. -// It returns false if <name> exists, and <instance> would be ignored. +// SetIfNotExist sets <instance> to the map if the `name` does not exist, then returns true. +// It returns false if <name> exists, and `instance` would be ignored. func SetIfNotExist(name string, instance interface{}) bool { return instances.SetIfNotExist(name, instance) } diff --git a/frame/gins/gins_config.go b/frame/gins/gins_config.go index 38bca58b4..b6d0be9cf 100644 --- a/frame/gins/gins_config.go +++ b/frame/gins/gins_config.go @@ -11,7 +11,7 @@ import ( ) // Config returns an instance of View with default settings. -// The parameter <name> is the name for the instance. +// The parameter `name` is the name for the instance. func Config(name ...string) *gcfg.Config { return gcfg.Instance(name...) } diff --git a/frame/gins/gins_database.go b/frame/gins/gins_database.go index dfe83eae7..8d722a10d 100644 --- a/frame/gins/gins_database.go +++ b/frame/gins/gins_database.go @@ -77,7 +77,7 @@ func Database(name ...string) gdb.DB { if len(configMap) == 0 { configMap = make(map[string]interface{}) } - // Parse <m> as map-slice and adds it to gdb's global configurations. + // Parse `m` as map-slice and adds it to gdb's global configurations. for g, groupConfig := range configMap { cg := gdb.ConfigGroup{} switch value := groupConfig.(type) { @@ -102,7 +102,7 @@ func Database(name ...string) gdb.DB { } } } - // Parse <m> as a single node configuration, + // Parse `m` as a single node configuration, // which is the default group configuration. if node := parseDBConfigNode(configMap); node != nil { cg := gdb.ConfigGroup{} diff --git a/frame/gins/gins_i18n.go b/frame/gins/gins_i18n.go index 71b57b63a..110896b42 100644 --- a/frame/gins/gins_i18n.go +++ b/frame/gins/gins_i18n.go @@ -11,7 +11,7 @@ import ( ) // I18n returns an instance of gi18n.Manager. -// The parameter <name> is the name for the instance. +// The parameter `name` is the name for the instance. func I18n(name ...string) *gi18n.Manager { return gi18n.Instance(name...) } diff --git a/frame/gins/gins_log.go b/frame/gins/gins_log.go index 3ec6c691c..30018f031 100644 --- a/frame/gins/gins_log.go +++ b/frame/gins/gins_log.go @@ -18,7 +18,7 @@ const ( ) // Log returns an instance of glog.Logger. -// The parameter <name> is the name for the instance. +// The parameter `name` is the name for the instance. func Log(name ...string) *glog.Logger { instanceName := glog.DefaultName if len(name) > 0 && name[0] != "" { diff --git a/frame/gins/gins_resource.go b/frame/gins/gins_resource.go index fa97179fb..30f78ba00 100644 --- a/frame/gins/gins_resource.go +++ b/frame/gins/gins_resource.go @@ -11,7 +11,7 @@ import ( ) // Resource returns an instance of Resource. -// The parameter <name> is the name for the instance. +// The parameter `name` is the name for the instance. func Resource(name ...string) *gres.Resource { return gres.Instance(name...) } diff --git a/frame/gins/gins_view.go b/frame/gins/gins_view.go index ab49298fe..c67cef1ac 100644 --- a/frame/gins/gins_view.go +++ b/frame/gins/gins_view.go @@ -18,7 +18,7 @@ const ( ) // View returns an instance of View with default settings. -// The parameter <name> is the name for the instance. +// The parameter `name` is the name for the instance. func View(name ...string) *gview.View { instanceName := gview.DefaultName if len(name) > 0 && name[0] != "" { diff --git a/frame/gmvc/view.go b/frame/gmvc/view.go index 3f77dce2b..ff623aa60 100644 --- a/frame/gmvc/view.go +++ b/frame/gmvc/view.go @@ -53,7 +53,7 @@ func (view *View) Assign(key string, value interface{}) { view.mu.Unlock() } -// Parse parses given template file <tpl> with assigned template variables +// Parse parses given template file `tpl` with assigned template variables // and returns the parsed template content. func (view *View) Parse(file string) (string, error) { view.mu.RLock() @@ -62,7 +62,7 @@ func (view *View) Parse(file string) (string, error) { return buffer, err } -// ParseContent parses given template file <file> with assigned template variables +// ParseContent parses given template file `file` with assigned template variables // and returns the parsed template content. func (view *View) ParseContent(content string) (string, error) { view.mu.RLock() @@ -71,23 +71,23 @@ func (view *View) ParseContent(content string) (string, error) { return buffer, err } -// LockFunc locks writing for template variables by callback function <f>. +// LockFunc locks writing for template variables by callback function `f`. func (view *View) LockFunc(f func(data gview.Params)) { view.mu.Lock() defer view.mu.Unlock() f(view.data) } -// RLockFunc locks reading for template variables by callback function <f>. +// RLockFunc locks reading for template variables by callback function `f`. func (view *View) RLockFunc(f func(data gview.Params)) { view.mu.RLock() defer view.mu.RUnlock() f(view.data) } -// BindFunc registers customized template function named <name> -// with given function <function> to current view object. -// The <name> is the function name which can be called in template content. +// BindFunc registers customized template function named `name` +// with given function `function` to current view object. +// The `name` is the function name which can be called in template content. func (view *View) BindFunc(name string, function interface{}) { view.view.BindFunc(name, function) } diff --git a/net/gsmtp/gsmtp.go b/net/gsmtp/gsmtp.go index f52d1b5c8..a1096b2dc 100644 --- a/net/gsmtp/gsmtp.go +++ b/net/gsmtp/gsmtp.go @@ -20,7 +20,7 @@ import ( "strings" ) -// SMTP is the structure for smtp connection +// SMTP is the structure for smtp connection. type SMTP struct { Address string Username string @@ -42,7 +42,7 @@ var ( ) // SendMail connects to the server at addr, switches to TLS if -// possible, authenticates with the optional mechanism a if possible, +// possible, authenticates with the optional mechanism an if possible, // and then sends an email from address <from>, to addresses <to>, with // message msg. // diff --git a/os/gcache/gcache.go b/os/gcache/gcache.go index 8a0b1c07d..f4805fbad 100644 --- a/os/gcache/gcache.go +++ b/os/gcache/gcache.go @@ -5,6 +5,7 @@ // You can obtain one at https://github.com/gogf/gf. // Package gcache provides kinds of cache management for process. +// // It provides a concurrent-safe in-memory cache adapter for process in default. package gcache @@ -24,26 +25,60 @@ func Ctx(ctx context.Context) *Cache { } // Set sets cache with `key`-`value` pair, which is expired after `duration`. +// // It does not expire if `duration` == 0. +// It deletes the keys of `data` if `duration` < 0 or given `value` is nil. func Set(key interface{}, value interface{}, duration time.Duration) error { return defaultCache.Set(key, value, duration) } -// SetIfNotExist sets cache with `key`-`value` pair if `key` does not exist in the cache, -// which is expired after `duration`. It does not expire if `duration` == 0. -func SetIfNotExist(key interface{}, value interface{}, duration time.Duration) (bool, error) { - return defaultCache.SetIfNotExist(key, value, duration) -} - -// Sets batch sets cache with key-value pairs by `data`, which is expired after `duration`. +// Sets batch sets cache with key-value pairs by `data` map, which is expired after `duration`. // // It does not expire if `duration` == 0. +// It deletes the keys of `data` if `duration` < 0 or given `value` is nil. func Sets(data map[interface{}]interface{}, duration time.Duration) error { return defaultCache.Sets(data, duration) } -// Get returns the value of `key`. -// It returns nil if it does not exist or its value is nil. +// SetIfNotExist sets cache with `key`-`value` pair which is expired after `duration` +// if `key` does not exist in the cache. It returns true the `key` does not exist in the +// cache, and it sets `value` successfully to the cache, or else it returns false. +// +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil. +func SetIfNotExist(key interface{}, value interface{}, duration time.Duration) (bool, error) { + return defaultCache.SetIfNotExist(key, value, duration) +} + +// SetIfNotExistFunc sets `key` with result of function `f` and returns true +// if `key` does not exist in the cache, or else it does nothing and returns false if `key` already exists. +// +// The parameter `value` can be type of `func() interface{}`, but it does nothing if its +// result is nil. +// +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil. +func SetIfNotExistFunc(key interface{}, f func() (interface{}, error), duration time.Duration) (bool, error) { + return defaultCache.SetIfNotExistFunc(key, f, duration) +} + +// SetIfNotExistFuncLock sets `key` with result of function `f` and returns true +// if `key` does not exist in the cache, or else it does nothing and returns false if `key` already exists. +// +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil. +// +// Note that it differs from function `SetIfNotExistFunc` is that the function `f` is executed within +// writing mutex lock for concurrent safety purpose. +func SetIfNotExistFuncLock(key interface{}, f func() (interface{}, error), duration time.Duration) (bool, error) { + return defaultCache.SetIfNotExistFuncLock(key, f, duration) +} + +// Get retrieves and returns the associated value of given `key`. +// It returns nil if it does not exist, or its value is nil, or it's expired. +// If you would like to check if the `key` exists in the cache, it's better using function Contains. +// +// It is suggested using GetVar instead for compatibility of different adapters purpose. func Get(key interface{}) (interface{}, error) { return defaultCache.Get(key) } @@ -53,49 +88,130 @@ func GetVar(key interface{}) (*gvar.Var, error) { return defaultCache.GetVar(key) } -// GetOrSet returns the value of `key`, -// or sets `key`-`value` pair and returns `value` if `key` does not exist in the cache. -// The key-value pair expires after `duration`. +// GetOrSet retrieves and returns the value of `key`, or sets `key`-`value` pair and +// returns `value` if `key` does not exist in the cache. The key-value pair expires +// after `duration`. // // It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing +// if `value` is a function and the function result is nil. +// +// It is suggested using GetVarOrSet instead for compatibility of different adapters purpose. func GetOrSet(key interface{}, value interface{}, duration time.Duration) (interface{}, error) { return defaultCache.GetOrSet(key, value, duration) } -// GetOrSetFunc returns the value of `key`, or sets `key` with result of function `f` -// and returns its result if `key` does not exist in the cache. The key-value pair expires -// after `duration`. It does not expire if `duration` == 0. +// GetOrSetFunc retrieves and returns the value of `key`, or sets `key` with result of +// function `f` and returns its result if `key` does not exist in the cache. The key-value +// pair expires after `duration`. +// +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing +// if `value` is a function and the function result is nil. +// +// It is suggested using GetVarOrSetFunc instead for compatibility of different adapters purpose. func GetOrSetFunc(key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) { return defaultCache.GetOrSetFunc(key, f, duration) } -// GetOrSetFuncLock returns the value of `key`, or sets `key` with result of function `f` -// and returns its result if `key` does not exist in the cache. The key-value pair expires -// after `duration`. It does not expire if `duration` == 0. +// GetOrSetFuncLock retrieves and returns the value of `key`, or sets `key` with result of +// function `f` and returns its result if `key` does not exist in the cache. The key-value +// pair expires after `duration`. // -// Note that the function `f` is executed within writing mutex lock. +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing +// if `value` is a function and the function result is nil. +// +// Note that it differs from function `GetOrSetFunc` is that the function `f` is executed within +// writing mutex lock for concurrent safety purpose. +// +// It is suggested using GetVarOrSetFuncLock instead for compatibility of different adapters purpose. func GetOrSetFuncLock(key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) { return defaultCache.GetOrSetFuncLock(key, f, duration) } -// Contains returns true if `key` exists in the cache, or else returns false. +// GetVarOrSet acts as function GetOrSet except it returns value as type gvar.Var. +// Also see GetOrSet. +func GetVarOrSet(key interface{}, value interface{}, duration time.Duration) (*gvar.Var, error) { + return defaultCache.GetVarOrSet(key, value, duration) +} + +// GetVarOrSetFunc acts as function GetOrSetFunc except it returns value as type gvar.Var. +// Also see GetOrSetFunc. +func GetVarOrSetFunc(key interface{}, f func() (interface{}, error), duration time.Duration) (*gvar.Var, error) { + return defaultCache.GetVarOrSetFunc(key, f, duration) +} + +// GetVarOrSetFuncLock acts as function GetOrSetFuncLock except it returns value as type gvar.Var. +// Also see GetOrSetFuncLock. +func GetVarOrSetFuncLock(key interface{}, f func() (interface{}, error), duration time.Duration) (*gvar.Var, error) { + return defaultCache.GetVarOrSetFunc(key, f, duration) +} + +// Contains checks and returns true if `key` exists in the cache, or else returns false. func Contains(key interface{}) (bool, error) { return defaultCache.Contains(key) } -// Remove deletes the one or more keys from cache, and returns its value. -// If multiple keys are given, it returns the value of the deleted last item. +// GetExpire retrieves and returns the expiration of `key` in the cache. +// +// Note that, +// It returns 0 if the `key` does not expire. +// It returns -1 if the `key` does not exist in the cache. +func GetExpire(key interface{}) (time.Duration, error) { + return defaultCache.GetExpire(key) +} + +// Remove deletes one or more keys from cache, and returns its value. +// If multiple keys are given, it returns the value of the last deleted item. +// +// It is suggested using RemoveVar instead for compatibility of different adapters purpose. func Remove(keys ...interface{}) (value interface{}, err error) { return defaultCache.Remove(keys...) } +// RemoveVar acts as function Remove except it returns value as type gvar.Var. +// Also see Remove. +func RemoveVar(keys ...interface{}) (*gvar.Var, error) { + return defaultCache.RemoveVar(keys...) +} + // Removes deletes `keys` in the cache. -// Deprecated, use Remove instead. -func Removes(keys []interface{}) { - defaultCache.Remove(keys...) +func Removes(keys []interface{}) error { + return defaultCache.Removes(keys) +} + +// Update updates the value of `key` without changing its expiration and returns the old value. +// The returned value `exist` is false if the `key` does not exist in the cache. +// +// It deletes the `key` if given `value` is nil. +// It does nothing if `key` does not exist in the cache. +func Update(key interface{}, value interface{}) (oldValue interface{}, exist bool, err error) { + return defaultCache.Update(key, value) +} + +// UpdateVar acts as function Update except it returns value as type gvar.Var. +// Also see Update. +func UpdateVar(key interface{}, value interface{}) (oldValue *gvar.Var, exist bool, err error) { + return defaultCache.UpdateVar(key, value) +} + +// UpdateExpire updates the expiration of `key` and returns the old expiration duration value. +// +// It returns -1 and does nothing if the `key` does not exist in the cache. +// It deletes the `key` if `duration` < 0. +func UpdateExpire(key interface{}, duration time.Duration) (oldDuration time.Duration, err error) { + return defaultCache.UpdateExpire(key, duration) +} + +// Size returns the number of items in the cache. +func Size() (int, error) { + return defaultCache.Size() } // Data returns a copy of all key-value pairs in the cache as map type. +// Note that this function may lead lots of memory usage, you can implement this function +// if necessary. func Data() (map[interface{}]interface{}, error) { return defaultCache.Data() } @@ -114,26 +230,3 @@ func KeyStrings() ([]string, error) { func Values() ([]interface{}, error) { return defaultCache.Values() } - -// Size returns the size of the cache. -func Size() (int, error) { - return defaultCache.Size() -} - -// GetExpire retrieves and returns the expiration of `key`. -// It returns -1 if the `key` does not exist in the cache. -func GetExpire(key interface{}) (time.Duration, error) { - return defaultCache.GetExpire(key) -} - -// Update updates the value of `key` without changing its expiration and returns the old value. -// The returned `exist` value is false if the `key` does not exist in the cache. -func Update(key interface{}, value interface{}) (oldValue interface{}, exist bool, err error) { - return defaultCache.Update(key, value) -} - -// UpdateExpire updates the expiration of `key` and returns the old expiration duration value. -// It returns -1 if the `key` does not exist in the cache. -func UpdateExpire(key interface{}, duration time.Duration) (oldDuration time.Duration, err error) { - return defaultCache.UpdateExpire(key, duration) -} diff --git a/os/gcache/gcache_adapter.go b/os/gcache/gcache_adapter.go index 33f179058..d84a371e4 100644 --- a/os/gcache/gcache_adapter.go +++ b/os/gcache/gcache_adapter.go @@ -12,14 +12,18 @@ import ( ) // Adapter is the core adapter for cache features implements. +// +// Note that the implements should guarantee the concurrent safety calling its functions. +// You can implement one or more functions if necessary, it is suggested returning gcode.CodeNotImplemented error +// for those unimplemented functions. type Adapter interface { // Set sets cache with `key`-`value` pair, which is expired after `duration`. // // It does not expire if `duration` == 0. - // It deletes the `key` if `duration` < 0. + // It deletes the keys of `data` if `duration` < 0 or given `value` is nil. Set(ctx context.Context, key interface{}, value interface{}, duration time.Duration) error - // Sets batch sets cache with key-value pairs by `data`, which is expired after `duration`. + // Sets batch sets cache with key-value pairs by `data` map, which is expired after `duration`. // // It does not expire if `duration` == 0. // It deletes the keys of `data` if `duration` < 0 or given `value` is nil. @@ -29,15 +33,33 @@ type Adapter interface { // if `key` does not exist in the cache. It returns true the `key` does not exist in the // cache, and it sets `value` successfully to the cache, or else it returns false. // + // It does not expire if `duration` == 0. + // It deletes the `key` if `duration` < 0 or given `value` is nil. + SetIfNotExist(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (ok bool, err error) + + // SetIfNotExistFunc sets `key` with result of function `f` and returns true + // if `key` does not exist in the cache, or else it does nothing and returns false if `key` already exists. + // // The parameter `value` can be type of `func() interface{}`, but it does nothing if its // result is nil. // // It does not expire if `duration` == 0. // It deletes the `key` if `duration` < 0 or given `value` is nil. - SetIfNotExist(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (bool, error) + SetIfNotExistFunc(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (ok bool, err error) + + // SetIfNotExistFuncLock sets `key` with result of function `f` and returns true + // if `key` does not exist in the cache, or else it does nothing and returns false if `key` already exists. + // + // It does not expire if `duration` == 0. + // It deletes the `key` if `duration` < 0 or given `value` is nil. + // + // Note that it differs from function `SetIfNotExistFunc` is that the function `f` is executed within + // writing mutex lock for concurrent safety purpose. + SetIfNotExistFuncLock(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (ok bool, err error) // Get retrieves and returns the associated value of given `key`. - // It returns nil if it does not exist, its value is nil, or it's expired. + // It returns nil if it does not exist, or its value is nil, or it's expired. + // If you would like to check if the `key` exists in the cache, it's better using function Contains. Get(ctx context.Context, key interface{}) (interface{}, error) // GetOrSet retrieves and returns the value of `key`, or sets `key`-`value` pair and @@ -47,7 +69,7 @@ type Adapter interface { // It does not expire if `duration` == 0. // It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing // if `value` is a function and the function result is nil. - GetOrSet(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (interface{}, error) + GetOrSet(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (result interface{}, err error) // GetOrSetFunc retrieves and returns the value of `key`, or sets `key` with result of // function `f` and returns its result if `key` does not exist in the cache. The key-value @@ -56,31 +78,33 @@ type Adapter interface { // It does not expire if `duration` == 0. // It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing // if `value` is a function and the function result is nil. - GetOrSetFunc(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) + GetOrSetFunc(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (result interface{}, err error) // GetOrSetFuncLock retrieves and returns the value of `key`, or sets `key` with result of // function `f` and returns its result if `key` does not exist in the cache. The key-value // pair expires after `duration`. // // It does not expire if `duration` == 0. - // It does nothing if function `f` returns nil. + // It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing + // if `value` is a function and the function result is nil. // - // Note that the function `f` should be executed within writing mutex lock for concurrent - // safety purpose. - GetOrSetFuncLock(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) + // Note that it differs from function `GetOrSetFunc` is that the function `f` is executed within + // writing mutex lock for concurrent safety purpose. + GetOrSetFuncLock(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (result interface{}, err error) - // Contains returns true if `key` exists in the cache, or else returns false. + // Contains checks and returns true if `key` exists in the cache, or else returns false. Contains(ctx context.Context, key interface{}) (bool, error) // GetExpire retrieves and returns the expiration of `key` in the cache. // + // Note that, // It returns 0 if the `key` does not expire. // It returns -1 if the `key` does not exist in the cache. GetExpire(ctx context.Context, key interface{}) (time.Duration, error) // Remove deletes one or more keys from cache, and returns its value. // If multiple keys are given, it returns the value of the last deleted item. - Remove(ctx context.Context, keys ...interface{}) (value interface{}, err error) + Remove(ctx context.Context, keys ...interface{}) (lastValue interface{}, err error) // Update updates the value of `key` without changing its expiration and returns the old value. // The returned value `exist` is false if the `key` does not exist in the cache. @@ -101,13 +125,13 @@ type Adapter interface { // Data returns a copy of all key-value pairs in the cache as map type. // Note that this function may lead lots of memory usage, you can implement this function // if necessary. - Data(ctx context.Context) (map[interface{}]interface{}, error) + Data(ctx context.Context) (data map[interface{}]interface{}, err error) // Keys returns all keys in the cache as slice. - Keys(ctx context.Context) ([]interface{}, error) + Keys(ctx context.Context) (keys []interface{}, err error) // Values returns all values in the cache as slice. - Values(ctx context.Context) ([]interface{}, error) + Values(ctx context.Context) (values []interface{}, err error) // Clear clears all data of the cache. // Note that this function is sensitive and should be carefully used. diff --git a/os/gcache/gcache_adapter_memory.go b/os/gcache/gcache_adapter_memory.go index c70b2b3e3..8f21faf05 100644 --- a/os/gcache/gcache_adapter_memory.go +++ b/os/gcache/gcache_adapter_memory.go @@ -18,8 +18,8 @@ import ( "github.com/gogf/gf/os/gtimer" ) -// Internal cache object. -type adapterMemory struct { +// AdapterMemory is an adapter implements using memory. +type AdapterMemory struct { // cap limits the size of the cache pool. // If the size of the cache exceeds the cap, // the cache expiration process performs according to the LRU algorithm. @@ -52,9 +52,9 @@ const ( defaultMaxExpire = 9223372036854 ) -// newAdapterMemory creates and returns a new memory cache object. -func newAdapterMemory(lruCap ...int) *adapterMemory { - c := &adapterMemory{ +// NewAdapterMemory creates and returns a new memory cache object. +func NewAdapterMemory(lruCap ...int) Adapter { + c := &AdapterMemory{ data: newAdapterMemoryData(), lruGetList: glist.New(true), expireTimes: newAdapterMemoryExpireTimes(), @@ -72,8 +72,8 @@ func newAdapterMemory(lruCap ...int) *adapterMemory { // Set sets cache with `key`-`value` pair, which is expired after `duration`. // // It does not expire if `duration` == 0. -// It deletes the `key` if `duration` < 0. -func (c *adapterMemory) Set(ctx context.Context, key interface{}, value interface{}, duration time.Duration) error { +// It deletes the keys of `data` if `duration` < 0 or given `value` is nil. +func (c *AdapterMemory) Set(ctx context.Context, key interface{}, value interface{}, duration time.Duration) error { expireTime := c.getInternalExpire(duration) c.data.Set(key, adapterMemoryItem{ v: value, @@ -86,73 +86,11 @@ func (c *adapterMemory) Set(ctx context.Context, key interface{}, value interfac return nil } -// Update updates the value of `key` without changing its expiration and returns the old value. -// The returned value `exist` is false if the `key` does not exist in the cache. -// -// It deletes the `key` if given `value` is nil. -// It does nothing if `key` does not exist in the cache. -func (c *adapterMemory) Update(ctx context.Context, key interface{}, value interface{}) (oldValue interface{}, exist bool, err error) { - return c.data.Update(key, value) -} - -// UpdateExpire updates the expiration of `key` and returns the old expiration duration value. -// -// It returns -1 and does nothing if the `key` does not exist in the cache. -// It deletes the `key` if `duration` < 0. -func (c *adapterMemory) UpdateExpire(ctx context.Context, key interface{}, duration time.Duration) (oldDuration time.Duration, err error) { - newExpireTime := c.getInternalExpire(duration) - oldDuration, err = c.data.UpdateExpire(key, newExpireTime) - if err != nil { - return - } - if oldDuration != -1 { - c.eventList.PushBack(&adapterMemoryEvent{ - k: key, - e: newExpireTime, - }) - } - return -} - -// GetExpire retrieves and returns the expiration of `key` in the cache. -// -// It returns 0 if the `key` does not expire. -// It returns -1 if the `key` does not exist in the cache. -func (c *adapterMemory) GetExpire(ctx context.Context, key interface{}) (time.Duration, error) { - if item, ok := c.data.Get(key); ok { - return time.Duration(item.e-gtime.TimestampMilli()) * time.Millisecond, nil - } - return -1, nil -} - -// SetIfNotExist sets cache with `key`-`value` pair which is expired after `duration` -// if `key` does not exist in the cache. It returns true the `key` does not exist in the -// cache, and it sets `value` successfully to the cache, or else it returns false. -// The parameter `value` can be type of <func() interface{}>, but it dose nothing if its -// result is nil. -// -// It does not expire if `duration` == 0. -// It deletes the `key` if `duration` < 0 or given `value` is nil. -func (c *adapterMemory) SetIfNotExist(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (bool, error) { - isContained, err := c.Contains(ctx, key) - if err != nil { - return false, err - } - if !isContained { - _, err := c.doSetWithLockCheck(key, value, duration) - if err != nil { - return false, err - } - return true, nil - } - return false, nil -} - -// Sets batch sets cache with key-value pairs by `data`, which is expired after `duration`. +// Sets batch sets cache with key-value pairs by `data` map, which is expired after `duration`. // // It does not expire if `duration` == 0. // It deletes the keys of `data` if `duration` < 0 or given `value` is nil. -func (c *adapterMemory) Sets(ctx context.Context, data map[interface{}]interface{}, duration time.Duration) error { +func (c *AdapterMemory) Sets(ctx context.Context, data map[interface{}]interface{}, duration time.Duration) error { var ( expireTime = c.getInternalExpire(duration) err = c.data.Sets(data, expireTime) @@ -169,9 +107,78 @@ func (c *adapterMemory) Sets(ctx context.Context, data map[interface{}]interface return nil } +// SetIfNotExist sets cache with `key`-`value` pair which is expired after `duration` +// if `key` does not exist in the cache. It returns true the `key` does not exist in the +// cache, and it sets `value` successfully to the cache, or else it returns false. +// +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil. +func (c *AdapterMemory) SetIfNotExist(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (bool, error) { + isContained, err := c.Contains(ctx, key) + if err != nil { + return false, err + } + if !isContained { + if _, err = c.doSetWithLockCheck(key, value, duration); err != nil { + return false, err + } + return true, nil + } + return false, nil +} + +// SetIfNotExistFunc sets `key` with result of function `f` and returns true +// if `key` does not exist in the cache, or else it does nothing and returns false if `key` already exists. +// +// The parameter `value` can be type of `func() interface{}`, but it does nothing if its +// result is nil. +// +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil. +func (c *AdapterMemory) SetIfNotExistFunc(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (bool, error) { + isContained, err := c.Contains(ctx, key) + if err != nil { + return false, err + } + if !isContained { + value, err := f() + if err != nil { + return false, err + } + if _, err = c.doSetWithLockCheck(key, value, duration); err != nil { + return false, err + } + return true, nil + } + return false, nil +} + +// SetIfNotExistFuncLock sets `key` with result of function `f` and returns true +// if `key` does not exist in the cache, or else it does nothing and returns false if `key` already exists. +// +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil. +// +// Note that it differs from function `SetIfNotExistFunc` is that the function `f` is executed within +// writing mutex lock for concurrent safety purpose. +func (c *AdapterMemory) SetIfNotExistFuncLock(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (bool, error) { + isContained, err := c.Contains(ctx, key) + if err != nil { + return false, err + } + if !isContained { + if _, err = c.doSetWithLockCheck(key, f, duration); err != nil { + return false, err + } + return true, nil + } + return false, nil +} + // Get retrieves and returns the associated value of given `key`. -// It returns nil if it does not exist or its value is nil. -func (c *adapterMemory) Get(ctx context.Context, key interface{}) (interface{}, error) { +// It returns nil if it does not exist, or its value is nil, or it's expired. +// If you would like to check if the `key` exists in the cache, it's better using function Contains. +func (c *AdapterMemory) Get(ctx context.Context, key interface{}) (interface{}, error) { item, ok := c.data.Get(key) if ok && !item.IsExpired() { // Adding to LRU history if LRU feature is enabled. @@ -190,7 +197,7 @@ func (c *adapterMemory) Get(ctx context.Context, key interface{}) (interface{}, // It does not expire if `duration` == 0. // It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing // if `value` is a function and the function result is nil. -func (c *adapterMemory) GetOrSet(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (interface{}, error) { +func (c *AdapterMemory) GetOrSet(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (interface{}, error) { v, err := c.Get(ctx, key) if err != nil { return nil, err @@ -209,7 +216,7 @@ func (c *adapterMemory) GetOrSet(ctx context.Context, key interface{}, value int // It does not expire if `duration` == 0. // It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing // if `value` is a function and the function result is nil. -func (c *adapterMemory) GetOrSetFunc(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) { +func (c *AdapterMemory) GetOrSetFunc(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) { v, err := c.Get(ctx, key) if err != nil { return nil, err @@ -233,11 +240,12 @@ func (c *adapterMemory) GetOrSetFunc(ctx context.Context, key interface{}, f fun // pair expires after `duration`. // // It does not expire if `duration` == 0. -// It does nothing if function `f` returns nil. +// It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing +// if `value` is a function and the function result is nil. // -// Note that the function `f` should be executed within writing mutex lock for concurrent -// safety purpose. -func (c *adapterMemory) GetOrSetFuncLock(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) { +// Note that it differs from function `GetOrSetFunc` is that the function `f` is executed within +// writing mutex lock for concurrent safety purpose. +func (c *AdapterMemory) GetOrSetFuncLock(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) { v, err := c.Get(ctx, key) if err != nil { return nil, err @@ -249,8 +257,8 @@ func (c *adapterMemory) GetOrSetFuncLock(ctx context.Context, key interface{}, f } } -// Contains returns true if `key` exists in the cache, or else returns false. -func (c *adapterMemory) Contains(ctx context.Context, key interface{}) (bool, error) { +// Contains checks and returns true if `key` exists in the cache, or else returns false. +func (c *AdapterMemory) Contains(ctx context.Context, key interface{}) (bool, error) { v, err := c.Get(ctx, key) if err != nil { return false, err @@ -258,9 +266,21 @@ func (c *adapterMemory) Contains(ctx context.Context, key interface{}) (bool, er return v != nil, nil } -// Remove deletes the one or more keys from cache, and returns its value. -// If multiple keys are given, it returns the value of the deleted last item. -func (c *adapterMemory) Remove(ctx context.Context, keys ...interface{}) (value interface{}, err error) { +// GetExpire retrieves and returns the expiration of `key` in the cache. +// +// Note that, +// It returns 0 if the `key` does not expire. +// It returns -1 if the `key` does not exist in the cache. +func (c *AdapterMemory) GetExpire(ctx context.Context, key interface{}) (time.Duration, error) { + if item, ok := c.data.Get(key); ok { + return time.Duration(item.e-gtime.TimestampMilli()) * time.Millisecond, nil + } + return -1, nil +} + +// Remove deletes one or more keys from cache, and returns its value. +// If multiple keys are given, it returns the value of the last deleted item. +func (c *AdapterMemory) Remove(ctx context.Context, keys ...interface{}) (value interface{}, err error) { var removedKeys []interface{} removedKeys, value, err = c.data.Remove(keys...) if err != nil { @@ -275,34 +295,62 @@ func (c *adapterMemory) Remove(ctx context.Context, keys ...interface{}) (value return } +// Update updates the value of `key` without changing its expiration and returns the old value. +// The returned value `exist` is false if the `key` does not exist in the cache. +// +// It deletes the `key` if given `value` is nil. +// It does nothing if `key` does not exist in the cache. +func (c *AdapterMemory) Update(ctx context.Context, key interface{}, value interface{}) (oldValue interface{}, exist bool, err error) { + return c.data.Update(key, value) +} + +// UpdateExpire updates the expiration of `key` and returns the old expiration duration value. +// +// It returns -1 and does nothing if the `key` does not exist in the cache. +// It deletes the `key` if `duration` < 0. +func (c *AdapterMemory) UpdateExpire(ctx context.Context, key interface{}, duration time.Duration) (oldDuration time.Duration, err error) { + newExpireTime := c.getInternalExpire(duration) + oldDuration, err = c.data.UpdateExpire(key, newExpireTime) + if err != nil { + return + } + if oldDuration != -1 { + c.eventList.PushBack(&adapterMemoryEvent{ + k: key, + e: newExpireTime, + }) + } + return +} + +// Size returns the size of the cache. +func (c *AdapterMemory) Size(ctx context.Context) (size int, err error) { + return c.data.Size() +} + // Data returns a copy of all key-value pairs in the cache as map type. -func (c *adapterMemory) Data(ctx context.Context) (map[interface{}]interface{}, error) { +func (c *AdapterMemory) Data(ctx context.Context) (map[interface{}]interface{}, error) { return c.data.Data() } // Keys returns all keys in the cache as slice. -func (c *adapterMemory) Keys(ctx context.Context) ([]interface{}, error) { +func (c *AdapterMemory) Keys(ctx context.Context) ([]interface{}, error) { return c.data.Keys() } // Values returns all values in the cache as slice. -func (c *adapterMemory) Values(ctx context.Context) ([]interface{}, error) { +func (c *AdapterMemory) Values(ctx context.Context) ([]interface{}, error) { return c.data.Values() } -// Size returns the size of the cache. -func (c *adapterMemory) Size(ctx context.Context) (size int, err error) { - return c.data.Size() -} - // Clear clears all data of the cache. // Note that this function is sensitive and should be carefully used. -func (c *adapterMemory) Clear(ctx context.Context) error { +func (c *AdapterMemory) Clear(ctx context.Context) error { return c.data.Clear() } // Close closes the cache. -func (c *adapterMemory) Close(ctx context.Context) error { +func (c *AdapterMemory) Close(ctx context.Context) error { if c.cap > 0 { c.lru.Close() } @@ -314,20 +362,20 @@ func (c *adapterMemory) Close(ctx context.Context) error { // cache, which is expired after `duration`. // // It does not expire if `duration` == 0. -// The parameter `value` can be type of <func() interface{}>, but it dose nothing if the +// The parameter `value` can be type of <func() interface{}>, but it does nothing if the // function result is nil. // // It doubly checks the `key` whether exists in the cache using mutex writing lock // before setting it to the cache. -func (c *adapterMemory) doSetWithLockCheck(key interface{}, value interface{}, duration time.Duration) (result interface{}, err error) { +func (c *AdapterMemory) doSetWithLockCheck(key interface{}, value interface{}, duration time.Duration) (result interface{}, err error) { expireTimestamp := c.getInternalExpire(duration) result, err = c.data.SetWithLock(key, value, expireTimestamp) c.eventList.PushBack(&adapterMemoryEvent{k: key, e: expireTimestamp}) return } -// getInternalExpire converts and returns the expire time with given expired duration in milliseconds. -func (c *adapterMemory) getInternalExpire(duration time.Duration) int64 { +// getInternalExpire converts and returns the expiration time with given expired duration in milliseconds. +func (c *AdapterMemory) getInternalExpire(duration time.Duration) int64 { if duration == 0 { return defaultMaxExpire } else { @@ -336,7 +384,7 @@ func (c *adapterMemory) getInternalExpire(duration time.Duration) int64 { } // makeExpireKey groups the `expire` in milliseconds to its according seconds. -func (c *adapterMemory) makeExpireKey(expire int64) int64 { +func (c *AdapterMemory) makeExpireKey(expire int64) int64 { return int64(math.Ceil(float64(expire/1000)+1) * 1000) } @@ -344,7 +392,7 @@ func (c *adapterMemory) makeExpireKey(expire int64) int64 { // 1. Asynchronously process the data in the event list, // and synchronize the results to the `expireTimes` and `expireSets` properties. // 2. Clean up the expired key-value pair data. -func (c *adapterMemory) syncEventAndClearExpired() { +func (c *AdapterMemory) syncEventAndClearExpired() { if c.closed.Val() { gtimer.Exit() return @@ -365,14 +413,14 @@ func (c *adapterMemory) syncEventAndClearExpired() { event = v.(*adapterMemoryEvent) // Fetching the old expire set. oldExpireTime = c.expireTimes.Get(event.k) - // Calculating the new expire set. + // Calculating the new expiration time set. newExpireTime = c.makeExpireKey(event.e) if newExpireTime != oldExpireTime { c.expireSets.GetOrNew(newExpireTime).Add(event.k) if oldExpireTime != 0 { c.expireSets.GetOrNew(oldExpireTime).Remove(event.k) } - // Updating the expire time for <event.k>. + // Updating the expired time for <event.k>. c.expireTimes.Set(event.k, newExpireTime) } // Adding the key the LRU history by writing operations. @@ -413,11 +461,11 @@ func (c *adapterMemory) syncEventAndClearExpired() { // clearByKey deletes the key-value pair with given `key`. // The parameter `force` specifies whether doing this deleting forcibly. -func (c *adapterMemory) clearByKey(key interface{}, force ...bool) { +func (c *AdapterMemory) clearByKey(key interface{}, force ...bool) { // Doubly check before really deleting it from cache. c.data.DeleteWithDoubleCheck(key, force...) - // Deleting its expire time from `expireTimes`. + // Deleting its expiration time from `expireTimes`. c.expireTimes.Delete(key) // Deleting it from LRU. diff --git a/os/gcache/gcache_adapter_memory_lru.go b/os/gcache/gcache_adapter_memory_lru.go index c2f2a64d5..6ff25e4fd 100644 --- a/os/gcache/gcache_adapter_memory_lru.go +++ b/os/gcache/gcache_adapter_memory_lru.go @@ -18,7 +18,7 @@ import ( // LRU cache object. // It uses list.List from stdlib for its underlying doubly linked list. type adapterMemoryLru struct { - cache *adapterMemory // Parent cache object. + cache *AdapterMemory // Parent cache object. data *gmap.Map // Key mapping to the item of the list. list *glist.List // Key list. rawList *glist.List // History for key adding. @@ -26,7 +26,7 @@ type adapterMemoryLru struct { } // newMemCacheLru creates and returns a new LRU object. -func newMemCacheLru(cache *adapterMemory) *adapterMemoryLru { +func newMemCacheLru(cache *AdapterMemory) *adapterMemoryLru { lru := &adapterMemoryLru{ cache: cache, data: gmap.New(true), diff --git a/os/gcache/gcache_cache.go b/os/gcache/gcache_cache.go index 216549bd9..2fd34aff2 100644 --- a/os/gcache/gcache_cache.go +++ b/os/gcache/gcache_cache.go @@ -23,16 +23,23 @@ type Cache struct { // New creates and returns a new cache object using default memory adapter. // Note that the LRU feature is only available using memory adapter. func New(lruCap ...int) *Cache { - memAdapter := newAdapterMemory(lruCap...) + memAdapter := NewAdapterMemory(lruCap...) c := &Cache{ adapter: memAdapter, } // Here may be a "timer leak" if adapter is manually changed from memory adapter. - // Do not worry about this, as adapter is less changed and it dose nothing if it's not used. - gtimer.AddSingleton(time.Second, memAdapter.syncEventAndClearExpired) + // Do not worry about this, as adapter is less changed, and it does nothing if it's not used. + gtimer.AddSingleton(time.Second, memAdapter.(*AdapterMemory).syncEventAndClearExpired) return c } +// NewWithAdapter creates and returns a Cache object with given Adapter implements. +func NewWithAdapter(adapter Adapter) *Cache { + return &Cache{ + adapter: adapter, + } +} + // Clone returns a shallow copy of current object. func (c *Cache) Clone() *Cache { return &Cache{ @@ -62,13 +69,62 @@ func (c *Cache) GetVar(key interface{}) (*gvar.Var, error) { return gvar.New(v), err } +// GetVarOrSet acts as function GetOrSet except it returns value as type gvar.Var. +// Also see GetOrSet. +func (c *Cache) GetVarOrSet(key interface{}, value interface{}, duration time.Duration) (*gvar.Var, error) { + v, err := c.GetOrSet(key, value, duration) + if err != nil { + return nil, err + } + return gvar.New(v), nil +} + +// GetVarOrSetFunc acts as function GetOrSetFunc except it returns value as type gvar.Var. +// Also see GetOrSetFunc. +func (c *Cache) GetVarOrSetFunc(key interface{}, f func() (interface{}, error), duration time.Duration) (*gvar.Var, error) { + v, err := c.GetOrSetFunc(key, f, duration) + if err != nil { + return nil, err + } + return gvar.New(v), nil +} + +// GetVarOrSetFuncLock acts as function GetOrSetFuncLock except it returns value as type gvar.Var. +// Also see GetOrSetFuncLock. +func (c *Cache) GetVarOrSetFuncLock(key interface{}, f func() (interface{}, error), duration time.Duration) (*gvar.Var, error) { + v, err := c.GetOrSetFuncLock(key, f, duration) + if err != nil { + return nil, err + } + return gvar.New(v), nil +} + +// RemoveVar acts as function Remove except it returns value as type gvar.Var. +// Also see Remove. +func (c *Cache) RemoveVar(keys ...interface{}) (*gvar.Var, error) { + v, err := c.Remove(keys...) + if err != nil { + return nil, err + } + return gvar.New(v), nil +} + // Removes deletes `keys` in the cache. -// Deprecated, use Remove instead. func (c *Cache) Removes(keys []interface{}) error { _, err := c.Remove(keys...) return err } +// UpdateVar acts as function Update except it returns value as type gvar.Var. +// Also see Update. +func (c *Cache) UpdateVar(key interface{}, value interface{}) (oldValue *gvar.Var, exist bool, err error) { + v, exist, err := c.Update(key, value) + if err != nil { + return nil, exist, err + } + return gvar.New(v), exist, err +} + // KeyStrings returns all keys in the cache as string slice. func (c *Cache) KeyStrings() ([]string, error) { keys, err := c.Keys() diff --git a/os/gcache/gcache_cache_adapter.go b/os/gcache/gcache_cache_adapter.go index dce6b19ef..7cd5970c4 100644 --- a/os/gcache/gcache_cache_adapter.go +++ b/os/gcache/gcache_cache_adapter.go @@ -13,12 +13,12 @@ import ( // Set sets cache with `key`-`value` pair, which is expired after `duration`. // // It does not expire if `duration` == 0. -// It deletes the `key` if `duration` < 0. +// It deletes the keys of `data` if `duration` < 0 or given `value` is nil. func (c *Cache) Set(key interface{}, value interface{}, duration time.Duration) error { return c.adapter.Set(c.getCtx(), key, value, duration) } -// Sets batch sets cache with key-value pairs by `data`, which is expired after `duration`. +// Sets batch sets cache with key-value pairs by `data` map, which is expired after `duration`. // // It does not expire if `duration` == 0. // It deletes the keys of `data` if `duration` < 0 or given `value` is nil. @@ -30,17 +30,41 @@ func (c *Cache) Sets(data map[interface{}]interface{}, duration time.Duration) e // if `key` does not exist in the cache. It returns true the `key` does not exist in the // cache, and it sets `value` successfully to the cache, or else it returns false. // -// The parameter `value` can be type of <func() interface{}>, but it does nothing if its -// result is nil. -// // It does not expire if `duration` == 0. // It deletes the `key` if `duration` < 0 or given `value` is nil. func (c *Cache) SetIfNotExist(key interface{}, value interface{}, duration time.Duration) (bool, error) { return c.adapter.SetIfNotExist(c.getCtx(), key, value, duration) } +// SetIfNotExistFunc sets `key` with result of function `f` and returns true +// if `key` does not exist in the cache, or else it does nothing and returns false if `key` already exists. +// +// The parameter `value` can be type of `func() interface{}`, but it does nothing if its +// result is nil. +// +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil. +func (c *Cache) SetIfNotExistFunc(key interface{}, f func() (interface{}, error), duration time.Duration) (bool, error) { + return c.adapter.SetIfNotExistFunc(c.getCtx(), key, f, duration) +} + +// SetIfNotExistFuncLock sets `key` with result of function `f` and returns true +// if `key` does not exist in the cache, or else it does nothing and returns false if `key` already exists. +// +// It does not expire if `duration` == 0. +// It deletes the `key` if `duration` < 0 or given `value` is nil. +// +// Note that it differs from function `SetIfNotExistFunc` is that the function `f` is executed within +// writing mutex lock for concurrent safety purpose. +func (c *Cache) SetIfNotExistFuncLock(key interface{}, f func() (interface{}, error), duration time.Duration) (bool, error) { + return c.adapter.SetIfNotExistFuncLock(c.getCtx(), key, f, duration) +} + // Get retrieves and returns the associated value of given `key`. -// It returns nil if it does not exist, its value is nil or it's expired. +// It returns nil if it does not exist, or its value is nil, or it's expired. +// If you would like to check if the `key` exists in the cache, it's better using function Contains. +// +// It is suggested using GetVar instead for compatibility of different adapters purpose. func (c *Cache) Get(key interface{}) (interface{}, error) { return c.adapter.Get(c.getCtx(), key) } @@ -52,6 +76,8 @@ func (c *Cache) Get(key interface{}) (interface{}, error) { // It does not expire if `duration` == 0. // It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing // if `value` is a function and the function result is nil. +// +// It is suggested using GetVarOrSet instead for compatibility of different adapters purpose. func (c *Cache) GetOrSet(key interface{}, value interface{}, duration time.Duration) (interface{}, error) { return c.adapter.GetOrSet(c.getCtx(), key, value, duration) } @@ -63,6 +89,8 @@ func (c *Cache) GetOrSet(key interface{}, value interface{}, duration time.Durat // It does not expire if `duration` == 0. // It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing // if `value` is a function and the function result is nil. +// +// It is suggested using GetVarOrSetFunc instead for compatibility of different adapters purpose. func (c *Cache) GetOrSetFunc(key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) { return c.adapter.GetOrSetFunc(c.getCtx(), key, f, duration) } @@ -72,21 +100,25 @@ func (c *Cache) GetOrSetFunc(key interface{}, f func() (interface{}, error), dur // pair expires after `duration`. // // It does not expire if `duration` == 0. -// It does nothing if function `f` returns nil. +// It deletes the `key` if `duration` < 0 or given `value` is nil, but it does nothing +// if `value` is a function and the function result is nil. // -// Note that the function `f` should be executed within writing mutex lock for concurrent -// safety purpose. +// Note that it differs from function `GetOrSetFunc` is that the function `f` is executed within +// writing mutex lock for concurrent safety purpose. +// +// It is suggested using GetVarOrSetFuncLock instead for compatibility of different adapters purpose. func (c *Cache) GetOrSetFuncLock(key interface{}, f func() (interface{}, error), duration time.Duration) (interface{}, error) { return c.adapter.GetOrSetFuncLock(c.getCtx(), key, f, duration) } -// Contains returns true if `key` exists in the cache, or else returns false. +// Contains checks and returns true if `key` exists in the cache, or else returns false. func (c *Cache) Contains(key interface{}) (bool, error) { return c.adapter.Contains(c.getCtx(), key) } // GetExpire retrieves and returns the expiration of `key` in the cache. // +// Note that, // It returns 0 if the `key` does not expire. // It returns -1 if the `key` does not exist in the cache. func (c *Cache) GetExpire(key interface{}) (time.Duration, error) { @@ -95,6 +127,8 @@ func (c *Cache) GetExpire(key interface{}) (time.Duration, error) { // Remove deletes one or more keys from cache, and returns its value. // If multiple keys are given, it returns the value of the last deleted item. +// +// It is suggested using RemoveVar instead for compatibility of different adapters purpose. func (c *Cache) Remove(keys ...interface{}) (value interface{}, err error) { return c.adapter.Remove(c.getCtx(), keys...) } diff --git a/os/gcache/gcache_z_unit_basic_test.go b/os/gcache/gcache_z_unit_basic_test.go index 9ea748cd3..79776f25a 100644 --- a/os/gcache/gcache_z_unit_basic_test.go +++ b/os/gcache/gcache_z_unit_basic_test.go @@ -24,8 +24,8 @@ import ( func TestCache_GCache_Set(t *testing.T) { gtest.C(t, func(t *gtest.T) { - gcache.Set(1, 11, 0) - defer gcache.Removes(g.Slice{1, 2, 3}) + t.AssertNil(gcache.Set(1, 11, 0)) + defer gcache.Remove(g.Slice{1, 2, 3}...) v, _ := gcache.Get(1) t.Assert(v, 11) b, _ := gcache.Contains(1) @@ -91,13 +91,17 @@ func TestCache_Set_Expire(t *testing.T) { }) } -func TestCache_Update_GetExpire(t *testing.T) { +func TestCache_Update(t *testing.T) { // gcache gtest.C(t, func(t *gtest.T) { key := guid.S() - gcache.Set(key, 11, 3*time.Second) + t.AssertNil(gcache.Set(key, 11, 3*time.Second)) expire1, _ := gcache.GetExpire(key) - gcache.Update(key, 12) + oldValue, exist, err := gcache.Update(key, 12) + t.AssertNil(err) + t.Assert(oldValue, 11) + t.Assert(exist, true) + expire2, _ := gcache.GetExpire(key) v, _ := gcache.GetVar(key) t.Assert(v, 12) @@ -106,9 +110,48 @@ func TestCache_Update_GetExpire(t *testing.T) { // gcache.Cache gtest.C(t, func(t *gtest.T) { cache := gcache.New() - cache.Set(1, 11, 3*time.Second) + t.AssertNil(cache.Set(1, 11, 3*time.Second)) + + oldValue, exist, err := cache.Update(1, 12) + t.AssertNil(err) + t.Assert(oldValue, 11) + t.Assert(exist, true) + + expire1, _ := cache.GetExpire(1) + expire2, _ := cache.GetExpire(1) + v, _ := cache.GetVar(1) + t.Assert(v, 12) + t.Assert(math.Ceil(expire1.Seconds()), math.Ceil(expire2.Seconds())) + }) +} + +func TestCache_UpdateVar(t *testing.T) { + // gcache + gtest.C(t, func(t *gtest.T) { + key := guid.S() + t.AssertNil(gcache.Set(key, 11, 3*time.Second)) + expire1, _ := gcache.GetExpire(key) + oldValue, exist, err := gcache.UpdateVar(key, 12) + t.AssertNil(err) + t.Assert(oldValue, 11) + t.Assert(exist, true) + + expire2, _ := gcache.GetExpire(key) + v, _ := gcache.GetVar(key) + t.Assert(v, 12) + t.Assert(math.Ceil(expire1.Seconds()), math.Ceil(expire2.Seconds())) + }) + // gcache.Cache + gtest.C(t, func(t *gtest.T) { + cache := gcache.New() + t.AssertNil(cache.Set(1, 11, 3*time.Second)) + + oldValue, exist, err := cache.UpdateVar(1, 12) + t.AssertNil(err) + t.Assert(oldValue, 11) + t.Assert(exist, true) + expire1, _ := cache.GetExpire(1) - cache.Update(1, 12) expire2, _ := cache.GetExpire(1) v, _ := cache.GetVar(1) t.Assert(v, 12) @@ -120,11 +163,14 @@ func TestCache_UpdateExpire(t *testing.T) { // gcache gtest.C(t, func(t *gtest.T) { key := guid.S() - gcache.Set(key, 11, 3*time.Second) + t.AssertNil(gcache.Set(key, 11, 3*time.Second)) defer gcache.Remove(key) oldExpire, _ := gcache.GetExpire(key) newExpire := 10 * time.Second - gcache.UpdateExpire(key, newExpire) + oldExpire2, err := gcache.UpdateExpire(key, newExpire) + t.AssertNil(err) + t.Assert(oldExpire2, oldExpire) + e, _ := gcache.GetExpire(key) t.AssertNE(e, oldExpire) e, _ = gcache.GetExpire(key) @@ -133,10 +179,13 @@ func TestCache_UpdateExpire(t *testing.T) { // gcache.Cache gtest.C(t, func(t *gtest.T) { cache := gcache.New() - cache.Set(1, 11, 3*time.Second) + t.AssertNil(cache.Set(1, 11, 3*time.Second)) oldExpire, _ := cache.GetExpire(1) newExpire := 10 * time.Second - cache.UpdateExpire(1, newExpire) + oldExpire2, err := cache.UpdateExpire(1, newExpire) + t.AssertNil(err) + t.Assert(oldExpire2, oldExpire) + e, _ := cache.GetExpire(1) t.AssertNE(e, oldExpire) @@ -166,7 +215,7 @@ func TestCache_LRU(t *testing.T) { gtest.C(t, func(t *gtest.T) { cache := gcache.New(2) for i := 0; i < 10; i++ { - cache.Set(i, i, 0) + t.AssertNil(cache.Set(i, i, 0)) } n, _ := cache.Size() t.Assert(n, 10) @@ -198,21 +247,127 @@ func TestCache_LRU_expire(t *testing.T) { func TestCache_SetIfNotExist(t *testing.T) { gtest.C(t, func(t *gtest.T) { cache := gcache.New() - cache.SetIfNotExist(1, 11, 0) + ok, err := cache.SetIfNotExist(1, 11, 0) + t.AssertNil(err) + t.Assert(ok, true) + v, _ := cache.Get(1) t.Assert(v, 11) - cache.SetIfNotExist(1, 22, 0) + + ok, err = cache.SetIfNotExist(1, 22, 0) + t.AssertNil(err) + t.Assert(ok, false) + v, _ = cache.Get(1) t.Assert(v, 11) - cache.SetIfNotExist(2, 22, 0) + + ok, err = cache.SetIfNotExist(2, 22, 0) + t.AssertNil(err) + t.Assert(ok, true) + v, _ = cache.Get(2) t.Assert(v, 22) - gcache.Removes(g.Slice{1, 2, 3}) - gcache.SetIfNotExist(1, 11, 0) + gcache.Remove(g.Slice{1, 2, 3}...) + ok, err = gcache.SetIfNotExist(1, 11, 0) + t.AssertNil(err) + t.Assert(ok, true) + v, _ = gcache.Get(1) t.Assert(v, 11) - gcache.SetIfNotExist(1, 22, 0) + + ok, err = gcache.SetIfNotExist(1, 22, 0) + t.AssertNil(err) + t.Assert(ok, false) + + v, _ = gcache.Get(1) + t.Assert(v, 11) + }) +} + +func TestCache_SetIfNotExistFunc(t *testing.T) { + gtest.C(t, func(t *gtest.T) { + cache := gcache.New() + exist, err := cache.SetIfNotExistFunc(1, func() (interface{}, error) { + return 11, nil + }, 0) + t.AssertNil(err) + t.Assert(exist, true) + + v, _ := cache.Get(1) + t.Assert(v, 11) + + exist, err = cache.SetIfNotExistFunc(1, func() (interface{}, error) { + return 22, nil + }, 0) + t.AssertNil(err) + t.Assert(exist, false) + + v, _ = cache.Get(1) + t.Assert(v, 11) + }) + gtest.C(t, func(t *gtest.T) { + gcache.Remove(g.Slice{1, 2, 3}...) + + ok, err := gcache.SetIfNotExistFunc(1, func() (interface{}, error) { + return 11, nil + }, 0) + t.AssertNil(err) + t.Assert(ok, true) + + v, _ := gcache.Get(1) + t.Assert(v, 11) + + ok, err = gcache.SetIfNotExistFunc(1, func() (interface{}, error) { + return 22, nil + }, 0) + t.AssertNil(err) + t.Assert(ok, false) + + v, _ = gcache.Get(1) + t.Assert(v, 11) + }) +} + +func TestCache_SetIfNotExistFuncLock(t *testing.T) { + gtest.C(t, func(t *gtest.T) { + cache := gcache.New() + exist, err := cache.SetIfNotExistFuncLock(1, func() (interface{}, error) { + return 11, nil + }, 0) + t.AssertNil(err) + t.Assert(exist, true) + + v, _ := cache.Get(1) + t.Assert(v, 11) + + exist, err = cache.SetIfNotExistFuncLock(1, func() (interface{}, error) { + return 22, nil + }, 0) + t.AssertNil(err) + t.Assert(exist, false) + + v, _ = cache.Get(1) + t.Assert(v, 11) + }) + gtest.C(t, func(t *gtest.T) { + gcache.Remove(g.Slice{1, 2, 3}...) + + exist, err := gcache.SetIfNotExistFuncLock(1, func() (interface{}, error) { + return 11, nil + }, 0) + t.AssertNil(err) + t.Assert(exist, true) + + v, _ := gcache.Get(1) + t.Assert(v, 11) + + exist, err = gcache.SetIfNotExistFuncLock(1, func() (interface{}, error) { + return 22, nil + }, 0) + t.AssertNil(err) + t.Assert(exist, false) + v, _ = gcache.Get(1) t.Assert(v, 11) }) @@ -221,12 +376,12 @@ func TestCache_SetIfNotExist(t *testing.T) { func TestCache_Sets(t *testing.T) { gtest.C(t, func(t *gtest.T) { cache := gcache.New() - cache.Sets(g.MapAnyAny{1: 11, 2: 22}, 0) + t.AssertNil(cache.Sets(g.MapAnyAny{1: 11, 2: 22}, 0)) v, _ := cache.Get(1) t.Assert(v, 11) - gcache.Removes(g.Slice{1, 2, 3}) - gcache.Sets(g.MapAnyAny{1: 11, 2: 22}, 0) + gcache.Remove(g.Slice{1, 2, 3}...) + t.AssertNil(gcache.Sets(g.MapAnyAny{1: 11, 2: 22}, 0)) v, _ = cache.Get(1) t.Assert(v, 11) }) @@ -235,21 +390,36 @@ func TestCache_Sets(t *testing.T) { func TestCache_GetOrSet(t *testing.T) { gtest.C(t, func(t *gtest.T) { cache := gcache.New() - cache.GetOrSet(1, 11, 0) + value, err := cache.GetOrSet(1, 11, 0) + t.AssertNil(err) + t.Assert(value, 11) + v, _ := cache.Get(1) t.Assert(v, 11) - cache.GetOrSet(1, 111, 0) + value, err = cache.GetOrSet(1, 111, 0) + t.AssertNil(err) + t.Assert(value, 11) v, _ = cache.Get(1) t.Assert(v, 11) - gcache.Removes(g.Slice{1, 2, 3}) - gcache.GetOrSet(1, 11, 0) + }) - v, _ = cache.Get(1) + gtest.C(t, func(t *gtest.T) { + gcache.Remove(g.Slice{1, 2, 3}...) + value, err := gcache.GetOrSet(1, 11, 0) + t.AssertNil(err) + t.Assert(value, 11) + + v, err := gcache.Get(1) + t.AssertNil(err) t.Assert(v, 11) - gcache.GetOrSet(1, 111, 0) - v, _ = cache.Get(1) + value, err = gcache.GetOrSet(1, 111, 0) + t.AssertNil(err) + t.Assert(value, 11) + + v, err = gcache.Get(1) + t.AssertNil(err) t.Assert(v, 11) }) } @@ -269,7 +439,7 @@ func TestCache_GetOrSetFunc(t *testing.T) { v, _ = cache.Get(1) t.Assert(v, 11) - gcache.Removes(g.Slice{1, 2, 3}) + gcache.Remove(g.Slice{1, 2, 3}...) gcache.GetOrSetFunc(1, func() (interface{}, error) { return 11, nil @@ -300,7 +470,7 @@ func TestCache_GetOrSetFuncLock(t *testing.T) { v, _ = cache.Get(1) t.Assert(v, 11) - gcache.Removes(g.Slice{1, 2, 3}) + gcache.Remove(g.Slice{1, 2, 3}...) gcache.GetOrSetFuncLock(1, func() (interface{}, error) { return 11, nil }, 0) @@ -315,6 +485,104 @@ func TestCache_GetOrSetFuncLock(t *testing.T) { }) } +func TestCache_GetVarOrSet(t *testing.T) { + gtest.C(t, func(t *gtest.T) { + cache := gcache.New() + value, err := cache.GetVarOrSet(1, 11, 0) + t.AssertNil(err) + t.Assert(value, 11) + + v, _ := cache.GetVar(1) + t.Assert(v, 11) + value, err = cache.GetVarOrSet(1, 111, 0) + t.AssertNil(err) + t.Assert(value, 11) + + v, _ = cache.GetVar(1) + t.Assert(v, 11) + }) + + gtest.C(t, func(t *gtest.T) { + gcache.Remove(g.Slice{1, 2, 3}...) + value, err := gcache.GetVarOrSet(1, 11, 0) + t.AssertNil(err) + t.Assert(value, 11) + + v, err := gcache.GetVar(1) + t.AssertNil(err) + t.Assert(v, 11) + + value, err = gcache.GetVarOrSet(1, 111, 0) + t.AssertNil(err) + t.Assert(value, 11) + + v, err = gcache.GetVar(1) + t.AssertNil(err) + t.Assert(v, 11) + }) +} + +func TestCache_GetVarOrSetFunc(t *testing.T) { + gtest.C(t, func(t *gtest.T) { + cache := gcache.New() + cache.GetVarOrSetFunc(1, func() (interface{}, error) { + return 11, nil + }, 0) + v, _ := cache.GetVar(1) + t.Assert(v, 11) + + cache.GetVarOrSetFunc(1, func() (interface{}, error) { + return 111, nil + }, 0) + v, _ = cache.GetVar(1) + t.Assert(v, 11) + + gcache.RemoveVar(g.Slice{1, 2, 3}...) + + gcache.GetVarOrSetFunc(1, func() (interface{}, error) { + return 11, nil + }, 0) + v, _ = cache.GetVar(1) + t.Assert(v, 11) + + gcache.GetVarOrSetFunc(1, func() (interface{}, error) { + return 111, nil + }, 0) + v, _ = cache.GetVar(1) + t.Assert(v, 11) + }) +} + +func TestCache_GetVarOrSetFuncLock(t *testing.T) { + gtest.C(t, func(t *gtest.T) { + cache := gcache.New() + cache.GetVarOrSetFuncLock(1, func() (interface{}, error) { + return 11, nil + }, 0) + v, _ := cache.GetVar(1) + t.Assert(v, 11) + + cache.GetVarOrSetFuncLock(1, func() (interface{}, error) { + return 111, nil + }, 0) + v, _ = cache.GetVar(1) + t.Assert(v, 11) + + gcache.Remove(g.Slice{1, 2, 3}...) + gcache.GetVarOrSetFuncLock(1, func() (interface{}, error) { + return 11, nil + }, 0) + v, _ = cache.GetVar(1) + t.Assert(v, 11) + + gcache.GetVarOrSetFuncLock(1, func() (interface{}, error) { + return 111, nil + }, 0) + v, _ = cache.GetVar(1) + t.Assert(v, 11) + }) +} + func TestCache_Clear(t *testing.T) { gtest.C(t, func(t *gtest.T) { cache := gcache.New() @@ -380,7 +648,8 @@ func TestCache_Basic(t *testing.T) { t.Assert(removeData1, 11) n, _ = cache.Size() t.Assert(n, 1) - cache.Removes(g.Slice{2}) + + cache.Remove(2) n, _ = cache.Size() t.Assert(n, 0) } @@ -408,13 +677,46 @@ func TestCache_Basic(t *testing.T) { t.Assert(removeData1, 11) n, _ = gcache.Size() t.Assert(n, 1) - gcache.Removes(g.Slice{2}) + gcache.Remove(2) n, _ = gcache.Size() t.Assert(n, 0) } }) } +func TestCache_Removes(t *testing.T) { + gtest.C(t, func(t *gtest.T) { + cache := gcache.New() + t.AssertNil(cache.Set(1, 11, 0)) + t.AssertNil(cache.Set(2, 22, 0)) + t.AssertNil(cache.Set(3, 33, 0)) + t.AssertNil(cache.Removes(g.Slice{2, 3})) + + ok, err := cache.Contains(1) + t.AssertNil(err) + t.Assert(ok, true) + + ok, err = cache.Contains(2) + t.AssertNil(err) + t.Assert(ok, false) + }) + + gtest.C(t, func(t *gtest.T) { + t.AssertNil(gcache.Set(1, 11, 0)) + t.AssertNil(gcache.Set(2, 22, 0)) + t.AssertNil(gcache.Set(3, 33, 0)) + t.AssertNil(gcache.Removes(g.Slice{2, 3})) + + ok, err := gcache.Contains(1) + t.AssertNil(err) + t.Assert(ok, true) + + ok, err = gcache.Contains(2) + t.AssertNil(err) + t.Assert(ok, false) + }) +} + func TestCache_Ctx(t *testing.T) { gtest.C(t, func(t *gtest.T) { cache := gcache.New()