141 lines
3.9 KiB
Markdown
141 lines
3.9 KiB
Markdown
# Timestring
|
|
|
|
[](https://www.npmjs.com/package/timestring)
|
|
[](http://travis-ci.org/mike182uk/timestring)
|
|
[](https://codeclimate.com/github/mike182uk/timestring)
|
|
[](https://coveralls.io/r/mike182uk/timestring)
|
|
[](https://www.npmjs.com/package/timestring)
|
|
[](https://www.npmjs.com/package/timestring)
|
|
|
|
Parse a human readable time string into a time based value.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install --save timestring
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Overview
|
|
|
|
```js
|
|
var timestring = require('timestring')
|
|
|
|
var str = '1h 15m'
|
|
var time = timestring(str)
|
|
|
|
console.log(time) // will log 4500
|
|
```
|
|
|
|
**By default the returned time value from `timestring` will be in seconds.**
|
|
|
|
The time string can contain as many time groups as needed:
|
|
|
|
```js
|
|
var str = '1d 3h 25m 18s'
|
|
var time = timestring(str)
|
|
|
|
console.log(time) // will log 98718
|
|
```
|
|
|
|
and can be as messy as you like:
|
|
|
|
```js
|
|
var str = '1 d 3HOurS 25 min 1 8s'
|
|
var time = timestring(str)
|
|
|
|
console.log(time) // will log 98718
|
|
```
|
|
|
|
### Keywords
|
|
|
|
Timestring will parse the following keywords into time values:
|
|
|
|
1. `ms, milli, millisecond, milliseconds` - will parse to milliseconds
|
|
2. `s, sec, secs, second, seconds` - will parse to seconds
|
|
3. `m, min, mins, minute, minutes` - will parse to minutes
|
|
4. `h, hr, hrs, hour, hours` - will parse to hours
|
|
5. `d, day, days` - will parse to days
|
|
6. `w, week, weeks` - will parse to weeks
|
|
7. `mon, mth, mths, month, months` - will parse to months
|
|
8. `y, yr, yrs, year, years` - will parse to years
|
|
|
|
Keywords can be used interchangeably:
|
|
|
|
```js
|
|
var str = '1day 15h 20minutes 15s'
|
|
var time = timestring(str)
|
|
|
|
console.log(time) // will log 141615
|
|
```
|
|
|
|
### Return Time Value
|
|
|
|
By default the return time value will be in seconds. This can be changed by passing one of the following strings as an argument to `timestring`:
|
|
|
|
1. `ms` - Milliseconds
|
|
2. `s` - Seconds
|
|
3. `m` - Minutes
|
|
4. `h` - Hours
|
|
5. `d` - Days
|
|
6. `w` - Weeks
|
|
7. `mth` - Months
|
|
8. `y` - Years
|
|
|
|
```js
|
|
var str = '22h 16m'
|
|
|
|
var hours = timestring(str, 'h') // 22.266666666666666
|
|
var days = timestring(str, 'd') // 0.9277777777777778
|
|
var weeks = timestring(str, 'w') // 0.13253968253968254
|
|
```
|
|
|
|
### Optional Configuration
|
|
|
|
A few assumptions are made by default:
|
|
|
|
1. There are 24 hours per day
|
|
2. There are 7 days per week
|
|
3. There are 4 weeks per month
|
|
4. There are 12 months per year
|
|
|
|
These options can be changed by passing an options object as an argument to `timestring`.
|
|
|
|
The following options are configurable:
|
|
|
|
1. `hoursPerDay`
|
|
2. `daysPerWeek`
|
|
3. `weeksPerMonth`
|
|
4. `monthsPerYear`
|
|
|
|
```js
|
|
var str = '1d'
|
|
var opts = {
|
|
hoursPerDay: 1
|
|
}
|
|
|
|
var time = timestring(str, 'h', opts)
|
|
|
|
console.log(time) // will log 1
|
|
```
|
|
|
|
In the example above `hoursPerDay` is being set to `1`. When the time string is being parsed, the return value is being specified as hours. Normally `1d` would parse to `24` hours (as by default there are 24 hours in a day) but because `hoursPerDay` has been set to `1`, `1d` will now only parse to `1` hour.
|
|
|
|
This would be useful for specific application needs.
|
|
|
|
*Example - Employees of my company work 7.5 hours a day, and only work 5 days a week. In my time tracking app, when they type `1d` i want 7.5 hours to be tracked. When they type `1w` i want 5 days to be tracked etc.*
|
|
|
|
```js
|
|
var opts = {
|
|
hoursPerDay: 7.5,
|
|
daysPerWeek: 5
|
|
}
|
|
|
|
var hoursToday = timestring('1d', 'h', opts)
|
|
var daysThisWeek = timestring('1w', 'd', opts)
|
|
|
|
console.log(hoursToday) // will log 7.5
|
|
console.log(daysThisWeek) // will log 5
|
|
```
|