Merge branch 'master' into avl_tree

Author: eulerkochy

.travis.yml

@@ -4,7 +4,6 @@ os:
   - linux
   - osx
 julia:
-  - 0.7
   - 1.0
   - nightly
 notifications:

Project.toml

@@ -1,12 +1,14 @@
 name = "DataStructures"
 uuid = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
-version = "0.17.17"
+version = "0.18.1"
 
 [deps]
+Compat = "34da2185-b29b-5c13-b0c7-acf172513d20"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
 
 [compat]
+Compat = "3.0.0"
 OrderedCollections = "1.1.0"
 julia = "1"
 

README.md

@@ -3,6 +3,7 @@
 [![Test Coverage](https://coveralls.io/repos/github/JuliaCollections/DataStructures.jl/badge.svg?branch=master)](https://coveralls.io/github/JuliaCollections/DataStructures.jl?branch=master)
 [![Test Coverage](https://codecov.io/github/JuliaCollections/DataStructures.jl/coverage.svg?branch=master)](https://codecov.io/github/JuliaCollections/DataStructures.jl?branch=master)
 [![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://juliacollections.github.io/DataStructures.jl/latest)
+[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
 
 DataStructures.jl
 =================
@@ -29,6 +30,7 @@ This package implements a variety of data structures, including
 -   DataStructures.IntSet
 -   SparseIntSet
 -   DiBitVector (in which each element can store two bits)
+-   Red Black Tree
 
 Resources
 ---------

appveyor.yml

@@ -1,6 +1,6 @@
 environment:
   matrix:
-  - julia_version: 0.7
+  - julia_version: 1.0
   - julia_version: latest
 
 platform:

benchmark/bench_heap.jl

@@ -26,13 +26,12 @@ heaptypes = [BinaryHeap, MutableBinaryHeap]
 aexps = [1,3]
 datatypes = [Int, Float64]
 baseorderings = Dict(
-    "Min" => DataStructures.LessThan,
-    #"Max" => DataStructures.GreaterThan,
+    "Min" => Base.ForwardOrdering,
+    #"Max" => Base.ReverseOrdering,
     )
 fastfloatorderings = Dict(
-    # These will be enabled upon reordering change
-    #"FastMin" => DataStructures.FasterForward(),
-    #"FastMax" => DataStructures.FasterReverse(),
+    "Min" => DataStructures.FasterForward,
+    "Max" => DataStructures.FasterReverse,
     )
 
 for heap in heaptypes
@@ -41,7 +40,8 @@ for heap in heaptypes
             Random.seed!(0)
             a = rand(dt, 10^aexp)
 
-            orderings = baseorderings
+            # Dict types to force use of abstract type if containing single value
+            orderings = Dict{String, DataType}(baseorderings)
             if dt == Float64
                 # swap to faster ordering operation
                 for (k,v) in orderings
@@ -66,38 +66,22 @@ for heap in heaptypes
     end
 end
 
-# Quick check to ensure no Float regressions with Min/Max convenience functions
-# These don't fit in well with the above loop, since ordering is hardcoded.
-heapalias = Dict(
-    "BinaryMinHeap" => BinaryMinHeap,
-    "BinaryMaxHeap" => BinaryMaxHeap,
-    "BinaryMinMaxHeap" => BinaryMinMaxHeap, # <- no alias issue
-)
-for (heapname, heap) in heapalias
-    for aexp in aexps
-        for dt in [Float64]
-            Random.seed!(0)
-            a = rand(dt, 10^aexp)
-            prepath = [heapname]
-            postpath = [string(dt), "10^"*string(aexp)]
-            suite[vcat(prepath, ["make"], postpath)] =
-                @benchmarkable $(heap)($a)
-            suite[vcat(prepath, ["push"], postpath)] =
-                @benchmarkable push_heap(h, $a) setup=(h=$(heap){$dt}())
-            suite[vcat(prepath, ["pop"], postpath)] =
-                @benchmarkable pop_heap(h) setup=(h=$(heap)($a))
-        end
-    end
-end
+fast_extreme_orderings = Dict(
+    nsmallest => DataStructures.FasterForward(),
+    nlargest => DataStructures.FasterReverse(),
+    )
 
 for func in [nlargest, nsmallest]
+    fastord = fast_extreme_orderings[func]
     for aexp in [4]
         Random.seed!(0);
         a = rand(10^aexp);
         for nexp in [2]
             n = 10^nexp
-            suite[[string(func), "a=rand(10^"*string(aexp)*")", "n=10^"*string(nexp)]] =
+            suite[["Slow " * string(func), "a=rand(10^"*string(aexp)*")", "n=10^"*string(nexp)]] =
                 @benchmarkable $(func)($n, $a)
+            suite[[string(func), "a=rand(10^"*string(aexp)*")", "n=10^"*string(nexp)]] =
+                @benchmarkable DataStructures.nextreme($fastord, $n, $a)
         end
     end
 end

docs/make.jl

@@ -25,6 +25,7 @@ makedocs(
         "intset.md",
         "sorted_containers.md",
         "dibit_vector.md",
+        "red_black_tree.md",
     ],
     modules = [DataStructures],
     format = Documenter.HTML()

docs/src/heaps.md

@@ -7,25 +7,32 @@ All heaps in this package are derived from `AbstractHeap`, and provide
 the following interface:
 
 ```julia
-# Let h be a heap, i be a handle, and v be a value.
+# Let `h` be a heap, `v` be a value, and `n` be an integer size
 
-length(h)         # returns the number of elements
+length(h)            # returns the number of elements
 
-isempty(h)        # returns whether the heap is empty
+isempty(h)           # returns whether the heap is empty
 
-push!(h, v)       # add a value to the heap
+push!(h, v)          # add a value to the heap
 
-top(h)            # return the top value of a heap
+first(h)             # return the first (top) value of a heap
 
-pop!(h)           # removes the top value, and returns it
+pop!(h)              # removes the first (top) value, and returns it
 
+extract_all!(h)      # removes all elements and returns sorted array
+
+extract_all_rev!(h)  # removes all elements and returns reverse sorted array
+
+sizehint!(h, n)      # reserve capacity for at least `n` elements
 ```
 
 Mutable heaps (values can be changed after being pushed to a heap) are
 derived from `AbstractMutableHeap <: AbstractHeap`, and additionally
 provides the following interface:
 
 ```julia
+# Let `h` be a heap, `i` be a handle, and `v` be a value.
+
 i = push!(h, v)              # adds a value to the heap and and returns a handle to v
 
 update!(h, i, v)             # updates the value of an element (referred to by the handle i)
@@ -54,6 +61,21 @@ h = MutableBinaryMinHeap([1,4,3,2])
 h = MutableBinaryMaxHeap([1,4,3,2])    # create a mutable min/max heap from a vector
 ```
 
+Heaps may be constructed with a custom ordering. One use case for custom orderings
+is to achieve faster performance with `Float` elements with the risk of random ordering
+if any elements are `NaN`. The provided `DataStructures.FasterForward` and
+`DataStructures.FasterReverse` orderings are optimized for this purpose.
+Custom orderings may also be used for defining the order of structs as heap elements.
+```julia
+h = BinaryHeap{Float64, DataStructures.FasterForward}() # faster min heap
+h = BinaryHeap{Float64, DataStructures.FasterReverse}() # faster max heap
+
+h = MutableBinaryHeap{Float64, DataStructures.FasterForward}() # faster mutable min heap
+h = MutableBinaryHeap{Float64, DataStructures.FasterReverse}() # faster mutable max heap
+
+h = BinaryHeap{MyStruct, MyStructOrdering}() # heap containing custom struct
+```
+
 ## Min-max heaps
 Min-max heaps maintain the minimum _and_ the maximum of a set,
 allowing both to be retrieved in constant (`O(1)`) time.
@@ -73,7 +95,7 @@ popmax!(h, k)  # remove and return the largest k elements
 popall!(h)     # remove and return all the elements, sorted smallest to largest
 popall!(h, o)  # remove and return all the elements according to ordering o
 ```
-The usual `top(h)` and `pop!(h)` are defined to be `minimum(h)` and `popmin!(h)`,
+The usual `first(h)` and `pop!(h)` are defined to be `minimum(h)` and `popmin!(h)`,
 respectively.
 
 This package includes an implementation of a binary min-max heap (`BinaryMinMaxHeap`).
@@ -97,5 +119,9 @@ nlargest(3, [0,21,-12,68,-25,14]) # => [68,21,14]
 nsmallest(3, [0,21,-12,68,-25,14]) # => [-25,-12,0]
 ```
 
-`nlargest(n, a)` is equivalent to `sort(a, lt = >)[1:min(n, end)]`, and
-`nsmallest(n, a)` is equivalent to `sort(a, lt = <)[1:min(n, end)]`.
+Note that if the array contains floats and is free of NaN values,
+then the following alternatives may be used to achieve a 2x performance boost.
+```
+DataStructures.nextreme(DataStructures.FasterReverse(), n, a) # faster nlargest(n, a)
+DataStructures.nextreme(DataStructures.FasterForward(), n, a) # faster nsmallest(n, a)
+```

docs/src/index.md

@@ -14,14 +14,15 @@ This package implements a variety of data structures, including
 -   Binary Heap
 -   Mutable Binary Heap
 -   Ordered Dicts and Sets
--   RobinDict (implemented with [Robin Hood Hashing](https://cs.uwaterloo.ca/research/tr/1986/CS-86-14.pdf))
+-   RobinDict and OrderedRobinDict (implemented with [Robin Hood Hashing](https://cs.uwaterloo.ca/research/tr/1986/CS-86-14.pdf))
 -   Dictionaries with Defaults
 -   Trie
 -   Linked List and Mutable Linked List
 -   Sorted Dict, Sorted Multi-Dict and Sorted Set
 -   DataStructures.IntSet
 -   SparseIntSet
 -   DiBitVector
+-   Red Black Tree
 
 ## Contents
 
@@ -46,6 +47,7 @@ Pages = [
     "intset.md",
     "sorted_containers.md",
     "sparse_int_set.md",
-    "dibit_vector.md"
+    "dibit_vector.md",
+    "red_black_tree.md"
 ]
 ```

docs/src/red_black_tree.md

@@ -0,0 +1,34 @@
+```@meta
+DocTestSetup = :(using DataStructures)
+```
+
+# Red Black Tree
+
+The `RBTree` type is an implementation of Red Black Tree in Julia. It is a self-balancing binary search tree with an extra bit of information, the color, in each of its node. Operations such as search, insert and delete can be done in `O(log n)` complexity, where `n` is the number of nodes in the `RBTree`.
+
+Examples:
+
+```jldoctest
+julia> tree = RBTree{Int}();
+
+julia> for k in 1:2:20
+           push!(tree, k)
+       end
+
+julia> haskey(tree, 3)
+true
+
+julia> tree[4]
+7
+
+julia> for k in 1:2:10
+           delete!(tree, k)
+       end
+
+julia> haskey(tree, 5)
+false
+```
+
+```@meta
+DocTestSetup = nothing
+```

docs/src/robin_dict.md

@@ -7,6 +7,7 @@ DocTestSetup = :(using DataStructures)
 `RobinDict` provides a standard dictionary, conforming to the AbstractDict protocol, which uses the Robin Hood hashing algorithm with backward-shift deletion to provide improved average performance over Dict.
 
 The interface of `RobinDict` replicates that of `Dict`.
+This has an ordered version called `OrderedRobinDict`, which replicates the interface of `OrderedDict`.
 
 Examples: