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}