cordova-plugin-example-isprime
Version:
Checks if a number is prime, and if not, returns the corresponding factors. Used for PhoneGap Day EU 2017 'Creating Modern PhoneGap Plugins' workshop; not intended for production use (there are better ways to find primes!)
114 lines (84 loc) • 5.25 kB
Markdown
# cordova-plugin-example-isprime
Determines if a number is prime, and if not, returns the factors.
> **IMPORTANT:** This plugin was developed for PhoneGap Day EU 2017's "Creating a Modern PhoneGap Plugin" workshop as an example. This is not intended for use in production applications! There are far better and faster ways to check candidate primes!
## Platforms
Supported on iOS, Android, Windows, and browser platforms.
> **Note:** iOS, Android, and Windows gain the benefit of faster computations. In order for the browser and Windows apps to remain responsive, the computations are batched in smaller portions.
> **Windows:** When running on Windows 10, you'll need to specify the platform (e.g., `cordova run windows --archs=x64`)
## Installation
To install, use one of two methods:
* `cordova plugin add [--save] cordova-plugin-example-isprime`
* Add the following to your `config.xml`:
```xml
<plugin name="cordova-plugin-example-isprime"/>
```
> **Note:** This will retrieve the latest version of the plugin should you later remove it (or use with PhoneGap Build). You may wish to pin to a specific version using the `spec` attribute.
## Usage
You can use one of two patterns to check if a number is prime:
* Typical callback pattern
```javascript
cordova.plugins.kas.isPrime(win, fail, 7);
function win(result) {
if (result.complete) {
if (result.isPrime) {
console.log(result.candidate + " is prime!");
} else {
console.log(result.candidate + " has factors " + result.factors);
}
} else {
// calculation ongoing; progress is 0 - 100
console.log(result.progress);
}
}
function fail(err) {
console.log("error: " + err);
}
```
* Promise pattern (if supported by the environment)
```javascript
cordova.plugins.kas.isPrime(7)
.then(function(result) {
if (result.isPrime) {
console.log(result.candidate + " is prime!");
} else {
console.log(result.candidate + " has factors " + result.factors);
}
}).catch(function(err) {
console.log("error: " + err);
});
> **Note:** If you need progress reports, pass a function as the second parameter; i.e., `cordova.plugins.kas.isPrime(7, progressFn)`
Interim and completion results passed to the success callback look like this:
```typescript
{
candidate: Number, // the requested candidate
complete: Boolean, // true if the calculation is complete
factors: Array<Number> // factors of the candidate if NOT prime
isPrime: Boolean, // indicates if the candidate is prime
progress: Number, // indicates progress of the calculation (0-100)
}
```
**Note:** do **not** count on intermediate progress reports being made; different platforms report at different intervals, and there may not be a report prior to the completion report.
The following errors can be thrown (when using `Promises`, they are propagated to your `catch` handler):
* "Native promises aren't supported in this environment" — API was called using the Promise pattern, but Promises aren't available in this environment. **Note:** this is the only error that is actually _thrown_ when using the Promise pattern; all others are passed to your `catch` handler.
* "Success callback must be a function" — You must supply a function that can be called upon completion of the calculation when not using the Promise pattern.
* "Failure callback must be a function" — although rare, some platforms can generate native-side errors; you need to supply a failure function to handle these errors when not using the Promise pattern.
* "Candidate must be a positive whole number greater than 1" — Primes are not defined for any numbers less than 2.
* "Candidate must be within JavaScript's safe integer limit of 2^53-1" — Attempting to calculate primes beyond this limit could yield incorrect results. Because of this, no calculation is attempted.
* "Candidate must be an integer" — Primes are only defined for whole numbers.
* "JSON Exception; check that the JS API is passing the right result object" (Android) — This error should never occur. If it does, please contact the plugin developer.
## Important Notes
* Calculations are processed in background threads on iOS and Android. These calculations **do not** stop if the webview is navigated. This is left as an exercise to the reader.
* Calculations on the Browser platform are much slower in order to avoid blocking the webview.
* Be careful with the size of primes passed; you may end up with a computation that takes quite some time.
* Do remember — this plugin can't check primality of any number greater than 2^53-1.
## Testing
You can run the tests by executing the following commands:
```
$ npm run test:android
$ npm run test:browser
$ npm run test:ios
$ npm run test:windows
```
> **Note:** You must have appropriate SDK installed in order to run the corresponding tests. If testing Windows apps, you must **NOT** be logged in as an administrator.
## License
MIT.