Skip to content

Commit 28a9723

Browse files
kgrytekgryte
committed
feat: add complex/base/assert/is-same-value 
1 parent dc81423 commit 28a9723

File tree

15 files changed

+1178
-0
lines changed

15 files changed

+1178
-0
lines changed

‎lib/node_modules/@stdlib/complex/base/assert/is-same-value/README.md

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2024 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# isSameValue
22+
23+
> Test whether two double-precision complex floating-point numbers are the same value.
24+
25+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
26+
27+
<section class="intro">
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<!-- Package usage documentation. -->
34+
35+
<section class="usage">
36+
37+
## Usage
38+
39+
```javascript
40+
var isSameValue = require( '@stdlib/complex/base/assert/is-same-value' );
41+
```
42+
43+
#### isSameValue( z1, z2 )
44+
45+
Tests whether two double-precision complex floating-point numbers are the same value.
46+
47+
```javascript
48+
var Complex128 = require( '@stdlib/complex/float64' );
49+
50+
var z1 = new Complex128( 5.0, 3.0 );
51+
var z2 = new Complex128( 5.0, 3.0 );
52+
53+
var out = isSameValue( z1, z2 );
54+
// returns true
55+
```
56+
57+
In contract to the strict equality operator `===`, the function distinguishes between `+0` and `-0` and treats `NaNs` as the same value.
58+
59+
```javascript
60+
var Complex128 = require( '@stdlib/complex/float64' );
61+
62+
var z1 = new Complex128( NaN, NaN );
63+
var z2 = new Complex128( NaN, NaN );
64+
65+
var out = isSameValue( z1, z2 );
66+
// returns true
67+
68+
z1 = new Complex128( -0.0, 0.0 );
69+
z2 = new Complex128( 0.0, -0.0 );
70+
71+
out = isSameValue( z1, z2 );
72+
// returns false
73+
```
74+
75+
</section>
76+
77+
<!-- /.usage -->
78+
79+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
80+
81+
<section class="notes">
82+
83+
## Notes
84+
85+
- The function implements the [SameValue Algorithm][ecma-262-same-value-algorithm] as specified in ECMAScript 5.
86+
87+
</section>
88+
89+
<!-- /.notes -->
90+
91+
<!-- Package usage examples. -->
92+
93+
<section class="examples">
94+
95+
## Examples
96+
97+
<!-- eslint no-undef: "error" -->
98+
99+
```javascript
100+
var Complex128 = require( '@stdlib/complex/float64' );
101+
var isSameValue = require( '@stdlib/complex/base/assert/is-same-value' );
102+
103+
var z1 = new Complex128( 5.0, 3.0 );
104+
var z2 = new Complex128( 5.0, 3.0 );
105+
var out = isSameValue( z1, z2 );
106+
// returns true
107+
108+
z1 = new Complex128( -5.0, -3.0 );
109+
z2 = new Complex128( 5.0, 3.0 );
110+
out = isSameValue( z1, z2 );
111+
// returns false
112+
113+
z1 = new Complex128( NaN, 3.0 );
114+
z2 = new Complex128( NaN, 3.0 );
115+
out = isSameValue( z1, z2 );
116+
// returns true
117+
```
118+
119+
</section>
120+
121+
<!-- /.examples -->
122+
123+
<!-- C interface documentation. -->
124+
125+
* * *
126+
127+
<section class="c">
128+
129+
## C APIs
130+
131+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
132+
133+
<section class="intro">
134+
135+
</section>
136+
137+
<!-- /.intro -->
138+
139+
<!-- C usage documentation. -->
140+
141+
<section class="usage">
142+
143+
### Usage
144+
145+
```c
146+
#include "stdlib/complex/base/assert/is_same_value.h"
147+
```
148+
149+
#### stdlib_complex_is_same_value( z1, z2 )
150+
151+
Tests whether double-precision complex floating-point numbers are the same value.
152+
153+
```c
154+
#include "stdlib/complex/float64.h"
155+
#include <stdbool.h>
156+
157+
stdlib_complex128_t z1 = stdlib_complex128( 5.0, 2.0 );
158+
stdlib_complex128_t z2 = stdlib_complex128( 5.0, 2.0 );
159+
160+
bool v = stdlib_complex_is_same_value( z1, z2 );
161+
```
162+
163+
The function accepts the following arguments:
164+
165+
- **z1**: `[in] stdlib_complex128_t` first double-precision complex floating-point number.
166+
- **z2**: `[in] stdlib_complex128_t` second double-precision complex floating-point number.
167+
168+
```c
169+
bool stdlib_complex_is_same_value( const stdlib_complex128_t z1, const stdlib_complex128_t z2 );
170+
```
171+
172+
</section>
173+
174+
<!-- /.usage -->
175+
176+
<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
177+
178+
<section class="notes">
179+
180+
</section>
181+
182+
<!-- /.notes -->
183+
184+
<!-- C API usage examples. -->
185+
186+
<section class="examples">
187+
188+
### Examples
189+
190+
```c
191+
#include "stdlib/complex/base/assert/is_same_value.h"
192+
#include "stdlib/complex/float64.h"
193+
#include <stdbool.h>
194+
#include <stdio.h>
195+
196+
int main( void ) {
197+
const stdlib_complex128_t z[] = {
198+
stdlib_complex128( 5.0, 2.0 ),
199+
stdlib_complex128( -2.0, 1.0 ),
200+
stdlib_complex128( 0.0, -0.0 ),
201+
stdlib_complex128( 0.0/0.0, 0.0/0.0 )
202+
};
203+
204+
bool v;
205+
int i;
206+
for ( i = 0; i < 4; i++ ) {
207+
v = stdlib_complex_is_same_value( z[ i ], z[ i ] );
208+
printf( "Same value? %s\n", ( v ) ? "True" : "False" );
209+
}
210+
}
211+
```
212+
213+
</section>
214+
215+
<!-- /.examples -->
216+
217+
</section>
218+
219+
<!-- /.c -->
220+
221+
<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
222+
223+
<section class="references">
224+
225+
</section>
226+
227+
<!-- /.references -->
228+
229+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
230+
231+
<section class="related">
232+
233+
</section>
234+
235+
<!-- /.related -->
236+
237+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
238+
239+
<section class="links">
240+
241+
[ecma-262-same-value-algorithm]: http://ecma-international.org/ecma-262/5.1/#sec-9.12
242+
243+
</section>
244+
245+
<!-- /.links -->

‎lib/node_modules/@stdlib/complex/base/assert/is-same-value/benchmark/benchmark.js

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2024 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
// MODULES //
22+
23+
var bench = require( '@stdlib/bench' );
24+
var Complex128 = require( '@stdlib/complex/float64' );
25+
var randu = require( '@stdlib/random/base/randu' );
26+
var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive;
27+
var pkg = require( './../package.json' ).name;
28+
var isSameValue = require( './../lib' );
29+
30+
31+
// MAIN //
32+
33+
bench( pkg, function benchmark( b ) {
34+
var z1;
35+
var z2;
36+
var v;
37+
var i;
38+
39+
z1 = [
40+
new Complex128( randu(), randu() ),
41+
new Complex128( randu(), randu() )
42+
];
43+
z2 = [
44+
new Complex128( randu(), randu() ),
45+
new Complex128( randu(), randu() ),
46+
z1[ 0 ],
47+
z1[ 1 ]
48+
];
49+
50+
b.tic();
51+
for ( i = 0; i < b.iterations; i++ ) {
52+
v = isSameValue( z1[ i%z1.length ], z2[ i%z2.length ] );
53+
if ( typeof v !== 'boolean' ) {
54+
b.fail( 'should return a boolean' );
55+
}
56+
}
57+
b.toc();
58+
if ( !isBoolean( v ) ) {
59+
b.fail( 'should return a boolean' );
60+
}
61+
b.pass( 'benchmark finished' );
62+
b.end();
63+
});

‎lib/node_modules/@stdlib/complex/base/assert/is-same-value/docs/repl.txt

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
2+
{{alias}}( z1, z2 )
3+
Tests whether two double-precision complex floating-point numbers are the
4+
same value.
5+
6+
The function differs from the `===` operator in that the function treats
7+
`-0` and `+0` as distinct and `NaNs` as the same.
8+
9+
Parameters
10+
----------
11+
z1: Complex128
12+
First complex number.
13+
14+
z2: Complex128
15+
Second complex number.
16+
17+
Returns
18+
-------
19+
out: boolean
20+
Result.
21+
22+
Examples
23+
--------
24+
> var z1 = new {{alias:@stdlib/complex/float64}}( 5.0, 3.0 );
25+
> var z2 = new {{alias:@stdlib/complex/float64}}( 5.0, 3.0 );
26+
> var v = {{alias}}( z1, z2 )
27+
true
28+
29+
See Also
30+
--------
31+

‎lib/node_modules/@stdlib/complex/base/assert/is-same-value/docs/types/index.d.ts

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
/*
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2024 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
// TypeScript Version: 4.1
20+
21+
import Complex128 = require( '@stdlib/complex/float64' );
22+
23+
/**
24+
* Tests whether two double-precision complex floating-point numbers are the same value.
25+
*
26+
* ## Notes
27+
*
28+
* - The function implements the [SameValue Algorithm][ecma-262-same-value-algorithm], as specified in ECMAScript 5.
29+
* - In contrast to the strict equality operator `===`, `-0` and `+0` are distinguishable and `NaNs` are the same.
30+
*
31+
* [ecma-262-same-value-algorithm]: http://ecma-international.org/ecma-262/5.1/#sec-9.12
32+
*
33+
* @param z1 - first complex number
34+
* @param z2 - second complex number
35+
* @returns boolean indicating if both complex numbers are the same value
36+
*
37+
* @example
38+
* var Complex128 = require( '@stdlib/complex/float64' );
39+
*
40+
* var z1 = new Complex128( 5.0, 3.0 );
41+
* var z2 = new Complex128( 5.0, 3.0 );
42+
*
43+
* var v = isSameValue( z1, z2 );
44+
* // returns true
45+
*/
46+
declare function isSameValue( z1: Complex128, z2: Complex128 ): boolean;
47+
48+
49+
// EXPORTS //
50+
51+
export = isSameValue;

0 commit comments

Comments
 (0)