# DS-Math¶ DS-Math provides arithmetic functions for the common numerical primitive types of Solidity. You can safely add, subtract, multiply, and divide `uint256` and `uint128` numbers without fear of integer overflow. You can also conveniently find the minimum and maximum of two `uint256`, `uint128`, or `int256` numbers.

Additionally, this package provides arithmetic functions for new two higher level numerical concepts called Wad and Ray. These are used to represent decimal numbers using a `uint128`, as the Solidity compiler does not yet support fixed-point mathematics natively (e.g. representing the number `3.141592` as `3141592`).

A Wad is a decimal number with 18 digits of precision and a Ray is a decimal number with 27 digits of precision. These functions are necessary to account for the difference between how integer arithmetic behaves normally, and how decimal arithmetic should actually work. A brief example using `wmul`, which returns the product of two Wads:

```1.1 * 2.2 = 2.24

Regular integer arithmetic adds orders of magnitude:

110 * 220 = 22400

wmul(1100000000000000000, 2200000000000000000) = 2240000000000000000
```

Naming Convention:

The standard functions are considered the `uint256` set, so their function names are not prefixed: `add`, `sub`, `mul`, `div`, `min`, and `max`.

Since `uint128` is half the size of the standard type, `h` is the prefix for this set: `hadd`, `hsub`, `hmul`, `hdiv`, `hmin`, and `hmax`.

The `int256` functions have an `i` prefix: `imin`, and `imax`.

Wad functions have a `w` prefix: `wadd`, `wsub`, `wmul`, `wdiv`, `wmin`, and `wmax`.

Ray functions have a `r` prefix: `radd`, `rsub`, `rmul`, `rdiv`, `rmin`, and `rmax`.

## DSMath¶

Your contract should inherit from this type if you want to perform safe arithmetic functions on `uint256`, `uint128`, `int256` primitive types, or decimal numbers being represented with unsigned integers.

### Import¶

`import ds-math/math.sol`

None

### API Reference¶

This function will return `x + y` unless it results in a `uint256` overflow, in which case it will throw an exception.

```function add(uint256 x, uint256 y) constant internal returns (uint256 z)
```

#### function sub¶

This function will return `x - y` unless it results in a `uint256` overflow, in which case it will throw an exception.

```function sub(uint256 x, uint256 y) constant internal returns (uint256 z)
```

#### function mul¶

This function will return `x * y` unless it results in a `uint256` overflow, in which case it will throw an exception.

```function mul(uint256 x, uint256 y) constant internal returns (uint256 z)
```

#### function div¶

This function will return `x / y` unless `y` is equal to 0, in which case it will throw an exception.

```function div(uint256 x, uint256 y) constant internal returns (uint256 z)
```

#### function min¶

This function returns the smaller number between `x` and `y`.

```function min(uint256 x, uint256 y) constant internal returns (uint256 z)
```

#### function max¶

This function returns the larger number between `x` and `y`.

```function max(uint256 x, uint256 y) constant internal returns (uint256 z)
```

This function will return `x + y` unless it results in a `uint128` overflow, in which case it will throw an exception.

```function hadd(uint128 x, uint128 y) constant internal returns (uint128 z)
```

#### function hsub¶

This function will return `x - y` unless it results in a `uint128` overflow, in which case it will throw an exception.

```function hsub(uint128 x, uint128 y) constant internal returns (uint128 z)
```

#### function hmul¶

This function will return `x * y` unless it results in a `uint128` overflow, in which case it will throw an exception.

```function hmul(uint128 x, uint128 y) constant internal returns (uint128 z)
```

#### function hdiv¶

This function will return `x / y` unless `y` is equal to 0, in which case it will throw an exception.

```function hdiv(uint128 x, uint128 y) constant internal returns (uint128 z)
```

#### function hmin¶

This function returns the smaller number between `x` and `y`.

```function hmin(uint128 x, uint128 y) constant internal returns (uint128 z)
```

#### function hmax¶

This function returns the larger number between `x` and `y`.

```function hmax(uint128 x, uint128 y) constant internal returns (uint128 z)
```

#### function imin¶

This function returns the smaller number between `x` and `y`.

```function imin(int256 x, int256 y) constant internal returns (int256 z)
```

#### function imax¶

This function returns the larger number between `x` and `y`.

```function imax(int256 x, int256 y) constant internal returns (int256 z)
```

```function wadd(uint128 x, uint128 y) constant internal returns (uint128)
```

#### function wsub¶

Alias for hsub.

```function wsub(uint128 x, uint128 y) constant internal returns (uint128)
```

#### function wmul¶

This function will multiply two Wads and return a new Wad with the correct level of precision. A Wad is a decimal number with 18 digits of precision that is being represented as an integer. To learn more, see the introduction to DS-Math above.

```function wmul(uint128 x, uint128 y) constant internal returns (uint128 z)
```

#### function wdiv¶

This function will divide two Wads and return a new Wad with the correct level of precision. A Wad is a decimal number with 18 digits of precision that is being represented as an integer. To learn more, see the introduction to DS-Math above.

```function wdiv(uint128 x, uint128 y) constant internal returns (uint128 z)
```

#### function wmin¶

Alias for hmin.

```function wmin(uint128 x, uint128 y) constant internal returns (uint128)
```

#### function wmax¶

Alias for hmax.

```function wmax(uint128 x, uint128 y) constant internal returns (uint128)
```

```function radd(uint128 x, uint128 y) constant internal returns (uint128)
```

#### function rsub¶

Alias for hsub.

```function rsub(uint128 x, uint128 y) constant internal returns (uint128)
```

#### function rmul¶

This function will multiply two Rays and return a new Ray with the correct level of precision. A Ray is a decimal number with 27 digits of precision that is being represented as an integer. To learn more, see the introduction to DS-Math above.

```function rmul(uint128 x, uint128 y) constant internal returns (uint128 z)
```

#### function rdiv¶

This function will divide two Rays and return a new Ray with the correct level of precision. A Ray is a decimal number with 27 digits of precision that is being represented as an integer. To learn more, see the introduction to DS-Math above.

```function rdiv(uint128 x, uint128 y) constant internal returns (uint128 z)
```

#### function rpow¶

This function will raise a Ray to the n^th power and return a new Ray with the correct level of precision. A Ray is a decimal number with 27 digits of precision that is being represented as an integer. To learn more, see the introduction to DS-Math above.

```function rpow(uint128 x, uint64 n) constant internal returns (uint128 z)
```

#### function rmin¶

Alias for hmin.

```function rmin(uint128 x, uint128 y) constant internal returns (uint128)
```

#### function rmax¶

Alias for hmax.

```function rmax(uint128 x, uint128 y) constant internal returns (uint128)
```

#### function cast¶

This function will transform a `uint256` into a `uint128` and return it after asserting that it is equal to the original parameter `x`.

```function cast(uint256 x) constant internal returns (uint128 z)
```