# 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)
```
These functions also return a mutable reference to the modified object,
allowing you to chain multiple operations together.
```rust
let mut obj a = InfInt::new(1);
a.add_destroy(&InfInt::new(2)).multiply_destroy(&InfInt::new(3)); // a is now InfInt(9)
```
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 cannot create an `InfInt` object with no value.
If you perform an operation on an empty `InfInt`, it will panic.
### Displaying the object
You can print the object using the `fmt` trait:
```rust
use inf_add::InfInt;
let obj = InfInt::new(123456789012345678901234567890);
println!("{}", obj); // prints "123456789012345678901234567890"
```
You can also get a formatted decimal string representation of the object
using the `to_formatted_string` method:
```rust
use inf_add::InfInt;
let obj = InfInt::new(123456789012345678901234567890);
let formatted = obj.to_formatted_string(2);
println!("{}", formatted); // prints "1,234,567,890,123,456,789,012,345,678.90"
```
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.
### 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.