Skip to content

Commit 09de35c

Browse files
stdlib-botstdlib-bot
committed
Auto-generated commit
1 parent 7deffaa commit 09de35c

12 files changed

Lines changed: 164 additions & 43 deletions

File tree

‎.github/.keepalive‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
2022-09-01T01:18:36.973Z
1+
2022-10-01T01:45:01.393Z

‎README.md‎

Lines changed: 32 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ limitations under the License.
1818
1919
-->
2020

21-
# Left Pad
21+
# lpad
2222

2323
[![NPM version][npm-image]][npm-url] [![Build Status][test-image]][test-url] [![Coverage Status][coverage-image]][coverage-url] <!-- [![dependencies][dependencies-image]][dependencies-url] -->
2424

@@ -52,14 +52,14 @@ var lpad = require( '@stdlib/string-left-pad' );
5252

5353
#### lpad( str, len\[, pad] )
5454

55-
Left pads a `string` such that the padded `string` has a `length` of **at least** `len`.
55+
Left pads a string such that the padded string has a length of **at least** `len`.
5656

5757
```javascript
5858
var str = lpad( 'a', 5 );
5959
// returns ' a'
6060
```
6161

62-
By default, an input `string` is padded with `spaces`. To pad with a different character or sequence of characters, provide a `pad` string.
62+
By default, an input string is padded with a Unicode "space" character (U+0020). To pad with a different character or sequence of characters, provide a `pad` string.
6363

6464
```javascript
6565
var str = lpad( 'beep', 10, 'b' );
@@ -77,7 +77,7 @@ str = lpad( 'boop', 12, 'beep' );
7777

7878
## Notes
7979

80-
- An output `string` is **not** guaranteed to have a length of **exactly** `len`, but to have a `length` of **at least** `len`. To generate a padded `string` having a `length` equal to `len`
80+
- An output string is **not** guaranteed to have a length of **exactly** `len`, but to have a length of **at least** `len`. To generate a padded string having a length equal to `len`
8181

8282
```javascript
8383
var str = lpad( 'boop', 10, 'beep' ); // => length 12
@@ -87,6 +87,29 @@ str = lpad( 'boop', 12, 'beep' );
8787
// returns 'epbeepboop'
8888
```
8989

90+
- This function differs from [`String.prototype.padStart`][mdn-string-padstart] in the following ways:
91+
92+
- The function is **not** guaranteed to return a string having a length exactly equal to `len` (as explained above).
93+
- The function does **not** truncate `pad` (from the end) in order to ensure the returned string has length `len`.
94+
95+
To replicate [`String.prototype.padStart`][mdn-string-padstart] truncation behavior
96+
97+
```javascript
98+
var floorb = require( '@stdlib/math-base-special-floorb' );
99+
100+
function padStart( str, len, pad ) {
101+
var n;
102+
if ( len <= str.length ) {
103+
return str;
104+
}
105+
n = floorb( len-str.length, 1, pad.length ) + str.length;
106+
return pad.substring( 0, len-n ) + lpad( str, n, pad );
107+
}
108+
109+
var str = padStart( 'boop', 10, 'beep' );
110+
// returns 'bebeepboop'
111+
```
112+
90113
</section>
91114

92115
<!-- /.notes -->
@@ -98,17 +121,13 @@ str = lpad( 'boop', 12, 'beep' );
98121
<!-- eslint no-undef: "error" -->
99122

100123
```javascript
101-
var round = require( '@stdlib/math-base-special-round' );
102-
var randu = require( '@stdlib/random-base-randu' );
124+
var discreteUniform = require( '@stdlib/random-base-discrete-uniform' );
103125
var lpad = require( '@stdlib/string-left-pad' );
104126
105127
var str = 'beep';
106-
var n;
107128
var i;
108-
109129
for ( i = 0; i < 100; i++ ) {
110-
n = round( randu()*10 ) + str.length;
111-
console.log( lpad( str, n, 'b' ) );
130+
console.log( lpad( str, discreteUniform( str.length, str.length+10 ), 'b' ) );
112131
}
113132
```
114133

@@ -141,7 +160,7 @@ npm install -g @stdlib/string-left-pad
141160
### Usage
142161

143162
```text
144-
Usage: lpad [options] [<string>] --len=<length>
163+
Usage: lpad [options] --len=<length> [<string>]
145164
146165
Options:
147166
@@ -298,6 +317,8 @@ Copyright &copy; 2016-2022. The Stdlib [Authors][stdlib-authors].
298317

299318
[mdn-regexp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
300319

320+
[mdn-string-padstart]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/padStart
321+
301322
<!-- <related-links> -->
302323

303324
[@stdlib/string/pad]: https://github.com/stdlib-js/string-pad

‎benchmark/benchmark.builtin.js‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2018 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+
// MODULES //
22+
23+
var bench = require( '@stdlib/bench' );
24+
var isString = require( '@stdlib/assert-is-string' ).isPrimitive;
25+
var pkg = require( './../package.json' ).name;
26+
27+
28+
// VARIABLES //
29+
30+
var opts = {
31+
'skip': typeof String.prototype.padStart !== 'function'
32+
};
33+
34+
35+
// FUNCTIONS //
36+
37+
/**
38+
* Creates a benchmark function.
39+
*
40+
* @private
41+
* @param {PositiveInteger} len - string length
42+
* @returns {Function} benchmark function
43+
*/
44+
function createBenchmark( len ) {
45+
return benchmark;
46+
47+
/**
48+
* Benchmark function.
49+
*
50+
* @private
51+
* @param {Benchmark} b - benchmark instance
52+
*/
53+
function benchmark( b ) {
54+
var values;
55+
var out;
56+
var i;
57+
58+
values = [
59+
'a',
60+
'b',
61+
'c'
62+
];
63+
64+
b.tic();
65+
for ( i = 0; i < b.iterations; i++ ) {
66+
out = 'beep'.padStart( len, values[ i%values.length ] );
67+
if ( typeof out !== 'string' ) {
68+
b.fail( 'should return a string' );
69+
}
70+
}
71+
b.toc();
72+
if ( !isString( out ) ) {
73+
b.fail( 'should return a string' );
74+
}
75+
b.pass( 'benchmark finished' );
76+
b.end();
77+
}
78+
}
79+
80+
81+
// MAIN //
82+
83+
/**
84+
* Main execution sequence.
85+
*
86+
* @private
87+
*/
88+
function main() {
89+
var len;
90+
var min;
91+
var max;
92+
var f;
93+
var i;
94+
95+
min = 1; // 10*min
96+
max = 10; // 10*max
97+
98+
for ( i = min; i <= max; i++ ) {
99+
len = 10 * i;
100+
f = createBenchmark( len );
101+
bench( pkg+'::builtin:len='+len, opts, f );
102+
}
103+
}
104+
105+
main();

‎benchmark/benchmark.js‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,6 @@
2222

2323
var bench = require( '@stdlib/bench' );
2424
var isString = require( '@stdlib/assert-is-string' ).isPrimitive;
25-
var fromCodePoint = require( '@stdlib/string-from-code-point' );
2625
var pkg = require( './../package.json' ).name;
2726
var lpad = require( './../lib' );
2827

@@ -46,13 +45,20 @@ function createBenchmark( len ) {
4645
* @param {Benchmark} b - benchmark instance
4746
*/
4847
function benchmark( b ) {
48+
var values;
4949
var out;
5050
var i;
5151

52+
values = [
53+
'a',
54+
'b',
55+
'c'
56+
];
57+
5258
b.tic();
5359
for ( i = 0; i < b.iterations; i++ ) {
54-
out = lpad( 'beep', len, fromCodePoint( i%126 ) );
55-
if ( !isString( out ) ) {
60+
out = lpad( 'beep', len, values[ i%values.length ] );
61+
if ( typeof out !== 'string' ) {
5662
b.fail( 'should return a string' );
5763
}
5864
}

‎docs/repl.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11

22
{{alias}}( str, len[, pad] )
3-
Left pads a `string` such that the padded `string` has a length of at least
3+
Left pads a string such that the padded string has a length of at least
44
`len`.
55

66
An output string is not guaranteed to have a length of exactly `len`, but to

‎docs/types/test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ import lpad = require( './index' );
2828
lpad( 'abd', 10 ); // $ExpectType string
2929
}
3030

31-
// The function does not compile if provided arguments having invalid types...
31+
// The compiler throws an error if the function is provided arguments having invalid types...
3232
{
3333
lpad( true, 6 ); // $ExpectError
3434
lpad( false, 6 ); // $ExpectError
@@ -52,7 +52,7 @@ import lpad = require( './index' );
5252
lpad( 'abd', 6, /[a-z]/ ); // $ExpectError
5353
}
5454

55-
// The function does not compile if provided insufficient arguments...
55+
// The compiler throws an error if the function is provided insufficient arguments...
5656
{
5757
lpad(); // $ExpectError
5858
lpad( 'abc' ); // $ExpectError

‎docs/usage.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11

2-
Usage: lpad [options] [<string>] --len=<length>
2+
Usage: lpad [options] --len=<length> [<string>]
33

44
Options:
55

‎examples/index.js‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,15 +18,11 @@
1818

1919
'use strict';
2020

21-
var round = require( '@stdlib/math-base-special-round' );
22-
var randu = require( '@stdlib/random-base-randu' );
21+
var discreteUniform = require( '@stdlib/random-base-discrete-uniform' );
2322
var lpad = require( './../lib' );
2423

2524
var str = 'beep';
26-
var n;
2725
var i;
28-
2926
for ( i = 0; i < 100; i++ ) {
30-
n = round( randu()*10 ) + str.length;
31-
console.log( lpad( str, n, 'b' ) );
27+
console.log( lpad( str, discreteUniform( str.length, str.length+10 ), 'b' ) );
3228
}

‎lib/index.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,9 @@
3838

3939
// MODULES //
4040

41-
var lpad = require( './left_pad.js' );
41+
var main = require( './main.js' );
4242

4343

4444
// EXPORTS //
4545

46-
module.exports = lpad;
46+
module.exports = main;

lib/left_pad.js renamed to lib/main.js

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,9 @@
2222

2323
var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;
2424
var isString = require( '@stdlib/assert-is-string' ).isPrimitive;
25-
var repeat = require( '@stdlib/string-repeat' );
26-
var ceil = require( '@stdlib/math-base-special-ceil' );
2725
var format = require( '@stdlib/string-format' );
2826
var FLOAT64_MAX_SAFE_INTEGER = require( '@stdlib/constants-float64-max-safe-integer' );
27+
var base = require( '@stdlib/string-base-left-pad' );
2928

3029

3130
// MAIN //
@@ -55,7 +54,6 @@ var FLOAT64_MAX_SAFE_INTEGER = require( '@stdlib/constants-float64-max-safe-inte
5554
* // returns 'beepbeepboop'
5655
*/
5756
function lpad( str, len, pad ) {
58-
var n;
5957
var p;
6058
if ( !isString( str ) ) {
6159
throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );
@@ -77,12 +75,7 @@ function lpad( str, len, pad ) {
7775
if ( len > FLOAT64_MAX_SAFE_INTEGER ) {
7876
throw new RangeError( format( 'invalid argument. Output string length exceeds maximum allowed string length. Value: `%u`.', len ) );
7977
}
80-
n = ( len - str.length ) / p.length;
81-
if ( n <= 0 ) {
82-
return str;
83-
}
84-
n = ceil( n );
85-
return repeat( p, n ) + str;
78+
return base( str, len, p );
8679
}
8780

8881

0 commit comments

Comments
 (0)