feat: add number/float16/ctor

lib/node_modules/@stdlib/number/float16/ctor/README.md

@@ -0,0 +1,374 @@
+<!--
+
+@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.
+
+-->
+
+# Float16
+
+> 16-bit half-precision floating-point number.
+
+<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<!-- Package usage documentation. -->
+
+<section class="usage">
+
+## 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 <Float16>
+```
+
+* * *
+
+## 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
+```
+
+</section>
+
+<!-- /.usage -->
+
+* * *
+
+<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="notes">
+
+## 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.
+
+</section>
+
+<!-- /.notes -->
+
+* * *
+
+<!-- Package usage examples. -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```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}'
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- C interface documentation. -->
+
+* * *
+
+<section class="c">
+
+## C APIs
+
+<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<!-- C usage documentation. -->
+
+<section class="usage">
+
+### 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 <stdint.h>
+
+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 <stdint.h>
+
+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.
+
+</section>
+
+<!-- /.usage -->
+
+<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="notes">
+
+### 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.
+
+</section>
+
+<!-- /.notes -->
+
+<!-- C API usage examples. -->
+
+<section class="examples">
+
+### Examples
+
+```c
+#include "stdlib/number/float16/ctor.h"
+#include <stdint.h>
+#include <stdio.h>
+
+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 ] ) );
+  }
+}
+```
+
+</section>
+
+<!-- /.examples -->
+
+</section>
+
+<!-- /.c -->
+
+<!-- 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. -->
+
+<section class="references">
+
+</section>
+
+<!-- /.references -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+[ieee754]: https://en.wikipedia.org/wiki/IEEE_754-1985
+
+[json]: http://www.json.org/
+
+[mdn-json-stringify]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
+
+[mdn-json-parse]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse
+
+[@stdlib/number/float16/reviver]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/number/float16/reviver
+
+<!-- <related-links> -->
+
+<!-- </related-links> -->
+
+</section>
+
+<!-- /.links -->