feat: add plot/table/unicode

lib/node_modules/@stdlib/plot/table/unicode/benchmark/benchmark.render.js

@@ -0,0 +1,142 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 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 pow = require( '@stdlib/math/base/special/pow' );
+var Float64Array = require( '@stdlib/array/float64' );
+var array = require( '@stdlib/ndarray/array' );
+var pkg = require( './../package.json' ).name;
+var UnicodeTable = require( './../lib' );
+
+
+// FUNCTIONS //
+
+/**
+* Creates a benchmark function.
+*
+* @private
+* @param {PositiveInteger} rows - number of rows
+* @param {PositiveInteger} columns - number of columns
+* @param {UnicodeSparkline} table - table instance
+* @returns {Function} benchmark function
+*/
+function createBenchmark( rows, columns, table ) {
+	return benchmark;
+
+	/**
+	* Generates table data.
+	*
+	* @private
+	* @returns {ndarray} table data
+	*/
+	function data() {
+		var data;
+		var i;
+
+		data = new Float64Array( rows * columns );
+		for ( i = 0; i < data.length; i++ ) {
+			data[ i ] = randu();
+		}
+		data = array( data, {
+			'shape': [ rows, columns ]
+		});
+		return data;
+	}
+
+	/**
+	* Generates table headers.
+	*
+	* @private
+	* @returns {Float64Array} table data
+	*/
+	function headers() {
+		var data;
+		var i;
+
+		data = new Float64Array( columns );
+		for ( i = 0; i < data.length; i++ ) {
+			data[ i ] = randu();
+		}
+		return data;
+	}
+
+	/**
+	* Benchmark function.
+	*
+	* @private
+	* @param {Benchmark} b - benchmark instance
+	*/
+	function benchmark( b ) {
+		var str;
+		var i;
+
+		b.tic();
+		for ( i = 0; i < b.iterations; i++ ) {
+			str = table.setData( data(), headers() ).render();
+			if ( typeof str !== 'string' ) {
+				b.fail( 'should return a string' );
+			}
+		}
+		b.toc();
+		if ( typeof str !== 'string' ) {
+			b.fail( 'should return a string' );
+		}
+		b.pass( 'benchmark finished' );
+		b.end();
+	}
+}
+
+
+// MAIN //
+
+/**
+* Main execution sequence.
+*
+* @private
+*/
+function main() {
+	var columns;
+	var table;
+	var rows;
+	var min;
+	var max;
+	var f;
+	var i;
+	var j;
+
+	min = 1; // 5^min
+	max = 3; // 5^max
+
+	for ( i = min; i <= max; i++ ) {
+		for ( j = min; j <= max; j++ ) {
+			rows = pow( 5, i );
+			columns = pow( 5, j );
+
+			table = new UnicodeTable();
+			f = createBenchmark( rows, columns, table );
+			bench( pkg+':render:rows='+rows+',columns='+columns, f );
+		}
+	}
+}
+
+main();

lib/node_modules/@stdlib/plot/table/unicode/docs/repl.txt

@@ -0,0 +1,112 @@
+
+{{alias}}( [data,] [headers,] [options] )
+    Returns a Unicode table instance.
+
+    Parameters
+    ----------
+    data: Object|Array<Object>|Array<Array>|MatrixLike (optional)
+        Table data.
+
+    headers: Collection (optional)
+        Table headers.
+
+    options: Object (optional)
+        Table options.
+
+    options.alignment: string (optional)
+        Datum's cell alignment. Default: 'right'.
+
+    options.borders: string (optional)
+        Border characters. Default: '─ │ ─ │'.
+
+    options.cellPadding: NonNegativeInteger (optional)
+        Cell padding. Default: 1.
+
+    options.columnSeparator: string (optional)
+        Column separator character. Default: '│'.
+
+    options.corners: string (optional)
+        Corner characters. Default: '┌ ┐ ┘ └'.
+
+    options.headerSeparator: string (optional)
+        Header separator character. Default: '─'.
+
+    options.joints: string (optional)
+        Joint characters. Default: '┼ ┬ ┤ ┴ ├'.
+
+    options.marginX: NonNegativeInteger (optional)
+        Horizontal output margin. Default: 0.
+
+    options.marginY: NonNegativeInteger (optional)
+        Vertical output margin. Default: 0.
+
+    options.maxCellWidth: NonNegativeInteger (optional)
+        Maximum cell width (excluding padding). Default: FLOAT64_MAX.
+
+    options.maxOutputWidth: NonNegativeInteger (optional)
+        Maximum output width (including margin). Default: FLOAT64_MAX.
+
+    options.rowSeparator: string (optional)
+        Row separator character. Default: 'None'.
+
+    Returns
+    -------
+    table.addRow( row )
+        Adds a row to table data.
+
+    table.alignment
+        Datum's cell alignment.
+
+    table.borders
+        Border characters.
+
+    table.cellPadding
+        Cell Padding.
+
+    table.columnSeparator
+        Column separator character.
+
+    table.corners
+        Corner characters.
+
+    table.getData()
+        Gets table data and headers.
+
+    table.headerSeparator
+        Header separator character.
+
+    table.joints
+        Joint characters.
+
+    table.marginX
+        Horizontal output margin.
+
+    table.marginY
+        Vertical output margin.
+
+    table.maxCellWidth
+        Maximum cell width.
+
+    table.maxOutputWidth
+        Maximum output width.
+
+    table.render()
+        Renders a table.
+
+    table.rowSeparator
+        Row separator character.
+
+    table.setData( data, [headers] )
+        Sets table data and headers
+
+    Examples
+    --------
+    > var data = [ [ 45, 33, 'hello' ], [ 32.54, true, null ] ];
+    > var headers = [ 'col1', 'col2', 'col3' ];
+    > var table = new {{alias}}( data, headers );
+    > table.render()
+    '...'
+
+    See Also
+    --------
+

lib/node_modules/@stdlib/plot/table/unicode/examples/index.js

@@ -0,0 +1,53 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 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 randu = require( '@stdlib/random/base/randu' );
+var Float64Array = require( '@stdlib/array/float64' );
+var array = require( '@stdlib/ndarray/array' );
+var ctor = require( './../lib' );
+
+var headers;
+var table;
+var data;
+var str;
+var i;
+
+// Generate some random data...
+data = new Float64Array( 50 );
+for ( i = 0; i < data.length; i++ ) {
+	data[ i ] = randu() * 100.0;
+}
+data = array( data, {
+	'shape': [ 10, 5 ]
+});
+
+// Generate headers...
+headers = new Float64Array( 5 );
+for ( i = 0; i < headers.length; i++ ) {
+	headers[ i ] = randu() * 100.0;
+}
+
+// Create a table:
+table = ctor( data, headers );
+
+// Render the table:
+str = table.render();
+console.log( str );
+// => '...'

lib/node_modules/@stdlib/plot/table/unicode/lib/addrow.js

@@ -0,0 +1,63 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 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 format = require( '@stdlib/string/format' );
+var isCollection = require( '@stdlib/assert/is-collection' );
+var parse2dArray = require( './parser/parse_2d_array.js' );
+
+
+// MAIN //
+
+/**
+* Adds a row to table data.
+*
+* @private
+* @param {Collection} row - row to add
+* @throws {TypeError} must provide a collection with equal number of columns to existing data
+* @returns {UnicodeTable} class instance
+*/
+function addRow( row ) {
+	/* eslint-disable no-invalid-this */
+	var parsed;
+
+	if ( !isCollection ) {
+		throw new TypeError( format( 'invalid argument. Must provide a collection. Value: `%s`.', row ) );
+	}
+	// If data doesn't already exist, parse row as new data...
+	if ( !this._data || !this._data.length ) {
+		parsed = parse2dArray( [ row ], this._headers );
+		this._data = parsed.data;
+		this._headers = parsed.headers;
+		this._columnWidths = parsed.columnWidths;
+		return this;
+	}
+	if ( this._data[ 0 ].length !== row.length ) {
+		throw new TypeError( format( 'invalid argument. Must provide a collection with equal number of columns to existing data. Value: `%s`.', row ) );
+	}
+	this._data.push( row );
+	return this;
+}
+
+
+// EXPORTS //
+
+module.exports = addRow;