Move empty and exists to ExistenceFunctions and document

fhirpath/src/main/java/au/csiro/pathling/fhirpath/function/ExistenceFunctions.java

@@ -1,8 +1,12 @@
 package au.csiro.pathling.fhirpath.function;
 
+import static java.util.Objects.nonNull;
+
 import au.csiro.pathling.fhirpath.collection.BooleanCollection;
+import au.csiro.pathling.fhirpath.collection.Collection;
 import au.csiro.pathling.fhirpath.validation.FhirPathFunction;
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 
 /**
  * Contains functions for evaluating the existence of elements in a collection.
@@ -15,6 +19,46 @@
 @SuppressWarnings("unused")
 public class ExistenceFunctions {
 
+  /**
+   * Returns {@code true} if the input collection has any elements (optionally filtered by the
+   * criteria), and {@code false} otherwise. This is the opposite of {@code empty()}, and as such is
+   * a shorthand for {@code empty().not()}. If the input collection is empty, the result is
+   * {@code false}.
+   * <p>
+   * Using the optional criteria can be considered a shorthand for
+   * {@code where(criteria).exists()}.
+   *
+   * @param input The input collection
+   * @param criteria The criteria to apply to the input collection
+   * @return A {@link BooleanCollection} containing the result
+   * @see <a
+   * href="https://build.fhir.org/ig/HL7/FHIRPath/#existscriteria--expression--boolean">FHIRPath
+   * Specification - exists</a>
+   */
+  @FhirPathFunction
+  @Nonnull
+  public static BooleanCollection exists(@Nonnull final Collection input,
+      @Nullable final CollectionTransform criteria) {
+    return BooleanLogicFunctions.not(empty(nonNull(criteria)
+                                           ? FilteringAndProjectionFunctions.where(input, criteria)
+                                           : input));
+
+  }
+
+  /**
+   * Returns {@code true} if the input collection is empty and {@code false} otherwise.
+   *
+   * @param input The input collection
+   * @return A {@link BooleanCollection} containing the result
+   * @see <a href="https://build.fhir.org/ig/HL7/FHIRPath/#empty--boolean">FHIRPath Specification -
+   * empty</a>
+   */
+  @FhirPathFunction
+  @Nonnull
+  public static BooleanCollection empty(@Nonnull final Collection input) {
+    return BooleanCollection.build(input.getColumn().empty());
+  }
+
   /**
    * Takes a collection of Boolean values and returns {@code true} if all the items are
    * {@code true}. If any items are {@code false}, the result is {@code false}.

fhirpath/src/main/java/au/csiro/pathling/fhirpath/function/StandardFunctions.java

@@ -71,17 +71,6 @@ public static Collection first(@Nonnull final Collection input) {
     return input.copyWith(input.getColumn().first());
   }
 
-  /**
-   * This function returns true if the input collection is empty.
-   *
-   * @param input the input collection
-   * @see <a href="https://pathling.csiro.au/docs/fhirpath/functions.html#empty">empty</a>
-   */
-  @FhirPathFunction
-  public static BooleanCollection empty(@Nonnull final Collection input) {
-    return BooleanCollection.build(input.getColumn().empty());
-  }
-
   /**
    * A function for aggregating data based on counting the number of rows within the result.
    *
@@ -120,23 +109,6 @@ public static StringCollection join(@Nonnull final StringCollection input,
     ));
   }
 
-  /**
-   * A function which is able to test whether the input collection is empty. It can also optionally
-   * accept an argument which can filter the input collection prior to applying the test.
-   *
-   * @param input the input collection
-   * @param criteria the criteria to apply to the input collection
-   * @see <a href="https://pathling.csiro.au/docs/fhirpath/functions.html#exists">exists</a>
-   */
-  @FhirPathFunction
-  public static BooleanCollection exists(@Nonnull final Collection input,
-      @Nullable final CollectionTransform criteria) {
-    return BooleanLogicFunctions.not(empty(nonNull(criteria)
-                                           ? FilteringAndProjectionFunctions.where(input, criteria)
-                                           : input));
-
-  }
-
   public static boolean isTypeSpecifierFunction(@Nonnull final String functionName) {
     return "ofType".equals(functionName) || "getReferenceKey".equals(functionName);
   }