Skip to content

Commit 5b58696

Browse files
Planeshifterkgrytestdlib-bot
authored
Add utility to parse a duration string (stdlib-js#560)
* Add README for package to parse duration string * Fix leading description * Add missing heading * Add support for hours and days in duration * Scaffold time/base/parse-duration package files * Finish implementation * Apply suggestions from code review * Update spelling * Update lib/node_modules/@stdlib/time/base/parse-duration/docs/repl.txt Co-authored-by: Athan <kgryte@gmail.com> * Resolve issues flagged during review * Update lib/node_modules/@stdlib/time/base/parse-duration/lib/main.js Co-authored-by: Athan <kgryte@gmail.com> * Update lib/node_modules/@stdlib/time/base/parse-duration/lib/main.js Co-authored-by: Athan <kgryte@gmail.com> * Update lib/node_modules/@stdlib/time/base/parse-duration/docs/types/index.d.ts Co-authored-by: Athan <kgryte@gmail.com> * Update lib/node_modules/@stdlib/time/base/parse-duration/README.md Co-authored-by: Athan <kgryte@gmail.com> * Use hash lookup to reduce code complexity. Co-authored-by: Athan <kgryte@gmail.com> Co-authored-by: Athan <kgryte@gmail.com> Co-authored-by: stdlib-bot <noreply@stdlib.io>
1 parent 090b1cc commit 5b58696

File tree

10 files changed

+787
-0
lines changed

10 files changed

+787
-0
lines changed

‎lib/node_modules/@stdlib/time/base/parse-duration/README.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2022 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+
# parseDuration
22+
23+
> Parse a duration string into an object.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var parseDuration = require( '@stdlib/time/base/parse-duration' );
31+
```
32+
33+
#### parseDuration
34+
35+
Parses a duration string into an object.
36+
37+
```javascript
38+
var obj = parseDuration( '1m3s10ms' );
39+
// returns { 'days': 0, 'hours': 0, 'minutes': 1, 'seconds': 3, 'milliseconds': 10 }
40+
41+
obj = parseDuration( '1m3s' );
42+
// returns { 'days': 0, 'hours': 0, 'minutes': 1, 'seconds': 3, 'milliseconds': 0 }
43+
```
44+
45+
The returned object has the following properties:
46+
47+
- **days**: number of days.
48+
- **hours**: number of hours.
49+
- **minutes**: number of minutes.
50+
- **seconds**: number of seconds.
51+
- **milliseconds**: number of milliseconds.
52+
53+
</section>
54+
55+
<!-- /.usage -->
56+
57+
<!-- Package notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
58+
59+
<section class="notes">
60+
61+
## Notes
62+
63+
- A duration string is a string containing a sequence of time units. A time unit is a nonnegative integer followed by a unit identifier. The following unit identifiers are supported:
64+
65+
- `d`: days
66+
- `h`: hours
67+
- `m`: minutes
68+
- `s`: seconds
69+
- `ms`: milliseconds
70+
71+
For example, the string `1m3s10ms` is a duration string containing three time units: `1m` (1 minute), `3s` (3 seconds), and `10ms` (10 milliseconds). The string `60m` is a duration string containing a single time unit: `60m` (60 minutes).
72+
73+
- Duration strings are case insensitive. For example, the string `1M3S10MS` is equivalent to `1m3s10ms`.
74+
75+
- If a duration string does not contain a time unit, the respective property is set to `0`.
76+
77+
- An empty string is considered a valid duration string and is parsed as `0d0h0m0s0ms`.
78+
79+
</section>
80+
81+
<!-- /.notes -->
82+
83+
<section class="examples">
84+
85+
## Examples
86+
87+
<!-- eslint no-undef: "error" -->
88+
89+
```javascript
90+
var parseDuration = require( '@stdlib/time/base/parse-duration' );
91+
92+
var obj = parseDuration( '1m3s10ms' );
93+
// returns { 'days': 0, 'hours': 0, 'minutes': 1, 'seconds': 3, 'milliseconds': 10 }
94+
95+
obj = parseDuration( '60m' );
96+
// returns { 'days': 0, 'hours': 0, 'minutes': 60, 'seconds': 0, 'milliseconds': 0 }
97+
98+
obj = parseDuration( '2d3h' );
99+
// returns { 'days': 2, 'hours': 3, 'minutes': 0, 'seconds': 0, 'milliseconds': 0 }
100+
101+
obj = parseDuration( '1M3S' );
102+
// returns { 'days': 0, 'hours': 0, 'minutes': 1, 'seconds': 3, 'milliseconds': 0 }
103+
104+
obj = parseDuration( '' );
105+
// returns { 'days': 0, 'hours': 0, 'minutes': 0, 'seconds': 0, 'milliseconds': 0 }
106+
```
107+
108+
</section>
109+
110+
<!-- /.examples -->
111+
112+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
113+
114+
<section class="related">
115+
116+
</section>
117+
118+
<!-- /.related -->
119+
120+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
121+
122+
<section class="links">
123+
124+
</section>
125+
126+
<!-- /.links -->

‎lib/node_modules/@stdlib/time/base/parse-duration/benchmark/benchmark.js‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2022 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 isObject = require( '@stdlib/assert/is-object' );
25+
var pkg = require( './../package.json' ).name;
26+
var parseDuration = require( './../lib' );
27+
28+
29+
// MAIN //
30+
31+
bench( pkg, function benchmark( b ) {
32+
var values;
33+
var str;
34+
var obj;
35+
var i;
36+
37+
values = [
38+
'1m3s10ms',
39+
'3d2h1m',
40+
'1d2h3m4s5ms',
41+
'2m3s',
42+
'1h2m3s4ms',
43+
'1m3s10ms',
44+
''
45+
];
46+
b.tic();
47+
for ( i = 0; i < b.iterations; i++ ) {
48+
str = values[ i % values.length ];
49+
obj = parseDuration( str );
50+
if ( typeof obj !== 'object' ) {
51+
b.fail( 'should return an object' );
52+
}
53+
}
54+
b.toc();
55+
if ( !isObject( obj ) ) {
56+
b.fail( 'should return an object' );
57+
}
58+
b.pass( 'benchmark finished' );
59+
b.end();
60+
});

‎lib/node_modules/@stdlib/time/base/parse-duration/docs/repl.txt‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
2+
{{alias}}( str )
3+
Parses a duration string into an object.
4+
5+
A duration string is a string containing a sequence of time units. A time
6+
unit is a nonnegative integer followed by a unit identifier. The following
7+
unit identifiers are supported:
8+
9+
- d: days
10+
- h: hours
11+
- m: minutes
12+
- s: seconds
13+
- ms: milliseconds
14+
15+
Duration strings are case insensitive. For example, the string `1M3S10MS` is
16+
equivalent to `1m3s10ms`.
17+
18+
If a duration string does not contain a time unit, the respective property
19+
is set to 0.
20+
21+
An empty string is considered a valid duration string and is parsed as
22+
`0d0h0m0s0ms`.
23+
24+
Parameters
25+
----------
26+
str: string
27+
Duration string.
28+
29+
Returns
30+
-------
31+
out: Object
32+
Duration object.
33+
34+
out.days: integer
35+
Number of days.
36+
37+
out.hours: integer
38+
Number of hours.
39+
40+
out.minutes: integer
41+
Number of minutes.
42+
43+
out.seconds: integer
44+
Number of seconds.
45+
46+
out.milliseconds: integer
47+
Number of milliseconds.
48+
49+
Examples
50+
--------
51+
> var obj = {{alias}}( '1m3s10ms' )
52+
{ 'days': 0, 'hours': 0, 'minutes': 1, 'seconds': 3, 'milliseconds': 10 }
53+
> obj = {{alias}}( '1m3s' )
54+
{ 'days': 0, 'hours': 0, 'minutes': 1, 'seconds': 3, 'milliseconds': 0 }
55+
56+
See Also
57+
--------

‎lib/node_modules/@stdlib/time/base/parse-duration/docs/types/index.d.ts‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2022 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+
/**
22+
* Interface describing a duration object.
23+
*/
24+
interface Duration {
25+
/**
26+
* Number of days.
27+
*/
28+
'days': number;
29+
30+
/**
31+
* Number of hours.
32+
*/
33+
'hours': number;
34+
35+
/**
36+
* Number of minutes.
37+
*/
38+
'minutes': number;
39+
40+
/**
41+
* Number of seconds.
42+
*/
43+
'seconds': number;
44+
45+
/**
46+
* Number of milliseconds.
47+
*/
48+
'milliseconds': number;
49+
}
50+
51+
/**
52+
* Parses a duration string into an object.
53+
*
54+
* ## Notes
55+
*
56+
* - A duration string is a string containing a sequence of time units. A time unit is a nonnegative integer followed by a unit identifier. The following unit identifiers are supported:
57+
*
58+
* - `d`: days
59+
* - `h`: hours
60+
* - `m`: minutes
61+
* - `s`: seconds
62+
* - `ms`: milliseconds
63+
*
64+
* For example, the string `1m3s10ms` is a duration string containing three time units: `1m` (1 minute), `3s` (3 seconds), and `10ms` (10 milliseconds). The string `60m` is a duration string containing a single time unit: `60m` (60 minutes).
65+
*
66+
* - Duration strings are case insensitive. For example, the string `1M3S10MS` is equivalent to `1m3s10ms`.
67+
*
68+
* - If a duration string does not contain a time unit, the respective property is set to `0`.
69+
*
70+
* - An empty string is considered a valid duration string and is parsed as `0d0h0m0s0ms`.
71+
*
72+
* @param str - duration string
73+
* @returns duration object
74+
*
75+
* @example
76+
* var obj = parseDuration( '1m3s10ms' );
77+
* // returns { 'days': 0, 'hours': 0, 'minutes': 1, 'seconds': 3, 'milliseconds': 10 }
78+
*
79+
* @example
80+
* var obj = parseDuration( '1m3s' );
81+
* // returns { 'days': 0, 'hours': 0, 'minutes': 1, 'seconds': 3, 'milliseconds': 0 }
82+
*/
83+
declare function parseDuration( str: string ): Duration;
84+
85+
86+
// EXPORTS //
87+
88+
export = parseDuration;

‎lib/node_modules/@stdlib/time/base/parse-duration/docs/types/test.ts‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2022 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+
import parseDuration = require( './index' );
20+
21+
22+
// TESTS //
23+
24+
// The function returns a duration object...
25+
{
26+
parseDuration( '1h' ); // $ExpectType Duration
27+
parseDuration( '1d3h' ); // $ExpectType Duration
28+
parseDuration( '1h1m1s' ); // $ExpectType Duration
29+
parseDuration( '1ms' ); // $ExpectType Duration
30+
parseDuration( '1h1m1s1ms' ); // $ExpectType Duration
31+
}
32+
33+
// The compiler throws an error if the function is provided a value other than a string...
34+
{
35+
parseDuration( true ); // $ExpectError
36+
parseDuration( false ); // $ExpectError
37+
parseDuration( null ); // $ExpectError
38+
parseDuration( undefined ); // $ExpectError
39+
parseDuration( 5 ); // $ExpectError
40+
parseDuration( [] ); // $ExpectError
41+
parseDuration( {} ); // $ExpectError
42+
parseDuration( ( x: number ): number => x ); // $ExpectError
43+
}
44+
45+
// The compiler throws an error if the function is provided insufficient arguments...
46+
{
47+
parseDuration(); // $ExpectError
48+
}

0 commit comments

Comments
 (0)