001/** 002 * MutableReal.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.reals; 020 021import java.math.BigDecimal; 022import java.math.BigInteger; 023 024import net.sf.jaccumulator.Domain; 025import net.sf.jaccumulator.scalars.MutableScalar; 026import net.sf.jaccumulator.unlimiteds.MutableUnlimitedDecimalValue; 027import net.sf.jaccumulator.unlimiteds.MutableUnlimitedIntegerValue; 028 029/** 030 * Write behavior for any representation of {@link Domain#REAL real} numbers, 031 * either {@code boolean} vector, {@link BigDecimal unlimited} array 032 * representation or {@link String text} 033 * 034 * @param <REAL> 035 * this type (used to facilitate operation chaining) 036 * @since JAccumulator 4.0 037 * @author Nicole Tedesco (<a 038 * href="mailto:Nicole@NicoleTedesco.com">Nicole@NicoleTedesco.com</a>) 039 */ 040public interface MutableReal<REAL extends MutableReal<REAL>> 041 extends 042 MutableScalar<REAL>, 043 MutableRealDomain<REAL>, 044 MutableUnlimitedIntegerValue<REAL>, 045 MutableUnlimitedDecimalValue<REAL> 046{ 047 /** 048 * Set this value to the bit <b>and</b> of the <i>integral</i> boolean 049 * vector equivalent of this value and the specified integral boolean vector 050 * 051 * @param aValue 052 * an integral boolean vector 053 * @return this object (facilitates operation chaining) 054 * @throws UnsupportedOperationException 055 * if this object's value cannot be changed 056 * @throws IllegalArgumentException 057 * if the new value was incommensurate with this object's 058 * specification 059 * @throws ArithmeticException 060 * the new numeric value was incompatible with with algebraic 061 * interpretation of this object 062 */ 063 public REAL and( final BigInteger aValue ) 064 throws UnsupportedOperationException, 065 IllegalArgumentException, 066 ArithmeticException; 067 068 /** 069 * Set this value to the bit <b>and</b> of the <i>integral</i> boolean 070 * vector equivalent of this value and the specified integral boolean vector 071 * 072 * @param aValue 073 * an integral boolean vector 074 * @return this object (facilitates operation chaining) 075 * @throws UnsupportedOperationException 076 * if this object's value cannot be changed 077 * @throws IllegalArgumentException 078 * if the new value was incommensurate with this object's 079 * specification 080 * @throws ArithmeticException 081 * the new numeric value was incompatible with with algebraic 082 * interpretation of this object 083 */ 084 public REAL andOfReal( 085 final SealedReal<?> aValue ) 086 throws UnsupportedOperationException, 087 IllegalArgumentException, 088 ArithmeticException; 089 090 /** 091 * Set this value to the angle formed by the rectangular coordinates given 092 * by the current value, <i>x</i>, and the specified value, <i>y</i>. In 093 * other words returns the angle <i>theta</i> from the conversion of 094 * rectangular coordinates (x,y) to polar coordinates (r,<i>theta</i>). 095 * 096 * @param y 097 * a <i>y</i> coordinate value 098 * @return this object (facilitates operation chaining) 099 * @throws UnsupportedOperationException 100 * if this object's value cannot be changed 101 * @throws IllegalArgumentException 102 * if the new value was incommensurate with this object's 103 * specification 104 * @throws ArithmeticException 105 * the new numeric value was incompatible with with algebraic 106 * interpretation of this object 107 * @see Math#atan2(double, double) 108 */ 109 public REAL angleWithReal( final SealedReal<?> y ) 110 throws UnsupportedOperationException, 111 IllegalArgumentException, 112 ArithmeticException; 113 114 /** 115 * Set the value of this scalar to the <i>mathematical</i> difference 116 * between its current value and the specified value 117 * 118 * @param aValue 119 * a subtrahend 120 * @return this object (facilitates operation chaining) 121 * @throws UnsupportedOperationException 122 * if this object's value cannot be changed 123 * @throws IllegalArgumentException 124 * if the new value was incommensurate with this object's 125 * specification 126 * @throws ArithmeticException 127 * the new numeric value was incompatible with with algebraic 128 * interpretation of this object 129 */ 130 public REAL difference( final BigDecimal aValue ) 131 throws UnsupportedOperationException, 132 IllegalArgumentException, 133 ArithmeticException; 134 135 /** 136 * Set the value of this scalar to the <i>mathematical</i> difference 137 * between its current value and the specified value 138 * 139 * @param aValue 140 * a subtrahend 141 * @return this object (facilitates operation chaining) 142 * @throws UnsupportedOperationException 143 * if this object's value cannot be changed 144 * @throws IllegalArgumentException 145 * if the new value was incommensurate with this object's 146 * specification 147 * @throws ArithmeticException 148 * the new numeric value was incompatible with with algebraic 149 * interpretation of this object 150 */ 151 public REAL difference( final BigInteger aValue ) 152 throws UnsupportedOperationException, 153 IllegalArgumentException, 154 ArithmeticException; 155 156 /** 157 * Set the value of this scalar to the <i>mathematical</i> difference 158 * between its current value and the specified value 159 * 160 * @param aValue 161 * a subtrahend 162 * @return this object (facilitates operation chaining) 163 * @throws UnsupportedOperationException 164 * if this object's value cannot be changed 165 * @throws IllegalArgumentException 166 * if the new value was incommensurate with this object's 167 * specification 168 * @throws ArithmeticException 169 * the new numeric value was incompatible with with algebraic 170 * interpretation of this object 171 */ 172 public REAL differenceOfReal( 173 final SealedReal<?> aValue ) 174 throws UnsupportedOperationException, 175 IllegalArgumentException, 176 ArithmeticException; 177 178 /** 179 * Replace the current value with the greatest common denonimator between 180 * this value and the specific one 181 * 182 * @param aValue 183 * a value 184 * @return this object (facilitates operation chaining) 185 * @throws UnsupportedOperationException 186 * if this object's value cannot be changed 187 * @throws IllegalArgumentException 188 * if the new value was incommensurate with this object's 189 * specification 190 * @throws ArithmeticException 191 * the new numeric value was incompatible with with algebraic 192 * interpretation of this object 193 */ 194 public REAL gcd( final BigInteger aValue ) 195 throws UnsupportedOperationException, 196 ArithmeticException, 197 IllegalArgumentException; 198 199 /** 200 * Replace the current value with the greatest common denonimator between 201 * this value and the specific one 202 * 203 * @param aValue 204 * a value 205 * @return this object (facilitates operation chaining) 206 * @throws UnsupportedOperationException 207 * if this object's value cannot be changed 208 * @throws IllegalArgumentException 209 * if the new value was incommensurate with this object's 210 * specification 211 * @throws ArithmeticException 212 * the new numeric value was incompatible with with algebraic 213 * interpretation of this object 214 */ 215 public REAL gcdOfReal( final Real<?> aReal ) 216 throws UnsupportedOperationException, 217 ArithmeticException, 218 IllegalArgumentException; 219 220 /** 221 * Set this value to the hypotenuse formed by the square root of the sum of 222 * the square of the current value, <i>x</i>, and the square of the 223 * specified value, <i>y</i>, without intermediate overflow or underflow 224 * 225 * @param y 226 * a <i>y</i> value 227 * @return this object (facilitates operation chaining) 228 * @throws UnsupportedOperationException 229 * if this object's value cannot be changed 230 * @throws IllegalArgumentException 231 * if the new value was incommensurate with this object's 232 * specification 233 * @throws ArithmeticException 234 * the new numeric value was incompatible with with algebraic 235 * interpretation of this object 236 * @see Math#hypot(double, double) 237 */ 238 public REAL hypotenuseWithReal( final SealedReal<?> y ) 239 throws UnsupportedOperationException, 240 IllegalArgumentException, 241 ArithmeticException; 242 243 /** 244 * Set the value of this scalar to its current value <i>modulo</i> of the 245 * specified value 246 * 247 * @param aValue 248 * a modulus 249 * @return this object (facilitates operation chaining) 250 * @throws UnsupportedOperationException 251 * if this object's value cannot be changed 252 * @throws IllegalArgumentException 253 * if the new value was incommensurate with this object's 254 * specification 255 * @throws ArithmeticException 256 * the new numeric value was incompatible with with algebraic 257 * interpretation of this object 258 */ 259 public REAL mod( final BigDecimal aValue ) 260 throws UnsupportedOperationException, 261 IllegalArgumentException, 262 ArithmeticException; 263 264 /** 265 * Set the value of this scalar to its current value <i>modulo</i> of the 266 * specified value 267 * 268 * @param aValue 269 * a modulus 270 * @return this object (facilitates operation chaining) 271 * @throws UnsupportedOperationException 272 * if this object's value cannot be changed 273 * @throws IllegalArgumentException 274 * if the new value was incommensurate with this object's 275 * specification 276 * @throws ArithmeticException 277 * the new numeric value was incompatible with with algebraic 278 * interpretation of this object 279 */ 280 public REAL mod( final BigInteger aValue ) 281 throws UnsupportedOperationException, 282 IllegalArgumentException, 283 ArithmeticException; 284 285 /** 286 * Set the value of this scalar to its current value <i>modulo</i> of the 287 * specified value 288 * 289 * @param aValue 290 * a modulus 291 * @return this object (facilitates operation chaining) 292 * @throws UnsupportedOperationException 293 * if this object's value cannot be changed 294 * @throws IllegalArgumentException 295 * if the new value was incommensurate with this object's 296 * specification 297 * @throws ArithmeticException 298 * the new numeric value was incompatible with with algebraic 299 * interpretation of this object 300 */ 301 public REAL modOfReal( 302 final SealedReal<?> aValue ) 303 throws UnsupportedOperationException, 304 IllegalArgumentException, 305 ArithmeticException; 306 307 /** 308 * Set this value to the bit <b>or</b> of the <i>integral</i> boolean vector 309 * equivalent of this value and the specified integral boolean vector 310 * 311 * @param aValue 312 * an integral boolean vector 313 * @return this object (facilitates operation chaining) 314 * @throws UnsupportedOperationException 315 * if this object's value cannot be changed 316 * @throws IllegalArgumentException 317 * if the new value was incommensurate with this object's 318 * specification 319 * @throws ArithmeticException 320 * the new numeric value was incompatible with with algebraic 321 * interpretation of this object 322 */ 323 public REAL or( final BigInteger aValue ) 324 throws UnsupportedOperationException, 325 IllegalArgumentException, 326 ArithmeticException; 327 328 /** 329 * Set this value to the bit <b>or</b> of the <i>integral</i> boolean vector 330 * equivalent of this value and the specified integral boolean vector 331 * 332 * @param aValue 333 * an integral boolean vector 334 * @return this object (facilitates operation chaining) 335 * @throws UnsupportedOperationException 336 * if this object's value cannot be changed 337 * @throws IllegalArgumentException 338 * if the new value was incommensurate with this object's 339 * specification 340 * @throws ArithmeticException 341 * the new numeric value was incompatible with with algebraic 342 * interpretation of this object 343 */ 344 public REAL orOfReal( 345 final SealedReal<?> aValue ) 346 throws UnsupportedOperationException, 347 IllegalArgumentException, 348 ArithmeticException; 349 350 /** 351 * Set this value to the current value, <i>x</i>, raised to the specified 352 * exponent, <i>n</i>, or <i>x<sup>n</sup></i> 353 * 354 * @param aValue 355 * an exponent 356 * @return this object (facilitates operation chaining) 357 * @throws UnsupportedOperationException 358 * if this object's value cannot be changed 359 * @throws IllegalArgumentException 360 * if the new value was incommensurate with this object's 361 * specification 362 * @throws ArithmeticException 363 * the new numeric value was incompatible with with algebraic 364 * interpretation of this object 365 */ 366 public REAL powerOfReal( final SealedReal<?> aValue ) 367 throws UnsupportedOperationException, 368 IllegalArgumentException, 369 ArithmeticException; 370 371 /** 372 * Set the value of this scalar to the <i>mathematical</i> product of its 373 * current value and the specified value 374 * 375 * @param aValue 376 * a multiplicand 377 * @return this object (facilitates operation chaining) 378 * @throws UnsupportedOperationException 379 * if this object's value cannot be changed 380 * @throws IllegalArgumentException 381 * if the new value was incommensurate with this object's 382 * specification 383 * @throws ArithmeticException 384 * the new numeric value was incompatible with with algebraic 385 * interpretation of this object 386 */ 387 public REAL product( final BigDecimal aValue ) 388 throws UnsupportedOperationException, 389 IllegalArgumentException, 390 ArithmeticException; 391 392 /** 393 * Set the value of this scalar to the <i>mathematical</i> product of its 394 * current value and the specified value 395 * 396 * @param aValue 397 * a multiplicand 398 * @return this object (facilitates operation chaining) 399 * @throws UnsupportedOperationException 400 * if this object's value cannot be changed 401 * @throws IllegalArgumentException 402 * if the new value was incommensurate with this object's 403 * specification 404 * @throws ArithmeticException 405 * the new numeric value was incompatible with with algebraic 406 * interpretation of this object 407 */ 408 public REAL product( final BigInteger aValue ) 409 throws UnsupportedOperationException, 410 IllegalArgumentException, 411 ArithmeticException; 412 413 /** 414 * Set the value of this scalar to the <i>mathematical</i> product of its 415 * current value and the specified value 416 * 417 * @param aValue 418 * a multiplicand 419 * @return this object (facilitates operation chaining) 420 * @throws UnsupportedOperationException 421 * if this object's value cannot be changed 422 * @throws IllegalArgumentException 423 * if the new value was incommensurate with this object's 424 * specification 425 * @throws ArithmeticException 426 * the new numeric value was incompatible with with algebraic 427 * interpretation of this object 428 */ 429 public REAL productOfReal( 430 final SealedReal<?> aValue ) 431 throws UnsupportedOperationException, 432 IllegalArgumentException, 433 ArithmeticException; 434 435 /** 436 * Set the value of this scalar to the <i>mathematical</i> quotient between 437 * its current value and the specified value 438 * 439 * @param aValue 440 * a divisor 441 * @return this object (facilitates operation chaining) 442 * @throws UnsupportedOperationException 443 * if this object's value cannot be changed 444 * @throws IllegalArgumentException 445 * if the new value was incommensurate with this object's 446 * specification 447 * @throws ArithmeticException 448 * the new numeric value was incompatible with with algebraic 449 * interpretation of this object 450 */ 451 public REAL quotient( final BigDecimal aValue ) 452 throws UnsupportedOperationException, 453 IllegalArgumentException, 454 ArithmeticException; 455 456 /** 457 * Set the value of this scalar to the <i>mathematical</i> quotient between 458 * its current value and the specified value 459 * 460 * @param aValue 461 * a divisor 462 * @return this object (facilitates operation chaining) 463 * @throws UnsupportedOperationException 464 * if this object's value cannot be changed 465 * @throws IllegalArgumentException 466 * if the new value was incommensurate with this object's 467 * specification 468 * @throws ArithmeticException 469 * the new numeric value was incompatible with with algebraic 470 * interpretation of this object 471 */ 472 public REAL quotient( final BigInteger aValue ) 473 throws UnsupportedOperationException, 474 IllegalArgumentException, 475 ArithmeticException; 476 477 /** 478 * Set the value of this scalar to the <i>mathematical</i> quotient between 479 * its current value and the specified value 480 * 481 * @param aValue 482 * a divisor 483 * @return this object (facilitates operation chaining) 484 * @throws UnsupportedOperationException 485 * if this object's value cannot be changed 486 * @throws IllegalArgumentException 487 * if the new value was incommensurate with this object's 488 * specification 489 * @throws ArithmeticException 490 * the new numeric value was incompatible with with algebraic 491 * interpretation of this object 492 */ 493 public REAL quotientOfReal( 494 final SealedReal<?> aValue ) 495 throws UnsupportedOperationException, 496 IllegalArgumentException, 497 ArithmeticException; 498 499 /** 500 * Set this property to the specified numeric {@link SealedReal 501 * primitive} and answer this object (facilitates chaining) 502 * 503 * @param aValue 504 * a numeric {@link SealedReal primitive} 505 * @return this object (facilitates operation chaining) 506 * @throws UnsupportedOperationException 507 * if this object's value cannot be changed 508 * @throws IllegalArgumentException 509 * if the specified value was incommensurate with this object's 510 * specification 511 * @throws ArithmeticException 512 * the numeric value provided was incompatible with with algebraic 513 * interpretation of this object 514 * @throws NullPointerException 515 * a {@code null} value was provided though this object does not 516 * accept {@code null} values 517 */ 518 public REAL setReal( final SealedReal<?> aValue ) 519 throws UnsupportedOperationException, 520 IllegalArgumentException, 521 ArithmeticException, 522 NullPointerException; 523 524 /** 525 * Set the value of this scalar to the <i>mathematical</i> sum of its 526 * current value and the specified value 527 * 528 * @param aValue 529 * an addend 530 * @return this object (facilitates operation chaining) 531 * @throws UnsupportedOperationException 532 * if this object's value cannot be changed 533 * @throws IllegalArgumentException 534 * if the new value was incommensurate with this object's 535 * specification 536 * @throws ArithmeticException 537 * the new numeric value was incompatible with with algebraic 538 * interpretation of this object 539 */ 540 public REAL sum( final BigDecimal aValue ) 541 throws UnsupportedOperationException, 542 IllegalArgumentException, 543 ArithmeticException; 544 545 /** 546 * Set the value of this scalar to the <i>mathematical</i> sum of its 547 * current value and the specified value 548 * 549 * @param aValue 550 * an addend 551 * @return this object (facilitates operation chaining) 552 * @throws UnsupportedOperationException 553 * if this object's value cannot be changed 554 * @throws IllegalArgumentException 555 * if the new value was incommensurate with this object's 556 * specification 557 * @throws ArithmeticException 558 * the new numeric value was incompatible with with algebraic 559 * interpretation of this object 560 */ 561 public REAL sum( final BigInteger aValue ) 562 throws UnsupportedOperationException, 563 IllegalArgumentException, 564 ArithmeticException; 565 566 /** 567 * Set the value of this scalar to the <i>mathematical</i> sum of its 568 * current value and the specified value 569 * 570 * @param aValue 571 * an addend 572 * @return this object (facilitates operation chaining) 573 * @throws UnsupportedOperationException 574 * if this object's value cannot be changed 575 * @throws IllegalArgumentException 576 * if the new value was incommensurate with this object's 577 * specification 578 * @throws ArithmeticException 579 * the new numeric value was incompatible with with algebraic 580 * interpretation of this object 581 */ 582 public REAL sumOfReal( 583 final SealedReal<?> aValue ) 584 throws UnsupportedOperationException, 585 IllegalArgumentException, 586 ArithmeticException; 587 588 /** 589 * Set this value to the bit <b>exclusive-or</b> of the <i>integral</i> 590 * boolean vector equivalent of this value and the specified integral 591 * boolean vector 592 * 593 * @param aValue 594 * an integral boolean vector 595 * @return this object (facilitates operation chaining) 596 * @throws UnsupportedOperationException 597 * if this object's value cannot be changed 598 * @throws IllegalArgumentException 599 * if the new value was incommensurate with this object's 600 * specification 601 * @throws ArithmeticException 602 * the new numeric value was incompatible with with algebraic 603 * interpretation of this object 604 */ 605 public REAL xor( final BigInteger aValue ) 606 throws UnsupportedOperationException, 607 IllegalArgumentException, 608 ArithmeticException; 609 610 /** 611 * Set this value to the bit <b>exclusive-or</b> of the <i>integral</i> 612 * boolean vector equivalent of this value and the specified integral 613 * boolean vector 614 * 615 * @param aValue 616 * an integral boolean vector 617 * @return this object (facilitates operation chaining) 618 * @throws UnsupportedOperationException 619 * if this object's value cannot be changed 620 * @throws IllegalArgumentException 621 * if the new value was incommensurate with this object's 622 * specification 623 * @throws ArithmeticException 624 * the new numeric value was incompatible with with algebraic 625 * interpretation of this object 626 */ 627 public REAL xorOfReal( 628 final SealedReal<?> aValue ) 629 throws UnsupportedOperationException, 630 IllegalArgumentException, 631 ArithmeticException; 632}