001/** 002 * MutablePrimitive.java 003 * 004 * Copyright (c) 2004-2012, Nicole C. Tedesco. All rights reserved. 005 * 006 * Licensed under the Apache License, Version 2.0 (the "License"); 007 * you may not use this file except in compliance with the License. 008 * You may obtain a copy of the License at: 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, software 013 * distributed under the License is distributed on an "AS IS" BASIS, 014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 015 * See the License for the specific language governing permissions and 016 * limitations under the License. 017 */ 018 019package net.sf.jaccumulator.primitives; 020 021import java.math.BigDecimal; 022import java.math.BigInteger; 023 024import net.sf.jaccumulator.reals.MutableReal; 025import net.sf.jaccumulator.scalars.MutableScalar; 026import net.sf.jaccumulator.texts.MutableText; 027 028/** 029 * Write operations for system supported primitives. "Primitives", as defined in 030 * the UML 2.1 specification, are: 031 * <ul> 032 * <li>{@code boolean}</li> 033 * <li>{@code byte}</li> 034 * <li>{@code char}</li> 035 * <li>{@code int}</li> 036 * <li>{@code long}</li> 037 * <li>{@code float}</li> 038 * <li>{@code double}</li> 039 * <li>{@code short}</li> 040 * <li>unlimited {@link BigInteger integer}</li> 041 * <li>unlimited {@link BigDecimal decimal}</li> 042 * <li>{@link String text}</li> 043 * </ul> 044 * 045 * @param <PRIMITIVE> 046 * this type (used to facilitate operation chaining) 047 * @since JAccumulator 4.0 048 * @author Nicole Tedesco (<a 049 * href="mailto:Nicole@NicoleTedesco.com">Nicole@NicoleTedesco.com</a>) 050 */ 051public interface MutablePrimitive<PRIMITIVE extends MutablePrimitive<PRIMITIVE>> 052 extends 053 MutableText<PRIMITIVE>, 054 MutableReal<PRIMITIVE>, 055 MutableScalar<PRIMITIVE> 056{ 057 /** 058 * Set this value to the bit <b>and</b> of the <i>integral</i> boolean 059 * vector equivalent of this value and the specified integral boolean vector 060 * 061 * @param aValue 062 * an integral boolean vector 063 * @return this object (facilitates operation chaining) 064 * @throws UnsupportedOperationException 065 * if this object's value cannot be changed 066 * @throws IllegalArgumentException 067 * if the new value was incommensurate with this object's 068 * specification 069 * @throws ArithmeticException 070 * the new numeric value was incompatible with with algebraic 071 * interpretation of this object 072 */ 073 public PRIMITIVE andOfPrimitive( final SealedPrimitive<?> aValue ) 074 throws UnsupportedOperationException, 075 IllegalArgumentException, 076 ArithmeticException; 077 078 /** 079 * Set this value to the angle formed by the rectangular coordinates given 080 * by the current value, <i>x</i>, and the specified value, <i>y</i>. In 081 * other words returns the angle <i>theta</i> from the conversion of 082 * rectangular coordinates (x,y) to polar coordinates (r,<i>theta</i>). 083 * 084 * @param y 085 * a <i>y</i> coordinate value 086 * @return this object (facilitates operation chaining) 087 * @throws UnsupportedOperationException 088 * if this object's value cannot be changed 089 * @throws IllegalArgumentException 090 * if the new value was incommensurate with this object's 091 * specification 092 * @throws ArithmeticException 093 * the new numeric value was incompatible with with algebraic 094 * interpretation of this object 095 * @see Math#atan2(double, double) 096 */ 097 public PRIMITIVE angleWithPrimitive( final SealedPrimitive<?> y ) 098 throws UnsupportedOperationException, 099 IllegalArgumentException, 100 ArithmeticException; 101 102 /** 103 * Set the value of this scalar to the <i>mathematical</i> difference 104 * between its current value and the specified value. 105 * 106 * @param aValue 107 * a subtrahend 108 * @return this object (facilitates operation chaining) 109 * @throws UnsupportedOperationException 110 * if this object's value cannot be changed 111 * @throws IllegalArgumentException 112 * if the new value was incommensurate with this object's 113 * specification 114 * @throws ArithmeticException 115 * the new numeric value was incompatible with with algebraic 116 * interpretation of this object 117 */ 118 public PRIMITIVE differenceOfPrimitive( final SealedPrimitive<?> aValue ) 119 throws UnsupportedOperationException, 120 IllegalArgumentException, 121 ArithmeticException; 122 123 /** 124 * Set this value to the hypotenuse formed by the square root of the sum of 125 * the square of the current value, <i>x</i>, and the square of the 126 * specified value, <i>y</i>, without intermediate overflow or underflow 127 * 128 * @param y 129 * a <i>y</i> value 130 * @return this object (facilitates operation chaining) 131 * @throws UnsupportedOperationException 132 * if this object's value cannot be changed 133 * @throws IllegalArgumentException 134 * if the new value was incommensurate with this object's 135 * specification 136 * @throws ArithmeticException 137 * the new numeric value was incompatible with with algebraic 138 * interpretation of this object 139 * @see Math#hypot(double, double) 140 */ 141 public PRIMITIVE hypotenuseWithPrimitive( final SealedPrimitive<?> y ) 142 throws UnsupportedOperationException, 143 IllegalArgumentException, 144 ArithmeticException; 145 146 /** 147 * Set the value of this scalar to its current value <i>modulo</i> of the 148 * specified value 149 * 150 * @param aValue 151 * a modulus 152 * @return this object (facilitates operation chaining) 153 * @throws UnsupportedOperationException 154 * if this object's value cannot be changed 155 * @throws IllegalArgumentException 156 * if the new value was incommensurate with this object's 157 * specification 158 * @throws ArithmeticException 159 * the new numeric value was incompatible with with algebraic 160 * interpretation of this object 161 */ 162 public PRIMITIVE modOfPrimitive( final SealedPrimitive<?> aValue ) 163 throws UnsupportedOperationException, 164 IllegalArgumentException, 165 ArithmeticException; 166 167 /** 168 * Set this value to the bit <b>or</b> of the <i>integral</i> boolean vector 169 * equivalent of this value and the specified integral boolean vector 170 * 171 * @param aValue 172 * an integral boolean vector 173 * @return this object (facilitates operation chaining) 174 * @throws UnsupportedOperationException 175 * if this object's value cannot be changed 176 * @throws IllegalArgumentException 177 * if the new value was incommensurate with this object's 178 * specification 179 * @throws ArithmeticException 180 * the new numeric value was incompatible with with algebraic 181 * interpretation of this object 182 */ 183 public PRIMITIVE orOfPrimitive( final SealedPrimitive<?> aValue ) 184 throws UnsupportedOperationException, 185 IllegalArgumentException, 186 ArithmeticException; 187 188 /** 189 * Set this value to the current value, <i>x</i>, raised to the specified 190 * exponent, <i>n</i>, or <i>x<sup>n</sup></i> 191 * 192 * @param aValue 193 * an exponent 194 * @return this object (facilitates operation chaining) 195 * @throws UnsupportedOperationException 196 * if this object's value cannot be changed 197 * @throws IllegalArgumentException 198 * if the new value was incommensurate with this object's 199 * specification 200 * @throws ArithmeticException 201 * the new numeric value was incompatible with with algebraic 202 * interpretation of this object 203 */ 204 public PRIMITIVE powerOfPrimitive( final SealedPrimitive<?> aValue ) 205 throws UnsupportedOperationException, 206 IllegalArgumentException, 207 ArithmeticException; 208 209 /** 210 * Set the value of this scalar to the <i>mathematical</i> product of its 211 * current value and the specified value. 212 * 213 * @param aValue 214 * a multiplicand 215 * @return this object (facilitates operation chaining) 216 * @throws UnsupportedOperationException 217 * if this object's value cannot be changed 218 * @throws IllegalArgumentException 219 * if the new value was incommensurate with this object's 220 * specification 221 * @throws ArithmeticException 222 * the new numeric value was incompatible with with algebraic 223 * interpretation of this object 224 */ 225 public PRIMITIVE productOfPrimitive( final SealedPrimitive<?> aValue ) 226 throws UnsupportedOperationException, 227 IllegalArgumentException, 228 ArithmeticException; 229 230 /** 231 * Set the value of this scalar to the <i>mathematical</i> quotient between 232 * its current value and the specified value. 233 * 234 * @param aValue 235 * a divisor 236 * @return this object (facilitates operation chaining) 237 * @throws UnsupportedOperationException 238 * if this object's value cannot be changed 239 * @throws IllegalArgumentException 240 * if the new value was incommensurate with this object's 241 * specification 242 * @throws ArithmeticException 243 * the new numeric value was incompatible with with algebraic 244 * interpretation of this object 245 */ 246 public PRIMITIVE quotientOfPrimitive( final SealedPrimitive<?> aValue ) 247 throws UnsupportedOperationException, 248 IllegalArgumentException, 249 ArithmeticException; 250 251 /** 252 * Set this property to the specified system-supported {@link Boolean} and 253 * answer this object (facilitates chaining) 254 * 255 * @param aValue 256 * a system-supported {@link Boolean} 257 * @return this object (facilitates operation chaining) 258 * @throws UnsupportedOperationException 259 * if this object's value cannot be changed 260 * @throws IllegalArgumentException 261 * if the specified value was incommensurate with this object's 262 * specification 263 * @throws ArithmeticException 264 * the numeric value provided was incompatible with with algebraic 265 * interpretation of this object 266 * @throws NullPointerException 267 * a {@code null} value was provided though this object does not 268 * accept {@code null} values 269 */ 270 public PRIMITIVE setBoolean( final Boolean aValue ) 271 throws UnsupportedOperationException, 272 IllegalArgumentException, 273 ArithmeticException, 274 NullPointerException; 275 276 /** 277 * Set this property to the specified system-supported {@link Character} and 278 * answer this object (facilitates chaining) 279 * 280 * @param aValue 281 * a system-supported {@link Character} 282 * @return this object (facilitates operation chaining) 283 * @throws UnsupportedOperationException 284 * if this object's value cannot be changed 285 * @throws IllegalArgumentException 286 * if the specified value was incommensurate with this object's 287 * specification 288 * @throws ArithmeticException 289 * the numeric value provided was incompatible with with algebraic 290 * interpretation of this object 291 * @throws NullPointerException 292 * a {@code null} value was provided though this object does not 293 * accept {@code null} values 294 */ 295 public PRIMITIVE setCharacter( final Character aValue ) 296 throws UnsupportedOperationException, 297 IllegalArgumentException, 298 ArithmeticException, 299 NullPointerException; 300 301 /** 302 * Set this property to the specified primitive 303 * 304 * @param aValue 305 * a primitive 306 * @return this object (facilitates operation chaining) 307 * @throws UnsupportedOperationException 308 * if this object's value cannot be changed 309 * @throws IllegalArgumentException 310 * if the specified value was incommensurate with this object's 311 * specification 312 * @throws ArithmeticException 313 * the numeric value provided was incompatible with with algebraic 314 * interpretation of this object 315 * @throws NullPointerException 316 * a {@code null} value was provided though this object does not 317 * accept {@code null} values 318 */ 319 public PRIMITIVE setPrimitive( final SealedPrimitive<?> aValue ) 320 throws UnsupportedOperationException, 321 IllegalArgumentException, 322 ArithmeticException, 323 NullPointerException; 324 325 /** 326 * Set the value of this scalar to the <i>mathematical</i> sum of its 327 * current value and the specified value. 328 * 329 * @param aValue 330 * an addend 331 * @return this object (facilitates operation chaining) 332 * @throws UnsupportedOperationException 333 * if this object's value cannot be changed 334 * @throws IllegalArgumentException 335 * if the new value was incommensurate with this object's 336 * specification 337 * @throws ArithmeticException 338 * the new numeric value was incompatible with with algebraic 339 * interpretation of this object 340 */ 341 public PRIMITIVE sumOfPrimitive( final SealedPrimitive<?> aValue ) 342 throws UnsupportedOperationException, 343 IllegalArgumentException, 344 ArithmeticException; 345 346 /** 347 * Set this value to the bit <b>exclusive-or</b> of the <i>integral</i> 348 * boolean vector equivalent of this value and the specified integral 349 * boolean vector 350 * 351 * @param aValue 352 * an integral boolean vector 353 * @return this object (facilitates operation chaining) 354 * @throws UnsupportedOperationException 355 * if this object's value cannot be changed 356 * @throws IllegalArgumentException 357 * if the new value was incommensurate with this object's 358 * specification 359 * @throws ArithmeticException 360 * the new numeric value was incompatible with with algebraic 361 * interpretation of this object 362 */ 363 public PRIMITIVE xorOfPrimitive( final SealedPrimitive<?> aValue ) 364 throws UnsupportedOperationException, 365 IllegalArgumentException, 366 ArithmeticException; 367}