{"id":13564852,"url":"https://github.com/timtadh/data-structures","last_synced_at":"2025-06-29T18:05:11.237Z","repository":{"id":12451537,"uuid":"15112139","full_name":"timtadh/data-structures","owner":"timtadh","description":"Go datastructures.","archived":false,"fork":false,"pushed_at":"2022-10-07T08:55:56.000Z","size":1251,"stargazers_count":417,"open_issues_count":3,"forks_count":81,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-04-03T21:36:34.643Z","etag":null,"topics":["arraylist","avl","avl-tree","btree","data-structures","error-handling","exceptions","hash-tables","hashtable","immutable","linear-hash-table","linked-list","priority-queue","ternary-search-trie","tree","trie"],"latest_commit_sha":null,"homepage":"http://hackthology.com/data-structures/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/timtadh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-12-11T16:13:38.000Z","updated_at":"2025-01-23T02:36:15.000Z","dependencies_parsed_at":"2022-07-15T11:30:33.018Z","dependency_job_id":null,"html_url":"https://github.com/timtadh/data-structures","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/timtadh/data-structures","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timtadh%2Fdata-structures","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timtadh%2Fdata-structures/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timtadh%2Fdata-structures/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timtadh%2Fdata-structures/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timtadh","download_url":"https://codeload.github.com/timtadh/data-structures/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timtadh%2Fdata-structures/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262642953,"owners_count":23341817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arraylist","avl","avl-tree","btree","data-structures","error-handling","exceptions","hash-tables","hashtable","immutable","linear-hash-table","linked-list","priority-queue","ternary-search-trie","tree","trie"],"created_at":"2024-08-01T13:01:37.021Z","updated_at":"2025-06-29T18:05:11.121Z","avatar_url":"https://github.com/timtadh.png","language":"Go","readme":"# Go Data Structures\n\nby Tim Henderson (tim.tadh@gmail.com)\n\nCopyright 2013, Licensed under the BSD 3-clause license. Please reach out to me\ndirectly if you require another licensing option. I am willing to work with you.\n\n## Purpose\n\nTo collect many important data structures for usage in go programs. Golang's\nstandard library lacks many useful and important structures. This library\nattempts to fill the gap. I have implemented data-structure's as I have needed\nthem. If there is a missing structure or even just a missing (or incorrect)\nmethod open an issue, send a pull request, or send an email patch.\n\nThe library also provides generic\n[types](https://godoc.org/github.com/timtadh/data-structures/types) to allow the\nuser to swap out various data structures transparently. The interfaces provide\noperation for adding, removing, retrieving objects from collections as well as\niterating over the collection using functional iterators.\n\nThe tree sub-package provides a variety of generic tree traversals. The tree\ntraversals and other iterators in the package use a functional iteration\ntechnique [detailed on my blog](\nhttp://hackthology.com/functional-iteration-in-go.html).\n\nI hope you find my library useful. If you are using it drop me a line I would\nlove to hear about it.\n\n# Current Collection\n\n[![GoDoc](https://godoc.org/github.com/timtadh/data-structures?status.svg)](https://godoc.org/github.com/timtadh/data-structures)\n\n## Lists\n\n### Doubly Linked List [`linked.LinkedList`](https://godoc.org/github.com/timtadh/data-structures/linked#LinkedList)\n\nA simple an extensible doubly linked list. It is\n[Equatable](https://godoc.org/github.com/timtadh/data-structures/types#Equatable)\n[Sortable](https://godoc.org/github.com/timtadh/data-structures/types#Sortable),\nand [Hashable](https://godoc.org/github.com/timtadh/data-structures/types#Hashable)\nas are the [Node](https://godoc.org/github.com/timtadh/data-structures/linked#Node)s.\n\n### Array List [`list.List`](https://godoc.org/github.com/timtadh/data-structures/list#List)\n\nSimilar to a Java ArrayList or a Python or Ruby \"list\". There is a version\n(called Sortable) which integrates with the `\"sort\"` package from the standard\nlibrary.\n\n### Sorted Array List [`list.Sorted`](https://godoc.org/github.com/timtadh/data-structures/list#Sorted)\n\nKeeps the ArrayList in sorted order for you.\n\n### Sorted Set [`set.SortedSet`](https://godoc.org/github.com/timtadh/data-structures/set#SortedSet)\n\nBuilt on top of `*list.Sorted`, it provides basic set operations. With\n`set.SortedSet` you don't have to write code re-implementing sets with the\n`map[type]` datatype. Supports: intersection, union, set difference and overlap\ntests.\n\n### Map Set [`set.MapSet`](https://godoc.org/github.com/timtadh/data-structures/set#MapSet)\n\nConstruct a\n[`types.Map`](https://godoc.org/github.com/timtadh/data-structures/types#Map)\nfrom any [`types.Set`](https://godoc.org/github.com/timtadh/data-structures/types#Set).\n\n### Set Map [`set.SetMap`](https://godoc.org/github.com/timtadh/data-structures/set#SetMap)\n\nConstruct a set from any\n[`types.Map`](https://godoc.org/github.com/timtadh/data-structures/types#Map).\n\n### Unique Deque [`linked.UniqueDeque`](https://godoc.org/github.com/timtadh/data-structures/linked#UniqueDeque)\n\nA double ended queue that only allows unique items inside. Constructed from a\ndoubly linked list and a linear hash table.\n\n### Fixed Size Lists\n\nBoth `list.List` and `list.Sorted` have alternative constructors which make them\nfixed size. This prevents them from growing beyond a certain size bound and is\nuseful for implementing other data structures on top of them.\n\n### Serialization\n\n`list.List`, `list.Sorted`, and `set.SortedSet` all can be serialized provided\ntheir contents can be serialized. They are therefore suitable for being sent\nover the wire. See this\n[example](https://github.com/timtadh/data-structures/blob/master/set/example_serialize_test.go)\nfor how to use the serialization.\n\n\n## Heaps and Priority Queues\n\n### Binary Heap [`heap/Heap`](https://godoc.org/github.com/timtadh/data-structures/heap#Heap)\n\nThis is a binary heap for usage as a priority queue. The priorities are given to\nitems in the queue on insertion and cannot be changed after insertion. It can be\nused as both a min heap and a max heap.\n\n### Unique Priority Queue [`heap/UniquePQ`](https://godoc.org/github.com/timtadh/data-structures/heap#UniquePQ)\n\nA priority queue which only allows unique entries.\n\n## Trees\n\n### AVL Tree [`tree/avl.AvlTree`](https://godoc.org/github.com/timtadh/data-structures/tree/avl#AvlTree)\n\nAn [AVL Tree](https://en.wikipedia.org/wiki/AVL_tree) is a height balanced\nbinary search tree. Insertion and retrieval are both O(log(n)) where n is the\nnumber items in the tree.\n\n### Immutable AVL Tree [`tree/avl.ImmutableAvlTree`](https://godoc.org/github.com/timtadh/data-structures/tree/avl#ImmutableAvlTree)\n\nThis version of the classic is immutable and should be thread safe due to\nimmutability. However, there is a performance hit:\n\n    BenchmarkAvlTree           10000            166657 ns/op\n    BenchmarkImmutableAvlTree   5000            333709 ns/op\n\n### Ternary Search Trie [`trie.TST`](https://godoc.org/github.com/timtadh/data-structures/trie#TST)\n\nA [ternary search trie](\nhttp://hackthology.com/ternary-search-tries-for-fast-flexible-string-search-part-1.html)\nis a symbol table specialized to byte strings.  Ternary Search Tries (TSTs)\nare a particularly fast version of the more common R-Way Trie. They utilize less\nmemory allowing them to store more data while still retaining all of the\nflexibility of the R-Way Trie. TSTs can be used to build a suffix tree for full\ntext string indexing by storing every suffix of each string in addition to the\nstring. However, even without storing all of the suffixes it is still a great\nstructure for flexible prefix searches. For instance, TSTs can be used to\nimplement extremely fast auto-complete functionality.\n\n### B+Tree [`tree/bptree.BpTree`](https://godoc.org/github.com/timtadh/data-structures/tree/bptree)\n\nA\n[B+Tree](http://hackthology.com/lessons-learned-while-implementing-a-btree.html)\nis a general symbol table usually used for database indices. This implementation\nis not currently thread safe. However, unlike many B+Trees it fully supports\nduplicate keys making it suitable for use as a Multi-Map. There is also a\nvariant which has unique keys, `bptree.BpMap`. B+Trees are storted and efficient\nto iterate over making them ideal choices for storing a large amount of data\nin sorted order. For storing a **very** large amount of data please utilize the\nfs2 version, [fs2/bptree](https://github.com/timtadh/fs2#b-tree). fs2 utilizes\nmemory mapped files in order to allow you to store more data than your computer\nhas RAM.\n\n## Hash Tables\n\n### Separate Chaining Hash Table [`hashtable.Hash`](https://godoc.org/github.com/timtadh/data-structures/hashtable#Hash)\n\nSee `hashtable/hashtable.go`. An implementation of the classic hash table with\nseparate chaining to handle collisions.\n\n### Linear Hash Table with AVL Tree Buckets [`hashtable.LinearHash`](https://godoc.org/github.com/timtadh/data-structures/hashtable#LinearHash)\n\nSee `hashtables/linhash.go`. An implementation of [Linear\nHashing](http://hackthology.com/linear-hashing.html), a technique usually used\nfor secondary storage hash tables. Often employed by databases and file systems\nfor hash indices. This version is mostly instructional see the [accompanying\nblog post](\nhttp://hackthology.com/an-in-memory-go-implementation-of-linear-hashing.html).\nIf you want a disk backed version check out my\n[file-structures](https://github.com/timtadh/file-structures) repository. See\nthe `linhash` directory.\n\n## Exceptions, Errors, and Testing\n\n### Errors [`errors`](https://godoc.org/github.com/timtadh/data-structures/errors)\n\nBy default, most errors in Go programs to not track where they were created.\nMany programmers quickly discover they need to have stack traces associated with\ntheir errors. This is a light weight package which adds stack traces to errors.\nIt also provides a very very simple logging function that reports where in your\ncode your printed out the log. This is not a full featured logging solution but\nrather a replacement for using fmt.Printf when debugging.\n\n### Test Support [`test`](https://godoc.org/github.com/timtadh/data-structures/test)\n\nThe test package provides two minimal assertions and a way to get random strings\nand data. It also seeds the math/rand number generator. I consider this to the\nbare minimum of what is often needed when testing go code particularly\ndata-structures. Since this package seeks to be entirely self contained with no\ndependencies no external testing package is used. This package is slowly being\nimproved to encompass more common functionality between the different tests.\n\n### Exceptions as a Library [`exc`](https://github.com/timtadh/data-structures/tree/master/exc)\n\n- [![GoDoc](https://godoc.org/github.com/timtadh/data-structures/exc?status.svg)](https://godoc.org/github.com/timtadh/data-structures/exc)\n- [Explanation of Implementation](http://hackthology.com/exceptions-for-go-as-a-library.html)\n- [Explanation of Inheritance](http://hackthology.com/object-oriented-inheritance-in-go.html)\n\nThe [`exc`](https://github.com/timtadh/data-structures/tree/master/exc) package\nprovides support for exceptions. They work very similarly to the way unchecked\nexceptions work in Java. They are built on top of the built-in `panic` and\n`recover` functions. See the README in the package for more information or\ncheckout the documentation. They should play nice with the usual way of handling\nerrors in Go and provide an easy way to create public APIs which return errors\nrather than throwing these non-standard exceptions.\n\n\n## Benchmarks\n\n**Note**: these benchmarsk are fairly old and probably not easy to understand.\nLook at the relative difference not the absolute numbers as they are misleading.\nEach benchmark does many operations per \"test\" which makes it difficult to\ncompare these numbers to numbers found elsewhere.\n\nBenchmarks Put + Remove\n\n    $ go test -v -bench '.*' \\\n    \u003e   github.com/timtadh/data-structures/hashtable\n    \u003e   github.com/timtadh/data-structures/tree/...\n    \u003e   github.com/timtadh/data-structures/trie\n\n    BenchmarkGoMap             50000             30051 ns/op\n    BenchmarkMLHash            20000             78840 ns/op\n    BenchmarkHash              20000             81012 ns/op\n    BenchmarkTST               10000            149985 ns/op\n    BenchmarkBpTree            10000            185134 ns/op\n    BenchmarkAvlTree           10000            193069 ns/op\n    BenchmarkImmutableAvlTree   5000            367602 ns/op\n    BenchmarkLHash              1000           2743693 ns/op\n\nBenchmarks Put\n\n    BenchmarkGoMap            100000             22036 ns/op\n    BenchmarkMLHash            50000             52104 ns/op\n    BenchmarkHash              50000             53426 ns/op\n    BenchmarkTST               50000             69852 ns/op\n    BenchmarkBpTree            20000             76124 ns/op\n    BenchmarkAvlTree           10000            142104 ns/op\n    BenchmarkImmutableAvlTree  10000            302196 ns/op\n    BenchmarkLHash              1000           1739710 ns/op\n\nThe performance of the in memory linear hash (MLHash) is slightly improved since\nthe [blog post](\nhttp://hackthology.com/an-in-memory-go-implementation-of-linear-hashing.html) do\nto the usage of an AVL Tree `tree/avltree.go` instead of an unbalanced binary\nsearch tree.\n\n# Related Projects\n\n- [fs2](https://github.com/timtadh/fs2) Memory mapped datastructures. A B+Tree,\n  a list, and a platform for implementing more.\n\n- [file-structures](https://github.com/timtadh/file-structures) The previous\n  version of fs2 of disk based file-structures. Also includes a linear virtual\n  hashing implementation.\n\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimtadh%2Fdata-structures","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimtadh%2Fdata-structures","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimtadh%2Fdata-structures/lists"}