diff --git a/lib/node_modules/@stdlib/number/float16/ctor/README.md b/lib/node_modules/@stdlib/number/float16/ctor/README.md new file mode 100644 index 000000000000..56ef1ab0798d --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/README.md @@ -0,0 +1,374 @@ + + +# Float16 + +> 16-bit half-precision floating-point number. + + + +
+ +
+ + + + + +
+ +## Usage + +```javascript +var Float16 = require( '@stdlib/number/float16/ctor' ); +``` + +#### Float16( value ) + +16-bit half-precision floating-point number constructor. + +```javascript +var x = new Float16( 5.0 ); +// returns +``` + +* * * + +## Properties + +#### Float16.name + +Static property returning the constructor name. + +```javascript +var str = Float16.name; +// returns 'Float16' +``` + +#### Float16.BYTES_PER_ELEMENT + +Size (in bytes) of the underlying value. + +```javascript +var nbytes = Float16.BYTES_PER_ELEMENT; +// returns 2 +``` + +#### Float16.prototype.BYTES_PER_ELEMENT + +Size (in bytes) of the underlying value. + +```javascript +var x = new Float16( 5.0 ); + +var nbytes = x.BYTES_PER_ELEMENT; +// returns 2 +``` + +### Instance + +A `Float16` instance has the following properties... + +#### value + +A **read-only** property returning the underlying value as a number. + +```javascript +var x = new Float16( 5.0 ); + +var v = x.value; +// returns 5.0 +``` + +* * * + +## Methods + +### Accessor Methods + +These methods do **not** mutate a `Float16` instance and, instead return a half-precision floating-point number representation. + +#### Float16.prototype.toString() + +Returns a string representation of a `Float16` instance. + +```javascript +var x = new Float16( 5.0 ); +var str = x.toString(); +// returns '5' + +x = new Float16( -3.14 ); +str = x.toString(); +// returns '-3.140625' +``` + +#### Float16.prototype.toJSON() + +Returns a [JSON][json] representation of a `Float16` instance. [`JSON.stringify()`][mdn-json-stringify] implicitly calls this method when stringifying a `Float16` instance. + +```javascript +var x = new Float16( 5.0 ); + +var o = x.toJSON(); +/* + { + "type": "Float16", + "value": 5.0 + } +*/ +``` + +To [revive][mdn-json-parse] a `Float16` number from a [JSON][json] `string`, see [@stdlib/number/float16/reviver][@stdlib/number/float16/reviver]. + +#### Float16.prototype.valueOf() + +Converts a `Float16` instance to a primitive value. + +```javascript +var x = new Float16( 5.0 ); +var v = x.valueOf(); +// returns 5.0 + +x = new Float16( 3.14 ); +v = x.valueOf(); +// returns 3.140625 +``` + +
+ + + +* * * + + + +
+ +## Notes + +- The underlying value is stored as a half-precision floating-point number [IEEE 754][ieee754] with 1 sign bit, 5 exponent bits, and 10 significand bits. +- A half-precision floating-point number has a range of approximately `±6.55e4` and a precision of about 3-4 decimal digits. + +
+ + + +* * * + + + +
+ +## Examples + + + +```javascript +var Float16 = require( '@stdlib/number/float16/ctor' ); + +var x = new Float16( 3.14 ); + +console.log( 'type: %s', typeof x ); +// => 'type: object' + +console.log( 'str: %s', x ); +// => 'str: 3.140625' + +console.log( 'value: %d', x.value ); +// => 'value: 3.140625' + +console.log( 'JSON: %s', JSON.stringify( x ) ); +// => 'JSON: {"type":"Float16","value":3.140625}' +``` + +
+ + + + + +* * * + +
+ +## C APIs + + + +
+ +
+ + + + + +
+ +### Usage + +```c +#include "stdlib/number/float16/ctor.h" +``` + +#### stdlib_float16_t + +An opaque type definition for a half-precision floating-point number. + +```c +stdlib_float16_t v = stdlib_float16_from_bits( 51648 ); +``` + +#### stdlib_float16_bits_t + +An opaque type definition for a union for accessing the underlying binary representation of a half-precision floating-point number. + +```c +#include + +stdlib_float16_t x = stdlib_float16_from_bits( 51648 ); + +stdlib_float16_bits_t y; +y.value = x; + +uint16_t bits = y.bits; +// returns 51648 +``` + +The union has the following members: + +- **value**: `stdlib_float16_t` half-precision floating-point number. +- **bits**: `uint16_t` binary representation. + +The union allows "type punning"; however, while (more or less) defined in C99, behavior is implementation-defined in C++. For more robust conversion, prefer using explicit helpers for converting to and from binary representation. + +#### stdlib_float16_from_bits( bits ) + +Converts a 16-bit binary representation to a half-precision floating-point number. + +```c +stdlib_float16_t v = stdlib_float16_from_bits( 51648 ); // => -11.5 +``` + +The function accepts the following arguments: + +- **bits**: `[in] uint16_t` 16-bit integer corresponding to a binary representation. + +#### stdlib_float16_to_bits( x ) + +Converts a half-precision floating-point number to a 16-bit binary representation. + +```c +#include + +stdlib_float16_t v = stdlib_float16_from_bits( 51648 ); // => -11.5 + +uint16_t bits = stdlib_float16_to_bits( v ); +``` + +The function accepts the following arguments: + +- **x**: `[in] stdlib_float16_t` half-precision floating-point number. + +
+ + + + + +
+ +### Notes + +- The `stdlib_float16_t` type should be treated as a storage and interchange type. Native hardware support for mathematical functions operating on half-precision floating-point numbers varies. As a consequence, for most operations, one should first promote to single-precision (i.e., `float`), perform the desired operation, and then downcast back to half-precision. + +
+ + + + + +
+ +### Examples + +```c +#include "stdlib/number/float16/ctor.h" +#include +#include + +int main( void ) { + const stdlib_float16_t x[] = { + stdlib_float16_from_bits( 51648 ), // -11.5 + stdlib_float16_from_bits( 18880 ) // 11.5 + }; + + int i; + for ( i = 0; i < 2; i++ ) { + printf( "%d\n", stdlib_float16_to_bits( x[ i ] ) ); + } +} +``` + +
+ + + +
+ + + + + +
+ +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/number/float16/ctor/benchmark/benchmark.js b/lib/node_modules/@stdlib/number/float16/ctor/benchmark/benchmark.js new file mode 100644 index 000000000000..ed1265e901c0 --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/benchmark/benchmark.js @@ -0,0 +1,116 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 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'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var randu = require( '@stdlib/random/base/randu' ); +var isnan = require( '@stdlib/math/base/assert/is-nan' ); +var format = require( '@stdlib/string/format' ); +var pkg = require( './../package.json' ).name; +var Float16 = require( './../lib' ); + + +// MAIN // + +bench( pkg, function benchmark( b ) { + var z; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + z = new Float16( i, i ); + if ( isnan( z ) ) { + b.fail( 'should not return NaN' ); + } + } + b.toc(); + if ( !( z instanceof Float16 ) ) { + b.fail( 'should return a complex number' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::get:value', pkg ), function benchmark( b ) { + var v; + var z; + var i; + + z = new Float16( randu() ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = z.value; + if ( isnan( v ) ) { + b.fail( 'should not return NaN' ); + } + } + b.toc(); + if ( isnan( v ) ) { + b.fail( 'should not return NaN' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s:toString', pkg ), function benchmark( b ) { + var o; + var z; + var i; + + z = new Float16( randu() ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + o = z.toString(); + if ( typeof o !== 'string' ) { + b.fail( 'should return a string' ); + } + } + b.toc(); + if ( typeof o !== 'string' ) { + b.fail( 'should return a string' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s:toJSON', pkg ), function benchmark( b ) { + var o; + var z; + var i; + + z = new Float16( randu() ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + o = z.toJSON(); + if ( typeof o !== 'object' ) { + b.fail( 'should return an object' ); + } + } + b.toc(); + if ( typeof o !== 'object' ) { + b.fail( 'should return an object' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/number/float16/ctor/docs/repl.txt b/lib/node_modules/@stdlib/number/float16/ctor/docs/repl.txt new file mode 100644 index 000000000000..69b082d5f0c8 --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/docs/repl.txt @@ -0,0 +1,66 @@ + +{{alias}}( value ) + 16-bit half-precision floating-point number constructor. + + Parameters + ---------- + value: number + Numeric value. + + Returns + ------- + v: Float16 + Half-precision floating-point number. + + v.value: number + Read-only property returning the underlying value. + + Examples + -------- + > var x = new {{alias}}( 3.14 ) + + > x.value + 3.140625 + + +{{alias}}.name + Constructor name. + + Examples + -------- + > var str = {{alias}}.name + 'Float16' + + +{{alias}}.BYTES_PER_ELEMENT + Size (in bytes) of the underlying value. + + Returns + ------- + s: integer + Size (in bytes) of the underlying value. + + Examples + -------- + > var s = {{alias}}.BYTES_PER_ELEMENT + 2 + + +{{alias}}.prototype.BYTES_PER_ELEMENT + Size (in bytes) of the underlying value. + + Returns + ------- + s: integer + Size (in bytes) of the underlying value. + + Examples + -------- + > var x = new {{alias}}( 5.0 ) + + > var s = x.BYTES_PER_ELEMENT + 2 + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/number/float16/ctor/docs/types/index.d.ts b/lib/node_modules/@stdlib/number/float16/ctor/docs/types/index.d.ts new file mode 100644 index 000000000000..c674712de312 --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/docs/types/index.d.ts @@ -0,0 +1,103 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2025 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 + +/** +* 16-bit half-precision floating-point number. +*/ +declare class Float16 { + /** + * 16-bit half-precision floating-point number constructor. + * + * @param value - numeric value + * @returns half-precision floating-point number + * + * @example + * var x = new Float16( 5.0 ); + * // returns + */ + constructor( value: number ); + + /** + * Read-only property returning the value. + * + * @returns value + */ + readonly value: number; + + /** + * Size (in bytes) of the underlying value. + * + * @returns size of the underlying value. + * + * @example + * var nbytes = Float16.BYTES_PER_ELEMENT; + * // returns 2 + */ + readonly BYTES_PER_ELEMENT: 2; + + /** + * Serializes a half-precision floating-point number as a string. + * + * @returns serialized half-precision floating-point number + * + * @example + * var x = new Float16( 5.0 ); + * + * var str = x.toString(); + * // returns '5' + */ + toString(): string; + + /** + * Serializes a half-precision floating-point number as a JSON object. + * + * ## Notes + * + * - `JSON.stringify()` implicitly calls this method when stringifying a `Float16` instance. + * + * + * @returns serialized half-precision floating-point number + * + * @example + * var x = new Float16( 5.0 ); + * + * var obj = x.toJSON(); + * // returns { 'type': 'Float16', 'value': 5.0 } + */ + toJSON(): any; + + /** + * Converts a half-precision floating-point number to a primitive value. + * + * @returns primitive value + * + * @example + * var x = new Float16( 5.0 ); + * + * var v = x.valueOf(); + * // returns 5.0 + */ + valueOf(): number; +} + + +// EXPORTS // + +export = Float16; diff --git a/lib/node_modules/@stdlib/number/float16/ctor/docs/types/test.ts b/lib/node_modules/@stdlib/number/float16/ctor/docs/types/test.ts new file mode 100644 index 000000000000..c836c2d9a3fa --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/docs/types/test.ts @@ -0,0 +1,64 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2025 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. +*/ + +/* eslint-disable @typescript-eslint/no-unused-expressions */ + +import Float16 = require( './index' ); + + +// TESTS // + +// The function returns a 16-bit half-precision floating-point number with the expected properties... +{ + const x = new Float16( 5.0 ); // $ExpectType Float16 + + x.value; // $ExpectType number + x.BYTES_PER_ELEMENT; // $ExpectType 2 +} + +// 16-bit half-precision floating-point number comes with a `toString` method to serialize a number as a string... +{ + const x = new Float16( 5.0 ); // $ExpectType Float16 + + x.toString(); // $ExpectType string +} + +// 16-bit half-precision floating-point number comes with a `toJSON` method to serialize a number as a JSON object.... +{ + const x = new Float16( 5.0 ); // $ExpectType Float16 + + x.toJSON(); // $ExpectType any +} + +// 16-bit half-precision floating-point number comes with a `valueOf` method to serialize a number to a primitive value... +{ + const x = new Float16( 5.0 ); // $ExpectType Float16 + + x.valueOf(); // $ExpectType number +} + +// The compiler throws an error if the constructor is invoked without the `new` keyword... +{ + Float16( 5.0 ); // $ExpectError +} + +// The compiler throws an error if the constructor is provided an unsupported number of arguments... +{ + new Float16( ); // $ExpectError + new Float16( 5.0, 3.0 ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/number/float16/ctor/examples/c/Makefile b/lib/node_modules/@stdlib/number/float16/ctor/examples/c/Makefile new file mode 100644 index 000000000000..25ced822f96a --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/examples/c/Makefile @@ -0,0 +1,146 @@ +#/ +# @license Apache-2.0 +# +# Copyright (c) 2025 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. +#/ + +# VARIABLES # + +ifndef VERBOSE + QUIET := @ +else + QUIET := +endif + +# Determine the OS ([1][1], [2][2]). +# +# [1]: https://en.wikipedia.org/wiki/Uname#Examples +# [2]: http://stackoverflow.com/a/27776822/2225624 +OS ?= $(shell uname) +ifneq (, $(findstring MINGW,$(OS))) + OS := WINNT +else +ifneq (, $(findstring MSYS,$(OS))) + OS := WINNT +else +ifneq (, $(findstring CYGWIN,$(OS))) + OS := WINNT +else +ifneq (, $(findstring Windows_NT,$(OS))) + OS := WINNT +endif +endif +endif +endif + +# Define the program used for compiling C source files: +ifdef C_COMPILER + CC := $(C_COMPILER) +else + CC := gcc +endif + +# Define the command-line options when compiling C files: +CFLAGS ?= \ + -std=c99 \ + -O3 \ + -Wall \ + -pedantic + +# Determine whether to generate position independent code ([1][1], [2][2]). +# +# [1]: https://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code-Gen-Options +# [2]: http://stackoverflow.com/questions/5311515/gcc-fpic-option +ifeq ($(OS), WINNT) + fPIC ?= +else + fPIC ?= -fPIC +endif + +# List of includes (e.g., `-I /foo/bar -I /beep/boop/include`): +INCLUDE ?= + +# List of source files: +SOURCE_FILES ?= + +# List of libraries (e.g., `-lopenblas -lpthread`): +LIBRARIES ?= + +# List of library paths (e.g., `-L /foo/bar -L /beep/boop`): +LIBPATH ?= + +# List of C targets: +c_targets := example.out + + +# RULES # + +#/ +# Compiles source files. +# +# @param {string} [C_COMPILER] - C compiler (e.g., `gcc`) +# @param {string} [CFLAGS] - C compiler options +# @param {(string|void)} [fPIC] - compiler flag determining whether to generate position independent code (e.g., `-fPIC`) +# @param {string} [INCLUDE] - list of includes (e.g., `-I /foo/bar -I /beep/boop/include`) +# @param {string} [SOURCE_FILES] - list of source files +# @param {string} [LIBPATH] - list of library paths (e.g., `-L /foo/bar -L /beep/boop`) +# @param {string} [LIBRARIES] - list of libraries (e.g., `-lopenblas -lpthread`) +# +# @example +# make +# +# @example +# make all +#/ +all: $(c_targets) + +.PHONY: all + +#/ +# Compiles C source files. +# +# @private +# @param {string} CC - C compiler (e.g., `gcc`) +# @param {string} CFLAGS - C compiler options +# @param {(string|void)} fPIC - compiler flag determining whether to generate position independent code (e.g., `-fPIC`) +# @param {string} INCLUDE - list of includes (e.g., `-I /foo/bar`) +# @param {string} SOURCE_FILES - list of source files +# @param {string} LIBPATH - list of library paths (e.g., `-L /foo/bar`) +# @param {string} LIBRARIES - list of libraries (e.g., `-lopenblas`) +#/ +$(c_targets): %.out: %.c + $(QUIET) $(CC) $(CFLAGS) $(fPIC) $(INCLUDE) -o $@ $(SOURCE_FILES) $< $(LIBPATH) -lm $(LIBRARIES) + +#/ +# Runs compiled examples. +# +# @example +# make run +#/ +run: $(c_targets) + $(QUIET) ./$< + +.PHONY: run + +#/ +# Removes generated files. +# +# @example +# make clean +#/ +clean: + $(QUIET) -rm -f *.o *.out + +.PHONY: clean diff --git a/lib/node_modules/@stdlib/number/float16/ctor/examples/c/example.c b/lib/node_modules/@stdlib/number/float16/ctor/examples/c/example.c new file mode 100644 index 000000000000..49fb399cf6f4 --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/examples/c/example.c @@ -0,0 +1,33 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 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. +*/ + +#include "stdlib/number/float16/ctor.h" +#include +#include + +int main( void ) { + const stdlib_float16_t x[] = { + stdlib_float16_from_bits( 51648 ), // -11.5 + stdlib_float16_from_bits( 18880 ) // 11.5 + }; + + int i; + for ( i = 0; i < 2; i++ ) { + printf( "%d\n", stdlib_float16_to_bits( x[ i ] ) ); + } +} diff --git a/lib/node_modules/@stdlib/number/float16/ctor/examples/index.js b/lib/node_modules/@stdlib/number/float16/ctor/examples/index.js new file mode 100644 index 000000000000..649e98d74215 --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/examples/index.js @@ -0,0 +1,35 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 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'; + +var Float16 = require( './../lib' ); + +var x = new Float16( 3.14 ); + +console.log( 'type: %s', typeof x ); +// => 'type: object' + +console.log( 'str: %s', x ); +// => 'str: 3.140625' + +console.log( 'value: %d', x.value ); +// => 'value: 3.140625' + +console.log( 'JSON: %s', JSON.stringify( x ) ); +// => 'JSON: {"type":"Float16","value":3.140625}' diff --git a/lib/node_modules/@stdlib/number/float16/ctor/include/stdlib/number/float16/ctor.h b/lib/node_modules/@stdlib/number/float16/ctor/include/stdlib/number/float16/ctor.h new file mode 100644 index 000000000000..c4905add04b4 --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/include/stdlib/number/float16/ctor.h @@ -0,0 +1,110 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 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. +*/ + +#ifndef STDLIB_NUMBER_FLOAT16_CTOR_H +#define STDLIB_NUMBER_FLOAT16_CTOR_H + +#include + +/* +* If C++, prevent name mangling so that the compiler emits a binary file having undecorated names, thus mirroring the behavior of a C compiler. +*/ +#ifdef __cplusplus +extern "C" { +#endif + +// Check for native Float16 support... + +// First check the language standard first, as `_Float16` was standardized in C23... +#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 202311L + +/** +* An opaque type definition for a half-precision floating-point number. +*/ +typedef _Float16 stdlib_float16_t; + +// If the previous check failed, check for the GCC/Clang `_Float16` extension... +#elif defined(__FLT16_MANT_DIG__) + +/** +* An opaque type definition for a half-precision floating-point number. +*/ +typedef _Float16 stdlib_float16_t; + +// If the previous check failed, check for Clang support... +#elif defined(__clang__) && (defined(__has_extension) || defined(__has_feature)) && (__has_extension(c_float16) || __has_feature(c_float16)) + +/** +* An opaque type definition for a half-precision floating-point number. +*/ +typedef _Float16 stdlib_float16_t; + +// Otherwise, if we aren't going to use the native half-precision floating-point number type, we need to define a half-precision floating-point number as an "opaque" struct (here, "opaque" means type consumers should **not** be operating with the value directly, but only through dedicated functions) for storing the number value... +#else + +/** +* An opaque type definition for a half-precision floating-point number. +* +* @example +* #include "stdlib/number/float32/base/to_float16.h" +* #include "stdlib/number/float16/base/to_float32.h" +* +* stdlib_float16_t x = stdlib_float16_from_float32( 3.14f ); +* +* float y = stdlib_float16_to_float32( x ); +* // returns 3.140625f +*/ +typedef struct { + /** + * Raw IEEE 754 binary representation. + */ + uint16_t bits; +} stdlib_float16_t; + +/** +* An opaque type definition for a union for accessing the underlying binary representation of a half-precision floating-point number. +* +* ## Notes +* +* - The union allows "type punning"; however, while (more or less) defined in C99, behavior is implementation-defined in C++. For more robust conversion, prefer using explicit helpers for converting to and from binary representation. +*/ +typedef union { + // An opaque type for the output value (e.g., could be a `struct` or a native half-precision floating-point number): + stdlib_float16_t value; + + // Raw IEEE 754 binary representation. + uint16_t bits; +} stdlib_float16_bits_t; + +#endif + +#ifdef __cplusplus +} +#endif + +/** +* Converts a half-precision floating-point number to its binary representation. +*/ +uint16_t stdlib_float16_to_bits( stdlib_float16_t x ); + +/** +* Converts a 16-bit binary representation to a half-precision floating-point number. +*/ +stdlib_float16_t stdlib_float16_from_bits( uint16_t bits ); + +#endif // !STDLIB_NUMBER_FLOAT16_CTOR_H diff --git a/lib/node_modules/@stdlib/number/float16/ctor/lib/index.js b/lib/node_modules/@stdlib/number/float16/ctor/lib/index.js new file mode 100644 index 000000000000..e000e96cb7d2 --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/lib/index.js @@ -0,0 +1,40 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 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'; + +/** +* 16-bit half-precision floating-point number constructor. +* +* @module @stdlib/number/float16/ctor +* +* @example +* var Float16 = require( '@stdlib/number/float16/ctor' ); +* +* var x = new Float16( 5.0 ); +* // returns +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/number/float16/ctor/lib/main.js b/lib/node_modules/@stdlib/number/float16/ctor/lib/main.js new file mode 100644 index 000000000000..cf44b6b23c6e --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/lib/main.js @@ -0,0 +1,186 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 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'; + +// MODULES // + +var isNumber = require( '@stdlib/assert/is-number' ).isPrimitive; +var setEnumerableReadOnly = require( '@stdlib/utils/define-read-only-property' ); +var setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' ); +var float64ToFloat16 = require( '@stdlib/number/float64/base/to-float16' ); +var format = require( '@stdlib/string/format' ); +var hasToPrimitiveSymbolSupport = require( '@stdlib/assert/has-to-primitive-symbol-support' ); // eslint-disable-line id-length +var ToPrimitiveSymbol = require( '@stdlib/symbol/to-primitive' ); +var toStr = require( './tostring.js' ); +var toJSON = require( './tojson.js' ); +var valueOf = require( './valueof.js' ); // eslint-disable-line stdlib/no-redeclare + + +// MAIN // + +/** +* 16-bit half-precision floating-point number constructor. +* +* @constructor +* @param {number} value - numeric value +* @throws {TypeError} must invoke using the `new` keyword +* @throws {TypeError} value must be a number +* @returns {Float16} 16-bit half-precision floating-point number +* +* @example +* var x = new Float16( 5.0 ); +* // returns +*/ +function Float16( value ) { + if ( !( this instanceof Float16 ) ) { + throw new TypeError( 'invalid invocation. Constructor must be called with the `new` keyword.' ); + } + if ( !isNumber( value ) ) { + throw new TypeError( format( 'invalid argument. Must provide a number. Value: `%s`.', value ) ); + } + setEnumerableReadOnly( this, 'value', float64ToFloat16( value ) ); + return this; +} + +/** +* Constructor name. +* +* @name name +* @memberof Float16 +* @readonly +* @type {string} +* @default 'Float16' +* +* @example +* var name = Float16.name; +* // returns 'Float16' +*/ +setReadOnly( Float16, 'name', 'Float16' ); + +/** +* Size (in bytes) of the underlying value. +* +* @name BYTES_PER_ELEMENT +* @memberof Float16 +* @type {integer} +* @returns {integer} size in bytes +* +* @example +* var nbytes = Float16.BYTES_PER_ELEMENT; +* // returns 2 +*/ +setReadOnly( Float16, 'BYTES_PER_ELEMENT', 2 ); + +/** +* Size (in bytes) of the underlying value. +* +* @name BYTES_PER_ELEMENT +* @memberof Float16.prototype +* @type {integer} +* @returns {integer} size in bytes +* +* @example +* var x = new Float16( 5.0 ); +* +* var nbytes = x.BYTES_PER_ELEMENT; +* // returns 2 +*/ +setReadOnly( Float16.prototype, 'BYTES_PER_ELEMENT', 2 ); + +/** +* Serializes a half-precision floating-point number as a string. +* +* @name toString +* @memberof Float16.prototype +* @type {Function} +* @returns {string} serialized half-precision floating-point number +* +* @example +* var x = new Float16( 5.0 ); +* +* var str = x.toString(); +* // returns '5' +*/ +setReadOnly( Float16.prototype, 'toString', toStr ); + +/** +* Serializes a half-precision floating-point number as a JSON object. +* +* ## Notes +* +* - `JSON.stringify()` implicitly calls this method when stringifying a `Float16` instance. +* +* @name toJSON +* @memberof Float16.prototype +* @type {Function} +* @returns {Object} serialized half-precision floating-point number +* +* @example +* var x = new Float16( 5.0 ); +* +* var obj = x.toJSON(); +* // returns { 'type': 'Float16', 'value': 5.0 } +*/ +setReadOnly( Float16.prototype, 'toJSON', toJSON ); + +/** +* Converts a half-precision floating-point number to a primitive value. +* +* @name valueOf +* @memberof Float16.prototype +* @type {Function} +* @returns {number} primitive value +* +* @example +* var x = new Float16( 5.0 ); +* +* var v = x.valueOf(); +* // returns 5.0 +*/ +setReadOnly( Float16.prototype, 'valueOf', valueOf ); + +/** +* Returns the primitive value of a half-precision floating-point number. +* +* @name toPrimitive +* @memberof Float16.prototype +* @type {Function} +* @param {string} hint - conversion hint +* @returns {number} primitive value +* +* @example +* var hasSymbol = require( '@stdlib/assert/has-to-primitive-symbol-support' ); +* var ToPrimitiveSymbol = require( '@stdlib/symbol/to-primitive' ); +* +* var x = new Float16( 5.0 ); +* +* var v; +* if ( hasSymbol() ) { +* v = x[ ToPrimitiveSymbol ]( 'number' ); +* // returns 5.0 +* } +*/ +if ( hasToPrimitiveSymbolSupport() ) { + setReadOnly( Float16.prototype, ToPrimitiveSymbol, valueOf ); +} + + +// EXPORTS // + +module.exports = Float16; diff --git a/lib/node_modules/@stdlib/number/float16/ctor/lib/tojson.js b/lib/node_modules/@stdlib/number/float16/ctor/lib/tojson.js new file mode 100644 index 000000000000..49f01d7e83ca --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/lib/tojson.js @@ -0,0 +1,37 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 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'; + +/** +* Serializes a half-precision floating-point number as a JSON object. +* +* @private +* @returns {Object} JSON representation +*/ +function toJSON() { + var out = {}; + out.type = 'Float16'; + out.value = this.value; // eslint-disable-line no-invalid-this + return out; +} + + +// EXPORTS // + +module.exports = toJSON; diff --git a/lib/node_modules/@stdlib/number/float16/ctor/lib/tostring.js b/lib/node_modules/@stdlib/number/float16/ctor/lib/tostring.js new file mode 100644 index 000000000000..96cca94da401 --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/lib/tostring.js @@ -0,0 +1,34 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 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'; + +/** +* Serializes a half-precision floating-point number as a string. +* +* @private +* @returns {string} serialized half-precision floating-point number +*/ +function toString() { // eslint-disable-line stdlib/no-redeclare + return String( this.value ); // eslint-disable-line no-invalid-this +} + + +// EXPORTS // + +module.exports = toString; diff --git a/lib/node_modules/@stdlib/number/float16/ctor/lib/valueof.js b/lib/node_modules/@stdlib/number/float16/ctor/lib/valueof.js new file mode 100644 index 000000000000..c3e4742b6e64 --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/lib/valueof.js @@ -0,0 +1,34 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 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'; + +/** +* Converts a half-precision floating-point number to a primitive value. +* +* @private +* @returns {number} primitive value +*/ +function valueOf() { // eslint-disable-line stdlib/no-redeclare + return this.value; // eslint-disable-line no-invalid-this +} + + +// EXPORTS // + +module.exports = valueOf; diff --git a/lib/node_modules/@stdlib/number/float16/ctor/manifest.json b/lib/node_modules/@stdlib/number/float16/ctor/manifest.json new file mode 100644 index 000000000000..04e61e361caa --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/manifest.json @@ -0,0 +1,38 @@ +{ + "options": {}, + "fields": [ + { + "field": "src", + "resolve": true, + "relative": true + }, + { + "field": "include", + "resolve": true, + "relative": true + }, + { + "field": "libraries", + "resolve": false, + "relative": false + }, + { + "field": "libpath", + "resolve": true, + "relative": false + } + ], + "confs": [ + { + "src": [ + "./src/main.c" + ], + "include": [ + "./include" + ], + "libraries": [], + "libpath": [], + "dependencies": [] + } + ] +} diff --git a/lib/node_modules/@stdlib/number/float16/ctor/package.json b/lib/node_modules/@stdlib/number/float16/ctor/package.json new file mode 100644 index 000000000000..19c43238d2fb --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/package.json @@ -0,0 +1,70 @@ +{ + "name": "@stdlib/number/float16/ctor", + "version": "0.0.0", + "description": "16-bit half-precision floating-point number.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "include": "./include", + "lib": "./lib", + "src": "./src", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "stdtypes", + "types", + "data", + "structure", + "constructor", + "ctor", + "floating-point", + "float16", + "16-bit", + "integer", + "float", + "half", + "half-precision", + "ieee754" + ] +} diff --git a/lib/node_modules/@stdlib/number/float16/ctor/src/main.c b/lib/node_modules/@stdlib/number/float16/ctor/src/main.c new file mode 100644 index 000000000000..c2d4062c33e3 --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/src/main.c @@ -0,0 +1,45 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 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. +*/ + +#include "stdlib/number/float16/ctor.h" +#include +#include + +/** +* Converts a half-precision floating-point number to its binary representation. +* +* @param x half-precision floating-point number +* @return 16-bit integer corresponding to a binary representation +*/ +uint16_t stdlib_float16_to_bits( stdlib_float16_t x ) { + uint16_t bits; + memcpy( &bits, &x, sizeof( bits ) ); + return bits; +} + +/** +* Converts a 16-bit binary representation to a half-precision floating-point number. +* +* @param bits 16-bit integer corresponding to a binary representation +* @return half-precision floating-point number +*/ +stdlib_float16_t stdlib_float16_from_bits( uint16_t bits ) { + stdlib_float16_t x; + memcpy( &x, &bits, sizeof( bits ) ); + return x; +} diff --git a/lib/node_modules/@stdlib/number/float16/ctor/test/test.js b/lib/node_modules/@stdlib/number/float16/ctor/test/test.js new file mode 100644 index 000000000000..e35c0284b53f --- /dev/null +++ b/lib/node_modules/@stdlib/number/float16/ctor/test/test.js @@ -0,0 +1,221 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 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'; + +// MODULES // + +var tape = require( 'tape' ); +var hasOwnProp = require( '@stdlib/assert/has-own-property' ); +var hasToPrimitiveSymbolSupport = require( '@stdlib/assert/has-to-primitive-symbol-support' ); // eslint-disable-line id-length +var ToPrimitiveSymbol = require( '@stdlib/symbol/to-primitive' ); +var Float16 = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof Float16, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function is a constructor', function test( t ) { + var x = new Float16( 5.0 ); + t.strictEqual( x instanceof Float16, true, 'is an instance' ); + t.end(); +}); + +tape( 'the constructor throws an error if not provided a number', function test( t ) { + var values; + var i; + + values = [ + '5', + null, + void 0, + true, + false, + [], + {}, + function noop() {} + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + var x = new Float16( value ); // eslint-disable-line no-unused-vars + }; + } +}); + +tape( 'the constructor requires the `new` keyword', function test( t ) { + var ctor = Float16; + t.throws( foo, TypeError, 'throws an error' ); + t.end(); + + function foo() { + ctor( 5.0 ); + } +}); + +tape( 'the constructor has a read-only `name` property', function test( t ) { + t.strictEqual( hasOwnProp( Float16, 'name' ), true, 'has property' ); + t.strictEqual( Float16.name, 'Float16', 'returns expected value' ); + t.throws( foo, Error, 'throws an error' ); + t.end(); + + function foo() { + Float16.name = 'Foo'; + } +}); + +tape( 'the constructor has a read-only `BYTES_PER_ELEMENT` property', function test( t ) { + t.strictEqual( hasOwnProp( Float16, 'BYTES_PER_ELEMENT' ), true, 'has property' ); + t.strictEqual( Float16.BYTES_PER_ELEMENT, 2, 'returns expected value' ); + t.throws( foo, Error, 'throws an error' ); + t.end(); + + function foo() { + Float16.BYTES_PER_ELEMENT = 4; + } +}); + +tape( 'the constructor prototype has a read-only `BYTES_PER_ELEMENT` property', function test( t ) { + t.strictEqual( hasOwnProp( Float16.prototype, 'BYTES_PER_ELEMENT' ), true, 'has property' ); + t.strictEqual( Float16.prototype.BYTES_PER_ELEMENT, 2, 'returns expected value' ); + t.throws( foo, Error, 'throws an error' ); + t.end(); + + function foo() { + Float16.prototype.BYTES_PER_ELEMENT = 4; + } +}); + +tape( 'the constructor returns an instance having a property for accessing the underlying value', function test( t ) { + var x = new Float16( 5.0 ); + t.strictEqual( x.value, 5.0, 'returns expected value' ); + t.end(); +}); + +tape( 'the constructor returns an instance which throws an error when attempting to mutate the value', function test( t ) { + var x = new Float16( 5.0 ); + t.throws( foo, Error, 'throws an error' ); + t.end(); + + function foo() { + x.value = -5.0; + } +}); + +tape( 'the constructor returns an instance which stores a provided value as a half-precision floating-point number', function test( t ) { + var x = new Float16( 3.14 ); + t.strictEqual( x.value, 3.140625, 'returns expected value' ); + t.end(); +}); + +tape( 'the constructor returns an instance which supports serializing an instance as a string', function test( t ) { + var x; + + x = new Float16( 5.0 ); + t.strictEqual( x.toString(), '5', 'returns expected value' ); + + x = new Float16( -5.0 ); + t.strictEqual( x.toString(), '-5', 'returns expected value' ); + + t.end(); +}); + +tape( 'the constructor returns an instance which supports serializing an instance as a JSON object', function test( t ) { + var expected; + var x; + + x = new Float16( 5.0 ); + expected = { + 'type': 'Float16', + 'value': 5.0 + }; + t.deepEqual( x.toJSON(), expected, 'returns expected value' ); + t.strictEqual( JSON.stringify( x ), JSON.stringify( expected ), 'returns expected value' ); + + x = new Float16( -5.0 ); + expected = { + 'type': 'Float16', + 'value': -5.0 + }; + t.deepEqual( x.toJSON(), expected, 'returns expected value' ); + t.strictEqual( JSON.stringify( x ), JSON.stringify( expected ), 'returns expected value' ); + + t.end(); +}); + +tape( 'the constructor returns an instance which supports converting an instance to a primitive value', function test( t ) { + var x; + + x = new Float16( 5.0 ); + t.strictEqual( x.valueOf(), 5.0, 'returns expected value' ); + + x = new Float16( -5.0 ); + t.strictEqual( x.valueOf(), -5.0, 'returns expected value' ); + + x = new Float16( 3.14 ); + t.strictEqual( x.valueOf(), 3.140625, 'returns expected value' ); + + x = new Float16( 0.0 ); + t.strictEqual( x.valueOf(), 0.0, 'returns expected value' ); + + t.end(); +}); + +tape( 'the constructor returns an instance which supports implicit type coercion', function test( t ) { + var x; + var y; + + x = new Float16( 10.0 ); + t.strictEqual( x + 5, 15.0, 'returns expected value' ); + t.strictEqual( x * 2, 20.0, 'returns expected value' ); + + x = new Float16( 3.0 ); + y = new Float16( 2.0 ); + t.strictEqual( x + y, 5.0, 'returns expected value' ); + + t.end(); +}); + +tape( 'if an environment supports `Symbol.toPrimitive`, the constructor returns an instance which supports type coercion', function test( t ) { + var x; + + if ( !hasToPrimitiveSymbolSupport() ) { + t.ok( true, 'environment does not support Symbol.toPrimitive' ); + t.end(); + return; + } + x = new Float16( 5.0 ); + + t.strictEqual( x[ ToPrimitiveSymbol ]( 'number' ), 5.0, 'returns expected value' ); + t.strictEqual( x[ ToPrimitiveSymbol ]( 'default' ), 5.0, 'returns expected value' ); + t.strictEqual( x[ ToPrimitiveSymbol ]( 'string' ), 5.0, 'returns expected value' ); + + x = new Float16( -3.14 ); + t.strictEqual( x[ ToPrimitiveSymbol ](), -3.140625, 'returns expected value' ); + + t.end(); +});