Module dev.civl.sarl
Package dev.civl.sarl.IF.number

Interface NumberFactory

public interface NumberFactory
A number factory is used to produce concrete rational and integer numbers. The rational and integer numbers live in two separate worlds. Different implementations of this interface may make different choices regarding numerical precision, rounding policies, and other factors.

  • Method Details

    • integer

      IntegerNumber integer(String string)
      Returns the integer number specified by the given string. The string could be something like "7583902" or "-1" or "0". There is no bound on the length of the string.

    • integer

      IntegerNumber integer(int value)
      Returns an integer number corresponding to the given Java int.

    • infiniteInteger

      IntegerNumber infiniteInteger(boolean isPositiveInfinity)
      Returns an infinite IntegerNumber, its signum is determined by the given boolean value.
      Parameters:
      isPositiveInfinity - A boolean value determines whether this number is positive or negative.

    • rational

      RationalNumber rational(String string)
      Returns the rational number specified by the given string, where the string is a decimal representation of the number. The string may be an integer string, such as "394" or "-1" or "0". Or it may contain a decimal point, as in "-3.1415" or "2." or ".234" or "-.234". There is no limit on the number of digits.

    • infiniteRational

      RationalNumber infiniteRational(boolean isPositiveInfinity)
      Returns an infinite RationalNumber, its signum is determined by the given boolean value.
      Parameters:
      isPositiveInfinity - A boolean value determines whether this number is positive or negative.

    • number

      Number number(String string)
      Makes best guest on type of number based on string.

    • infiniteNumber

      Number infiniteNumber(boolean isIntegral, boolean isPositiveInfinity)
      Returns an infinite Number, its type is determined by the first boolean argument isIntegeral and its signum is determined by the second boolean argument isPositiveInfinity.
      Parameters:
      isPositiveInfinity - A boolean value determines whether this number is positive or negative.
      isIntegeral - A boolean value determines whether this number is an integer number or a rational one.
      Returns:

    • abs

      Number abs(Number number)
      Returns absolute value of number, preserving type.

    • isIntegral

      boolean isIntegral(RationalNumber arg0)
      Returns true iff the rational number is an integer, e.g., "3.0", or "4/2". If this method returns true, it is then safe to invoke method integerValue() on the number.

    • fraction

      RationalNumber fraction(IntegerNumber numerator, IntegerNumber denominator)
      Returns the rational number which is the quotient of the two integers.

    • integerToRational

      RationalNumber integerToRational(IntegerNumber integer)
      Casts an integer to a rational number.

    • zeroRational

      RationalNumber zeroRational()
      The rational number zero.

    • oneRational

      RationalNumber oneRational()
      The rational number one.

    • zeroInteger

      IntegerNumber zeroInteger()
      The integer number zero.

    • oneInteger

      IntegerNumber oneInteger()
      The integer number zero.

    • positiveInfinityRational

      RationalNumber positiveInfinityRational()
      Return a RationalNumber representing the positive infinity.
      Returns:

    • positiveInfinityInteger

      IntegerNumber positiveInfinityInteger()
      Return a IntegerNumber representing the positive infinity.
      Returns:

    • negativeInfinityRational

      RationalNumber negativeInfinityRational()
      Return a RationalNumber representing the negative infinity.
      Returns:

    • negativeInfinityInteger

      IntegerNumber negativeInfinityInteger()
      Return a IntegerNumber representing the negative infinity.
      Returns:

    • add

      Number add(Number arg0, Number arg1)
      Adds two numbers and returns result. The numbers must be of same type (integer or real), which is also the type of the result.

    • subtract

      Number subtract(Number arg0, Number arg1)
      Subtracts two numbers and returns result. The numbers must be of same type (integer or real), which is also the type of the result.

    • multiply

      Number multiply(Number arg0, Number arg1)
      Multiplies two numbers and returns result. The numbers must be of same type (integer or real), which is also the type of the result.

    • divide

      Number divide(Number arg0, Number arg1)
      Divides two numbers and returns result. The numbers must be of same type (integer or real), which is also the type of the result.

    • negate

      Number negate(Number arg0)
      Negates the number, preserving the type (IntegerNumberIF or RationalNumberIF).

    • add

      RationalNumber add(RationalNumber arg0, RationalNumber arg1)
      Adds two rational numbers and returns the result.

    • subtract

      RationalNumber subtract(RationalNumber arg0, RationalNumber arg1)
      Subtracts two rational numbers and returns the result.

    • multiply

      RationalNumber multiply(RationalNumber arg0, RationalNumber arg1)
      Multiplies two rational numbers and returns the result.

    • divide

      RationalNumber divide(RationalNumber arg0, RationalNumber arg1)
      Divides two rational numbers and returns the result. An ArithmeticException is thrown if arg1 is zero.

    • negate

      RationalNumber negate(RationalNumber arg0)
      Returns the negation of the given rational number, i.e., -x.

    • add

      IntegerNumber add(IntegerNumber arg0, IntegerNumber arg1)
      Adds two integer numbers and returns the result.

    • subtract

      IntegerNumber subtract(IntegerNumber arg0, IntegerNumber arg1)
      Subtracts two integer numbers and returns the result.

    • multiply

      IntegerNumber multiply(IntegerNumber arg0, IntegerNumber arg1)
      Multiplies two integer numbers and returns the result.

    • divide

      IntegerNumber divide(IntegerNumber arg0, IntegerNumber arg1)
      Divides two integer numbers and returns the result. Note that this is integer division. The result is obtained by taking the real quotient and rounding towards zero. An ArithmeticException is thrown if the denominator is zero.

    • mod

      IntegerNumber mod(IntegerNumber arg0, IntegerNumber arg1)
      Modulo operations. Returns the result of arg0 % arg1.

    • negate

      IntegerNumber negate(IntegerNumber arg0)
      Returns the negation of the given integer number, i.e., -x.

    • increment

      RationalNumber increment(RationalNumber arg)
      add(arg, 1.0)

    • increment

      IntegerNumber increment(IntegerNumber arg)
      add(arg, 1)

    • increment

      Number increment(Number arg)
      adds 1 of proper type

    • decrement

      RationalNumber decrement(RationalNumber arg)
      arg-1.0

    • decrement

      IntegerNumber decrement(IntegerNumber arg)
      arg - 1

    • decrement

      Number decrement(Number arg)
      subtracts 1 of proper type

    • gcd

      IntegerNumber gcd(IntegerNumber arg0, IntegerNumber arg1)
      Returns the greatest common divisor of two integers. The two integers must be positive.

    • lcm

      IntegerNumber lcm(IntegerNumber arg0, IntegerNumber arg1)
      Returns the least common multiple of the two positive integers.

    • numerator

      IntegerNumber numerator(RationalNumber arg0)
      Returns the numerator in a representation of the rational number as the quotient of two integers. This method is coordinated with method denominator so that the quotient of the numerator and denominator give the original rational number.

    • denominator

      IntegerNumber denominator(RationalNumber arg0)
      Returns the denominator in a representation of the rational number as the quotient of two integers. This method is coordinated with method numerator so that the quotient of the numerator and denominator give the original rational number.

    • integerValue

      IntegerNumber integerValue(RationalNumber arg0)
      Returns the value of the rational number as an integer number. Applies only to a rational number which is integral. I.e., the method isIntegral() must return true.
      Throws:
      ArithmeticException - if arg0 is not integral

    • floor

      IntegerNumber floor(RationalNumber arg0)
      Returns the greatest integer less than or equal to the given rational number.

    • ceil

      IntegerNumber ceil(RationalNumber arg0)
      Returns the least integer greater than or equal to the given rational number.

    • compare

      int compare(RationalNumber arg0, RationalNumber arg1)
      Returns a positive value if arg0>arg1, 0 if arg0 equals arg1, -1 if arg0invalid input: '<'arg1.

    • compare

      int compare(IntegerNumber arg0, IntegerNumber arg1)
      Returns a positive value if arg0 is greater than arg1, 0 if arg0 equals arg1, -1 if arg0 is less than arg1.

    • rational

      RationalNumber rational(Number number)
      Returns a rational representation of the number. If the number already is rational, returns the number. Else casts from integer to rational.

    • compare

      int compare(Number arg0, Number arg1)
      Returns a positive value if arg0 is greater than arg1, 0 if arg0 equals arg1, a negative value if arg0 is less than arg1.

    • gaussianElimination

      boolean gaussianElimination(RationalNumber[][] matrix)
      Performs Gauss-Jordan Elimination on a matrix of rational numbers, transforming the matrix to reduced row echelon form.
      Parameters:
      matrix -
      Returns:
      true iff a non-trivial modification was made to matrix. A non-trivial modification is any modification other than a permutation of the rows.

    • relativeGaussianElimination

      boolean relativeGaussianElimination(RationalNumber[][] mat1, RationalNumber[][] mat2)

      Performs a form of "relative Gauss-Jordan elimination". Given two matrices with the same number of columns. The first matrix is transformed to reduced row echelon form by the usual Gauss-Jordan elimination (method gaussianElimination(RationalNumber[][])). Then suitable multiples of the rows in the first matrix are added to rows in the second matrix so as to make all entries in columns in the second matrix corresponding to pivot columns in the first matrix 0. Then the usual Gauss-Jordan elimination is performed on the second matrix.

      Motivation: the idea is that a context specifies some set of constraints in mat1, and a sub-context specifies additional constraints in mat2. To simplify the sub-context, you can use any of the information in the original context.

      Let A1=mat1 in reduced row echelon form. Let A2=mat2 and A2' result of performing one elementary row operation. Want: 

       A2x=b2 iff A2'x=b2' for all x s.t. A1x=b1.
      This holds since A2' is obtained by adding the same number to both sides of an equation.

      Parameters:
      mat1 - the first matrix, which is the "background" context
      mat2 - the second matrix, which is the one being reduced under the context above
      Returns:
      true iff a non-trivial modification was made to matrix. A non-trivial modification is any modification other than a permutation of the rows.

    • rational

      RationalNumber rational(BigInteger numerator, BigInteger denominator)
      Returns the rational number which is the quotient of the two given integers. It can of course be simplified.
      Parameters:
      numerator - any BigInteger
      denominator - any BigInteger
      Returns:
      numerator/denominator
      Throws:
      ArithmeticException - if denominator is zero

    • integer

      IntegerNumber integer(BigInteger big)
      Returns the IntegerNumber with value specified by the BigInteger. No precision is lost
      Parameters:
      big - any BigInteger
      Returns:
      the corresponding IntegerNumber

    • integer

      IntegerNumber integer(long value)
      Returns the IntegerNumber with value specified by the long. No precision is lost.
      Parameters:
      value - any long
      Returns:
      the corresponding IntegerNumber

    • emptyIntegerInterval

      Interval emptyIntegerInterval()
      Returns the empty integer interval: (0,0).
      Returns:
      empty integer interval

    • emptyRealInterval

      Interval emptyRealInterval()
      Returns the empty real interval: (0.0, 0.0).
      Returns:
      empty real interval

    • universalIntegerInterval

      Interval universalIntegerInterval()
      Returns the universal integer interval: (-∞, +∞).
      Returns:
      universal integer interval

    • universalRealInterval

      Interval universalRealInterval()
      Returns the universal real interval: (-∞, +∞).
      Returns:
      universal real interval

    • singletonInterval

      Interval singletonInterval(Number x)
      Returns the interval consisting of the single finite number x: [x,x].
      Parameters:
      x - a non-null Number
      Returns:
      closed interval of same type as x with both bounds equal to x and non-strict

    • restrictUpper

      Interval restrictUpper(Interval interval, Number bound, boolean strict)
      Restricts the upper bound of an interval as specified. Returns the interval which is the intersection of the given interval and the interval (-∞,bound) (if strict) or (-∞,bound] (if not strict). This method could be implemented using intersection(Interval, Interval) or it could be implemented more efficiently in an equivalent way.
      Parameters:
      interval - a non-null Interval
      bound - a Number of same type as interval
      strict - is the bound strict?
      Returns:
      interval obtained by intersecting the two intervals

    • restrictLower

      Interval restrictLower(Interval interval, Number bound, boolean strict)
      Restricts the lower bound of an interval as specified. Returns the interval which is the intersection of the given interval and the interval (bound,∞) (if strict) or ( bound,∞] (if not strict). This method could be implemented using intersection(Interval, Interval) or it could be implemented more efficiently in an equivalent way.
      Parameters:
      interval - a non-null Interval
      bound - a Number of same type as interval
      strict - is the bound strict?
      Returns:
      interval obtained by intersecting the two intervals

    • newInterval

      Interval newInterval(boolean isIntegral, Number lower, boolean strictLower, Number upper, boolean strictUpper)
      Returns a new Interval as specified. If the bound of this Interval is an implementation of RealInfinity, the bound represents an infinity.
      Precondition:
      • if the type is integral, then the upper and lower bounds must be instances of IntegerNumber, else they must be instances of RationalNumber
      Postconditions: the parameters must specify an interval in "normal form", i.e., the following must all hold:
      • if the type is integral, then the upper and lower bounds must be instances of IntegerNumber, else they must be instances of RationalNumber
      • if the bound is exclusive, the corresponding strictLower (or strictUpper) must be true.
      • the lower bound must be less than or equal to the upper bound (Otherwise, this method will return an empty interval.)
      • if the bounds are finite and equal: either (1) both strictLower and strictUpper will be false, or (2) strictLower and strictUpper will be true and the upper and lower bounds will be 0. The first case represents an interval consisting of a single point; the second case represents the empty interval.
      • if the lower bound lower is infinite, it must be a negative infinity. And if the upper bound upper is infinite, it must be a positive infinity.
      • if isIntegral is true: if the lower bound is finite then strictLower must be false; if the upper bound is finite then strictUpper must be false.
      Parameters:
      isIntegral - does the interval have integer type (as opposed to real type)?
      lower - the lower bound of the interval with the type defined by isIntegral
      strictLower - is the lower bound strict? (i.e., "(" if exclusive, as opposed to "[" if inclusive)
      upper - the upper bound of the interval with the type defined by isIntegral
      strictUpper - is the upper bound strict? (i.e., ")" if exclusive, as opposed to "]" if inclusive)
      Returns:
      a new interval instance as specified

    • intersection

      Interval intersection(Interval i1, Interval i2)
      Returns the interval which is the intersection of the two given intervals. The two given intervals must have the same type.
      Parameters:
      i1 - a non-null Interval
      i2 - an non-null Interval with same type (integral or rational) as "i1"
      Returns:
      an Interval representing the intersection of "i1" and "i2"

    • union

      void union(Interval i1, Interval i2, NumberFactory.IntervalUnion result)
      Computes the union of two intervals or reports that the union is not an interval and why. The result is stored in the result object. If the union of the two intervals is an interval, result.status will be set to 0 and result.union will hold the union interval. Otherwise, the status will be set to either a negative or positive integer and result.union will be set to null. A positive status indicates that every element of i1 is greater than every element of i2; a negative status indicates every element of i1 is less than every element of i2.
      Parameters:
      i1 - an non-null Interval
      i2 - an non-null Interval of same type (integral or rational) as "i1"
      result - an non-null NumberFactory.IntervalUnion used for receiving the result union

    • join

      Interval join(Interval i1, Interval i2)
      Returns the smallest interval containing both of the given intervals.
      Parameters:
      i1 - a non-null Interval
      i2 - a non-null Interval of same type as i1
      Returns:
      the smallest Interval containing i1 and i2

    • affineTransform

      Interval affineTransform(Interval interval, Number a, Number b)
      Computes the affineTransform of the input interval itv with two numbers: a and b as parameters.
      Parameters:
      interval - an non-null Interval
      a - a non-null finite Number used to multiply with both upper and lower of "interval"
      b - a non-null finite Number used to add to both upper and lower of "interval", after multiplying "a".
      Returns:
      an Interval which is an affineTransform of "interval"

    • compare

      int compare(Interval i1, Interval i2)
      Computes the relationships of two Intervals.
    • Return -3, if the first Interval is on the left side and disjointed with the second Interval
    • Return -2, if the first Interval is on the left side and intersected with the second Interval
    • Return -1, if the first Interval contains the second Interval
    • Return 0, if the first Interval is exactly same with the second Interval
    • Return 1, if the first Interval is contained in the second Interval
    • Return 2, if the first Interval is on the right side and intersected with the second Interval
    • Return 3, if the first Interval is on the right side and disjointed with the second Interval

      • Parameters:
      i1 - a non-null Interval
      i2 - a non-null Interval of same type as i1
      Returns:
      an integer representing the relationship of two given Interval, the value is defined above.

    • negate

      Interval negate(Interval interval)
      To negate the given non-null interval.
      Parameters:
      interval - a non-null Interval
      Returns:
      the negated Interval

    • add

      Interval add(Interval i1, Interval i2)
      To calculate the sum of two non-null and not empty Interval with same type (real/integer)
      Parameters:
      i1 - a non-null Interval with same type of the other one
      i2 - a non-null Interval with same type of the other one
      Returns:
      the sum of two Interval.

    • multiply

      Interval multiply(Interval i1, Interval i2)
      To calculate the product of two non-null and not empty Interval with same type (real/integer)
      This is the smallest interval containing all x1*x2, where x1 is in i1 and x2 is in i2.
      Parameters:
      i1 - a non-null Interval with same type of the other one
      i2 - a non-null Interval with same type of the other one
      Returns:
      the product of two Interval.

    • power

      Interval power(Interval interval, int exp)
      To calculate the power-result of a given non-null and not empty Interval with a given natural number.
      Parameters:
      interval - a non-null Interval
      exp - an integer of natural number
      Returns:
      the power result of the Interval with the given integer

    • power

      Interval power(Interval interval, IntegerNumber expr)
      To calculate the power-result of a given non-null and not empty Interval with a given non-null non-negative IntegerNumber.
      Parameters:
      interval - a non-null Interval
      expr - an IntegerNumber of a natural number
      Returns:
      the power result described above.

    • power

      Number power(Number number, int exp)
      Calculate the given number powering a given exponent and returns result. The exponent must be a natural number.
      Parameters:
      number - a non-null IntegerNumber
      exp - a non-null IntegerNumber representing an natural number which is greater or equal to zero.
      Returns:
      the power result of the Number with the given integer

    • power

      IntegerNumber power(IntegerNumber number, int exp)
      Calculate the given integer number powering a given exponent and returns result. The exponent must be a natural number.
      Parameters:
      number - a non-null IntegerNumber
      exp - a non-null IntegerNumber representing an natural number which is greater or equal to zero.
      Returns:
      the power result of the IntegerNumber with the given integer

    • power

      RationalNumber power(RationalNumber number, int exp)
      Calculate the given rational number powering a given exponent and returns result. The exponent must be a natural number.
      Returns:
      the power result of the RationalNumber with the given integer

    • power

      Number power(Number number, IntegerNumber exp)
      Calculate the given Number base powering a given IntegerNumber exponent and returns result. The exponent must be a natural number.
      Parameters:
      number - a non-null Number
      exp - a non-null IntegerNumber representing an natural number which is greater or equal to zero.
      Returns:

    • power

      RationalNumber power(RationalNumber number, IntegerNumber exp)
      Calculate the given RationalNumber base powering a given IntegerNumber exponent and returns result. The exponent must be a natural number.
      Parameters:
      number - a non-null RationalNumber
      exp - a non-null IntegerNumber representing an natural number which is greater or equal to zero.
      Returns:

    • power

      IntegerNumber power(IntegerNumber number, IntegerNumber exp)
      Calculate the given IntegerNumber base powering a given IntegerNumber exponent and returns result. The exponent must be a natural number.
      Parameters:
      number - a non-null IntegerNumber
      exp - a non-null IntegerNumber representing an natural number which is greater or equal to zero.
      Returns:

    • nthRootInt

      IntegerNumber nthRootInt(IntegerNumber number, IntegerNumber n)
      Calculate the nth root of the given number and n. The inputs and output are
      invalid reference 
      IntegerNumbers
      Parameters:
      number - a non-null finite
      invalid reference 
      IntegerNumbers
      ;
      n - a non-null positive finite
      invalid reference 
      IntegerNumbers
      representing the n;
      Returns:

    • divide

      Interval divide(Interval interval, Number num)
      Return the Interval consisting of all Numbers that each Number x in the Interval multiplies with the given num is in the given interval.
      (i.e., for all x in the returned result, x*num is in interval.)
      E.g., for integer intervals: [1,3]/2 = [1,1]; [1,4]/3 = [1,1]; [1,5]/6 = empty, for rational intervals: [1,3]/2 = [0.5,1.5].
      Parameters:
      interval - A non-null Interval
      num - A non-null Number (which means it is a finite number) with the same type of the given Interval interval.
      Returns:
      the result

    • divide

      Interval divide(Interval i1, Interval i2)
      Divides two given Intervals and returns result. They must be of same type (integer or real), which is also the type of the result.
      This is the smallest interval containing all x1/x2, where x1 is in i1 and x2 is in i2.
      Parameters:
      i1 - A non-null Interval
      i2 - A non-null Interval with the same type of the given Interval interval.
      Returns:
      the result

    • multiply

      Interval multiply(Number num, Interval interval)
      Multiply the given Interval with a given Number and returns result. The numbers must be of same type (integer or real), which is also the type of the result.
      Parameters:
      num - A non-null finite Number
      interval - A non-null Interval with the same type of the given Number num.
      Returns:
      the result

    • scientificString

      String scientificString(RationalNumber num, int numSig)
      Constructs a string representation of the given rational number in scientific notation: x.xxxx * 10^{-yyy}.
      Parameters:
      num - the rational number
      numSig - the number of significant digits
      Returns:
      string representation in scientific notation