Skip to content

Latest commit

 

History

History
134 lines (88 loc) · 4.63 KB

README.md

File metadata and controls

134 lines (88 loc) · 4.63 KB
Raw

csBigInteger-JS-Wrapper

csBigInteger-JS-Wrapper is a robust JavaScript library designed to provide a C# BigInteger implementation within the JavaScript environment. This library bridges the gap between C#'s numerical precision and JavaScript's flexible but limited number handling, making it an essential tool for developers working on projects that require high precision with large integers.

The primary goal of csBigInteger-JS-Wrapper is to offer full compatibility with the C# Numerics implementation. This includes handling hexadecimal string formats and ensuring proper endianness. The library also includes auxiliary functions tailored for Fixed8 formatting, which is useful for various financial and blockchain applications.

Since its version 3.0, csBigInteger-JS-Wrapper integrates with bn.js (https://github.com/indutny/bn.js), a library known for its high-performance handling of large integers. This integration ensures that operations on big integers are executed efficiently and accurately.

Features

  • Full Compatibility with C# BigInteger: Mimics the behavior of C#'s BigInteger, supporting operations on large numbers and converting between different formats.
  • Hexadecimal String Handling: Properly processes and interprets hexadecimal strings, maintaining consistency with C# implementations.
  • Endianness Management: Handles little-endian and big-endian representations as needed, ensuring compatibility with various systems.
  • Fixed8 Format Support: Includes functions for managing Fixed8 formatting, which is particularly useful in blockchain and financial applications.
  • Integration with bn.js: Utilizes bn.js for efficient handling of large integer calculations, providing both performance and reliability.

How to Use

Basic Example

To get started with csBigInteger-JS-Wrapper, you can use it in various environments. Here’s a simple example of how to perform basic operations:

// Import the library (CommonJS example)
const csbiginteger = require('csbiginteger');

// Create BigInteger instances
let x1 = new csbiginteger.csBigInteger("0xff", 16); // Represents -1 in csBigInteger
let bx1 = x1.asBN(); // Access BN.js internals
let x2 = new csbiginteger.csBigInteger(5);
let bx2 = x2.asBN(); // Access BN.js internals

// Perform arithmetic operations
let bx3 = bx2.add(bx1); // Calculates '-1' + '5'
console.log(bx3.toString(10)); // Outputs '4'

Installation in Web Browsers

Classic JavaScript:

To use the library directly in a web browser, include the following script tag:

<script src="https://unpkg.com/csbiginteger/dist/csbiginteger.js"></script>

ES6 Module:

For those using ES6 modules, you can import the library as follows:

<script type="module">
import csbiginteger from "https://unpkg.com/csbiginteger/dist/csbiginteger-es6.mjs";
</script>

In your JavaScript code:

// Usage in ES6 module
const csBigInteger = csbiginteger.csBigInteger;
const csFixed8 = csbiginteger.csFixed8;

let x = new csBigInteger(1000);
let y = new csFixed8(1000);

Installation via npm

To install the library using npm, run the following command:

npm install csbiginteger

You can then use it in your Node.js applications as shown:

const csBigInteger = require('csbiginteger').csBigInteger;
const BN = require('bn.js');

let x = new csBigInteger(255);
console.log(x.toHexString()); // Outputs "ff00"

let y = x + 1; // Results in 256 (JS unsafe number)
let z = x.asBN().add(new BN(1)); // Safe handling of large numbers
console.log(z.toString(10)); // Outputs "256"

For Developers

Running Tests

To ensure that everything is working correctly, run the tests with:

npm test

Building with Webpack

To build the project for distribution using Webpack, execute:

npm run build

Updating the Version

To increment the minor version number of the library, use:

npm version minor

Pushing Changes and Publishing

To push changes to the repository and publish the new version, use:

git push origin master --tags
npm publish

Final Remarks

csBigInteger-JS-Wrapper is maintained by @igormcoelho. Special thanks are extended to @snowypowers for valuable advice and @ixje for insightful discussions on endianness.

License: This project is licensed under the MIT License, allowing for both personal and commercial use, as long as the original license and copyright notice are included.

Copyleft: 2024

This comprehensive description aims to provide users and developers with all the necessary information to effectively use, contribute to, and understand the csBigInteger-JS-Wrapper library.