Merge pull request #303 from dynatrace-oss/prg-improvements

PseudoRandomGenerator.reset returns self-reference, PseudoRandomGener…

.palantir/revapi.yml

@@ -100,6 +100,12 @@ acceptedBreaks:
       new: "method <T> long com.dynatrace.hash4j.hashing.HashStream64::resetAndHashToLong(T,\
         \ com.dynatrace.hash4j.hashing.HashFunnel<T>)"
       justification: "{added new methods}"
+  "0.19.0":
+    com.dynatrace.hash4j:hash4j:
+    - code: "java.method.returnTypeChanged"
+      old: "method void com.dynatrace.hash4j.random.PseudoRandomGenerator::reset(long)"
+      new: "method com.dynatrace.hash4j.random.PseudoRandomGenerator com.dynatrace.hash4j.random.PseudoRandomGenerator::reset(long)"
+      justification: "{return self-reference instead of void}"
   "0.7.1":
     com.dynatrace.hash4j:hash4j:
     - code: "java.class.noLongerImplementsInterface"

src/main/java/com/dynatrace/hash4j/random/PseudoRandomGenerator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 Dynatrace LLC
+ * Copyright 2022-2024 Dynatrace LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -47,8 +47,9 @@ public interface PseudoRandomGenerator {
    * Resets the pseudo-random generator using the given 64-bit seed value.
    *
    * @param seed the seed value
+   * @return this
    */
-  void reset(long seed);
+  PseudoRandomGenerator reset(long seed);
 
   /**
    * Returns a random uniformly distributed {@code double} value in the range [0, 1).

src/main/java/com/dynatrace/hash4j/random/PseudoRandomGeneratorProvider.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 Dynatrace LLC
+ * Copyright 2022-2024 Dynatrace LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,6 +25,16 @@ public interface PseudoRandomGeneratorProvider {
    */
   PseudoRandomGenerator create();
 
+  /**
+   * Creates a new {@link PseudoRandomGenerator} instance and sets a seed.
+   *
+   * @param seed the seed value
+   * @return the new pseudo-random generator instance
+   */
+  default PseudoRandomGenerator create(long seed) {
+    return create().reset(seed);
+  }
+
   /**
    * Returns a {@link PseudoRandomGeneratorProvider} based on the SplitMix64 algorithm.
    *

src/main/java/com/dynatrace/hash4j/random/SplitMix64V1.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 Dynatrace LLC
+ * Copyright 2022-2024 Dynatrace LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -44,7 +44,8 @@ public long nextLong() {
   }
 
   @Override
-  public void reset(long seed) {
+  public SplitMix64V1 reset(long seed) {
     this.state = seed;
+    return this;
   }
 }

src/test/java/com/dynatrace/hash4j/random/AbstractPseudoRandomGeneratorProviderTest.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2024 Dynatrace LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.dynatrace.hash4j.random;
+
+import org.assertj.core.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+public abstract class AbstractPseudoRandomGeneratorProviderTest {
+
+  protected abstract PseudoRandomGeneratorProvider getPseudoRandomGeneratorProvider();
+
+  @Test
+  void testCreateWithSeed() {
+    long seed = 0x668914708c9e7635L;
+    Assertions.assertThat(getPseudoRandomGeneratorProvider().create(seed).nextLong())
+        .isEqualTo(getPseudoRandomGeneratorProvider().create().reset(seed).nextLong());
+  }
+}

src/test/java/com/dynatrace/hash4j/random/PseudoRandomGeneratorProviderForTesting.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 Dynatrace LLC
+ * Copyright 2023-2024 Dynatrace LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -85,7 +85,9 @@ public int uniformInt(int exclusiveBound) {
       }
 
       @Override
-      public void reset(long seed) {}
+      public PseudoRandomGenerator reset(long seed) {
+        return this;
+      }
 
       @Override
       public double nextDouble() {

src/test/java/com/dynatrace/hash4j/random/SplitMix64_v1ProviderTest.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2024 Dynatrace LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.dynatrace.hash4j.random;
+
+public class SplitMix64_v1ProviderTest extends AbstractPseudoRandomGeneratorProviderTest {
+  @Override
+  protected PseudoRandomGeneratorProvider getPseudoRandomGeneratorProvider() {
+    return PseudoRandomGeneratorProvider.splitMix64_V1();
+  }
+}

src/test/java/com/dynatrace/hash4j/similarity/DistinctElementHashProviderTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 Dynatrace LLC
+ * Copyright 2022-2024 Dynatrace LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -125,9 +125,10 @@ public int uniformInt(int exclusiveBound) {
           }
 
           @Override
-          public void reset(long seed) {
+          public PseudoRandomGenerator reset(long seed) {
             prg.reset(seed);
             count = 0;
+            return this;
           }
 
           @Override