Windows API Guide - Reference - Volume 1: Version 3.0 For the MS-DOS and PC-DOS Operating Systems

2017-07-07 02:10:07

Declare Function MulDiv Lib "kernel32.dll" (ByVal nNumber As Long, ByVal nNumerator As Long, ByVal nDenominator As Long) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Not Supported.

Description & Usage

MulDiv multiplies two 32-bit integers together and divides the resulting 64-bit integer by a 32-bit integer. The final result is (usually) a 32-bit integer. This function is useful because it can calculate expressions which, although resulting in a perfectly acceptable value, would otherwise cause an overflow error if the programming language's arithmetic operators were used. If the end result is not an integer, it is rounded to the nearest integer.

Return Value

If an error occured (such as if the result is greater than a 32-bit value or division by zero was attempted), the function returns -1. If successful, the function returns the result of the expression (nNumber * nNumerator) / nDenominator rounded to the nearest integer.

Visual Basic-Specific Issues

None.

Parameters

nNumber: The first number to multiply.
nNumerator: The second number to multiply.
nDenominator: The number to divide by.

Example

' This code is licensed according to the terms and conditions listed here. ' Demonstrate how MulDiv can help avoid producing overflow errors. Dim result As Long ' Without MulDiv: If you uncomment the line below, an overflow error ' will occur because the result of the multiplication is greater ' than a 32-bit value. 'result = -134217728 * 243 / 110592 ' With MulDiv: There is no problem calculating the result. result = MulDiv(-134217728, 243, 110592) ' (The result is exactly -294912.)