Skip to content

Commit 285afbb

Browse files
gururaj1512kgrytestdlib-bot
authored
feat: add number/float16/ctor
PR-URL: #8871 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com> Co-authored-by: stdlib-bot <noreply@stdlib.io>
1 parent 5bbd6b0 commit 285afbb

File tree

18 files changed

+1752
-0
lines changed

18 files changed

+1752
-0
lines changed

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

Lines changed: 374 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,374 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 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+
# Float16
22+
23+
> 16-bit half-precision floating-point number.
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 Float16 = require( '@stdlib/number/float16/ctor' );
41+
```
42+
43+
#### Float16( value )
44+
45+
16-bit half-precision floating-point number constructor.
46+
47+
```javascript
48+
var x = new Float16( 5.0 );
49+
// returns <Float16>
50+
```
51+
52+
* * *
53+
54+
## Properties
55+
56+
#### Float16.name
57+
58+
Static property returning the constructor name.
59+
60+
```javascript
61+
var str = Float16.name;
62+
// returns 'Float16'
63+
```
64+
65+
#### Float16.BYTES_PER_ELEMENT
66+
67+
Size (in bytes) of the underlying value.
68+
69+
```javascript
70+
var nbytes = Float16.BYTES_PER_ELEMENT;
71+
// returns 2
72+
```
73+
74+
#### Float16.prototype.BYTES_PER_ELEMENT
75+
76+
Size (in bytes) of the underlying value.
77+
78+
```javascript
79+
var x = new Float16( 5.0 );
80+
81+
var nbytes = x.BYTES_PER_ELEMENT;
82+
// returns 2
83+
```
84+
85+
### Instance
86+
87+
A `Float16` instance has the following properties...
88+
89+
#### value
90+
91+
A **read-only** property returning the underlying value as a number.
92+
93+
```javascript
94+
var x = new Float16( 5.0 );
95+
96+
var v = x.value;
97+
// returns 5.0
98+
```
99+
100+
* * *
101+
102+
## Methods
103+
104+
### Accessor Methods
105+
106+
These methods do **not** mutate a `Float16` instance and, instead return a half-precision floating-point number representation.
107+
108+
#### Float16.prototype.toString()
109+
110+
Returns a string representation of a `Float16` instance.
111+
112+
```javascript
113+
var x = new Float16( 5.0 );
114+
var str = x.toString();
115+
// returns '5'
116+
117+
x = new Float16( -3.14 );
118+
str = x.toString();
119+
// returns '-3.140625'
120+
```
121+
122+
#### Float16.prototype.toJSON()
123+
124+
Returns a [JSON][json] representation of a `Float16` instance. [`JSON.stringify()`][mdn-json-stringify] implicitly calls this method when stringifying a `Float16` instance.
125+
126+
```javascript
127+
var x = new Float16( 5.0 );
128+
129+
var o = x.toJSON();
130+
/*
131+
{
132+
"type": "Float16",
133+
"value": 5.0
134+
}
135+
*/
136+
```
137+
138+
To [revive][mdn-json-parse] a `Float16` number from a [JSON][json] `string`, see [@stdlib/number/float16/reviver][@stdlib/number/float16/reviver].
139+
140+
#### Float16.prototype.valueOf()
141+
142+
Converts a `Float16` instance to a primitive value.
143+
144+
```javascript
145+
var x = new Float16( 5.0 );
146+
var v = x.valueOf();
147+
// returns 5.0
148+
149+
x = new Float16( 3.14 );
150+
v = x.valueOf();
151+
// returns 3.140625
152+
```
153+
154+
</section>
155+
156+
<!-- /.usage -->
157+
158+
* * *
159+
160+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
161+
162+
<section class="notes">
163+
164+
## Notes
165+
166+
- 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.
167+
- A half-precision floating-point number has a range of approximately `±6.55e4` and a precision of about 3-4 decimal digits.
168+
169+
</section>
170+
171+
<!-- /.notes -->
172+
173+
* * *
174+
175+
<!-- Package usage examples. -->
176+
177+
<section class="examples">
178+
179+
## Examples
180+
181+
<!-- eslint no-undef: "error" -->
182+
183+
```javascript
184+
var Float16 = require( '@stdlib/number/float16/ctor' );
185+
186+
var x = new Float16( 3.14 );
187+
188+
console.log( 'type: %s', typeof x );
189+
// => 'type: object'
190+
191+
console.log( 'str: %s', x );
192+
// => 'str: 3.140625'
193+
194+
console.log( 'value: %d', x.value );
195+
// => 'value: 3.140625'
196+
197+
console.log( 'JSON: %s', JSON.stringify( x ) );
198+
// => 'JSON: {"type":"Float16","value":3.140625}'
199+
```
200+
201+
</section>
202+
203+
<!-- /.examples -->
204+
205+
<!-- C interface documentation. -->
206+
207+
* * *
208+
209+
<section class="c">
210+
211+
## C APIs
212+
213+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
214+
215+
<section class="intro">
216+
217+
</section>
218+
219+
<!-- /.intro -->
220+
221+
<!-- C usage documentation. -->
222+
223+
<section class="usage">
224+
225+
### Usage
226+
227+
```c
228+
#include "stdlib/number/float16/ctor.h"
229+
```
230+
231+
#### stdlib_float16_t
232+
233+
An opaque type definition for a half-precision floating-point number.
234+
235+
```c
236+
stdlib_float16_t v = stdlib_float16_from_bits( 51648 );
237+
```
238+
239+
#### stdlib_float16_bits_t
240+
241+
An opaque type definition for a union for accessing the underlying binary representation of a half-precision floating-point number.
242+
243+
```c
244+
#include <stdint.h>
245+
246+
stdlib_float16_t x = stdlib_float16_from_bits( 51648 );
247+
248+
stdlib_float16_bits_t y;
249+
y.value = x;
250+
251+
uint16_t bits = y.bits;
252+
// returns 51648
253+
```
254+
255+
The union has the following members:
256+
257+
- **value**: `stdlib_float16_t` half-precision floating-point number.
258+
- **bits**: `uint16_t` binary representation.
259+
260+
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.
261+
262+
#### stdlib_float16_from_bits( bits )
263+
264+
Converts a 16-bit binary representation to a half-precision floating-point number.
265+
266+
```c
267+
stdlib_float16_t v = stdlib_float16_from_bits( 51648 ); // => -11.5
268+
```
269+
270+
The function accepts the following arguments:
271+
272+
- **bits**: `[in] uint16_t` 16-bit integer corresponding to a binary representation.
273+
274+
#### stdlib_float16_to_bits( x )
275+
276+
Converts a half-precision floating-point number to a 16-bit binary representation.
277+
278+
```c
279+
#include <stdint.h>
280+
281+
stdlib_float16_t v = stdlib_float16_from_bits( 51648 ); // => -11.5
282+
283+
uint16_t bits = stdlib_float16_to_bits( v );
284+
```
285+
286+
The function accepts the following arguments:
287+
288+
- **x**: `[in] stdlib_float16_t` half-precision floating-point number.
289+
290+
</section>
291+
292+
<!-- /.usage -->
293+
294+
<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
295+
296+
<section class="notes">
297+
298+
### Notes
299+
300+
- 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.
301+
302+
</section>
303+
304+
<!-- /.notes -->
305+
306+
<!-- C API usage examples. -->
307+
308+
<section class="examples">
309+
310+
### Examples
311+
312+
```c
313+
#include "stdlib/number/float16/ctor.h"
314+
#include <stdint.h>
315+
#include <stdio.h>
316+
317+
int main( void ) {
318+
const stdlib_float16_t x[] = {
319+
stdlib_float16_from_bits( 51648 ), // -11.5
320+
stdlib_float16_from_bits( 18880 ) // 11.5
321+
};
322+
323+
int i;
324+
for ( i = 0; i < 2; i++ ) {
325+
printf( "%d\n", stdlib_float16_to_bits( x[ i ] ) );
326+
}
327+
}
328+
```
329+
330+
</section>
331+
332+
<!-- /.examples -->
333+
334+
</section>
335+
336+
<!-- /.c -->
337+
338+
<!-- 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. -->
339+
340+
<section class="references">
341+
342+
</section>
343+
344+
<!-- /.references -->
345+
346+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
347+
348+
<section class="related">
349+
350+
</section>
351+
352+
<!-- /.related -->
353+
354+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
355+
356+
<section class="links">
357+
358+
[ieee754]: https://en.wikipedia.org/wiki/IEEE_754-1985
359+
360+
[json]: http://www.json.org/
361+
362+
[mdn-json-stringify]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
363+
364+
[mdn-json-parse]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse
365+
366+
[@stdlib/number/float16/reviver]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/number/float16/reviver
367+
368+
<!-- <related-links> -->
369+
370+
<!-- </related-links> -->
371+
372+
</section>
373+
374+
<!-- /.links -->

0 commit comments

Comments
 (0)