diff --git a/README.md b/README.md index f5a4c81..4c6006b 100644 --- a/README.md +++ b/README.md @@ -572,12 +572,12 @@ Some data structures (e.g. TreeMap, TreeSet) require a comparator function to au Comparator is defined as: -Return values: +Return values (int): ```go --1, if a < b - 0, if a == b - 1, if a > b +negative , if a < b +zero , if a == b +positive , if a > b ``` Comparator signature: diff --git a/containers/containers.go b/containers/containers.go index 0a26c44..91ca046 100644 --- a/containers/containers.go +++ b/containers/containers.go @@ -24,11 +24,18 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +// Package containers provides core interfaces and functions data structures. +// +// Container is the base interface for all data structures to implement. +// +// Iterators provide stateful iterators. +// +// Enumerable provides Ruby inspired (each, select, map, find, any?, etc.) container functions. package containers import "github.com/emirpasic/gods/utils" -// Container is base interface that all data structures implement +// Container is base interface that all data structures implement. type Container interface { Empty() bool Size() int diff --git a/containers/enumerable.go b/containers/enumerable.go index 0a09207..027de5a 100644 --- a/containers/enumerable.go +++ b/containers/enumerable.go @@ -24,9 +24,6 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -// Enumerable functions for ordered containers. -// Ruby's enumerable inspired package. - package containers // EnumerableWithIndex provides functions for ordered containers whose values can be fetched by an index. diff --git a/containers/iterator.go b/containers/iterator.go index b3d2254..fd2d4d4 100644 --- a/containers/iterator.go +++ b/containers/iterator.go @@ -24,8 +24,6 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -// Stateful iterator pattern for ordered containers. - package containers // IteratorWithIndex is stateful iterator for ordered containers whose values can be fetched by an index. diff --git a/lists/arraylist/arraylist.go b/lists/arraylist/arraylist.go index f471908..ad0fc09 100644 --- a/lists/arraylist/arraylist.go +++ b/lists/arraylist/arraylist.go @@ -24,10 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -// Implementation of list using a slice. +// Package arraylist implements the array list. +// // Structure is not thread safe. -// References: http://en.wikipedia.org/wiki/List_%28abstract_data_type%29 - +// +// Reference: https://en.wikipedia.org/wiki/List_%28abstract_data_type%29 package arraylist import ( diff --git a/lists/doublylinkedlist/doublylinkedlist.go b/lists/doublylinkedlist/doublylinkedlist.go index 58a0e4b..3f97647 100644 --- a/lists/doublylinkedlist/doublylinkedlist.go +++ b/lists/doublylinkedlist/doublylinkedlist.go @@ -24,10 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -// Implementation of doubly linked list. +// Package doublylinkedlist implements the doubly-linked list. +// // Structure is not thread safe. -// References: http://en.wikipedia.org/wiki/Doubly_linked_list - +// +// Reference: https://en.wikipedia.org/wiki/List_%28abstract_data_type%29 package doublylinkedlist import ( diff --git a/lists/lists.go b/lists/lists.go index ad241c2..539d14e 100644 --- a/lists/lists.go +++ b/lists/lists.go @@ -16,6 +16,11 @@ License along with this library. See the file LICENSE included with this distribution for more information. */ +// Package lists provides abstract List interface for that all concrete lists should implement. +// +// In computer science, a list or sequence is an abstract data type that represents an ordered sequence of values, where the same value may occur more than once. An instance of a list is a computer representation of the mathematical concept of a finite sequence; the (potentially) infinite analog of a list is a stream. Lists are a basic example of containers, as they contain other values. If the same value occurs multiple times, each occurrence is considered a distinct item. +// +// Reference: https://en.wikipedia.org/wiki/List_%28abstract_data_type%29 package lists import ( diff --git a/lists/singlylinkedlist/singlylinkedlist.go b/lists/singlylinkedlist/singlylinkedlist.go index baf028c..953ab8b 100644 --- a/lists/singlylinkedlist/singlylinkedlist.go +++ b/lists/singlylinkedlist/singlylinkedlist.go @@ -24,10 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -// Implementation of doubly linked list. +// Package singlylinkedlist implements the singly-linked list. +// // Structure is not thread safe. -// References: http://en.wikipedia.org/wiki/Linked_list#Singly_linked_list - +// +// Reference: https://en.wikipedia.org/wiki/List_%28abstract_data_type%29 package singlylinkedlist import ( diff --git a/maps/hashmap/hashmap.go b/maps/hashmap/hashmap.go index 6ce3145..6cb8565 100644 --- a/maps/hashmap/hashmap.go +++ b/maps/hashmap/hashmap.go @@ -24,11 +24,13 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -// Implementation of unorder map backed by a hash table. +// Package hashmap implements a map backed by a hash table. +// // Elements are unordered in the map. +// // Structure is not thread safe. -// References: http://en.wikipedia.org/wiki/Associative_array - +// +// Reference: http://en.wikipedia.org/wiki/Associative_array package hashmap import ( diff --git a/maps/maps.go b/maps/maps.go index 2e82434..809f138 100644 --- a/maps/maps.go +++ b/maps/maps.go @@ -24,6 +24,17 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +// Package maps provides abstract Map interface for that all concrete maps should implement. +// +// In computer science, an associative array, map, symbol table, or dictionary is an abstract data type composed of a collection of (key, value) pairs, such that each possible key appears just once in the collection. +// +// Operations associated with this data type allow: +// - the addition of a pair to the collection +// - the removal of a pair from the collection +// - the modification of an existing pair +// - the lookup of a value associated with a particular key +// +// Reference: https://en.wikipedia.org/wiki/Associative_array package maps import "github.com/emirpasic/gods/containers" diff --git a/maps/treemap/treemap.go b/maps/treemap/treemap.go index 4b8558d..efa46e4 100644 --- a/maps/treemap/treemap.go +++ b/maps/treemap/treemap.go @@ -24,11 +24,13 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -// Implementation of order map backed by red-black tree. +// Package treemap implements a map backed by red-black tree. +// // Elements are ordered by key in the map. +// // Structure is not thread safe. -// References: http://en.wikipedia.org/wiki/Associative_array - +// +// Reference: http://en.wikipedia.org/wiki/Associative_array package treemap import ( diff --git a/sets/hashset/hashset.go b/sets/hashset/hashset.go index 41b78c7..e3f44c7 100644 --- a/sets/hashset/hashset.go +++ b/sets/hashset/hashset.go @@ -24,10 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -// Implementation of set backed by a hash table. +// Package hashset implements a set backed by a hash table. +// // Structure is not thread safe. +// // References: http://en.wikipedia.org/wiki/Set_%28abstract_data_type%29 - package hashset import ( diff --git a/sets/sets.go b/sets/sets.go index fd4fc08..af4aa22 100644 --- a/sets/sets.go +++ b/sets/sets.go @@ -16,6 +16,11 @@ License along with this library. See the file LICENSE included with this distribution for more information. */ +// Package sets provides abstract Set interface for that all concrete sets should implement. +// +// In computer science, a set is an abstract data type that can store certain values and no repeated values. It is a computer implementation of the mathematical concept of a finite set. Unlike most other collection types, rather than retrieving a specific element from a set, one typically tests a value for membership in a set. +// +// Reference: https://en.wikipedia.org/wiki/Set_%28abstract_data_type%29 package sets import "github.com/emirpasic/gods/containers" diff --git a/sets/treeset/treeset.go b/sets/treeset/treeset.go index 7b09138..a1b8ee9 100644 --- a/sets/treeset/treeset.go +++ b/sets/treeset/treeset.go @@ -16,10 +16,11 @@ License along with this library. See the file LICENSE included with this distribution for more information. */ -// Implementation of an ordered set backed by a red-black tree. +// Package treeset implements a tree backed by a red-black tree. +// // Structure is not thread safe. -// References: http://en.wikipedia.org/wiki/Set_%28abstract_data_type%29 - +// +// Reference: http://en.wikipedia.org/wiki/Set_%28abstract_data_type%29 package treeset import ( diff --git a/stacks/arraystack/arraystack.go b/stacks/arraystack/arraystack.go index 1e69adc..caacf4d 100644 --- a/stacks/arraystack/arraystack.go +++ b/stacks/arraystack/arraystack.go @@ -24,10 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -// Implementation of stack backed by ArrayList. +// Package arraystack implements a stack backed by array list. +// // Structure is not thread safe. -// References: http://en.wikipedia.org/wiki/Stack_%28abstract_data_type%29 - +// +// Reference: https://en.wikipedia.org/wiki/Stack_%28abstract_data_type%29#Array package arraystack import ( diff --git a/stacks/linkedliststack/linkedliststack.go b/stacks/linkedliststack/linkedliststack.go index 843e159..858033e 100644 --- a/stacks/linkedliststack/linkedliststack.go +++ b/stacks/linkedliststack/linkedliststack.go @@ -24,11 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -// Implementation of stack backed by our singly linked list. -// Used by red-black tree during in-order traversal. +// Package linkedliststack implements a stack backed by a singly-linked list. +// // Structure is not thread safe. -// References: http://en.wikipedia.org/wiki/Stack_%28abstract_data_type%29 - +// +// Reference:https://en.wikipedia.org/wiki/Stack_%28abstract_data_type%29#Linked_list package linkedliststack import ( diff --git a/stacks/stacks.go b/stacks/stacks.go index ceaf6f1..749bd3f 100644 --- a/stacks/stacks.go +++ b/stacks/stacks.go @@ -24,6 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +// Package stacks provides abstract Stack interface for that all concrete stacks should implement. +// +// In computer science, a stack is an abstract data type that serves as a collection of elements, with two principal operations: push, which adds an element to the collection, and pop, which removes the most recently added element that was not yet removed. The order in which elements come off a stack gives rise to its alternative name, LIFO (for last in, first out). Additionally, a peek operation may give access to the top without modifying the stack. +// +// Reference: https://en.wikipedia.org/wiki/Stack_%28abstract_data_type%29 package stacks import "github.com/emirpasic/gods/containers" diff --git a/trees/binaryheap/binaryheap.go b/trees/binaryheap/binaryheap.go index 8a97d5a..2bad245 100644 --- a/trees/binaryheap/binaryheap.go +++ b/trees/binaryheap/binaryheap.go @@ -24,11 +24,13 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -// Implementation of binary heap backed by ArrayList. +// Package binaryheap implements a binary heap backed by array list. +// // Comparator defines this heap as either min or max heap. +// // Structure is not thread safe. +// // References: http://en.wikipedia.org/wiki/Binary_heap - package binaryheap import ( diff --git a/trees/redblacktree/redblacktree.go b/trees/redblacktree/redblacktree.go index abcdffd..adcd4ec 100644 --- a/trees/redblacktree/redblacktree.go +++ b/trees/redblacktree/redblacktree.go @@ -24,11 +24,13 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -// Implementation of Red-black tree. +// Package redblacktree implements a red-black tree. +// // Used by TreeSet and TreeMap. +// // Structure is not thread safe. +// // References: http://en.wikipedia.org/wiki/Red%E2%80%93black_tree - package redblacktree import ( diff --git a/trees/trees.go b/trees/trees.go index 055c308..069a880 100644 --- a/trees/trees.go +++ b/trees/trees.go @@ -24,6 +24,11 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +// Package trees provides abstract Tree interface for that all concrete trees should implement. +// +// In computer science, a tree is a widely used abstract data type (ADT) or data structure implementing this ADT that simulates a hierarchical tree structure, with a root value and subtrees of children with a parent node, represented as a set of linked nodes. +// +// Reference: https://en.wikipedia.org/wiki/Tree_%28data_structure%29 package trees import "github.com/emirpasic/gods/containers" diff --git a/utils/comparator.go b/utils/comparator.go index 6ce6829..7dfd698 100644 --- a/utils/comparator.go +++ b/utils/comparator.go @@ -29,10 +29,10 @@ package utils // Comparator will make type assertion (see IntComparator for example), // which will panic if a or b are not of the asserted type. // -// Should return: -// -1, if a < b -// 0, if a == b -// 1, if a > b +// Should return a number: +// negative , if a < b +// zero , if a == b +// positive , if a > b type Comparator func(a, b interface{}) int // IntComparator provides a basic comparison on ints diff --git a/utils/sort.go b/utils/sort.go index 3cf8c1f..154ce3d 100644 --- a/utils/sort.go +++ b/utils/sort.go @@ -24,14 +24,13 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -// Util methods for sorting a slice of values with respect to the comparator - package utils import "sort" -// Sort sorts values (in-place) -// Uses Go's sort (hybrid of quicksort for large and then insertion sort for smaller slices) +// Sort sorts values (in-place) with respect to the given comparator. +// +// Uses Go's sort (hybrid of quicksort for large and then insertion sort for smaller slices). func Sort(values []interface{}, comparator Comparator) { sort.Sort(sortable{values, comparator}) }