# inf_add
Create, add, subtract, multiply, divide, shift, compare, and display infinitely long positive numbers.
## WARNING
This library is in an early stage of development.
Breaking changes may occur in future versions.
Documentation is still in progress.
## Usage Notes
The recommended way to perform operations on `InfInt` objects is to use `*_destroy` functions,
such as `obj.add_destroy(other)`.
You can also use default operators, like so:
```rust
let obj a = InfInt::new(1);
let obj b = InfInt::new(2);
let obj c = a + b; // c is now InfInt(3)
```
However, the default operators will perform a clone to create a new object,
which is not very performant.
The `*_destroy` functions will not clone the object,
but will modify the original object in place.
```rust
let obj a = InfInt::new(1);
let obj b = InfInt::new(2);
a.add_destroy(&b); // a is now InfInt(3)
```
The full list of operations is as follows:
- `add_destroy(&other)`: Adds `other` to the current object
- `subtract_destroy(&other)`: Subtracts `other` from the current object
- `multiply_destroy(&other)`: Multiplies the current object by `other`
- `bitshift_left_destroy(&other)`: Performs a left bitwise shift by `other` bits
- `bitshift_right_destroy(&other)`: Performs a right bitwise shift by `other` bits
- `bitand_destroy(&other)`: Performs a bitwise AND operation with `other`
- `bitor_destroy(&other)`: Performs a bitwise OR operation with `other`
- `divide_destroy(&other)`: Divides the current object by `other`
You can also print the object using the `fmt` trait:
```rust
use inf_add::InfInt;
let obj = InfInt::new(123456789012345678901234567890);
println!("{}", obj); // prints "123456789012345678901234567890"
```
Keep in mind that the `fmt` trait will convert the number to a base 10 string representation,
which can be expensive for very large numbers.
You cannot create an `InfInt` object with no value.
If you perform an operation on an empty `InfInt`, it will panic.
### Notes on bitshift and division
Although bitshifts can be performed on an arbitrarily large number,
the amount shifted by must be a `u32` value, limiting the maximum shift to 2^32 bits.
This should cover the vast majority of use cases, and
any larger shifts would be extremely expensive in terms of computation.
Keep in mind that shifting 1 by 2^32 bits will result in 2^4294967296,
a number too large to fit on any screen.
Because division uses bitshifts internally,
the maximum value resulting from a division operation is limited to 2^2^32 bits.
Once again, this should cover most use cases,
and division can be done on two arbitrarily large numbers.
## Implementation details
Data is stored in a vector of u128 values.
The longer the vector, the higher the computation cost.
The most expensive operation is `fmt`,
as it requires constructing a base 10 vector representation of the number.
Future versions may cache the resulting string representation
to improve performance.