@webgap/format-utils/README.md

Common formatter utilities to handle numbers, dates, times, etc.

# WebGAP Format Utils

[![Build Status](https://travis-ci.org/webgap/format-utils.svg)](https://travis-ci.org/webgap/format-utils)
[![Test Coverage](https://codeclimate.com/github/webgap/format-utils/badges/coverage.svg)](https://codeclimate.com/github/webgap/format-utils/coverage)
[![Code Climate](https://codeclimate.com/github/webgap/format-utils/badges/gpa.svg)](https://codeclimate.com/github/webgap/format-utils)
[![Dependency Status](https://gemnasium.com/webgap/format-utils.png)](https://gemnasium.com/webgap/format-utils)

[![NPM version](http://img.shields.io/npm/v/@webgap/format-utils.svg?style=flat)](https://www.npmjs.com/package/@webgap/format-utils)
[![NPM downloads](http://img.shields.io/npm/dm/@webgap/format-utils.svg?style=flat)](https://www.npmjs.com/package/@webgap/format-utils)

# README

This is the format utilities module for WebGAP.
Contains formatter for Dates, String, Numbers, Bytes and Percentage.

# Dependencies

Loads default configuration using [**@webgap/configuration**](https://github.com/webgap/configuration).<br>
Depends on [**String**](https://github.com/jprichardson/string.js) for string format.<br>
Depends on [**Numeral**](http://numeraljs.com/) for number format.<br>

### Requirements

A configuration file must exist (check [**@webgap/configuration**](https://github.com/webgap/configuration) documentation).

### API

#### Installation

```bash
npm install @webgap/format-utils --save
```

#### Usage

```javascript
var format = require('@webgap/format-utils').format();
...
// using default options will output:
format.bytes(256000); // returns 256KB
format.percentage(1); // returns 100.00%
format.number(10); // returns 10.00
format.currentDateTimeUnix(); // returns e.g 1318781876406
format.date(1318781876406); // returns 2011-10-16 +00:00
format.dateTime(1318781876406); // returns 2011-10-16T16:17:56 +00:00
format.dateFromNow(1318781876406); // returns e.g. 4 years ago
format.truncate('This is a long string that should be truncated...lets make it a bit longer...and a bit longer...', 20); // 
```

## Options

```javascript
var options = {
  dateFormat: "YYYY-MM-DD Z",
  dateTimeFormat: "YYYY-MM-DDTHH:mm:ss Z",
  timeFormat: "HH:mm:ss Z",
  decimalFormat: "0,0.00",
  percentageFormat: "0.00%",
  byteFormat: "0.0b"
};
var format = require('@webgap/format-utils').format(options);
...
format.percentage(1); // 100.00%
...
```

Check tests for more examples.

# License

Apache License, Version 2.0