nodecpp-rational

A Node.js native C++ addon that defines a JavaScript class Rational for representing and manipulating rational numbers.

Installation

npm install [-g] @essamonline/nodecpp-rational

Usage

With CommonJS in JavaScript:

const { Rational } = require('@essamonline/nodecpp-rational');

With ESM or TypeScript:

import addon from '@essamonline/nodecpp-rational';
const { Rational } = addon;

Rational Class

class Rational{
	/*** Static Methods [1] ***/
	static gcd(a, b)         // returns the greatest common divisor of two integers

	/*** Constructor ***/
	constructor(arg1, arg2)  // constructor with no arguments, one rational object argument
                             // or 2 numeric arguments i.e. numerator and denominator

	/*** Helper Instance Methods [2] ***/
	_validate(arg)           // validates the given argument as a numerator or denominator
	_normalize()             // normalizes the rational number i.e. no common factors and positive denominator

	/*** Accessors Instance Methods [2] ***/
	getNumerator()           // an accessor function to return the numerator
	getDenominator()         // an accessor function to return the denominator

	/*** Operations Instance Methods [27] ***/
	assign(arg1, arg2)       // assignment to 'this' Rational object.

	selfAdd(arg)             // adds to 'this' Rational object another Rational object or an integer
	selfSub(arg)             // subtracts 'this' Rational object another Rational object or an integer
	selfMul(arg)             // multiplies 'this' Rational object by another Rational object or an integer
	selfDiv(arg)             // divides 'this' Rational object by another Rational object or an integer
	selfPow(arg)             // raise 'this' Rational object to the power given

	add(arg)                 // returns new Rational object without affecting 'this' Rational object
	sub(arg)                 // returns new Rational object without affecting 'this' Rational object
	mul(arg)                 // returns new Rational object without affecting 'this' Rational object
	div(arg)                 // returns new Rational object without affecting 'this' Rational object
	pow(arg)                 // returns new Rational object without affecting 'this' Rational object

	preInc()                 // increments 'this' Rational object and returns it
	preDec()                 // decrements 'this' Rational object and returns it
	postInc()                // increments 'this' Rational object and returns copy before increment
	postDec()                // increments 'this' Rational object and returns copy before decrement

	selfAbs()                // set 'this' Rational object to its absolute value
	selfNeg()                // negate 'this' Rational object to its absolute value

	abs()                    // returns absolute copy of 'this' Rational object
	neg()                    // returns negated copy of 'this' Rational object
	not()                    // returns true for zero rationals and false otherwise
	bool()                   // returns true for non-zero rationals and false otherwise
	
	lessThan(arg)            // comparison with a given Rational object or a number
	greaterThan(arg)         // comparison with a given Rational object or a number
	equalTo(arg)             // comparison with a given Rational object or a number
	notEqualTo(arg)          // comparison with a given Rational object or a number

	valueOf()                // returns the real numeric value of 'this' Rational object
	toString()               // returns a string representation of 'this' Rational object
}

Package Directory Structure

/nodecpp-rational
 │
 ├── binding.gyp            # JSON-like configuration file used by node-gyp to build the addon
 ├── demo                   # a package for demonstrating usage of 'nodecpp-rational' package
 │   ├── index.js
 │   ├── index.mjs
 │   └── package.json
 ├── docs
 │   ├── coverage           # code coverage reports
 │   │   ├── cpp            # code coverage report for C++ code
 │   │   │   ├── html       # HTML view of coverage data found in lcov.info tracefile
 │   │   │   └── lcov.info  # LCOV coverage trace file
 │   │   └── js             # code coverage report for JavaScript code
 │   │       ├── html       # HTML view of coverage data found in lcov.info tracefile
 │   │       └── lcov.info  # LCOV coverage trace file
 │   └── src                # source code documentation
 │       ├── cpp            # C++ source code documentation generated by doxygen
 │       └── js             # JavaScript source code documentation using JSDoc
 ├── include
 │   └── rational.h         # C++ header that defines a template based class rational
 ├── lib
 │   └── index.js
 ├── package.json
 ├── src
 │   ├── addon.cpp          # C++ code for registering the C++ addon within v8 context
 │   ├── rational-addon.cpp # C++ code implementing the addon-generated class 'Rational'
 │   └── rational-addon.h   # C++ header that defines the addon-generated class 'Rational'
 └── test
     ├── makefile           # makefile for building and documenting the 'rational.test.cpp' 
     ├── rational.module.js # JS module that defines a 'Rational' class to emulate the C++ addon
     ├── rational.test.cpp  # C++ code for testing the 'rational' class defined by rational.h
     └── rational.test.js   # JS module for testing the C++ addon againt the emulating JS module

Documentation

Source code documentation, along with test coverage reports for JavaScript and C++ addon code are all included under Documentation.

License

This software is licensed under the MIT license, see the LICENSE file.