2 // Copyright (c) 2013 Samsung Electronics Co., Ltd.
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
8 // http://www.apache.org/licenses/LICENSE-2.0
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
18 * @file FBaseBigInteger.h
19 * @brief This is the header file for the %BigInteger class.
22 * @final This class is not intended for extension.
24 * This header file contains the declarations of the %BigInteger class.
27 #ifndef _FBASE_BIG_INTEGER_H_
28 #define _FBASE_BIG_INTEGER_H_
30 #include <FBaseObject.h>
33 namespace Tizen { namespace Base { namespace Collection
39 namespace Tizen { namespace Base
41 class ImmutableString;
42 class _BigIntegerImpl;
45 class _OSP_EXPORT_ BigInteger
49 enum PrimeNumberResult
51 DEFINITELY_COMPOSITE = 0,
56 struct QuotientAndRemainder
59 BigInteger* remainder;
64 * Initializes %BigInteger instance with a random value in the range 0 to 2^numBits - 1.
68 * @param[in] numBits Number of bits
71 explicit BigInteger(int numBits);
74 * Initializes %BigInteger instance with @signed @long @long value.
78 * @param[in] value 64-bit @signed @long @long value
81 explicit BigInteger(int64_t value);
84 * Initializes %BigInteger instance with null-terminated C string representing a numeric value.
88 * @param[in] value Null-terminated C string representing a numeric value.
90 * @remarks -This method accepts only string representing integer value. Decimal separators are not allowed in the input string.
91 * -This method accepts binary, decimal, hexadecimal, and octal numbers given by the following grammar.
95 * Sign[opt] DecimalNumeral
96 * Sign[opt] 0b BinaryDigits
97 * Sign[opt] 0B BinaryDigits
98 * Sign[opt] 0 OctalDigits
99 * Sign[opt] 0x HexDigits
100 * Sign[opt] 0X HexDigits
103 * -The object is not fully constructed if the input string is not parseable. It sets the exception.
104 * -GetLastResult() should be called to retrieve the last set exception
105 * -The behavior of this constructor is not dependent on the system default locale setting.
107 * @exception E_SUCCESS The method is successful.
108 * @exception E_NUM_FORMAT The specified string does not represent valid binary, octal, decimal or hexadecimal number, or
109 * The specified string contains decimal separator which represent a floating point number.
111 explicit BigInteger(const char* pStr);
114 * Initializes %BigInteger instance with null-terminated C string with given radix
118 * @param[in] value Null-terminated C string representing a numeric value.
119 * @param[in] radix The radix of the string representing a numeric value @n
120 * Radix value range is from 2 to 36.
122 * @remarks -This method accepts only string representing integer value. Decimal separators are not allowed in the input string.
124 * Following examples explains the string representation for some of the radix
128 * BigInteger bigInt1("101010100", 2); // Radix 2 representation of decimal number 340
130 * BigInteger bigInt2("20112", 3); // Radix 3 representation of decimal number 176
132 * BigInteger bigInt3("1230321", 4); // Radix 4 representation of decimal number 6969
134 * BigInteger bigInt4("4231034", 5); // Radix 5 representation of decimal number 70769
138 * -The object is not fully constructed if the input string is not parseable. It sets the exception.
139 * -GetLastResult() should be called to retrieve the last set exception
140 * -The behavior of this constructor is not dependent on the system default locale setting.
142 * @exception E_SUCCESS The method is successful.
143 * @exception E_NUM_FORMAT The specified string does not represent valid binary, octal, decimal or hexadecimal number, or
144 * The specified string contains decimal separator which represent a floating point number.
145 * @exception E_OUT_OF_RANGE The specified radix is not in between 2 to 36.
147 BigInteger(const char* pStr, int radix);
150 * Initializes %BigInteger instance with String representing a numeric value.
154 * @param[in] value String representing a numeric value.
156 * @remarks -This method accepts only string representing integer value. Decimal separators are not allowed in the input string.
157 * -This method accepts decimal, hexadecimal, and octal numbers given by the following grammar.
158 * -The behavior of this constructor is not dependent on the system default locale setting.
162 * Sign[opt] DecimalNumeral
163 * Sign[opt] 0b BinaryDigits
164 * Sign[opt] 0B BinaryDigits
165 * Sign[opt] 0 OctalDigits
166 * Sign[opt] 0x HexDigits
167 * Sign[opt] 0X HexDigits
171 * -The object is not fully constructed if the input string is not parseable. It sets the exception.
172 * -GetLastResult() should be called to retrieve the last set exception
174 * @exception E_SUCCESS The method is successful.
175 * @exception E_NUM_FORMAT The specified string does not represent valid binary, octal, decimal or hexadecimal number, or
176 * The specified string contains decimal separator which represent a floating point number.
178 explicit BigInteger(const ImmutableString& str);
181 * Initializes %BigInteger instance with String with given radix
185 * @param[in] value String representing a numeric value.
186 * @param[in] radix The radix of the string representing a numeric value @n
187 * Radix value range is from 2 to 36.
189 * @remarks -This method accepts only string representing integer value. Decimal separators are not allowed in the input string.
190 * -The behavior of this constructor is not dependent on the system default locale setting.
192 * Following examples explains the string representation for some of the radix
196 * ImmutableString str1(L"CD14");
197 * BigInteger bigInt1(str1, 16); // Radix 16 representation of decimal number 52500
199 * ImmutableString str2(L"53214");
200 * BigInteger bigInt2(str1, 6); // Radix 6 representation of decimal number 7210
202 * ImmutableString str3(L"632456");
203 * BigInteger bigInt3(str1, 7); // Radix 7 representation of decimal number 108968
205 * ImmutableString str4(L"5746321");
206 * BigInteger bigInt4(str1, 8); // Radix 8 representation of decimal number 1559761
210 * -The object is not fully constructed if the input string is not parseable. It sets the exception.
211 * -GetLastResult() should be called to retrieve the last set exception
213 * @exception E_SUCCESS The method is successful.
214 * @exception E_NUM_FORMAT The specified string does not represent valid binary, octal, decimal or hexadecimal number, or
215 * The specified string contains decimal separator which represent a floating point number.
216 * @exception E_OUT_OF_RANGE The specified radix is not in between 2 to 36.
218 BigInteger(const ImmutableString& str, int radix);
221 * Copying of objects using this copy constructor is allowed.
225 * @param[in] value An instance of %BigInteger
227 BigInteger(const BigInteger& bigInt);
230 * This destructor overrides Tizen::Base::Object::~Object().
234 * @remarks The internally allocated memory block is freed when the instance is destroyed.
236 virtual ~BigInteger();
239 * Calculates absolute value of the calling %BigInteger instance and returns a new %BigInteger instance containing absolute value.
243 * @return New %BigInteger instance.
246 BigInteger Absolute(void) const;
249 * Adds value of the calling %BigInteger instance with value of specified %BigInteger rhs instance
250 * and returns a new %BigInteger instance whose value is this + rhs.
254 * @param[in] rhs Value to add with calling %BigInteger instance.
256 * @return A new %BigInteger instance containing this + rhs value.
259 BigInteger Add(const BigInteger& rhs) const;
262 * Performs binary And of value of the calling %BigInteger instance with value of specified %BigInteger rhs instance
263 * and returns a new %BigInteger instance whose value is this & rhs.
267 * @param[in] rhs Value to and with calling %BigInteger instance.
269 * @return A new %BigInteger instance containing this & rhs value.
272 BigInteger And(const BigInteger& rhs) const;
275 * Performs binary complement of value of specified %BigInteger rhs instance and And'ed with value of calling %BigInteger instance
276 * and returns a new %BigInteger instance whose value is this & ~rhs.
280 * @param[in] rhs Value is complemented and AND with calling %BigInteger instance.
282 * @return A new %BigInteger instance containing this & ~rhs value.
285 BigInteger AndNot(const BigInteger& rhs) const;
288 * Clears bit at a specified position in the calling %BigInteger instance and returns a new %BigInteger instance.
292 * @param[in] bitIndex Position where the bit has to be cleared.
294 * @return A new %BigInteger instance.
296 * @remarks -If the bitIndex is invalid it sets the exception.
297 * -GetLastResult() should be called to retrieve the last set exception
299 * @exception E_SUCCESS The method is successful.
300 * @exception E_OUT_OF_RANGE The specified bitIndex is less than 0 or grater than bit length of number in binary representation.
302 BigInteger ClearBit(int bitIndex) const;
305 * Compares value of calling %BigInteger instance with value of specified %BigInteger instance.
309 * @param[in] value Value to compare with calling %BigInteger instance..
311 * @return Comparision value.
313 * 1 -If the calling %BigInteger instance value is greater than value
314 * 0 -If the calling %BigInteger instance value is equal to value
315 * -1 -If the calling %BigInteger instance value is less than value
318 int CompareTo(const BigInteger& value) const;
321 * Divides value of the calling %BigInteger instance with value of specified %BigInteger rhs instance
322 * and returns a new %BigInteger instance whose value is this / rhs.
326 * @param[in] rhs Divisor,value which divides the calling %BigInteger instance.
328 * @return A new %BigInteger instance containing this / rhs value.
330 * @remarks -If the rhs represents a number 0 it sets the exception.
331 * -GetLastResult() should be called to retrieve the last set exception
333 * @exception E_SUCCESS The method is successful.
334 * @exception E_INVALID_ARG The specified rhs represents number 0.
336 BigInteger Divide(const BigInteger& rhs) const;
339 * Divides value of the calling %BigInteger instance with value of specified %BigInteger rhs instance
340 * and returns a struct QuotientAndRemainder containing the quotient and remainder.
344 * @param[in] rhs Divisor,value which divides the calling %BigInteger instance.
346 * @return QuotientAndRemainder containing quotient and reminder.
349 * @remarks -If the rhs represents a number 0 it sets the exception.
350 * -GetLastResult() should be called to retrieve the last set exception
351 * - User should free the memory allocated to QuotientAndRemainder member variables
353 * @exception E_SUCCESS The method is successful.
354 * @exception E_INVALID_ARG The specified rhs represents number 0.
357 QuotientAndRemainder DivideAndRemainderN(const BigInteger& rhs) const;
360 * Compares whether the value of the calling %BigInteger instance is equal to the specified object.
364 * @param[in] obj An instance of object to compare.
366 * @return @c true if the values are equal else @c false
369 bool Equals(const Object& obj) const;
372 * Flips bit at a specified position in the calling %BigInteger instance and returns a new %BigInteger instance.
376 * @param[in] bitIndex Position where the bit is flipped.
378 * @return A new %BigInteger instance.
380 * @remarks -If the bitIndex is invalid it sets the exception.
381 * -GetLastResult() should be called to retrieve the last set exception
383 * @exception E_SUCCESS The method is successful.
384 * @exception E_OUT_OF_RANGE The specified bitIndex is less than 0 or grater than bit length of number in binary representation.
386 BigInteger FlipBit(int bitIndex) const;
389 * Gets the number of bits set to 1 in the value of the calling %BigInteger instance.
393 * @return Number of bits set to 1.
395 int GetSetBitCount(void) const;
398 * Gets the number of bits in the binary representation value of the calling %BigInteger instance.
402 * @return Number of bits in the binary representation value of %BigInteger instance.
404 int GetBitLength(void) const;
407 * Gets the hash value of the calling %BigInteger instance.
411 * @return The hash value of the current instance.
413 int GetHashCode(void) const;
416 * Gets the lowest bit set value of the calling %BigInteger instance.
420 * @return The position of the lowest bit set.
422 int GetLowestSetBit(void) const;
425 * Gets the sign of the value of the calling %BigInteger instance.
429 * @return The sign of the value.
432 * -1 -If the value < 0
433 * 0 -If the value == 0
434 * 1 -If the value > 0
436 int GetSign(void) const;
439 * Gets the greater common divisor of the value of calling %BigInteger instance and value of the specified %BigInteger instance
440 * and returns a new %BigInteger instance containing value of the greater common divisor.
444 * @param[in] value Value with which the greater common divisor is computed
446 * @return A new %BigInteger instance containing value of greater common divisor.
449 * Zero is returned if the value of calling %BigInteger instance is 0 or value of the specified %BigInteger instance is 0
452 BigInteger GreaterCommonDivisor(const BigInteger& value) const;
455 * Checks whether the bit at specified index in the value of calling %BigInteger instance is set.
459 * @param[in] bitIndex Position of the bit whose value is checked whether it is set.
461 * @return A new %BigInteger instance containing value of greater common divisor.
463 * @remarks -If the bitIndex is invalid it sets the exception.
464 * -GetLastResult() should be called to retrieve the last set exception
466 * @exception E_SUCCESS The method is successful.
467 * @exception E_OUT_OF_RANGE The specified bitIndex is less than 0 or grater than bit length of number in binary representation.
469 bool IsBitSet(int bitIndex) const;
472 * Checks whether the value of calling %BigInteger instance is probably prime.
477 * @return @c true if the value if prime else @c false
480 * -returns PROBABLY_PRIME if probably prime.
481 * -returns DEFINITELY_PRIME if definitely prime.
482 * -returns DEFINITELY_COMPOSITE if definitely composite.
484 PrimeNumberResult IsProbablePrimeNumber(void) const;
487 * Finds the maximum between value of the calling %BigInteger instance with value of specified %BigInteger rhs instance
488 * and returns new %BigInteger instance containing maximum value.
492 * @param[in] rhs Value to compute the maximum with calling %BigInteger instance.
494 * @return A new %BigInteger instance containing maximum value.
497 BigInteger Maximum(const BigInteger& rhs) const;
500 * Finds the minimum between value of the calling %BigInteger instance with value of specified %BigInteger rhs instance
501 * and returns new %BigInteger instance containing minimum value.
505 * @param[in] rhs Value to compute the minimum with calling %BigInteger instance.
507 * @return A new %BigInteger instance containing minimum value.
510 BigInteger Minimum(const BigInteger& rhs) const;
513 * Performs modulus of value of the calling %BigInteger instance and value of specified %BigInteger instance
514 * and returns a new %BigInteger instance whose value is this mod value.
518 * @param[in] value The modulas.
520 * @return A new %BigInteger instance containing this mod value.
522 * @remarks -If the value represents a number 0 it sets the exception.
523 * -GetLastResult() should be called to retrieve the last set exception
525 * @exception E_SUCCESS The method is successful.
526 * @exception E_INVALID_ARG The specified value represents number 0 or number is negative.
528 * The modulus value must be positive.
529 * The result is always positive.
532 BigInteger Modulus(const BigInteger& value) const;
535 * Performs 1 divided by of value of the calling %BigInteger instance and modulus with value of specified %BigInteger instance
536 * and returns a new %BigInteger instance whose value is 1/this mod value.
540 * @param[in] value The modulus.
542 * @return A new %BigInteger instance containing 1/this mod value.
544 * @remarks -If the value represents a number 0 it sets the exception.
545 * -GetLastResult() should be called to retrieve the last set exception
547 * @exception E_SUCCESS The method is successful.
548 * @exception E_INVALID_ARG The specified value represents number 0 or number is negative.
550 * The modulas value must be positive.
551 * The result is always positive.
554 BigInteger ModulusInverse(const BigInteger& value) const;
557 * Calculates power of value of the calling %BigInteger instance and exponent specified in value of specified %BigInteger instance
558 * and the result is moded with value specified in the modulo %BigInteger instance.
562 * @param[in] exponent The exponent.
563 * @param[in] modulo The modulas.
565 * @return A new %BigInteger instance containing pow(this, exponent) mod modulo.
567 * @remarks -If the modulo represents a number 0 it sets the exception.
568 * -GetLastResult() should be called to retrieve the last set exception
570 * @exception E_SUCCESS The method is successful.
571 * @exception E_INVALID_ARG The specified modulo represents number 0 or modulo is negative.
573 BigInteger ModulusPower(const BigInteger& exponent, const BigInteger& modulo) const;
577 * Multiplies value of the calling %BigInteger instance with value of specified %BigInteger rhs instance
578 * and returns a new %BigInteger instance whose value is this * rhs.
582 * @param[in] rhs Value to multiply with calling %BigInteger instance.
584 * @return A new %BigInteger instance.
588 BigInteger Multiply(const BigInteger& rhs) const;
591 * Negates value of the calling %BigInteger instance and returns a new %BigInteger instance whose value is -this.
595 * @return A new %BigInteger instance.
598 BigInteger Negate(void) const;
601 * Gets the next probable prime number from the calling %BigInteger instance
602 * and returns a new %BigInteger instance which contains next probable prime number value is -this.
606 * @return A new %BigInteger instance containing next probable prime number.
609 BigInteger NextProbablePrimeNumber(void) const;
613 * Complements, performs logical negation on each bit in the value of calling %BigInteger instance
614 * and returns a new %BigInteger instance which contains complement value.
618 * @return A new %BigInteger instance containing complement value.
621 BigInteger Not(void) const;
624 * Performs binary Or of value of the calling %BigInteger instance with value of specified %BigInteger rhs instance
625 * and returns a new %BigInteger instance whose value is this | rhs.
629 * @param[in] rhs Value to Or with calling %BigInteger instance.
631 * @return A new %BigInteger instance containing this | rhs.
634 BigInteger Or(const BigInteger& rhs) const;
637 * Raises value of the calling %BigInteger instance to the power of specified %BigInteger rhs instance
638 * and returns a new %BigInteger instance whose value is pow(this, exponent).
642 * @param[in] exponent Exponent value.
644 * @return A new %BigInteger instance containing pow(this, exponent) value.
646 * @remarks -If the exponent is negative it sets the exception.
647 * -GetLastResult() should be called to retrieve the last set exception
649 * @exception E_SUCCESS The method is successful.
650 * @exception E_INVALID_ARG The specified exponent value is negative.
652 BigInteger Power(int exponent) const;
655 * Divides value of the calling %BigInteger instance with value of specified %BigInteger rhs instance
656 * and returns a new %BigInteger instance whose value is this % rhs.
660 * @param[in] rhs Divisor,value which divides the calling %BigInteger instance.
662 * @return A new %BigInteger instance containing this % rhs value.
664 * @remarks -If the divisor represents a number 0 it sets the exception.
665 * -GetLastResult() should be called to retrieve the last set exception
667 * @exception E_SUCCESS The method is successful.
668 * @exception E_INVALID_ARG The specified divisor represents number 0.
670 BigInteger Remainder(const BigInteger& divisor) const;
673 * Sets bit at a specified position in the calling %BigInteger instance and returns a new %BigInteger instance.
677 * @param[in] bitIndex Position where the bit has to be set.
679 * @return A new %BigInteger instance.
681 * @remarks -If the bitIndex is invalid it sets the exception.
682 * -GetLastResult() should be called to retrieve the last set exception
684 * @exception E_SUCCESS The method is successful.
685 * @exception E_OUT_OF_RANGE The specified bitIndex is less than 0 or grater than bit length of number in binary representation.
687 BigInteger SetBit(int bitIndex) const;
690 * Performs Shift left of value of the calling %BigInteger instance with specified shift distance
691 * and returns a new %BigInteger instance whose value is this << shiftDistance.
695 * @param[in] shiftDistance Shift distance.
697 * @return A new %BigInteger instance.
699 * @remarks -If the shiftDistance is invalid it sets the exception.
700 * -GetLastResult() should be called to retrieve the last set exception
702 * @exception E_SUCCESS The method is successful.
703 * @exception E_OUT_OF_RANGE The specified shiftDistance is less than 0 or grater than bit length of number in binary representation.
705 BigInteger ShiftLeft(int shiftDistance) const;
708 * Performs Shift right of value of the calling %BigInteger instance with specified shift distance
709 * and returns a new %BigInteger instance whose value is this >> shiftDistance.
713 * @param[in] shiftDistance Shift distance.
715 * @return A new %BigInteger instance.
717 * @remarks -If the shiftDistance is invalid it sets the exception.
718 * -GetLastResult() should be called to retrieve the last set exception
720 * @exception E_SUCCESS The method is successful.
721 * @exception E_OUT_OF_RANGE The specified shiftDistance is less than 0 or grater than bit length of number in binary representation.
723 BigInteger ShiftRight(int shiftDistance) const;
726 * Subtracts value of the calling %BigInteger instance with value of specified %BigInteger rhs instance
727 * and returns a new %BigInteger instance whose value is this - rhs.
731 * @param[in] rhs Value to subtract with calling %BigInteger instance.
733 * @return A new %BigInteger instance.
736 BigInteger Subtract(const BigInteger& rhs) const;
739 * Gets the @c double equivalent of the current instance of %BigInteger.
743 * @return The @c double equivalent of the current instance
745 * @remarks -If the value is not in double range it sets the exception.
746 * -When exception occurs value is set to DBL_MAX if the number is grater than 0.
747 * -When exception occurs value is set to DBL_MIN if the number is less than 0.
748 * -GetLastResult() should be called to retrieve the last set exception
750 * @exception E_SUCCESS The method is successful.
751 * @exception E_OUT_OF_RANGE The @cdouble value is not in between DBL_MAX and DBL_MIN range.
753 double ToDouble(void) const;
756 * Gets the @c int64_t equivalent of the current instance of %BigInteger.
760 * @return The @c int64_t equivalent of the current instance
762 * @remarks -If the value is not in long long range it sets the exception.
763 * -When exception occurs value is set to LongLong::VALUE_MAX if the number is grater than 0.
764 * -When exception occurs value is set to LongLong::VALUE_MIN if the number is less than 0.
765 * -GetLastResult() should be called to retrieve the last set exception
767 * @exception E_SUCCESS The method is successful.
768 * @exception E_OUT_OF_RANGE The @cint64_t value is not in between LongLong::VALUE_MAX and LongLong::VALUE_MIN range.
770 int64_t ToInt64(void) const;
773 * Converts value of the calling %BigInteger instance to string representation in decimal form.
777 * @return String containing the value in decimal form.
780 ImmutableString ToString(void) const;
783 * Converts value of the calling %BigInteger instance to string representation in specified radix.
787 * @param[in] radix Radix used for the string representation.
789 * @return String containing the value in specified radix.
791 * @remarks -If radix is invalid it sets the exception.
792 * -GetLastResult() should be called to retrieve the last set exception
794 * @exception E_SUCCESS The method is successful.
795 * @exception E_OUT_OF_RANGE The specified radix is not in between 2 to 36.
797 ImmutableString ToString(int radix) const;
800 * Performs binary Xor of value of the calling %BigInteger instance with value of specified %BigInteger rhs instance
801 * and returns a new %BigInteger instance whose value is this ^ rhs.
805 * @param[in] rhs Value to Xor with calling %BigInteger instance.
807 * @return A new %BigInteger instance containing this ^ rhs value.
810 BigInteger Xor(const BigInteger& rhs) const;
815 // This constructor is intentionally declared as private so that only the platform can create an instance.
817 // @param[in] bigInt An instance of %BigInteger class to copy from
822 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
824 // @param[in] list An instance of %BigInteger
826 BigInteger& operator =(const BigInteger& bigInt);
829 // Overloaded constructor
831 BigInteger(_BigIntegerImpl* pImpl);
834 friend class _BigIntegerImpl;
835 class _BigIntegerImpl* __pImpl;
838 #endif //_FBASE_BIG_INTEGER_H_