@ohos-ports/stdlib-simulate 0.4.1-beta.0

package/iter/awln/docs/repl.txt

@@ -0,0 +1,85 @@
+
+{{alias}}( iterator, sigma[, options] )
+    Returns an iterator which introduces additive white Laplacian noise (AWLN)
+    with standard deviation `sigma`.
+
+    If an environment supports Symbol.iterator and the provided iterator is
+    iterable, the returned iterator is iterable.
+
+    Parameters
+    ----------
+    iterator: Object
+        Input iterator.
+
+    sigma: number
+        Standard deviation of the noise.
+
+    options: Object (optional)
+        Options.
+
+    options.prng: Function (optional)
+        Pseudorandom number generator (PRNG) for generating uniformly
+        distributed pseudorandom numbers on the interval [0,1). If provided, the
+        `state` and `seed` options are ignored. In order to seed the returned
+        iterator, one must seed the provided `prng` (assuming the provided
+        `prng` is seedable).
+
+    options.seed: integer|ArrayLikeObject<integer> (optional)
+        Pseudorandom number generator seed. The seed may be either a positive
+        unsigned 32-bit integer or, for arbitrary length seeds, an array-like
+        object containing unsigned 32-bit integers.
+
+    options.state: Uint32Array (optional)
+        Pseudorandom number generator state. If provided, the `seed` option is
+        ignored.
+
+    options.copy: boolean (optional)
+        Boolean indicating whether to copy a provided pseudorandom number
+        generator state. Setting this option to `false` allows sharing state
+        between two or more pseudorandom number generators. Setting this option
+        to `true` ensures that a returned iterator has exclusive control over
+        its internal state. Default: true.
+
+    Returns
+    -------
+    iterator: Object
+        Iterator.
+
+    iterator.next(): Function
+        Returns an iterator protocol-compliant object containing the next
+        iterated value (if one exists) and a boolean flag indicating whether the
+        iterator is finished.
+
+    iterator.return( [value] ): Function
+        Finishes an iterator and returns a provided value.
+
+    iterator.PRNG: Function
+        Underlying pseudorandom number generator.
+
+    iterator.seed: Uint32Array|null
+        Pseudorandom number generator seed.
+
+    iterator.seedLength: integer|null
+        Length of generator seed.
+
+    iterator.state: Uint32Array|null
+        Pseudorandom random number generator state.
+
+    iterator.stateLength: integer|null
+        Length of generator state.
+
+    iterator.byteLength: integer|null
+        Size (in bytes) of generator state.
+
+    Examples
+    --------
+    > var src = {{alias:@stdlib/simulate/iter/sine-wave}}();
+    > var it = {{alias}}( src, 0.5 );
+    > var v = it.next().value
+    <number>
+    > v = it.next().value
+    <number>
+
+    See Also
+    --------
+

package/iter/awln/docs/types/index.d.ts

@@ -0,0 +1,155 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2019 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+// TypeScript Version: 4.1
+
+/// <reference types="@stdlib/types"/>
+
+import { Iterator as Iter, IterableIterator } from '@stdlib/types/iter';
+import * as random from '@stdlib/types/random';
+
+// Define a union type representing both iterable and non-iterable iterators:
+type Iterator = Iter | IterableIterator;
+
+/**
+* Interface defining function options.
+*/
+interface Options {
+	/**
+	* Pseudorandom number generator which generates uniformly distributed pseudorandom numbers on the interval `[0,1)`.
+	*
+	* ## Notes
+	*
+	* -   If provided, the `state` and `seed` options are ignored. In order to seed the returned iterator, one must seed the provided `prng` (assuming the provided `prng` is seedable).
+	*/
+	prng?: random.PRNG;
+
+	/**
+	* Pseudorandom number generator state.
+	*
+	* ## Notes
+	*
+	* -   If provided, the `seed` option is ignored.
+	*/
+	state?: random.PRNGStateMT19937;
+
+	/**
+	* Pseudorandom number generator seed.
+	*/
+	seed?: random.PRNGSeedMT19937;
+
+	/**
+	* Specifies whether to copy a provided pseudorandom number generator state.
+	*
+	* ## Notes
+	*
+	* -   Setting this option to `false` allows sharing state between two or more pseudorandom number generators. Setting this option to `true` ensures that a returned iterator has exclusive control over its internal state.
+	*/
+	copy?: boolean;
+}
+
+/**
+* Interface defining a returned iterator.
+*/
+interface ExtendedIter extends Iter {
+	/**
+	* Underlying PRNG.
+	*/
+	readonly PRNG: random.PRNG;
+
+	/**
+	* PRNG seed.
+	*/
+	readonly seed: random.PRNGSeedMT19937 | null;
+
+	/**
+	* PRNG seed length.
+	*/
+	readonly seedLength: number | null;
+
+	/**
+	* PRNG state.
+	*/
+	state: random.PRNGStateMT19937 | null;
+
+	/**
+	* PRNG state length.
+	*/
+	readonly stateLength: number | null;
+
+	/**
+	* PRNG state size (in bytes).
+	*/
+	readonly byteLength: number | null;
+}
+
+/**
+* Interface defining a returned iterable iterator.
+*/
+interface ExtendedIterableIterator extends ExtendedIter {
+	/**
+	* Returns a new iterable iterator.
+	*
+	* @returns iterable iterator
+	*/
+	[Symbol.iterator](): IterableIterator;
+}
+
+// Define a union type representing both iterable and non-iterable returned iterators:
+type ExtendedIterator = ExtendedIter | ExtendedIterableIterator;
+
+/**
+* Returns an iterator which introduces additive white Laplacian (a.k.a. biexponential or double-exponential) noise with standard deviation `sigma`.
+*
+* @param iterator - input iterator
+* @param sigma - standard deviation of the noise
+* @param options - function options
+* @param options.prng - pseudorandom number generator for generating uniformly distributed pseudorandom numbers on the interval `[0,1)`
+* @param options.state - pseudorandom number generator state
+* @param options.seed - pseudorandom number generator seed
+* @param options.copy - boolean indicating whether to copy a provided pseudorandom number generator state (default: true)
+* @throws `sigma` must be a positive number
+* @throws must provide a valid state
+* @returns iterator
+*
+* @example
+* var iterSineWave = require( '@stdlib/simulate/iter/sine-wave' );
+*
+* var sine = iterSineWave({
+*     'iter': 100
+* });
+*
+* var it = iterawln( sine, 0.5 );
+*
+* var v = it.next().value;
+* // returns <number>
+*
+* v = it.next().value;
+* // returns <number>
+*
+* v = it.next().value;
+* // returns <number>
+*
+* // ...
+*/
+declare function iterawln( iterator: Iterator, sigma: number, options?: Options ): ExtendedIterator;
+
+
+// EXPORTS //
+
+export = iterawln;

package/iter/awln/docs/types/test.ts

@@ -0,0 +1,150 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2019 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+import iterawln = require( './index' );
+
+/**
+* Returns an iterator protocol-compliant object.
+*
+* @returns iterator protocol-compliant object
+*/
+function iterator() {
+	return {
+		'next': next
+	};
+
+	/**
+	* Implements the iterator protocol `next` method.
+	*
+	* @returns iterator protocol-compliant object
+	*/
+	function next() {
+		return {
+			'value': true,
+			'done': false
+		};
+	}
+}
+
+
+// TESTS //
+
+// The function returns an iterator...
+{
+	iterawln( iterator(), 0.2 ); // $ExpectType ExtendedIterator
+	iterawln( iterator(), 0.2, {} ); // $ExpectType ExtendedIterator
+	iterawln( iterator(), 0.2, { 'seed': 12345 } ); // $ExpectType ExtendedIterator
+}
+
+// The compiler throws an error if the function is provided a first argument which is not an iterator protocol-compliant object...
+{
+	iterawln( '5', 1.0 ); // $ExpectError
+	iterawln( 5, 1.0 ); // $ExpectError
+	iterawln( true, 1.0 ); // $ExpectError
+	iterawln( false, 1.0 ); // $ExpectError
+	iterawln( null, 1.0 ); // $ExpectError
+	iterawln( undefined, 1.0 ); // $ExpectError
+	iterawln( [], 1.0 ); // $ExpectError
+	iterawln( {}, 1.0 ); // $ExpectError
+	iterawln( ( x: number ): number => x, 1.0 ); // $ExpectError
+
+	iterawln( '5', 1.0, {} ); // $ExpectError
+	iterawln( 5, 1.0, {} ); // $ExpectError
+	iterawln( true, 1.0, {} ); // $ExpectError
+	iterawln( false, 1.0, {} ); // $ExpectError
+	iterawln( null, 1.0, {} ); // $ExpectError
+	iterawln( undefined, 1.0, {} ); // $ExpectError
+	iterawln( [], 1.0, {} ); // $ExpectError
+	iterawln( {}, 1.0, {} ); // $ExpectError
+	iterawln( ( x: number ): number => x, 1.0, {} ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a second argument which is not a number...
+{
+	iterawln( iterator(), '5' ); // $ExpectError
+	iterawln( iterator(), true ); // $ExpectError
+	iterawln( iterator(), false ); // $ExpectError
+	iterawln( iterator(), null ); // $ExpectError
+	iterawln( iterator(), undefined ); // $ExpectError
+	iterawln( iterator(), [] ); // $ExpectError
+	iterawln( iterator(), {} ); // $ExpectError
+	iterawln( iterator(), ( x: number ): number => x ); // $ExpectError
+
+	iterawln( iterator(), '5', {} ); // $ExpectError
+	iterawln( iterator(), true, {} ); // $ExpectError
+	iterawln( iterator(), false, {} ); // $ExpectError
+	iterawln( iterator(), null, {} ); // $ExpectError
+	iterawln( iterator(), undefined, {} ); // $ExpectError
+	iterawln( iterator(), [], {} ); // $ExpectError
+	iterawln( iterator(), {}, {} ); // $ExpectError
+	iterawln( iterator(), ( x: number ): number => x, {} ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a third argument which is not an object...
+{
+	iterawln( iterator(), 1.0, null ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an invalid `seed` option...
+{
+	iterawln( iterator(), 1.0, { 'seed': '5' } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'seed': true } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'seed': false } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'seed': null } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'seed': {} } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'seed': ( x: number ): number => x } ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an invalid `prng` option...
+{
+	iterawln( iterator(), 1.0, { 'prng': '5' } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'prng': 5 } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'prng': true } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'prng': false } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'prng': null } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'prng': [] } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'prng': {} } ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an invalid `state` option...
+{
+	iterawln( iterator(), 1.0, { 'state': '5' } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'state': 5 } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'state': true } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'state': false } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'state': null } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'state': [] } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'state': {} } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'state': ( x: number ): number => x } ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an invalid `copy` option...
+{
+	iterawln( iterator(), 1.0, { 'copy': '5' } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'copy': 5 } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'copy': null } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'copy': [] } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'copy': {} } ); // $ExpectError
+	iterawln( iterator(), 1.0, { 'copy': ( x: number ): number => x } ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided insufficient arguments...
+{
+	iterawln(); // $ExpectError
+	iterawln( iterator() ); // $ExpectError
+}

package/iter/awln/lib/defaults.js

@@ -0,0 +1,38 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MAIN //
+
+/**
+* Returns default options.
+*
+* @private
+* @returns {Object} default options
+*/
+function defaults() {
+	return {
+		'copy': true
+	};
+}
+
+
+// EXPORTS //
+
+module.exports = defaults;

package/iter/awln/lib/index.js

@@ -0,0 +1,55 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2019 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+/**
+* Create an iterator which introduces additive white Laplacian noise (AWLN).
+*
+* @module @stdlib/simulate/iter/awln
+*
+* @example
+* var iterSineWave = require( '@stdlib/simulate/iter/sine-wave' );
+* var iterawln = require( '@stdlib/simulate/iter/awln' );
+*
+* var sine = iterSineWave({
+*     'iter': 100
+* });
+*
+* var it = iterawln( sine, 0.5 );
+*
+* var v = it.next().value;
+* // returns <number>
+*
+* v = it.next().value;
+* // returns <number>
+*
+* v = it.next().value;
+* // returns <number>
+*
+* // ...
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;