Deprecated RRB-Tree methods known to have bugs.

CHANGE_LOG.md

@@ -5,11 +5,12 @@ releases on the way from an old version to a new one.  Fix any deprecation warni
 release before upgrading to the next one.  The documentation next to each Deprecated annotation
 tells you what to use instead.  Once we delete the deprecated methods, that documentation goes too.
 
-### Release 3.5.7
+## Release 3.5.8 2020-10-06
  - Renamed all mutable collections from Mutable___ to Mut___ so they no longer conflict with Kotlin's StdLib.
  See script below to help you upgrade.
+ - Deprecated RRB-Tree join() and remove() methods until the bugs in them can be fixed.
  - Added jetbrains `@NotNull` and `@Nullable` annotations which  increased the size of the jar file by less than 3%.
- - Merged Kotlin-Friendly changes to master branch.  I have one less branch to keep patched.
+ - Merged Kotlin-Friendly changes to master branch and deleted that branch.
  - Use filterNonNull() Instead of .filter(Objects::nonNull) because sometimes IntelliJ
  gets confused about whether objects can be null in this case or not.
  - Fixed some nullability issues with the few varargs methods in this project.
@@ -53,18 +54,18 @@ After the above, you probably want to check out any Kotlin files.  Sorry.
 If you use MutableMap/MutableList/etc. inside a Kotlin file, you have to fix it manually.  Sorry.
 
 
-# Release 3.2.0: IllegalStateException
+## Release 3.2.0: IllegalStateException
  - Merged [kmark's](https://github.com/kmark) changes to ues IllegalStateException (extends RuntimeException) instead of IllegalAccessError (extends Error) in PersistentHashMap.
    IllegalAccessError was a holdover from the original Clojure source code and may have made sense in an earlier Java version, but IllegalStateException is a better choice today.
    Thank you, Kevin!
  - Updated test and plugin dependencies
  - Compiled with Java 11 (hence updating middle version number).
  - Fixed warnings
 
-# Release 3.1.3: Cowry (Copy-On Write aRraY)
+## Release 3.1.3: Cowry (Copy-On Write aRraY)
  - Made most Cowry methods public
 
-# Release 3.1.2: Heterogeneous RrbTree Fix
+## Release 3.1.2: Heterogeneous RrbTree Fix
  - Fixed a bug (reported by [fcurts](https://github.com/fcurts) - with unit test!) where Heterogeneous RrbTrees of more than 32 items
  would throw an exception at Runtime.  I had done something that in retrospect is obviously dumb.
  - Documented Cowry (Copy-On Write aRraY) better.

pom.xml

@@ -38,11 +38,11 @@ http://mvnrepository.com/artifact/org.organicdesign/Paguro
 	-->
 	<groupId>org.organicdesign</groupId>
 	<artifactId>Paguro</artifactId>
-	<version>3.5.7</version>
+	<version>3.5.8</version>
 	<packaging>jar</packaging>
 
-	<name>Paguro: Kotlin-Friendly</name>
-	<description>Immutable Clojure collections with transformations for Java 8+.  Classes renamed to not conflict with Kotlin.</description>
+	<name>Paguro</name>
+	<description>Immutable Clojure collections and a Transformation abstraction for Java 8+, immutably, type-safely, and with good performance.</description>
 	<url>https://github.com/GlenKPeterson/Paguro</url>
 
 	<licenses>

src/main/java/org/organicdesign/fp/collections/RrbTree.java

@@ -268,9 +268,11 @@ void debugValidate() {
         }
 
         /**
-         Joins the given tree to the right side of this tree (or this to the left side of that one) in
-         something like O(log n) time.
+         * THIS METHOD HAS BEEN SHOWN TO HAVE BUGS AND IS DEPRECATED UNTIL WE CAN FIX
+         * Joins the given tree to the right side of this tree (or this to the left side of that one) in
+         * something like O(log n) time.
          */
+        @Deprecated
         @SuppressWarnings("unchecked")
         public RrbTree<E> join(RrbTree<E> that) {
 
@@ -420,7 +422,7 @@ public RrbTree<E> join(RrbTree<E> that) {
 //                throw new IllegalStateException("Expected trees of equal height");
 //            }
 
-                @SuppressWarnings({"rawtypes", "unchecked"}) // Need raw types here.
+                @SuppressWarnings("unchecked") // Need raw types here.
                 Node<E>[] newRootArray = new Node[] {leftRoot, rightRoot};
                 int leftSize = leftRoot.size();
                 Node<E> newRoot =
@@ -472,6 +474,7 @@ public RrbTree<E> join(RrbTree<E> that) {
         }
 
         /** {@inheritDoc} */
+        @SuppressWarnings("deprecation")
         public MutRrbt<E> without(int index) { return (MutRrbt<E>) super.without(index); }
 
         @Override public int size() { return size; }
@@ -702,9 +705,11 @@ void debugValidate() {
         }
 
         /**
-         Joins the given tree to the right side of this tree (or this to the left side of that one)
-         in something like O(log n) time.
+         * THIS METHOD HAS BEEN SHOWN TO HAVE BUGS AND IS DEPRECATED UNTIL WE CAN FIX
+         * Joins the given tree to the right side of this tree (or this to the left side of that one) in
+         * something like O(log n) time.
          */
+        @Deprecated
         @SuppressWarnings("unchecked")
         public RrbTree<E> join(RrbTree<E> that) {
 
@@ -851,7 +856,7 @@ public RrbTree<E> join(RrbTree<E> that) {
 //                throw new IllegalStateException("Expected trees of equal height");
 //            }
 
-                @SuppressWarnings({"rawtypes", "unchecked"}) // Need raw types here.
+                @SuppressWarnings({"unchecked"}) // Need raw types here.
                 Node<E>[] newRootArray = new Node[] {leftRoot, rightRoot};
                 int leftSize = leftRoot.size();
                 Node<E> newRoot =
@@ -903,6 +908,7 @@ public RrbTree<E> join(RrbTree<E> that) {
 
 
         /** {@inheritDoc} */
+        @SuppressWarnings("deprecation")
         public ImRrbt<E> without(int index) { return (ImRrbt<E>) super.without(index); }
 
         @Override public int size() { return size; }
@@ -1047,9 +1053,11 @@ public RrbTree<E> join(RrbTree<? extends E> that)
   [1]: https://infoscience.epfl.ch/record/169879/files/RMTrees.pdf
 */
     /**
-     Joins the given tree to the right side of this tree (or this to the left side of that one) in
-     something like O(log n) time.
+     * THIS METHOD HAS BEEN SHOWN TO HAVE BUGS AND IS DEPRECATED UNTIL WE CAN FIX
+     * Joins the given tree to the right side of this tree (or this to the left side of that one) in
+     * something like O(log n) time.
      */
+    @Deprecated
     public abstract RrbTree<E> join(RrbTree<E> that);
 
     /** Internal method - do not use. */
@@ -1072,9 +1080,11 @@ one tree will be empty (but never null).
     abstract public Tuple2<? extends RrbTree<E>,? extends RrbTree<E>> split(int splitIndex);
 
     /**
-     Returns a new RrbTree minus the given item (all items to the right are shifted left one)
-     This is O(log n).
+     * THIS METHOD HAS BEEN SHOWN TO HAVE BUGS AND IS DEPRECATED UNTIL WE CAN FIX
+     * Returns a new RrbTree minus the given item (all items to the right are shifted left one)
+     * This is O(log n).
      */
+    @Deprecated
     public RrbTree<E> without(int index) {
         if ( (index > 0) && (index < size() - 1) ) {
             Tuple2<? extends RrbTree<E>,? extends RrbTree<E>> s1 = split(index);