# Timestring [![Version](https://img.shields.io/npm/v/timestring.svg?style=flat-square)](https://www.npmjs.com/package/timestring) [![Build Status](https://img.shields.io/travis/mike182uk/timestring.svg?style=flat-square)](http://travis-ci.org/mike182uk/timestring) [![Code Climate](https://img.shields.io/codeclimate/github/mike182uk/timestring.svg?style=flat-square)](https://codeclimate.com/github/mike182uk/timestring) [![Coveralls](https://img.shields.io/coveralls/mike182uk/timestring/master.svg?style=flat-square)](https://coveralls.io/r/mike182uk/timestring) [![npm](https://img.shields.io/npm/dm/timestring.svg?style=flat-square)](https://www.npmjs.com/package/timestring) [![License](https://img.shields.io/github/license/mike182uk/timestring.svg?style=flat-square)](https://www.npmjs.com/package/timestring) [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg?style=flat-square)](http://commitizen.github.io/cz-cli/) 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. `s, sec, secs, second, seconds` - will parse to seconds 2. `m, min, mins, minute, minutes` - will parse to minutes 3. `h, hr, hrs, hour, hours` - will parse to hours 4. `d, day, days` - will parse to days 5. `w, week, weeks` - will parse to weeks 6. `mth, mths, month, months` - will parse to months 7. `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. `s` - Seconds 2. `m` - Minutes 3. `h` - Hours 4. `d` - Days 5. `w` - Weeks 6. `mth` - Months 7. `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 ```