Cosmetic changes

README.md

@@ -1,11 +1,12 @@
 [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.cowwoc.requirements/java/badge.svg)](https://search.maven.org/search?q=g:com.github.cowwoc.requirements)
 [![build-status](../../workflows/Build/badge.svg)](../../actions?query=workflow%3ABuild)
 
-# <img src="docs/checklist.svg" width=64 height=64 alt="checklist"> Fluent API for Design Contracts
+# <img src="docs/checklist.svg" width=64 height=64 alt="checklist"> Requirements API
+## Fluent API for Design Contracts
 
 [![API](https://img.shields.io/badge/api_docs-5B45D5.svg)](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/)
 [![Changelog](https://img.shields.io/badge/changelog-A345D5.svg)](docs/Changelog.md)
-[![js](https://img.shields.io/badge/other%20languages-js-457FD5.svg)](../../../requirements.js)
+[![javascript, typescript](https://img.shields.io/badge/other%20languages-javascript,%20typescript-457FD5.svg)](../../../requirements.js)
 
 A [fluent API](https://en.m.wikipedia.org/docs/Fluent_interface) for enforcing
 [design contracts](https://en.wikipedia.org/docs/Design_by_contract) with
@@ -20,21 +21,21 @@ To get started, add this Maven dependency:
 ```xml
 
 <dependency>
-	<groupId>com.github.cowwoc.requirements</groupId>
-	<artifactId>java</artifactId>
-	<version>9.0.0</version>
+  <groupId>com.github.cowwoc.requirements</groupId>
+  <artifactId>java</artifactId>
+  <version>9.0.0</version>
 </dependency>
 ```
 
-You can learn about the API by using your IDE's auto-complete feature.
+`Designed for discovery using your favorite IDE's auto-complete feature.
 The main entry points are:
 
-* [requireThat(value, name)](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/DefaultJavaValidators.html#requireThat(T,java.lang.String))
-* [assumeThat(value, name)](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/DefaultJavaValidators.html#assumeThat(T,java.lang.String))
-* [checkIfThat(value, name)](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/DefaultJavaValidators.html#checkIf(T,java.lang.String))
-* [JavaValidators](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/JavaValidators.html)
+* [requireThat(value, name)](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/DefaultJavaValidators.html#requireThat(T,java.lang.String)) for preconditions
+* [assumeThat(value, name)](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/DefaultJavaValidators.html#assumeThat(T,java.lang.String)) for postconditions and class invariants
+* [checkIfThat(value, name)](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/DefaultJavaValidators.html#checkIf(T,java.lang.String)) for multiple failures and everything else
+* [JavaValidators](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/JavaValidators.html) for custom configurations
 
-The first three methods use a global configuration, while `JavaValidators` allows you to create a local
+The first three methods use a shared configuration, while `JavaValidators` allows you to create an independent
 configuration.
 
 See the [API documentation](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/) for more details.
@@ -48,23 +49,23 @@ import static com.github.cowwoc.requirements.java.DefaultJavaValidators.requireT
 
 public final class HelloWorldTest
 {
-	public static void main(String[] args)
-	{
-		// Preconditions
-		requireThat(args, "args").length().isPositive();
-
-		// Class invariants or method postconditions
-		assert assumeThat("args[0]", args[0]).isEqualTo("world").elseThrow();
-
-		// Return multiple validation failures at once
-		List<String> messages = checkIf(args, "args").isEmpty().
-			and(checkIf("args[0]", args[0]).isEqualTo("planet")).
-			elseGetMessages();
-		StringJoiner joiner = new StringJoiner("\n\n");
-		for (String message : messages)
-			joiner.add(message);
-		System.out.println("Multiple failures\n" + joiner.toString());
-	}
+  public static void main(String[] args)
+  {
+    // Preconditions
+    requireThat(args, "args").length().isPositive();
+
+    // Class invariants or method postconditions
+    assert assumeThat("args[0]", args[0]).isEqualTo("world").elseThrow();
+
+    // Return multiple validation failures at once
+    List<String> messages = checkIf(args, "args").isEmpty().
+      and(checkIf("args[0]", args[0]).isEqualTo("planet")).
+      elseGetMessages();
+    StringJoiner joiner = new StringJoiner("\n\n");
+    for (String message : messages)
+      joiner.add(message);
+    System.out.println("Multiple failures\n" + joiner.toString());
+  }
 }
 ```
 
@@ -102,7 +103,7 @@ This library offers the following features:
   once
 * [Nested validations](docs/Features.md#nested-validations) that allow you to validate complex objects
 * [String diff](docs/Features.md#string-diff) that shows the differences between two strings
-* [Performant and robust](docs/Performance.md) compared to other validation libraries
+* [Performant and robust](docs/Performance.md)
 
 ## Getting Started
 
@@ -112,16 +113,12 @@ The main entry points you should be aware of are:
 * [requireThat(value, name)](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/DefaultJavaValidators.html#requireThat(T,java.lang.String))
 * [assumeThat(value, name)](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/DefaultJavaValidators.html#assumeThat(T,java.lang.String))
 * [checkIfThat(value, name)](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/DefaultJavaValidators.html#checkIf(T,java.lang.String))
-* [JavaValidators](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/JavaValidators.html)
 
-The three static methods share a global configuration.
-`JavaValidators` contains a local configuration, which is useful if you want to use different configuration at
-once.
+The three static methods share the same configuration.
+To create an independent configuration, use [JavaValidators](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/JavaValidators.html).
 
 See the [API documentation](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/) for more details.
 
-## Performance Tips
-
 ## Best practices
 
 * Use `requireThat()` to verify the preconditions of public APIs.
@@ -136,7 +133,7 @@ See the [API documentation](https://cowwoc.github.io/requirements.java/9.0.0/doc
 
 ## Third-party libraries and tools
 
-This library supports the following 3rd-party libraries and tools:
+This library supports the following third-party libraries and tools:
 
 * [guava](docs/Supported_Libraries.md)
 * [IntelliJ IDEA](docs/Supported_Tools.md)

docs/Changelog.md

@@ -11,20 +11,23 @@ See https://github.com/cowwoc/requirements.java/commits/master for a full list.
         * This caused a “split package” error since only one module is allowed to export a package.
     3. Removed the use of native binaries. Colored DIFFs are still supported, but Windows requires the use of
        Windows Terminal (free download in Windows 10, built-in feature in Windows 11).
-    4. Improved performance by reducing memory usage and the frequency of GC runs.
-    5. Renamed `validateThat()` to `checkIf()`.
-    6. Renamed `assertThat()` to `assumeThat()`.
-    7. Added support for the built-in `assert` mechanism.
+    4. Renamed `validateThat()` to `checkIf()`.
+    5. Replaced `assertThat()` with `assert assumeThat().elseThrow()`.
+    6. Added support for the built-in `assert` mechanism.
         - Asserts can be used with any type of validator, but are typically used
           with `assumeThat().orElseThrow()` and `checkIf().orElseThrow()`.
-    8. Use consistent parameter ordering across the entire API: `(value, name)`
+    7. Use consistent parameter ordering across the entire API: `(value, name)`
         - Adding contextual information now looks like this: `requireThat().context(value, name)`
-    9. Added `Validator.apply(Consumer)` to nest validations, and `Validator.and(Validator)` to combine
+    8. Added `Validator.apply(Consumer)` to nest validations, and `Validator.and(Validator)` to combine
        validation results.
-    10. Added support for primitive types to avoid boxing when possible.
-    11. Dropped the `isOneOf()` and `isNotOneOf()` functionality yet again. I haven't figured out a good
+    9. Renamed `Validator.getActual()` to `getValue()`.
+    10. Replaced `isBetweenClosed(min, max)` with `isBetween(min, true, max, true)`.
+    11. Renamed `StringValidator.isInteger()` to `isInt()` and `isCharacter()` to `isChar()`.
+    12. Improved performance by reducing memory usage and the frequency of GC runs.
+    13. Added support for primitive types to avoid boxing when possible.
+    14. Dropped the `isOneOf()` and `isNotOneOf()` functionality yet again. I haven't figured out a good
         design for this yet.
-    12. Added `ObjectValidator.isX()` methods to downcast to known types.
+    15. Added `ObjectValidator.isX()` methods to downcast to known types.
 * Bugfixes:
     * `StringValidator/Verifier.asShort()`, `asInteger()` and `asLong()` were not handling the case where a
       string could not be converted to a number.

docs/Supported_Libraries.md

@@ -1,7 +1,14 @@
-Simply add a dependency for the module you are interested in, rebuild your project, and additional API methods
-will get generated
-inside [DefaultRequirements](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/DefaultRequirements.html)
-and [Requirements](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/Requirements.html):
+Each module uses a separate class pair for validation. For example, 
+[DefaultJavaValidators](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/java/DefaultJavaValidators.html)
+and
+[JavaValidators](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/java/JavaValidators.html)
+validate the core Java API. Similarly,
+[DefaultGuavaValidators](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/guava/DefaultGuavaValidators.html)
+and
+[GuavaValidators](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements/com/github/cowwoc/requirements/guava/GuavaValidators.html)
+validate the Guava API.
+
+The following table lists validators for third-party libraries: 
 
 | Library                                                       | Dependency |
 |---------------------------------------------------------------|------------|

java/src/main/java/com/github/cowwoc/requirements/java/DefaultJavaValidators.java

@@ -63,7 +63,7 @@
 /**
  * Creates validators for the Java API, using the default configuration.
  *
- * @see JavaValidators#newInstance() Creating a new instance with an independent configuration
+ * @see JavaValidators#newInstance() Creating an independent configuration
  */
 public final class DefaultJavaValidators
 {
@@ -2707,6 +2707,7 @@ public static InetAddressValidator checkIf(InetAddress value)
 	 * Returns the configuration used by new validators.
 	 *
 	 * @return the configuration used by new validators
+	 * @see JavaValidators#newInstance() Creating an independent configuration
 	 */
 	@CheckReturnValue
 	public static Configuration configuration()
@@ -2720,6 +2721,7 @@ public static Configuration configuration()
 	 * <b>NOTE</b>: Changes are only applied when {@link ConfigurationUpdater#close()} is invoked.
 	 *
 	 * @return the configuration updater
+	 * @see JavaValidators#newInstance() Creating an independent configuration
 	 */
 	@CheckReturnValue
 	public static ConfigurationUpdater updateConfiguration()

java/src/main/java/com/github/cowwoc/requirements/java/internal/util/ReentrantStampedLock.java

@@ -11,9 +11,14 @@
  */
 public final class ReentrantStampedLock
 {
+	private static void doNotUnlock()
+	{
+	}
+
 	// Excellent overview of StampedLock:
 	// https://www.javaspecialists.eu/talks/pdfs/2014%20JavaLand%20in%20Germany%20-%20%22Java%208%20From%20Smile%20To%20Tears%20-%20Emotional%20StampedLock%22%20by%20Heinz%20Kabutz.pdf
 	private final StampedLock lock = new StampedLock();
+
 	/**
 	 * The stamp associated with the current thread. {@code null} if none.
 	 */
@@ -26,8 +31,31 @@ public ReentrantStampedLock()
 	{
 	}
 
-	private static void doNotUnlock()
+	/**
+	 * @return true if the caller is holding an optimistic read-lock
+	 */
+	public boolean isOptimisticRead()
 	{
+		Long existingStamp = this.stamp.get();
+		return existingStamp != null && StampedLock.isOptimisticReadStamp(existingStamp);
+	}
+
+	/**
+	 * @return true if the caller is holding a read-lock
+	 */
+	public boolean isRead()
+	{
+		Long existingStamp = this.stamp.get();
+		return existingStamp != null && StampedLock.isReadLockStamp(existingStamp);
+	}
+
+	/**
+	 * @return true if the caller is holding a write-lock
+	 */
+	public boolean isWrite()
+	{
+		Long existingStamp = this.stamp.get();
+		return existingStamp != null && StampedLock.isWriteLockStamp(existingStamp);
 	}
 
 	/**