Following commit 9c4629dafc3aafc10f952824efd448700ad3363e, specify that hashing is deterministic and uses a specific algorithm.
--
MOS_MIGRATED_REVID=128070666
diff --git a/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java b/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java
index c108325..59690f4 100644
--- a/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java
+++ b/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java
@@ -1999,13 +1999,13 @@
};
@SkylarkSignature(name = "hash", returnType = Integer.class,
- doc = "Return a hash value for a string. Hash values of equal strings are always equal to "
- + "one another, but may change over different invocations of the Skylark interpreter. "
- + "Hashing of values besides strings is not currently supported.",
- // Java guarantees that Strings are hashed using a specific algorithm and are therefore
- // consistent across all invocations. Rather than re-export this promise to the user,
- // we'll just provide the same basic guarantee as Java and Python do for hashing any
- // kind of value.
+ doc = "Return a hash value for a string. This is computed deterministically using the same "
+ + "algorithm as Java's <code>String.hashCode()</code>, namely: "
+ + "<pre class=\"language-python\">s[0] * (31^(n-1)) + s[1] * (31^(n-2)) + ... + s[0]"
+ + "</pre> Hashing of values besides strings is not currently supported.",
+ // Deterministic hashing is important for the consistency of builds, hence why we
+ // promise a specific algorithm. This is in contrast to Java (Object.hashCode()) and
+ // Python, which promise stable hashing only within a given execution of the program.
parameters = {
@Param(name = "value", type = String.class,
doc = "String value to hash")
diff --git a/src/test/java/com/google/devtools/build/lib/syntax/MethodLibraryTest.java b/src/test/java/com/google/devtools/build/lib/syntax/MethodLibraryTest.java
index b93ce6e..725a21f 100644
--- a/src/test/java/com/google/devtools/build/lib/syntax/MethodLibraryTest.java
+++ b/src/test/java/com/google/devtools/build/lib/syntax/MethodLibraryTest.java
@@ -1485,9 +1485,7 @@
@Test
public void testHash() throws Exception {
- // This test is too strong, in that it tests whether the hash value of the string follows
- // Java's specific algorithm for Strings. If our hash implementation is changed then this
- // test will have to be modified.
+ // We specify the same string hashing algorithm as String.hashCode().
new SkylarkTest()
.testStatement("hash('skylark')", "skylark".hashCode())
.testStatement("hash('google')", "google".hashCode())
