*
 * <p>Advantages compared to {@code double[]}:
 *
 * <ul>
 *   <li>All the many well-known advantages of immutability (read <i>Effective Java</i>, third
 *       edition, Item 17).
 *   <li>Has the value-based (not identity-based) {@link #equals}, {@link #hashCode}, and {@link
 *       #toString} behavior you expect.
 *   <li>Offers useful operations beyond just {@code get} and {@code length}, so you don't have to

 * <p>The API of this class is designed to make it easy to achieve the following properties
 *
 * <ul>
 *   <li>Multiple events for the same listener are never dispatched concurrently.
 *   <li>Events for the different listeners are dispatched concurrently.
 *   <li>All events for a given listener dispatch on the provided {@link #executor}.
 *   <li>It is easy for the user to ensure that listeners are never invoked while holding locks.
 * </ul>
 *

   * IllegalStateException} if it is accessed in any way, with the following exceptions:
   *
   * <ul>
   *   <li>{@code view.equals(view)} evaluates to {@code true} (but any other `equals()` expression
   *       involving {@code view} will throw)
   *   <li>{@code hashCode()} does not throw
   *   <li>if {@code node} is re-added to the graph after having been removed, {@code view}'s
   *       behavior is undefined
   * </ul>
   *

 * actions taken by the java garbage collection system:
 *
 * <ul>
 *   <li>invoking the {@code finalize} methods of unreachable objects
 *   <li>clearing weak references to unreachable referents
 *   <li>enqueuing weak references to unreachable referents in their reference queue
 * </ul>
 *

   *       fail.
   *   <li>If the constructor or factory method takes a parameter that {@link
   *       AbstractPackageSanityTests} doesn't know how to construct, the test will fail.
   *   <li>If there is no visible constructor or visible static factory method declared by {@code
   *       C}, {@code C} is skipped for serialization test, even if it implements {@link
   *       Serializable}.

 * </pre>
 *
 * <p>Here are some examples of recognized formats:
 *
 * <ul>
 *   <li>example.com
 *   <li>example.com:80
 *   <li>192.0.2.1
 *   <li>192.0.2.1:80
 *   <li>[2001:db8::1] - {@link #getHost()} omits brackets
 *   <li>[2001:db8::1]:80 - {@link #getHost()} omits brackets
 *   <li>2001:db8::1 - Use {@link #requireBracketsForIPv6()} to prohibit this
 * </ul>
 *

 *   <li>Convert multiple instances "forward" using {@code converter.convertAll(as)}.
 *   <li>Convert in the "backward" direction using {@code converter.reverse().convert(b)} or {@code
 *       converter.reverse().convertAll(bs)}.
 *   <li>Use {@code converter} or {@code converter.reverse()} anywhere a {@link
 *       java.util.function.Function} is accepted (for example {@link java.util.stream.Stream#map
 *       Stream.map}).

 * Benchmarks (as of December 2011) show that:
 *
 * <ul>
 *   <li>for an unnested {@code lock()} and {@code unlock()}, a cycle detecting lock takes 38ns as
 *       opposed to the 24ns taken by a plain lock.
 *   <li>for nested locking, the cost increases with the depth of the nesting:
 *       <ul>
 *         <li>2 levels: average of 64ns per lock()/unlock()
 *         <li>3 levels: average of 77ns per lock()/unlock()

     * be able to accept <code>relative</code> parameter values that
     * <ul>
     * <li>use either / or \ file path separator,</li>
     * <li>have .. parent directory references,</li>
     * <li>point either at file or directory.</li>
     * </ul>
     *
     * @param relative is the path of the requested source relative to this source

 *
 * <ul>
 *   <li>An annotation named just "Suppress" might someday be treated by a non-Android tool as a
 *       suppression. This would follow the precedent of many of our annotation processors, which
 *       look for any annotation named, e.g., "GwtIncompatible," regardless of package.
 *   <li>An annotation named just "Suppress" might suggest to users that the test is suppressed