Skip to content

Commit b0b95aa

Browse files
SamHertsSamHerts
committed
Update README with revised usage examples, API details, and installation instructions
1 parent ca51506 commit b0b95aa

1 file changed

Lines changed: 81 additions & 124 deletions

File tree

‎README.md‎

Lines changed: 81 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -4,170 +4,127 @@
44

55
## Overview
66

7-
**BigInt** is a single-header C++ library designed to facilitate the creation and manipulation of arbitrary-sized integers. This lightweight and efficient library provides an easy-to-use interface for handling large integers that exceed the limits of built-in data types.
7+
**BigInt** is a single-header C++ library designed for arbitrary-precision integer arithmetic. It provides a lightweight, efficient, and easy-to-use interface for handling integers that exceed the limits of built-in types like `long long`.
88

99
## Features
1010

11-
- **Arbitrary Integer Size**: Create integers of any size, limited only by available memory.
12-
- **Basic Arithmetic Operations**: Support for addition, subtraction, multiplication, and division.
13-
- **Advanced Computations**: Support for modulos, Square Roots, Powers, and Logarithms
14-
- **Comparison Operators**: Full set of comparison operators (==, !=, <, <=, >, >=).
15-
- **Stream Input/Output**: Easy input and output via standard streams.
16-
- **Modular Design**: Simple and modular code for easy integration and extension.
11+
- **Arbitrary Precision**: Limited only by available system memory.
12+
- **Single-Header**: Easy integration; just drop `bigint.h` into your project.
13+
- **Modern C++**: Support for C++11 and newer (C++20 compatible).
14+
- **Rich Operator Support**: Full set of arithmetic, comparison, and increment/decrement operators.
15+
- **Advanced Math**: Built-in support for GCD, LCM, Factorials, Power, Square Root, and Logarithms.
16+
- **Hexadecimal Support**: Initialize big integers directly from hex strings.
17+
- **STL Integration**: Includes a `std::hash` specialization for use in `unordered_map` and `unordered_set`.
18+
- **Random Generation**: Static methods to generate cryptographically-seeded random big integers.
1719

1820
## Getting Started
1921

2022
### Prerequisites
2123

22-
Ensure you have a C++11 (or higher) compatible compiler.
24+
A C++11 (or higher) compatible compiler (e.g., GCC 4.8+, Clang 3.3+, MSVC 2015+).
2325

2426
### Installation
2527

2628
Simply include the header file in your project.
2729

28-
1. Download `BigInt.h`.
29-
2. Include it in your source file:
30+
1. Download `bigint.h`.
31+
2. Include it in your source:
3032
```cpp
31-
#include "BigInt.h"
33+
#include "bigint.h"
3234
```
3335

34-
### Usage
36+
Note: All functionality resides within the `BigInt` namespace.
3537

36-
Below is a basic example demonstrating the usage of the library.
38+
## Usage
3739

3840
```cpp
3941
#include <iostream>
4042
#include "bigint.h"
4143

44+
using BigInt::bigint;
45+
4246
int main() {
47+
// Initialization from strings (decimal or hex)
4348
bigint a("123456789012345678901234567890");
44-
bigint b("987654321098765432109876543210");
45-
46-
bigint small_number = 10;
47-
bigint big_number = 789456123;
49+
bigint b("0xDEADC0DEFE777");
4850

49-
bigint c = "123456789012345678901234567890";
50-
bigint d = "-987654321098765432109876543210";
51+
// Initialization from primitive types
52+
bigint small = 10;
53+
bigint negative = -500;
5154

55+
// Basic Arithmetic
5256
bigint sum = a + b;
53-
bigint diff = a - b;
54-
bigint product = a * b;
55-
bigint quotient = a / b;
56-
bigint modulo = a % b;
57+
bigint prod = a * b;
58+
59+
// Advanced Math
60+
bigint p = bigint::pow(2, 1024);
61+
bigint s = bigint::sqrt(a);
5762

58-
std::cout << "a + b = " << sum << std::endl;
59-
std::cout << "a - b = " << diff << std::endl;
60-
std::cout << "a * b = " << product << std::endl;
61-
std::cout << "a / b = " << quotient << std::endl;
62-
std::cout << "a % b = " << modulo << std::endl;
63+
std::cout << "2^1024 = " << p << std::endl;
64+
65+
// STL Integration
66+
if (a > b) {
67+
std::cout << "a is larger" << std::endl;
68+
}
6369

6470
return 0;
6571
}
6672
```
6773

68-
### API Reference
69-
Class: bigint
70-
Constructors
71-
72-
BigInt(): Default constructor.
73-
BigInt(const std::string& value): Constructs a BigInt from a string.
74-
BigInt(const BigInt& other): Copy constructor.
75-
76-
### Operators
77-
78-
BigInt operator+(const BigInt& rhs) const: Addition.
79-
BigInt operator+=(const BigInt& rhs)
80-
81-
BigInt operator-(const BigInt& rhs) const: Subtraction.
82-
BigInt operator-=(const BigInt& rhs)
83-
84-
BigInt operator*(const BigInt& rhs) const: Multiplication.
85-
BigInt operator*=(const BigInt& rhs)
86-
87-
BigInt operator/(const BigInt& rhs) const: Division.
88-
BigInt operator/=(const BigInt& rhs)
89-
90-
BigInt operator%(const BigInt& rhs) const: Modulo.
91-
BigInt operator%=(const BigInt& rhs)
92-
93-
bool operator==(const BigInt& rhs) const: Equality.
94-
95-
bool operator!=(const BigInt& rhs) const: Inequality.
96-
97-
bool operator<(const BigInt& rhs) const: Less than.
98-
99-
bool operator<=(const BigInt& rhs) const: Less than or equal to.
100-
101-
bool operator>(const BigInt& rhs) const: Greater than.
102-
103-
bool operator>=(const BigInt& rhs) const: Greater than or equal to.
104-
105-
### Member Functions
106-
107-
bigint pow(const bigint &base, const bigint &exponent): Returns the base raised to the exponent
74+
## API Reference
10875

109-
bigint maximum(const bigint &lhs, const bigint &rhs): Returns the larger number
110-
111-
bigint minimum(const bigint &lhs, const bigint &rhs): Returns the smaller number
112-
113-
bigint abs(const bigint &s): Returns the absolute (positive) value
114-
115-
bigint sqrt(const bigint &): Returns the square root
116-
117-
bigint log2(const bigint &): Returns the binary log
118-
119-
bigint log10(const bigint &): Returns the decimal log
120-
121-
bigint logwithbase(const bigint &, const bigint &): Returns an arbitrary integer based log
122-
123-
bigint antilog2(const bigint &): Returns the binary anti-log
124-
125-
bigint antilog10(const bigint &): Returns the decimal anti-log
126-
127-
void swap(bigint &, bigint &)
128-
129-
bigint gcd(const bigint &, const bigint &): Returns the greatest common divisor
130-
131-
bigint lcm(const bigint &lhs, const bigint &rhs): Returns the least common multiple
132-
133-
bigint factorial(const bigint &): Returns n! = (n)*(n-1)...(n-k)
134-
135-
bool is_even(const bigint &input)
136-
137-
bool is_negative(const bigint &input)
138-
139-
bool is_prime(const bigint &): Rudimentary prime check based on divisibility loop
140-
141-
bigint sum_of_digits(const bigint& input)
142-
143-
### Stream Operators
76+
The library uses the class `BigInt::bigint`.
14477

145-
friend std::ostream& operator<<(std::ostream& os, const BigInt& num): Output stream.
78+
### Constructors
79+
- `bigint()`: Defaults to 0.
80+
- `bigint(const std::string&)`: From decimal or hex (starts with `0x`) string.
81+
- `bigint(long long)`, `bigint(int)`, `bigint(double)`: From numeric types.
82+
- `bigint(const char*)`: From C-style strings.
14683

147-
### Build and Run Unit Tests
84+
### Operators
85+
- **Arithmetic**: `+`, `-`, `*`, `/`, `%`, `+=`, `-=`, `*=`, `/=`, `%=`
86+
- **Comparison**: `==`, `!=`, `<`, `<=`, `>`, `>=`
87+
- **Increment/Decrement**: Prefix and postfix `++`, `--`
88+
- **Unary**: `-` (negation)
89+
- **I/O**: `<<` (ostream)
90+
- **Conversion**: `explicit operator bool()`, `explicit operator std::string()`, `explicit operator int()`, `explicit operator long long()`
91+
92+
### Static Member Functions (Mathematical)
93+
- `bigint::pow(base, exp)`: Power function.
94+
- `bigint::sqrt(n)`: Integer square root.
95+
- `bigint::abs(n)`: Absolute value.
96+
- `bigint::gcd(a, b)`, `bigint::lcm(a, b)`: Greatest Common Divisor and Least Common Multiple.
97+
- `bigint::factorial(n)`: Factorial of n.
98+
- `bigint::log2(n)`, `bigint::log10(n)`, `bigint::logwithbase(n, base)`: Logarithmic functions.
99+
- `bigint::random(digits)`: Generates a random positive bigint with the specified number of digits.
100+
- `bigint::is_prime(n)`: Basic primality test.
101+
- `bigint::is_even(n)`, `bigint::is_negative(n)`: Property checks.
102+
103+
### Other Utilities
104+
- `bigint::sum_of_digits(n)`: Returns the sum of all digits.
105+
- `std::hash<BigInt::bigint>`: Specialization for hashing.
106+
107+
## Build and Run Unit Tests
108+
109+
The project uses GoogleTest for verification.
148110

149111
```bash
150-
$ git clone https://github.com/SamHerts/BigInt.git
151-
$ cd BigInt
152-
$ cd tests
153-
$ cmake .
154-
$ make
155-
$ ./BigInt_gtest
112+
git clone https://github.com/SamHerts/BigInt.git
113+
cd BigInt/tests
114+
cmake -B build
115+
cmake --build build
116+
./build/BigInt_gtest
156117
```
157118

158-
### Contributing
159-
160-
Contributions are welcome! Feel free to open an issue or submit a pull request.
161-
162-
Fork the repository.
163-
Create your feature branch (git checkout -b feature/NewFeature).
164-
Commit your changes (git commit -am 'Add some feature').
165-
Push to the branch (git push origin feature/NewFeature).
166-
Open a pull request.
119+
## Contributing
167120

168-
### License
121+
Contributions are welcome!
122+
1. Fork the repository.
123+
2. Create your feature branch (`git checkout -b feature/NewFeature`).
124+
3. Commit your changes.
125+
4. Push to the branch.
126+
5. Open a pull request.
169127

170-
This project is licensed under the MIT License. See the LICENSE file for details.
171-
Acknowledgments
128+
## License
172129

173-
Special thanks to the open-source community for their invaluable contributions and support.
130+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)