Skip to content

Commit ae31334

Browse files
PlaneshifterPlaneshifter
committed
Port function from compute-io/datespace
1 parent 4e5b7cf commit ae31334

11 files changed

Lines changed: 1326 additions & 0 deletions

File tree

‎lib/node_modules/@stdlib/array/datespace/README.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
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+
# Datespace
22+
23+
> Generate an array of linearly spaced [dates][mdn-date-object].
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var datespace = require( '@stdlib/array/datespace' );
31+
```
32+
33+
#### datespace( start, stop\[, length]\[, opts] )
34+
35+
Generates an `array` of linearly spaced [`Date`][mdn-date-object] objects. If a `length` is not provided, the default output `array` length is `100`.
36+
37+
```javascript
38+
var end = '2014-12-02T07:00:54.973Z';
39+
var start = new Date( end ) - 60000;
40+
41+
var arr = datespace( start, end, 6 );
42+
/* returns [
43+
'Mon Dec 01 2014 22:59:54 GMT-0800 (PST)',
44+
'Mon Dec 01 2014 23:00:06 GMT-0800 (PST)',
45+
'Mon Dec 01 2014 23:00:18 GMT-0800 (PST)',
46+
'Mon Dec 01 2014 23:00:30 GMT-0800 (PST)',
47+
'Mon Dec 01 2014 23:00:42 GMT-0800 (PST)',
48+
'Mon Dec 01 2014 23:00:54 GMT-0800 (PST)'
49+
]
50+
*/
51+
```
52+
53+
The `start` and `stop` times may be either [`Date`][mdn-date-object] objects, date strings, Unix timestamps, or JavaScript timestamps.
54+
55+
```javascript
56+
// JavaScript timestamps:
57+
var end = 1417503654973;
58+
var start = new Date( end - 60000 );
59+
60+
var arr = datespace( start, end, 6 );
61+
/* returns [
62+
'Mon Dec 01 2014 22:59:54 GMT-0800 (PST)',
63+
'Mon Dec 01 2014 23:00:06 GMT-0800 (PST)',
64+
'Mon Dec 01 2014 23:00:18 GMT-0800 (PST)',
65+
'Mon Dec 01 2014 23:00:30 GMT-0800 (PST)',
66+
'Mon Dec 01 2014 23:00:42 GMT-0800 (PST)',
67+
'Mon Dec 01 2014 23:00:54 GMT-0800 (PST)'
68+
]
69+
*/
70+
71+
// Unix timestamps:
72+
end = 1417503655;
73+
start = end - 60;
74+
75+
arr = datespace( start, end, 6 );
76+
/* returns [
77+
'Mon Dec 01 2014 22:59:54 GMT-0800 (PST)',
78+
'Mon Dec 01 2014 23:00:06 GMT-0800 (PST)',
79+
'Mon Dec 01 2014 23:00:18 GMT-0800 (PST)',
80+
'Mon Dec 01 2014 23:00:30 GMT-0800 (PST)',
81+
'Mon Dec 01 2014 23:00:42 GMT-0800 (PST)',
82+
'Mon Dec 01 2014 23:00:54 GMT-0800 (PST)'
83+
]
84+
*/
85+
```
86+
87+
The output `array` is guaranteed to include the `start` and `end` times. Beware, however, that values between the `start` and `end` are subject to rounding errors. For example,
88+
89+
```javascript
90+
var arr = datespace( 1417503655000, 1417503655001, 3 );
91+
// returns [ 1417503655000, 1417503655000, 1417503655001 ]
92+
```
93+
94+
where sub-millisecond values are truncated by the [`Date`][mdn-date-object] constructor. Duplicate values should only be a problem when the interval separating consecutive times is less than a millisecond. As the interval separating consecutive dates goes to infinity, the quantization noise introduced by millisecond resolution is negligible.
95+
96+
By default, fractional timestamps are floored. To specify that timestamps always be rounded up or to the nearest millisecond **when converted to [`Date`][mdn-date-object] objects**, set the `round` option (default: `floor`).
97+
98+
```javascript
99+
// Equivalent of Math.ceil():
100+
var arr = datespace( 1417503655000, 1417503655001, 3, {
101+
'round': 'ceil'
102+
});
103+
// returns [ 1417503655000, 1417503655001, 1417503655001 ]
104+
105+
// Equivalent of Math.round():
106+
arr = datespace( 1417503655000, 1417503655001, 3, {
107+
'round': 'round'
108+
});
109+
// returns [ 1417503655000, 1417503655001, 1417503655001 ]
110+
```
111+
112+
</section>
113+
114+
<!-- /.usage -->
115+
116+
<section class="notes">
117+
118+
</section>
119+
120+
<!-- /.notes -->
121+
122+
<section class="examples">
123+
124+
## Examples
125+
126+
```javascript
127+
var datespace = require( '@stdlib/array/datespace' );
128+
var start;
129+
var arr;
130+
var end;
131+
132+
end = '2014-12-02T07:00:54.973Z';
133+
start = new Date( end ) - 100000;
134+
135+
// Default behavior:
136+
arr = datespace( start, end );
137+
console.log( arr.join( '\n' ) );
138+
139+
// Specify length:
140+
arr = datespace( start, end, 10 );
141+
console.log( arr.join( '\n' ) );
142+
143+
arr = datespace( start, end, 11 );
144+
console.log( arr.join( '\n' ) );
145+
146+
// Create an array with decremented values:
147+
arr = datespace( end, start, 11 );
148+
console.log( arr.join( '\n' ) );
149+
```
150+
151+
</section>
152+
153+
<!-- /.examples -->
154+
155+
<section class="links">
156+
157+
[mdn-date-object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
158+
159+
</section>
160+
161+
<!-- /.links -->
162+

‎lib/node_modules/@stdlib/array/datespace/benchmark/benchmark.js‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
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+
// MODULES //
22+
23+
var bench = require( '@stdlib/bench' );
24+
var randu = require( '@stdlib/random/base/randu' );
25+
var round = require( '@stdlib/math/base/special/round' );
26+
var isArray = require( '@stdlib/assert/is-array' );
27+
var pkg = require( './../package.json' ).name;
28+
var datespace = require( './../lib' );
29+
30+
31+
// MAIN //
32+
33+
bench( pkg, function benchmark( b ) {
34+
var start;
35+
var end;
36+
var i;
37+
var v;
38+
39+
b.tic();
40+
for ( i = 0; i < b.iterations; i++ ) {
41+
end = '2014-12-02T07:00:54.973Z';
42+
start = new Date( end ) - round( randu()*100.0 );
43+
v = datespace( start, end );
44+
if ( typeof v !== 'object' ) {
45+
b.fail( 'should return an array' );
46+
}
47+
}
48+
b.toc();
49+
if ( !isArray( v ) ) {
50+
b.fail( 'should return an array' );
51+
}
52+
b.pass( 'benchmark finished' );
53+
b.end();
54+
});

‎lib/node_modules/@stdlib/array/datespace/benchmark/benchmark.length.js‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
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+
// MODULES //
22+
23+
var bench = require( '@stdlib/bench' );
24+
var pow = require( '@stdlib/math/base/special/pow' );
25+
var randu = require( '@stdlib/random/base/randu' );
26+
var round = require( '@stdlib/math/base/special/round' );
27+
var isArray = require( '@stdlib/assert/is-array' );
28+
var pkg = require( './../package.json' ).name;
29+
var datespace = require( './../lib' );
30+
31+
32+
// FUNCTIONS //
33+
34+
/**
35+
* Creates a benchmark function.
36+
*
37+
* @private
38+
* @param {PositiveInteger} len - array length
39+
* @returns {Function} benchmark function
40+
*/
41+
function createBenchmark( len ) {
42+
return benchmark;
43+
44+
/**
45+
* Benchmark function.
46+
*
47+
* @private
48+
* @param {Benchmark} b - benchmark instance
49+
*/
50+
function benchmark( b ) {
51+
var start;
52+
var end;
53+
var v;
54+
var i;
55+
56+
b.tic();
57+
for ( i = 0; i < b.iterations; i++ ) {
58+
end = '2014-12-02T07:00:54.973Z';
59+
start = new Date( end ) - round( randu()*100.0 );
60+
v = datespace( start, end, len );
61+
if ( typeof v !== 'object' ) {
62+
b.fail( 'should return an array' );
63+
}
64+
}
65+
b.toc();
66+
if ( !isArray( v ) ) {
67+
b.fail( 'should return an array' );
68+
}
69+
b.pass( 'benchmark finished' );
70+
b.end();
71+
}
72+
}
73+
74+
75+
// MAIN //
76+
77+
/**
78+
* Main execution sequence.
79+
*
80+
* @private
81+
*/
82+
function main() {
83+
var len;
84+
var min;
85+
var max;
86+
var f;
87+
var i;
88+
89+
min = 1; // 10^min
90+
max = 6; // 10^max
91+
92+
for ( i = min; i <= max; i++ ) {
93+
len = pow( 10, i );
94+
f = createBenchmark( len );
95+
bench( pkg+':len='+len, f );
96+
}
97+
}
98+
99+
main();

‎lib/node_modules/@stdlib/array/datespace/docs/repl.txt‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
2+
{{alias}}( start, stop[, length][ , options] )
3+
Generates an array of linearly spaced dates.
4+
5+
Parameters
6+
----------
7+
start: number
8+
Start time as either a `Date` object, Unix timestamp, JavaScript
9+
timestamp, or date string.
10+
11+
stop: number
12+
Stop time as either a `Date` object, Unix timestamp, JavaScript
13+
timestamp, or date string.
14+
15+
length: integer (optional)
16+
Length of output array. Default: `100`.
17+
18+
options: Object (optional)
19+
Options.
20+
21+
options.round: string (optional)
22+
Specifies how sub-millisecond times should be rounded:
23+
[ 'floor', 'ceil', 'round' ]. Default: 'floor'.
24+
25+
Returns
26+
-------
27+
arr: Array
28+
Array of dates.
29+
30+
Examples
31+
--------
32+
> var stop = '2014-12-02T07:00:54.973Z';
33+
> var start = new Date( stop ) - 60000;
34+
> var arr = {{alias}}( start, stop, 6 )
35+
[...]
36+
37+
// Equivalent of Math.ceil():
38+
> var opts = { 'round': 'ceil' };
39+
> arr = {{alias}}( 1417503655000, 1417503655001, 3, opts )
40+
[...]
41+
42+
See Also
43+
--------
44+

0 commit comments

Comments
 (0)