1- # Fast Ordered Collections for Swift<br > Using In-Memory B-Trees
1+ # Fast Sorted Collections for Swift<br >Using In-Memory B-Trees
22
33[ ![ Swift 3.0] ( https://img.shields.io/badge/Swift-3.0-blue.svg )] ( https://swift.org )
44[ ![ License] ( https://img.shields.io/badge/licence-MIT-blue.svg )] ( https://github.com/lorentey/BTree/blob/master/LICENSE.md )
55[ ![ Platform] ( https://img.shields.io/badge/platforms-macOS%20∙%20iOS%20∙%20watchOS%20∙%20tvOS-blue.svg )] ( https://developer.apple.com/platforms/ )
66
77[ ![ Build Status] ( https://travis-ci.org/lorentey/BTree.svg?branch=master )] ( https://travis-ci.org/lorentey/BTree )
88[ ![ Code Coverage] ( https://codecov.io/github/lorentey/BTree/coverage.svg?branch=master )] ( https://codecov.io/github/lorentey/BTree?branch=master )
9- [ ![ Documented] ( https://img.shields.io/cocoapods/metrics/doc-percent/BTree.svg )] ( http://lorentey.github.io/BTree/api )
109
1110[ ![ Carthage compatible] ( https://img.shields.io/badge/Carthage-compatible-4BC51D.svg )] ( https://github.com/Carthage/Carthage )
1211[ ![ CocoaPod Version] ( https://img.shields.io/cocoapods/v/BTree.svg )] ( http://cocoapods.org/pods/BTree )
1514
1615* [ Overview] ( #overview )
1716* [ Reference Documentation] ( #api )
17+ * [ Optimizing Collections: The Book] ( #book )
1818* [ What Are B-Trees?] ( #what )
1919* [ Why In-Memory B-Trees?] ( #why )
2020* [ Laundry List of Issues with Standard Collection Types] ( #boo )
2525### <a name =" overview " >Overview</a >
2626
2727This project provides an efficient in-memory B-tree implementation in pure Swift, and several useful
28- ordered collection types that use B-trees for their underlying storage.
28+ sorted collection types that use B-trees for their underlying storage.
2929
30- - [ ` Map<Key, Value> ` ] [ Map ] implements an ordered mapping from unique comparable keys to arbitrary values.
30+ - [ ` Map<Key, Value> ` ] [ Map ] implements a sorted mapping from unique comparable keys to arbitrary values.
3131 It is like ` Dictionary ` in the standard library, but it does not require keys to be hashable,
3232 it has strong guarantees on worst-case performance, and it maintains its elements in a well-defined
3333 order.
@@ -40,13 +40,13 @@ ordered collection types that use B-trees for their underlying storage.
4040 removal of any subrange of elements, or extraction of an arbitrary sub-list are also
4141 operations with O(log(* n* )) complexity.
4242
43- - [ ` SortedSet<Element> ` ] [ SortedSet ] implements an ordered collection of unique comparable elements.
43+ - [ ` SortedSet<Element> ` ] [ SortedSet ] implements a sorted collection of unique comparable elements.
4444 It is like ` Set ` in the standard library, but lookup, insertion and removal of any element
4545 has logarithmic complexity. Elements in an ` SortedSet ` are kept sorted in ascending order.
4646 Operations working on full sets (such as taking the union, intersection or difference)
4747 can take as little as O(log(* n* )) time if the elements in the source sets aren't interleaved.
4848
49- - [ ` SortedBag<Element> ` ] [ SortedBag ] implements an ordered [ multiset] [ multiset ] with
49+ - [ ` SortedBag<Element> ` ] [ SortedBag ] implements a sorted [ multiset] [ multiset ] with
5050 comparable elements. This is a generalization of a set that allows multiple instances of the same value.
5151 (The standard library does not include such a collection, although you can use a dictionary to emulate one
5252 by storing the multiplicities of the keys as values.)
@@ -55,7 +55,7 @@ ordered collection types that use B-trees for their underlying storage.
5555 ` SortedBag ` operations have the same time complexities as the equivalent operations in ` SortedSet ` .
5656
5757- [ ` BTree<Key, Value> ` ] [ BTree ] is the underlying primitive collection that serves as base storage
58- for all of the above collections. It is a general key-value store with full support
58+ for all of the above collections. It is a general sorted key-value store with full support
5959 for elements with duplicate keys; it provides a sum of all operations individually provided
6060 by the higher-level abstractions above (and more!).
6161
@@ -82,9 +82,22 @@ embedded in its source code.
8282
8383[ doc ] : http://lorentey.github.io/BTree/api
8484
85+ ### <a name =" book " >[ Optimizing Collections: The Book] [ OptimizingCollections ] </a >
86+
87+ If you want to learn more about how this package works, the book
88+ [ Optimizing Collections] [ OptimizingCollections ] includes detailed explanations of
89+ many of the algorithms and optimization tricks implemented by this package – and so, so much more.
90+ It is written by the same author, and published by the fine folks at objc.io.
91+ Buying a copy of the book is not only a nice way to support this project, it also gets you something quite interesting to read.
92+ Win-win!
93+
94+ [ ![ Optimizing Collections (eBook)] ( docs/images/OptimizingCollections.png )] [ OptimizingCollections ]
95+
96+ [ OptimizingCollections ] : https://www.objc.io/books/optimizing-collections/
97+
8598### <a name =" what " >What Are B-Trees?</a >
8699
87- [ B-trees] [ B-tree wiki ] are search trees that provide an ordered key-value store with excellent performance
100+ [ B-trees] [ B-tree wiki ] are search trees that provide a sorted key-value store with excellent performance
88101characteristics. In essence, each node maintains a sorted array of its own elements, and
89102another array for its children. The tree is kept balanced by three constraints:
90103
@@ -98,7 +111,7 @@ B-trees have huge nodes: nodes often contain hundreds (or even thousands) of key
98111This module implements a "vanilla" B-tree where every node contains full key-value pairs.
99112(The other popular type is the [ B+-tree] [ b-plus tree ] where only leaf nodes contain values;
100113internal nodes contain only copies of keys.
101- This often makes more sense on an external storage device with a fixed block size, but it is less useful for
114+ This often makes more sense on an external storage device with a fixed block size, but it seems less useful for
102115an in-memory implementation.)
103116
104117Each node in the tree also maintains the count of all elements under it.
@@ -144,7 +157,7 @@ For example, using a single array to hold a sorted list of items has quite horri
144157complexity when there are many elements. However, up to a certain maximum size, a simple array is in fact
145158the most efficient way to represent a sorted list.
146159
147- ![ Typical benchmark results for ordered collections] ( http://lorentey.github.io/BTree/ images/Ordered %20Collections%20in%20Swift.png)
160+ ![ Typical benchmark results for sorted collections] ( docs/ images/Sorted %20Collections%20in%20Swift.png)
148161
149162The benchmark above demonstrates this really well: insertion of * n* elements into a sorted array
150163costs O(n^2) when there are many items, but for many reasonably sized data sets, it is still much faster
@@ -225,7 +238,7 @@ is fiddling around with loading pointer values and dereferencing them.
225238So it makes perfect sense to employ B-trees as an in-memory data structure.
226239
227240Think about this, though: how many times do you need to work with a hundred thousand
228- ordered items in a typical app? Or even twenty thousand? Or even just two thousand? The most interesting
241+ sorted items in a typical app? Or even twenty thousand? Or even just two thousand? The most interesting
229242benefits of B-trees often occur at element counts well over a hundred thousand.
230243However, B-trees are not much slower than arrays for low element counts (remember, they * are* arrays in that
231244case), so it makes sense to use them when there's even a slight chance that the count will get large.
@@ -486,7 +499,7 @@ Let's enumerate:
486499[ BTree.unsorted-load ] : http://lorentey.github.io/BTree/api/Structs/BTree.html#/s:FV5BTree5BTreecuRd__s8SequenceWd__8Iterator7Element_zTxq__rFTqd__14dropDuplicatesSb5orderSi_GS0_xq__
487500
488501- The package contains O(log(n)) methods to [ extract a range of elements as a new B-tree] [ BTree.subtree ]
489- and to [ insert a B-tree into another B-tree] [ BTreeCursor.insertTree ] . (Keys need to remain ordered
502+ and to [ insert a B-tree into another B-tree] [ BTreeCursor.insertTree ] . (Keys need to remain sorted
490503 correctly, though.)
491504
492505- Merge operations (such as [ ` BTree.union ` ] [ BTree.union ] and [ ` BTree.symmetricDifference ` )] [ BTree.symmetricDifference ]
0 commit comments