001/*
002 * Portions of this software was developed by employees of the National Institute
003 * of Standards and Technology (NIST), an agency of the Federal Government and is
004 * being made available as a public service. Pursuant to title 17 United States
005 * Code Section 105, works of NIST employees are not subject to copyright
006 * protection in the United States. This software may be subject to foreign
007 * copyright. Permission in the United States and in foreign countries, to the
008 * extent that NIST may hold copyright, to use, copy, modify, create derivative
009 * works, and distribute this software and its documentation without fee is hereby
010 * granted on a non-exclusive basis, provided that this notice and disclaimer
011 * of warranty appears in all copies.
012 *
013 * THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND, EITHER
014 * EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY
015 * THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF
016 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND FREEDOM FROM
017 * INFRINGEMENT, AND ANY WARRANTY THAT THE DOCUMENTATION WILL CONFORM TO THE
018 * SOFTWARE, OR ANY WARRANTY THAT THE SOFTWARE WILL BE ERROR FREE.  IN NO EVENT
019 * SHALL NIST BE LIABLE FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT,
020 * INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM,
021 * OR IN ANY WAY CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY,
022 * CONTRACT, TORT, OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY PERSONS OR
023 * PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED FROM, OR AROSE OUT
024 * OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR SERVICES PROVIDED HEREUNDER.
025 */
026
027package gov.nist.secauto.metaschema.core.metapath.function;
028
029import gov.nist.secauto.metaschema.core.metapath.ISequence;
030import gov.nist.secauto.metaschema.core.metapath.InvalidTypeMetapathException;
031import gov.nist.secauto.metaschema.core.metapath.TypeMetapathException;
032import gov.nist.secauto.metaschema.core.metapath.function.library.FnData;
033import gov.nist.secauto.metaschema.core.metapath.item.IItem;
034import gov.nist.secauto.metaschema.core.metapath.item.atomic.IAnyAtomicItem;
035import gov.nist.secauto.metaschema.core.metapath.item.atomic.IDecimalItem;
036import gov.nist.secauto.metaschema.core.metapath.item.atomic.INumericItem;
037import gov.nist.secauto.metaschema.core.util.ObjectUtils;
038
039import java.math.BigInteger;
040import java.math.MathContext;
041import java.util.List;
042
043import edu.umd.cs.findbugs.annotations.NonNull;
044import edu.umd.cs.findbugs.annotations.Nullable;
045
046public final class FunctionUtils {
047  public static final MathContext MATH_CONTEXT = MathContext.DECIMAL64;
048
049  private FunctionUtils() {
050    // disable
051  }
052
053  /**
054   * Converts a {@link INumericItem} value to an integer value.
055   *
056   * @param value
057   *          the value to convert
058   * @return the integer value
059   * @throws ArithmeticException
060   *           if the provided value will not exactly fit in an {@code int}
061   */
062  public static int asInteger(@NonNull INumericItem value) {
063    return asInteger(value.asInteger());
064  }
065
066  /**
067   * Converts a {@link BigInteger} value to an integer value.
068   *
069   * @param value
070   *          the value to convert
071   * @return the integer value
072   * @throws ArithmeticException
073   *           if the provided value will not exactly fit in an {@code int}
074   */
075  public static int asInteger(@NonNull BigInteger value) {
076    return value.intValueExact();
077  }
078
079  /**
080   * Converts a {@link INumericItem} value to a long value.
081   *
082   * @param value
083   *          the value to convert
084   * @return the long value
085   * @throws ArithmeticException
086   *           if the provided value will not exactly fit in an {@code long}
087   */
088  public static long asLong(@NonNull INumericItem value) {
089    return asLong(value.asInteger());
090  }
091
092  /**
093   * Converts a {@link BigInteger} value to a long value.
094   *
095   * @param value
096   *          the value to convert
097   * @return the long value
098   * @throws ArithmeticException
099   *           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  }
104
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  }
139
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  }
172
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  }
194
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  }
211
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  }
229
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  }
244
245  @SuppressWarnings("unchecked")
246  @NonNull
247  public static <TYPE extends IItem> TYPE asType(@NonNull IItem item) {
248    return (TYPE) item;
249  }
250
251  @SuppressWarnings("unchecked")
252  @NonNull
253  public static <TYPE extends IItem> ISequence<TYPE> asType(@NonNull ISequence<?> sequence) {
254    return (ISequence<TYPE>) sequence;
255  }
256
257  @SuppressWarnings("unchecked")
258  @Nullable
259  public static <TYPE extends IItem> TYPE asTypeOrNull(@Nullable IItem item) {
260    return (TYPE) item;
261  }
262
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  }
279
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}