FunctionUtils.java

  1. /*
  2.  * Portions of this software was developed by employees of the National Institute
  3.  * of Standards and Technology (NIST), an agency of the Federal Government and is
  4.  * being made available as a public service. Pursuant to title 17 United States
  5.  * Code Section 105, works of NIST employees are not subject to copyright
  6.  * protection in the United States. This software may be subject to foreign
  7.  * copyright. Permission in the United States and in foreign countries, to the
  8.  * extent that NIST may hold copyright, to use, copy, modify, create derivative
  9.  * works, and distribute this software and its documentation without fee is hereby
  10.  * granted on a non-exclusive basis, provided that this notice and disclaimer
  11.  * of warranty appears in all copies.
  12.  *
  13.  * THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND, EITHER
  14.  * EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY
  15.  * THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF
  16.  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND FREEDOM FROM
  17.  * INFRINGEMENT, AND ANY WARRANTY THAT THE DOCUMENTATION WILL CONFORM TO THE
  18.  * SOFTWARE, OR ANY WARRANTY THAT THE SOFTWARE WILL BE ERROR FREE.  IN NO EVENT
  19.  * SHALL NIST BE LIABLE FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT,
  20.  * INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM,
  21.  * OR IN ANY WAY CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY,
  22.  * CONTRACT, TORT, OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY PERSONS OR
  23.  * PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED FROM, OR AROSE OUT
  24.  * OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR SERVICES PROVIDED HEREUNDER.
  25.  */

  27. package gov.nist.secauto.metaschema.core.metapath.function;

  29. import gov.nist.secauto.metaschema.core.metapath.ISequence;
  30. import gov.nist.secauto.metaschema.core.metapath.InvalidTypeMetapathException;
  31. import gov.nist.secauto.metaschema.core.metapath.TypeMetapathException;
  32. import gov.nist.secauto.metaschema.core.metapath.function.library.FnData;
  33. import gov.nist.secauto.metaschema.core.metapath.item.IItem;
  34. import gov.nist.secauto.metaschema.core.metapath.item.atomic.IAnyAtomicItem;
  35. import gov.nist.secauto.metaschema.core.metapath.item.atomic.IDecimalItem;
  36. import gov.nist.secauto.metaschema.core.metapath.item.atomic.INumericItem;
  37. import gov.nist.secauto.metaschema.core.util.ObjectUtils;

  39. import java.math.BigInteger;
  40. import java.math.MathContext;
  41. import java.util.List;

  43. import edu.umd.cs.findbugs.annotations.NonNull;
  44. import edu.umd.cs.findbugs.annotations.Nullable;

  46. public final class FunctionUtils {
  47.   public static final MathContext MATH_CONTEXT = MathContext.DECIMAL64;

  49.   private FunctionUtils() {
  50.     // disable
  51.   }

  53.   /**
  54.    * Converts a {@link INumericItem} value to an integer value.
  55.    *
  56.    * @param value
  57.    *          the value to convert
  58.    * @return the integer value
  59.    * @throws ArithmeticException
  60.    *           if the provided value will not exactly fit in an {@code int}
  61.    */
  62.   public static int asInteger(@NonNull INumericItem value) {
  63.     return asInteger(value.asInteger());
  64.   }

  66.   /**
  67.    * Converts a {@link BigInteger} value to an integer value.
  68.    *
  69.    * @param value
  70.    *          the value to convert
  71.    * @return the integer value
  72.    * @throws ArithmeticException
  73.    *           if the provided value will not exactly fit in an {@code int}
  74.    */
  75.   public static int asInteger(@NonNull BigInteger value) {
  76.     return value.intValueExact();
  77.   }

  79.   /**
  80.    * Converts a {@link INumericItem} value to a long value.
  81.    *
  82.    * @param value
  83.    *          the value to convert
  84.    * @return the long value
  85.    * @throws ArithmeticException
  86.    *           if the provided value will not exactly fit in an {@code long}
  87.    */
  88.   public static long asLong(@NonNull INumericItem value) {
  89.     return asLong(value.asInteger());
  90.   }

  92.   /**
  93.    * Converts a {@link BigInteger} value to a long value.
  94.    *
  95.    * @param value
  96.    *          the value to convert
  97.    * @return the long value
  98.    * @throws ArithmeticException
  99.    *           if the provided value will not exactly fit in an {@code long}
  100.    */
  101.   public static long asLong(@NonNull BigInteger value) {
  102.     return value.longValueExact();
  103.   }

  105.   /**
  106.    * Retrieves the first item in a sequence. If the sequence is empty, a
  107.    * {@link TypeMetapathException} exception is thrown. If requireSingleton is
  108.    * {@code true} and the sequence contains more than one item, a
  109.    * {@link TypeMetapathException} is thrown.
  110.    *
  111.    * @param <ITEM>
  112.    *          the item type to return derived from the provided sequence
  113.    * @param sequence
  114.    *          the sequence to retrieve the first item from
  115.    * @param requireSingleton
  116.    *          if {@code true} then a {@link TypeMetapathException} is thrown if
  117.    *          the sequence contains more than one item
  118.    * @return {@code null} if the sequence is empty, or the item otherwise
  119.    * @throws TypeMetapathException
  120.    *           if the sequence is empty, or contains more than one item and
  121.    *           requireSingleton is {@code true}
  122.    */
  123.   @NonNull
  124.   public static <ITEM extends IItem> ITEM requireFirstItem(@NonNull ISequence<ITEM> sequence,
  125.       boolean requireSingleton) {
  126.     if (sequence.isEmpty()) {
  127.       throw new InvalidTypeMetapathException(
  128.           null,
  129.           "Expected a non-empty sequence, but sequence was empty.");
  130.     }
  131.     List<ITEM> items = sequence.asList();
  132.     if (requireSingleton && items.size() != 1) {
  133.       throw new InvalidTypeMetapathException(
  134.           null,
  135.           String.format("sequence expected to contain one item, but found '%d'", items.size()));
  136.     }
  137.     return ObjectUtils.notNull(items.iterator().next());
  138.   }

  140.   /**
  141.    * Retrieves the first item in a sequence. If the sequence is empty, a
  142.    * {@code null} result is returned. If requireSingleton is {@code true} and the
  143.    * sequence contains more than one item, a {@link TypeMetapathException} is
  144.    * thrown.
  145.    *
  146.    * @param <ITEM>
  147.    *          the item type to return derived from the provided sequence
  148.    * @param sequence
  149.    *          the sequence to retrieve the first item from
  150.    * @param requireSingleton
  151.    *          if {@code true} then a {@link TypeMetapathException} is thrown if
  152.    *          the sequence contains more than one item
  153.    * @return {@code null} if the sequence is empty, or the item otherwise
  154.    * @throws TypeMetapathException
  155.    *           if the sequence contains more than one item and requireSingleton is
  156.    *           {@code true}
  157.    */
  158.   @Nullable
  159.   public static <ITEM extends IItem> ITEM getFirstItem(@NonNull ISequence<ITEM> sequence, boolean requireSingleton) {
  160.     @Nullable ITEM retval = null;
  161.     if (!sequence.isEmpty()) {
  162.       List<ITEM> items = sequence.asList();
  163.       if (requireSingleton && items.size() != 1) {
  164.         throw new InvalidTypeMetapathException(
  165.             null,
  166.             String.format("sequence expected to contain one item, but found '%d'", items.size()));
  167.       }
  168.       retval = items.iterator().next();
  169.     }
  170.     return retval;
  171.   }

  173.   /**
  174.    * Gets the first item of the provided sequence as a {@link INumericItem} value.
  175.    * If the sequence is empty, then a {@code null} value is returned.
  176.    *
  177.    * @param sequence
  178.    *          a Metapath sequence containing the value to convert
  179.    * @param requireSingleton
  180.    *          if {@code true} then a {@link TypeMetapathException} is thrown if
  181.    *          the sequence contains more than one item
  182.    * @return the numeric item value, or {@code null} if the result is an empty
  183.    *         sequence
  184.    * @throws TypeMetapathException
  185.    *           if the sequence contains more than one item, or the item cannot be
  186.    *           cast to a numeric value
  187.    *
  188.    */
  189.   @Nullable
  190.   public static INumericItem toNumeric(@NonNull ISequence<?> sequence, boolean requireSingleton) {
  191.     IItem item = getFirstItem(sequence, requireSingleton);
  192.     return item == null ? null : toNumeric(item);
  193.   }

  195.   /**
  196.    * Gets the provided item value as a {@link INumericItem} value.
  197.    *
  198.    * @param item
  199.    *          the value to convert
  200.    * @return the numeric item value
  201.    * @throws TypeMetapathException
  202.    *           if the sequence contains more than one item, or the item cannot be
  203.    *           cast to a numeric value
  204.    */
  205.   @NonNull
  206.   public static INumericItem toNumeric(@NonNull IItem item) {
  207.     // atomize
  208.     IAnyAtomicItem atomicItem = FnData.fnDataItem(item);
  209.     return toNumeric(atomicItem);
  210.   }

  212.   /**
  213.    * Gets the provided item value as a {@link INumericItem} value.
  214.    *
  215.    * @param item
  216.    *          the value to convert
  217.    * @return the numeric item value
  218.    * @throws TypeMetapathException
  219.    *           if the item cannot be cast to a numeric value
  220.    */
  221.   @NonNull
  222.   public static INumericItem toNumeric(@NonNull IAnyAtomicItem item) {
  223.     try {
  224.       return IDecimalItem.cast(item);
  225.     } catch (InvalidValueForCastFunctionException ex) {
  226.       throw new InvalidTypeMetapathException(item, ex.getLocalizedMessage(), ex);
  227.     }
  228.   }

  230.   /**
  231.    * Gets the provided item value as a {@link INumericItem} value. If the item is
  232.    * {@code null}, then a {@code null} value is returned.
  233.    *
  234.    * @param item
  235.    *          the value to convert
  236.    * @return the numeric item value
  237.    * @throws TypeMetapathException
  238.    *           if the item cannot be cast to a numeric value
  239.    */
  240.   @Nullable
  241.   public static INumericItem toNumericOrNull(@Nullable IAnyAtomicItem item) {
  242.     return item == null ? null : toNumeric(item);
  243.   }

  245.   @SuppressWarnings("unchecked")
  246.   @NonNull
  247.   public static <TYPE extends IItem> TYPE asType(@NonNull IItem item) {
  248.     return (TYPE) item;
  249.   }

  251.   @SuppressWarnings("unchecked")
  252.   @NonNull
  253.   public static <TYPE extends IItem> ISequence<TYPE> asType(@NonNull ISequence<?> sequence) {
  254.     return (ISequence<TYPE>) sequence;
  255.   }

  257.   @SuppressWarnings("unchecked")
  258.   @Nullable
  259.   public static <TYPE extends IItem> TYPE asTypeOrNull(@Nullable IItem item) {
  260.     return (TYPE) item;
  261.   }

  263.   @NonNull
  264.   public static <TYPE extends IItem> TYPE requireType(Class<TYPE> clazz, IItem item) {
  265.     if (item == null) {
  266.       throw new InvalidTypeMetapathException(
  267.           null,
  268.           String.format("Expected non-null type '%s', but the node was null.",
  269.               clazz.getName()));
  270.     } else if (!clazz.isInstance(item)) {
  271.       throw new InvalidTypeMetapathException(
  272.           item,
  273.           String.format("Expected type '%s', but the node was type '%s'.",
  274.               clazz.getName(),
  275.               item.getClass().getName()));
  276.     }
  277.     return FunctionUtils.asType(item);
  278.   }

  280.   @Nullable
  281.   public static <TYPE extends IItem> TYPE requireTypeOrNull(Class<TYPE> clazz, @Nullable IItem item) {
  282.     if (item == null || clazz.isInstance(item)) {
  283.       return FunctionUtils.asTypeOrNull(item);
  284.     }
  285.     throw new InvalidTypeMetapathException(
  286.         item,
  287.         String.format("Expected type '%s', but the node was type '%s'.",
  288.             clazz.getName(),
  289.             item.getClass().getName()));
  290.   }
  291. }
Created with JaCoCo 0.8.10.202304240956