bignum.h revision 972c3ecf2c929440ce70e51af38ba021101c8f7b
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * IPRT - Big Integer Numbers.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Copyright (C) 2006-2014 Oracle Corporation
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * available from http://www.virtualbox.org. This file is free software;
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * you can redistribute it and/or modify it under the terms of the GNU
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * General Public License (GPL) as published by the Free Software
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * The contents of this file may alternatively be used under the terms
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * of the Common Development and Distribution License Version 1.0
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * VirtualBox OSE distribution, in which case the provisions of the
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * CDDL are applicable instead of those of the GPL.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * You may elect to license modified versions of this file under the
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * terms and conditions of either the GPL or the CDDL or both.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** @defgroup grp_rtbignum RTBigNum - Big Integer Numbers
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @ingroup grp_rt
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** The big integer number element type. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** Pointer to a big integer number element. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** Pointer to a const big integer number element. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** The size (in bytes) of one array element. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** The number of bits in one array element. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync#define RTBIGNUM_ELEMENT_BITS (RTBIGNUM_ELEMENT_SIZE * 8)
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** Returns the bitmask corrsponding to given bit number. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** The maximum value one element can hold. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** Mask including all the element bits set to 1. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * IPRT big integer number.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsynctypedef struct RTBIGNUM
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** Elements array where the magnitue of the value is stored. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** The current number of elements we're using in the pauElements array. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** The current allocation size of pauElements. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** Reserved for future use. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** Set if it's a negative number, clear if positive or zero. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** Whether to use a the data is sensitive (RTBIGNUMINIT_F_SENSITIVE). */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** The number is currently scrambled */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync /** Bits reserved for future use. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumInit(PRTBIGNUM pBigNum, uint32_t fFlags, void const *pvRaw, size_t cbRaw);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumInitZero(PRTBIGNUM pBigNum, uint32_t fFlags);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** @name RTBIGNUMINIT_F_XXX - RTBigNumInit flags.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** The number is sensitive so use a safer allocator, scramble it when not
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * in use, and apply RTMemWipeThoroughly before freeing. The RTMemSafer API
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * takes care of these things.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @note When using this flag, concurrent access is not possible! */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** Big endian number. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** Little endian number. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** The raw number is unsigned. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** The raw number is signed. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumClone(PRTBIGNUM pBigNum, PCRTBIGNUM pSrc);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * The minimum number of bits require store the two's complement representation
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * of the number.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns Width in number of bits.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param pBigNum The big number.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(uint32_t) RTBigNumBitWidth(PCRTBIGNUM pBigNum);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(uint32_t) RTBigNumByteWidth(PCRTBIGNUM pBigNum);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Converts the big number to a sign-extended big endian byte sequence.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns IPRT status code
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @retval VERR_BUFFER_OVERFLOW if the specified buffer is too small.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param pBigNum The big number.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param pvBuf The output buffer (size is at least cbWanted).
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param cbWanted The number of bytes wanted.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumToBytesBigEndian(PCRTBIGNUM pBigNum, void *pvBuf, size_t cbWanted);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Compares two numbers.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @retval -1 if pLeft < pRight.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @retval 0 if pLeft == pRight.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @retval 1 if pLeft > pRight.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param pLeft The left side number.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param pRight The right side number.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumCompare(PRTBIGNUM pLeft, PRTBIGNUM pRight);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumCompareWithU64(PRTBIGNUM pLeft, uint64_t uRight);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumCompareWithS64(PRTBIGNUM pLeft, int64_t iRight);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumAssign(PRTBIGNUM pDst, PCRTBIGNUM pSrc);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumNegate(PRTBIGNUM pResult, PCRTBIGNUM pBigNum);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumAdd(PRTBIGNUM pResult, PCRTBIGNUM pAugend, PCRTBIGNUM pAddend);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumSubtract(PRTBIGNUM pResult, PCRTBIGNUM pMinuend, PCRTBIGNUM pSubtrahend);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumMultiply(PRTBIGNUM pResult, PCRTBIGNUM pMultiplicand, PCRTBIGNUM pMultiplier);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumDivide(PRTBIGNUM pQuotient, PRTBIGNUM pRemainder, PCRTBIGNUM pDividend, PCRTBIGNUM pDivisor);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumDivideKnuth(PRTBIGNUM pQuotient, PRTBIGNUM pRemainder, PCRTBIGNUM pDividend, PCRTBIGNUM pDivisor);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumDivideLong(PRTBIGNUM pQuotient, PRTBIGNUM pRemainder, PCRTBIGNUM pDividend, PCRTBIGNUM pDivisor);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumModulo(PRTBIGNUM pRemainder, PCRTBIGNUM pDividend, PCRTBIGNUM pDivisor);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumExponentiate(PRTBIGNUM pResult, PCRTBIGNUM pBase, PCRTBIGNUM pExponent);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumShiftLeft(PRTBIGNUM pResult, PCRTBIGNUM pValue, uint32_t cBits);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTBigNumShiftRight(PRTBIGNUM pResult, PCRTBIGNUM pValue, uint32_t cBits);