Skip to content

Commit e84bf81

Browse files
PlaneshifterPlaneshifter
committed
Expose buffer namespace
1 parent e2f2623 commit e84bf81

File tree

7 files changed

+483
-8
lines changed

7 files changed

+483
-8
lines changed

‎lib/node_modules/@stdlib/buffer/README.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2021 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+
# Buffer
22+
23+
> Buffer namespace.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var ns = require( '@stdlib/buffer' );
31+
```
32+
33+
#### ns
34+
35+
Buffer namespace.
36+
37+
```javascript
38+
var o = ns;
39+
// returns {...}
40+
```
41+
42+
The namespace contains the following:
43+
44+
<!-- <toc pattern="*"> -->
45+
46+
<div class="namespace-toc">
47+
48+
- <span class="signature">[`allocUnsafe( size )`][@stdlib/buffer/alloc-unsafe]</span><span class="delimiter">: </span><span class="description">allocate a buffer having a specified number of bytes.</span>
49+
- <span class="signature">[`Buffer()`][@stdlib/buffer/ctor]</span><span class="delimiter">: </span><span class="description">buffer constructor.</span>
50+
- <span class="signature">[`arraybuffer2buffer( buf[, byteOffset[, length]] )`][@stdlib/buffer/from-arraybuffer]</span><span class="delimiter">: </span><span class="description">allocate a buffer from an ArrayBuffer.</span>
51+
- <span class="signature">[`copyBuffer( buffer )`][@stdlib/buffer/from-buffer]</span><span class="delimiter">: </span><span class="description">copy buffer data to a new `Buffer` instance.</span>
52+
- <span class="signature">[`string2buffer( str[, encoding] )`][@stdlib/buffer/from-string]</span><span class="delimiter">: </span><span class="description">allocate a buffer containing a provided string.</span>
53+
- <span class="signature">[`reviver( key, value )`][@stdlib/buffer/reviver]</span><span class="delimiter">: </span><span class="description">revive a JSON-serialized Buffer.</span>
54+
- <span class="signature">[`toJSON( buffer )`][@stdlib/buffer/to-json]</span><span class="delimiter">: </span><span class="description">return a JSON representation of a Buffer.</span>
55+
56+
</div>
57+
58+
<!-- </toc> -->
59+
60+
</section>
61+
62+
<!-- /.usage -->
63+
64+
<section class="examples">
65+
66+
## Examples
67+
68+
<!-- TODO: better examples -->
69+
70+
<!-- eslint no-undef: "error" -->
71+
72+
```javascript
73+
var objectKeys = require( '@stdlib/utils/keys' );
74+
var ns = require( '@stdlib/buffer' );
75+
76+
console.log( objectKeys( ns ) );
77+
```
78+
79+
</section>
80+
81+
<!-- /.examples -->
82+
83+
<section class="links">
84+
85+
<!-- <toc-links> -->
86+
87+
[@stdlib/buffer/alloc-unsafe]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/buffer/alloc-unsafe
88+
89+
[@stdlib/buffer/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/buffer/ctor
90+
91+
[@stdlib/buffer/from-arraybuffer]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/buffer/from-arraybuffer
92+
93+
[@stdlib/buffer/from-buffer]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/buffer/from-buffer
94+
95+
[@stdlib/buffer/from-string]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/buffer/from-string
96+
97+
[@stdlib/buffer/reviver]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/buffer/reviver
98+
99+
[@stdlib/buffer/to-json]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/buffer/to-json
100+
101+
<!-- </toc-links> -->
102+
103+
</section>
104+
105+
<!-- /.links -->

‎lib/node_modules/@stdlib/buffer/docs/types/index.d.ts‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
/*
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2021 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: 2.0
20+
21+
/* tslint:disable:max-line-length */
22+
/* tslint:disable:max-file-line-count */
23+
24+
import allocUnsafe = require( '@stdlib/buffer/alloc-unsafe' );
25+
import Buffer = require( '@stdlib/buffer/ctor' );
26+
import array2buffer = require( '@stdlib/buffer/from-array' );
27+
import arraybuffer2buffer = require( '@stdlib/buffer/from-arraybuffer' );
28+
import copyBuffer = require( '@stdlib/buffer/from-buffer' );
29+
import string2buffer = require( '@stdlib/buffer/from-string' );
30+
import reviver = require( '@stdlib/buffer/reviver' );
31+
import toJSON = require( '@stdlib/buffer/to-json' );
32+
33+
/**
34+
* Interface describing the `buffer` namespace.
35+
*/
36+
interface Namespace {
37+
/**
38+
* Allocates a buffer having a specified number of bytes.
39+
*
40+
* ## Notes
41+
*
42+
* - The underlying memory of returned `Buffer` instances is not initialized. Memory contents are unknown and may contain sensitive data.
43+
* - When the size is less than half the pool size (specified on the `Buffer` constructor), memory is allocated from the `Buffer` pool for faster allocation of new `Buffer` instances.
44+
*
45+
*
46+
* @param size - number of bytes to allocate
47+
* @throws must provide a nonnegative integer
48+
* @returns new `Buffer` instance
49+
*
50+
* @example
51+
* var buf = ns.allocUnsafe( 10 );
52+
* // returns <Buffer>
53+
*/
54+
allocUnsafe: typeof allocUnsafe;
55+
56+
/**
57+
* Buffer constructor.
58+
*
59+
* @example
60+
* var ctor = require( `@stdlib/buffer/ctor` );
61+
*
62+
* var b = new ctor( [ 1, 2, 3, 4 ] );
63+
* // returns <Buffer>
64+
*/
65+
Buffer: typeof Buffer;
66+
67+
/**
68+
* Allocates a buffer using an octet array.
69+
*
70+
* @param arr - octet array
71+
* @returns new `Buffer` instance
72+
*
73+
* @example
74+
* var ns.array2buffer = require( `@stdlib/buffer/from-array` );
75+
*
76+
* var buf = ns.array2buffer( [ 1, 2, 3, 4 ] );
77+
* // returns <Buffer>
78+
*/
79+
array2buffer: typeof array2buffer;
80+
81+
/**
82+
* Allocates a buffer from an `ArrayBuffer`.
83+
*
84+
* ## Notes
85+
*
86+
* The behavior of this function varies across Node.js versions due to changes in the underlying Node.js APIs:
87+
*
88+
* - `<6.0.0`: if provided an empty ArrayBuffer, the function returns an empty Buffer which is **not** an ArrayBuffer view.
89+
* - otherwise, the function returns a view of an ArrayBuffer without copying the underlying memory.
90+
*
91+
*
92+
* @param buf - ArrayBuffer instance
93+
* @param byteOffset - index specifying the location of the first buffer byte (default: 0)
94+
* @param length - number of buffer bytes (default: buf.byteLength)
95+
* @throws second argument must be a nonnegative integer
96+
* @throws second argument must not exceed number of bytes in input ArrayBuffer
97+
* @throws last argument must be a nonnegative integer
98+
* @throws last argument must not exceed number of bytes in input ArrayBuffer
99+
* @returns new `Buffer` instance
100+
*
101+
* @example
102+
* var ArrayBuffer = require( `@stdlib/array/buffer` );
103+
* var ab = new ArrayBuffer( 10 );
104+
*
105+
* var buf = ns.arraybuffer2buffer( ab );
106+
* // returns <Buffer>
107+
*
108+
* @example
109+
* var ArrayBuffer = require( `@stdlib/array/buffer` );
110+
* var ab = new ArrayBuffer( 10 );
111+
*
112+
* var buf = ns.arraybuffer2buffer( ab, 2, 4 );
113+
* // returns <Buffer>
114+
*/
115+
arraybuffer2buffer: typeof arraybuffer2buffer;
116+
117+
/**
118+
* Copies buffer data to a new `Buffer` instance.
119+
*
120+
* @param buffer - buffer from which to copy
121+
* @returns new `Buffer` instance
122+
*
123+
* @example
124+
* var fromArray = require( `@stdlib/buffer/from-array` );
125+
*
126+
* var b1 = fromArray( [ 1, 2, 3, 4 ] );
127+
* // returns <Buffer>
128+
*
129+
* var b2 = ns.copyBuffer( b1 );
130+
* // returns <Buffer>
131+
*/
132+
copyBuffer: typeof copyBuffer;
133+
134+
/**
135+
* Allocates a buffer containing a provided string.
136+
*
137+
* @param str - input string
138+
* @param encoding - character encoding (default: 'utf8')
139+
* @throws second argument must be a valid encoding
140+
* @returns new `Buffer` instance
141+
*
142+
* @example
143+
* var buf = ns.string2buffer( 'beep boop' );
144+
* // returns <Buffer>
145+
*/
146+
string2buffer: typeof string2buffer;
147+
148+
/**
149+
* Revives a JSON-serialized `Buffer`.
150+
*
151+
* @param key - key
152+
* @param value - value
153+
* @returns value or Buffer
154+
*
155+
* @example
156+
* var parseJSON = require( `@stdlib/utils/parse-json` );
157+
*
158+
* var str = '{"type":"Buffer","data":[5,3]}';
159+
*
160+
* var buf = parseJSON( str, ns.reviver );
161+
* // returns <Buffer>[ 5, 3 ]
162+
*/
163+
reviver: typeof reviver;
164+
165+
/**
166+
* Returns a JSON representation of a `Buffer`.
167+
*
168+
* @param buffer - buffer to serialize
169+
* @throws first argument must be a `Buffer`
170+
* @returns JSON representation
171+
*
172+
* @example
173+
* var array2buffer = require( `@stdlib/buffer/from-array` );
174+
*
175+
* var buf = array2buffer( [ 1, 2 ] );
176+
* // returns <Buffer>
177+
*
178+
* var json = ns.toJSON( buf );
179+
* // returns { 'type': 'Buffer', 'data': [ 1, 2 ] }
180+
*/
181+
toJSON: typeof toJSON;
182+
}
183+
184+
/**
185+
* Buffer.
186+
*/
187+
declare var ns: Namespace;
188+
189+
190+
// EXPORTS //
191+
192+
export = ns;

‎lib/node_modules/@stdlib/buffer/docs/types/test.ts‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
/*
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2021 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+
/* tslint:disable:no-unused-expression */
20+
21+
import buffer = require( './index' );
22+
23+
24+
// TESTS //
25+
26+
// The exported value is the expected interface...
27+
{
28+
buffer; // $ExpectType Namespace
29+
}

‎lib/node_modules/@stdlib/buffer/examples/index.js‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2021 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+
var objectKeys = require( '@stdlib/utils/keys' );
22+
var ns = require( './../lib' );
23+
24+
console.log( objectKeys( ns ) );

0 commit comments

Comments
 (0)