module utility
1. function utility.YYYYMMDD (d, sep)
2. function utility.YYYYMMDDHHmmss (d, options)
3. function utility.YYYYMMDDHHmmssSSS (d, msSep)
4. function utility.accessLogDate (d)
5. function utility.argumentsToArray (args)
6. function utility.assign (target, objects)
7. function utility.base64decode (encodeStr, urlsafe, encoding)
8. function utility.base64encode (s, urlsafe)
9. function utility.datestruct (now)
10. function utility.decodeURIComponent (encodeText)
11. function utility.dig (obj)
12. function utility.encodeURIComponent (text)
13. function utility.escape (string)
14. function utility.getParamNames (func, cache)
15. function utility.has (obj, prop)
16. function utility.hash (method, s, format)
17. function utility.hmac (algorithm, key, data, encoding)
18. function utility.includesInvalidHttpHeaderChar (val)
19. function utility.isSafeNumberString (s)
20. function utility.logDate (d, msSep)
21. function utility.map (obj)
22. function utility.md5 (s, format)
23. function utility.noop ()
24. function utility.random (lower, upper)
25. function utility.randomSlice (arr, num)
26. function utility.randomString (length, charSet)
27. function utility.replace (str, substr, newSubstr)
28. function utility.replaceInvalidHttpHeaderChar (val, replacement)
29. function utility.setImmediate ()
30. function utility.sha1 (s, format)
31. function utility.sha256 (s, format)
32. function utility.spliceOne (arr, index)
33. function utility.split (str, sep)
34. function utility.splitAlwaysOptimized ()
35. function utility.strictJSONParse (str)
36. function utility.timestamp (t)
37. function utility.toSafeNumber (s)
38. function utility.try (fn)
39. number utility.MAX_SAFE_INTEGER
40. number utility.MIN_SAFE_INTEGER
41. object utility.array
42. object utility.crypto
43. object utility.date
44. object utility.function
45. object utility.json
46. object utility.number
47. object utility.object
48. object utility.optimize
49. object utility.polyfill
50. object utility.string
51. object utility.web
52. string utility.MAX_SAFE_INTEGER_STR
module utility.array
1. function utility.array.randomSlice (arr, num)
2. function utility.array.spliceOne (arr, index)
module utility.crypto
module utility.date
module utility.function
1. function utility.function.getParamNames (func, cache)
2. function utility.function.noop ()
module utility.json
1. function utility.json.strictJSONParse (str)
module utility.number
1. function utility.number.isSafeNumberString (s)
2. function utility.number.random (lower, upper)
3. function utility.number.toSafeNumber (s)
4. number utility.number.MAX_SAFE_INTEGER
5. number utility.number.MIN_SAFE_INTEGER
6. string utility.number.MAX_SAFE_INTEGER_STR
module utility.object
module utility.optimize
module utility.polyfill
1. function utility.polyfill.setImmediate ()
module utility.string
module utility.web

module utility

function utility.YYYYMMDD (d, sep)

description and source-code

function YYYYMMDD(d, sep) {
  if (typeof d === 'string') {
    // YYYYMMDD(sep)
    sep = d;
    d = new Date();
  } else {
    // YYYYMMDD(d, sep)
    d = d || new Date();
    if (typeof sep !== 'string') {
      sep = '-';
    }
  }
  var date = d.getDate();
  if (date < 10) {
    date = '0' + date;
  }
  var month = d.getMonth() + 1;
  if (month < 10) {
    month = '0' + month;
  }
  return d.getFullYear() + sep + month + sep + date;
}

example usage

...
utils.YYYYMMDDHHmmssSSS(','); // '2013-04-17 14:43:02,674'

// 'YYYY-MM-DD HH:mm:ss' format date string
utils.YYYYMMDDHHmmss(); // '2013-04-17 14:43:02'
utils.YYYYMMDDHHmmss(new Date(), {dateSep: '.'}); // '2013.04.17 14:43:02'

// 'YYYY-MM-DD' format date string
utils.YYYYMMDD(); // '2013-04-17'
utils.YYYYMMDD(''); // '20130417'
utils.YYYYMMDD(','); // '2013,04,17'

// datestruct
utils.datestruct(); // { YYYYMMDD: 20130416, H: 8 }

// Unix's timestamp
...

function utility.YYYYMMDDHHmmss (d, options)

description and source-code

YYYYMMDDHHmmss = function (d, options) {
  d = d || new Date();
  if (!(d instanceof Date)) {
    d = new Date(d);
  }

  var dateSep = '-';
  var timeSep = ':';
  if (options) {
    if (options.dateSep) {
      dateSep = options.dateSep;
    }
    if (options.timeSep) {
      timeSep = options.timeSep;
    }
  }
  var date = d.getDate();
  if (date < 10) {
    date = '0' + date;
  }
  var month = d.getMonth() + 1;
  if (month < 10) {
    month = '0' + month;
  }
  var hours = d.getHours();
  if (hours < 10) {
    hours = '0' + hours;
  }
  var mintues = d.getMinutes();
  if (mintues < 10) {
    mintues = '0' + mintues;
  }
  var seconds = d.getSeconds();
  if (seconds < 10) {
    seconds = '0' + seconds;
  }
  return d.getFullYear() + dateSep + month + dateSep + date + ' ' +
    hours + timeSep + mintues + timeSep + seconds;
}

example usage

...
// logDate,
// 'YYYY-MM-DD HH:mm:ss.SSS' format date string
utils.logDate(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(','); // '2013-04-17 14:43:02,674'

// 'YYYY-MM-DD HH:mm:ss' format date string
utils.YYYYMMDDHHmmss(); // '2013-04-17 14:43:02'
utils.YYYYMMDDHHmmss(new Date(), {dateSep: '.'}); // '2013.04.17 14:43:02'

// 'YYYY-MM-DD' format date string
utils.YYYYMMDD(); // '2013-04-17'
utils.YYYYMMDD(''); // '20130417'
utils.YYYYMMDD(','); // '2013,04,17'
...

function utility.YYYYMMDDHHmmssSSS (d, msSep)

description and source-code

YYYYMMDDHHmmssSSS = function (d, msSep) {
  if (typeof d === 'string') {
    // logDate(msSep)
    msSep = d;
    d = new Date();
  } else {
    // logDate(d, msSep)
    d = d || new Date();
  }
  var date = d.getDate();
  if (date < 10) {
    date = '0' + date;
  }
  var month = d.getMonth() + 1;
  if (month < 10) {
    month = '0' + month;
  }
  var hours = d.getHours();
  if (hours < 10) {
    hours = '0' + hours;
  }
  var mintues = d.getMinutes();
  if (mintues < 10) {
    mintues = '0' + mintues;
  }
  var seconds = d.getSeconds();
  if (seconds < 10) {
    seconds = '0' + seconds;
  }
  var milliseconds = d.getMilliseconds();
  if (milliseconds < 10) {
    milliseconds = '00' + milliseconds;
  } else if (milliseconds < 100) {
    milliseconds = '0' + milliseconds;
  }
  return d.getFullYear() + '-' + month + '-' + date + ' ' +
    hours + ':' + mintues + ':' + seconds + (msSep || '.') + milliseconds;
}

example usage

...
```js
// accessLogDate
utils.accessLogDate(); // '16/Apr/2013:16:40:09 +0800'

// logDate,
// 'YYYY-MM-DD HH:mm:ss.SSS' format date string
utils.logDate(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(','); // '2013-04-17 14:43:02,674'

// 'YYYY-MM-DD HH:mm:ss' format date string
utils.YYYYMMDDHHmmss(); // '2013-04-17 14:43:02'
utils.YYYYMMDDHHmmss(new Date(), {dateSep: '.'}); // '2013.04.17 14:43:02'

// 'YYYY-MM-DD' format date string
...

function utility.accessLogDate (d)

description and source-code

accessLogDate = function (d) {
  // 16/Apr/2013:16:40:09 +0800
  d = d || new Date();
  var date = d.getDate();
  if (date < 10) {
    date = '0' + date;
  }
  var hours = d.getHours();
  if (hours < 10) {
    hours = '0' + hours;
  }
  var mintues = d.getMinutes();
  if (mintues < 10) {
    mintues = '0' + mintues;
  }
  var seconds = d.getSeconds();
  if (seconds < 10) {
    seconds = '0' + seconds;
  }
  return date + '/' + MONTHS[d.getMonth()] + '/' + d.getFullYear() +
    ':' + hours + ':' + mintues + ':' + seconds + TIMEZONE;
}

example usage

...
}
```

### Date utils

```js
// accessLogDate
utils.accessLogDate(); // '16/Apr/2013:16:40:09 +0800'

// logDate,
// 'YYYY-MM-DD HH:mm:ss.SSS' format date string
utils.logDate(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(','); // '2013-04-17 14:43:02,674'
...

function utility.argumentsToArray (args)

description and source-code

argumentsToArray = function (args) {
  var res = new Array(args.length);
  for (var i = 0; i < args.length; i++) {
    res[i] = args[i];
  }
  return res;
}

example usage

...
// {error: Error, value: undefined}
```

### argumentsToArray

```js
function() {
  const arr = utility.argumentsToArray(arguments);
  console.log(arr.join(', '));
}
```

### JSON

```js
...

function utility.assign (target, objects)

description and source-code

assign = function (target, objects) {
  if (!Array.isArray(objects)) {
    objects = [ objects ];
  }

  for (var i = 0; i < objects.length; i++) {
    var obj = objects[i];
    if (obj) {
      var keys = Object.keys(obj);
      for (var j = 0; j < keys.length; j++) {
        var key = keys[j];
        target[key] = obj[key];
      }
    }
  }
  return target;
}

example usage

...
```

### Object.assign


```js
// assign object
utility.assign({}, { a: 1 });

// assign multiple object
utility.assign({}, [ { a: 1 }, { b: 1 } ]);
```

## benchmark
...

function utility.base64decode (encodeStr, urlsafe, encoding)

description and source-code

function base64decode(encodeStr, urlsafe, encoding) {
  if (urlsafe) {
    encodeStr = encodeStr.replace(/\-/g, '+').replace(/_/g, '/');
  }
  var buf = new Buffer(encodeStr, 'base64');
  if (encoding === 'buffer') {
    return buf;
  }
  return buf.toString(encoding || 'utf8');
}

example usage

...
```

### decode and encode

```js
// base64 encode
utils.base64encode('你好￥'); // '5L2g5aW977+l'
utils.base64decode('5L2g5aW977+l') // '你好￥'

// urlsafe base64 encode
utils.base64encode('你好￥', true); // '5L2g5aW977-l'
utils.base64decode('5L2g5aW977-l', true); // '你好￥'

// html escape
utils.escape('<script/>"& &amp;'); // '&lt;script/&gt;&quot;&amp; &#
x26;amp;'
...

function utility.base64encode (s, urlsafe)

description and source-code

function base64encode(s, urlsafe) {
  if (!Buffer.isBuffer(s)) {
    s = new Buffer(s);
  }
  var encode = s.toString('base64');
  if (urlsafe) {
    encode = encode.replace(/\+/g, '-').replace(/\//g, '_');
  }
  return encode;
}

example usage

...
utils.hmac('sha1', 'I am a key', 'hello world'); // 'pO6J0LKDxRRkvSECSEdxwKx84L0='
```

### decode and encode

```js
// base64 encode
utils.base64encode('你好￥'); // '5L2g5aW977+l'
utils.base64decode('5L2g5aW977+l') // '你好￥'

// urlsafe base64 encode
utils.base64encode('你好￥', true); // '5L2g5aW977-l'
utils.base64decode('5L2g5aW977-l', true); // '你好￥'

// html escape
...

function utility.datestruct (now)

description and source-code

datestruct = function (now) {
  now = now || new Date();
  return {
    YYYYMMDD: now.getFullYear() * 10000 + (now.getMonth() + 1) * 100 + now.getDate(),
    H: now.getHours()
  };
}

example usage

...

// 'YYYY-MM-DD' format date string
utils.YYYYMMDD(); // '2013-04-17'
utils.YYYYMMDD(''); // '20130417'
utils.YYYYMMDD(','); // '2013,04,17'

// datestruct
utils.datestruct(); // { YYYYMMDD: 20130416, H: 8 }

// Unix's timestamp
utils.timestamp(); // 1378153226

// Parse timestamp
// seconds
utils.timestamp(1385091596); // Fri Nov 22 2013 11:39:56 GMT+0800 (CST)
...

function utility.decodeURIComponent (encodeText)

description and source-code

function decodeURIComponent_(encodeText) {
  try {
    return decodeURIComponent(encodeText);
  } catch (e) {
    return encodeText;
  }
}

example usage

...
utils.base64encode('你好￥', true); // '5L2g5aW977-l'
utils.base64decode('5L2g5aW977-l', true); // '你好￥'

// html escape
utils.escape('<script/>"& &amp;'); // '&lt;script/&gt;&quot;&amp; &#
x26;amp;'

// Safe encodeURIComponent and decodeURIComponent
utils.decodeURIComponent(utils.encodeURIComponent('你好, nodejs')).should.equal
('你好, nodejs');
```

### others

___[WARNNING] getIP() remove, PLEASE use `https://github.com/node-modules/address` module instead.___

```js
...

function utility.dig (obj)

description and source-code

dig = function (obj) {
  if (!obj) {
    return;
  }
  if (arguments.length <= 1) {
    return obj;
  }

  var value = obj[arguments[1]];
  for (var i = 2; i < arguments.length; i++) {
    if (!value) {
      break;
    }
    value = value[arguments[i]];
  }

  return value;
}

example usage
```
n/a
```

function utility.encodeURIComponent (text)

description and source-code

function encodeURIComponent_(text) {
  try {
    return encodeURIComponent(text);
  } catch (e) {
    return text;
  }
}

example usage

...
utils.base64encode('你好￥', true); // '5L2g5aW977-l'
utils.base64decode('5L2g5aW977-l', true); // '你好￥'

// html escape
utils.escape('<script/>"& &amp;'); // '&lt;script/&gt;&quot;&amp; &#
x26;amp;'

// Safe encodeURIComponent and decodeURIComponent
utils.decodeURIComponent(utils.encodeURIComponent('你好, nodejs')).should.equal
('你好, nodejs');
```

### others

___[WARNNING] getIP() remove, PLEASE use `https://github.com/node-modules/address` module instead.___

```js
...

function utility.escape (string)

description and source-code

function escapeHtml(string) {
  var str = '' + string;
  var match = matchHtmlRegExp.exec(str);

  if (!match) {
    return str;
  }

  var escape;
  var html = '';
  var index = 0;
  var lastIndex = 0;

  for (index = match.index; index < str.length; index++) {
    switch (str.charCodeAt(index)) {
      case 34: // "
        escape = '&quot;';
        break;
      case 38: // &
        escape = '&amp;';
        break;
      case 39: // '
        escape = '&#39;';
        break;
      case 60: // <
        escape = '&lt;';
        break;
      case 62: // >
        escape = '&gt;';
        break;
      default:
        continue;
    }

    if (lastIndex !== index) {
      html += str.substring(lastIndex, index);
    }

    lastIndex = index + 1;
    html += escape;
  }

  return lastIndex !== index
    ? html + str.substring(lastIndex, index)
    : html;
}

example usage

...
utils.base64decode('5L2g5aW977+l') // '你好￥'

// urlsafe base64 encode
utils.base64encode('你好￥', true); // '5L2g5aW977-l'
utils.base64decode('5L2g5aW977-l', true); // '你好￥'

// html escape
utils.escape('<script/>"& &amp;'); // '&
lt;script/&gt;&quot;&amp; &amp;'

// Safe encodeURIComponent and decodeURIComponent
utils.decodeURIComponent(utils.encodeURIComponent('你好, nodejs')).should.equal('你好, nodejs');
```

### others
...

function utility.getParamNames (func, cache)

description and source-code

function getParamNames(func, cache) {
  cache = cache !== false;
  if (cache && func.__cache_names) {
    return func.__cache_names;
  }
  var str = func.toString();
  var names = str.slice(str.indexOf('(') + 1, str.indexOf(')')).match(/([^\s,]+)/g) || [];
  func.__cache_names = names;
  return names;
}

example usage

...

### others

___[WARNNING] getIP() remove, PLEASE use `https://github.com/node-modules/address` module instead.___

```js
// get a function parameter's names
utils.getParamNames(function (key1, key2) {}); // ['key1', 'key2']

// get a random string, default length is 16.
utils.randomString(32, '1234567890'); //18774480824014856763726145106142

// check if object has this property
utils.has({hello: 'world'}, 'hello'); //true
...

function utility.has (obj, prop)

description and source-code

function has(obj, prop) {
  return Object.prototype.hasOwnProperty.call(obj, prop);
}

example usage

...
// get a function parameter's names
utils.getParamNames(function (key1, key2) {}); // ['key1', 'key2']

// get a random string, default length is 16.
utils.randomString(32, '1234567890'); //18774480824014856763726145106142

// check if object has this property
utils.has({hello: 'world'}, 'hello'); //true

// empty function
utils.noop = function () {}
}
```

### Date utils
...

function utility.hash (method, s, format)

description and source-code

function hash(method, s, format) {
  var sum = crypto.createHash(method);
  var isBuffer = Buffer.isBuffer(s);
  if (!isBuffer && typeof s === 'object') {
    s = JSON.stringify(sortObject(s));
  }
  sum.update(s, isBuffer ? 'binary' : 'utf8');
  return sum.digest(format || 'hex');
}

example usage

...
*
* @param {String|Buffer} s
* @param {String} [format] output string format, could be 'hex' or 'base64'. default is 'hex'.
* @return {String} md5 hash string
* @public
*/
exports.md5 = function md5(s, format) {
 return exports.hash('md5', s, format);
};

/**
* sha1 hash
*
* @param {String|Buffer} s
* @param {String} [format] output string format, could be 'hex' or 'base64'. default is 'hex'.
...

function utility.hmac (algorithm, key, data, encoding)

description and source-code

function hmac(algorithm, key, data, encoding) {
  encoding = encoding || 'base64';
  var hmac = crypto.createHmac(algorithm, key);
  hmac.update(data, Buffer.isBuffer(data) ? 'binary' : 'utf8');
  return hmac.digest(encoding);
}

example usage

...
utils.sha256(new Buffer('苏千')).should.equal('75dd03e3fcdbba7d5bec07900bae740cc8e361d77e7df8949de421d3df5d3635'
;);
```

### hmac

```js
// hmac-sha1 with base64 output encoding
utils.hmac('sha1', 'I am a key', 'hello world'); // '
;pO6J0LKDxRRkvSECSEdxwKx84L0='
```

### decode and encode

```js
// base64 encode
utils.base64encode('你好￥'); // '5L2g5aW977+l'
...

function utility.includesInvalidHttpHeaderChar (val)

description and source-code

function includesInvalidHttpHeaderChar(val) {
  if (!val || typeof val !== 'string') {
    return false;
  }

  for (var i = 0; i < val.length; ++i) {
    if (!validHdrChars[val.charCodeAt(i)]) {
      return true;
    }
  }

  return false;
}

example usage
```
n/a
```

function utility.isSafeNumberString (s)

description and source-code

function isSafeNumberString(s) {
  if (s[0] === '-') {
    s = s.substring(1);
  }
  if (s.length < MAX_SAFE_INTEGER_STR_LENGTH ||
    (s.length === MAX_SAFE_INTEGER_STR_LENGTH && s <= MAX_SAFE_INTEGER_STR)) {
    return true;
  }
  return false;
}

example usage

...
utils.timestamp(1385091596000); // Fri Nov 22 2013 11:39:56 GMT+0800 (CST)
```

### Number utils

```js
// Detect a number string can safe convert to Javascript Number.: `-9007199254740991 ~ 9007199254740991`
utils.isSafeNumberString('9007199254740991'); // true
utils.isSafeNumberString('9007199254740993'); // false

// Convert string to number safe:
utils.toSafeNumber('9007199254740991'); // 9007199254740991
utils.toSafeNumber('9007199254740993'); // '9007199254740993'

// Produces a random integer between the inclusive `lower` and exclusive `upper` bounds.
...

function utility.logDate (d, msSep)

description and source-code

logDate = function (d, msSep) {
  if (typeof d === 'string') {
    // logDate(msSep)
    msSep = d;
    d = new Date();
  } else {
    // logDate(d, msSep)
    d = d || new Date();
  }
  var date = d.getDate();
  if (date < 10) {
    date = '0' + date;
  }
  var month = d.getMonth() + 1;
  if (month < 10) {
    month = '0' + month;
  }
  var hours = d.getHours();
  if (hours < 10) {
    hours = '0' + hours;
  }
  var mintues = d.getMinutes();
  if (mintues < 10) {
    mintues = '0' + mintues;
  }
  var seconds = d.getSeconds();
  if (seconds < 10) {
    seconds = '0' + seconds;
  }
  var milliseconds = d.getMilliseconds();
  if (milliseconds < 10) {
    milliseconds = '00' + milliseconds;
  } else if (milliseconds < 100) {
    milliseconds = '0' + milliseconds;
  }
  return d.getFullYear() + '-' + month + '-' + date + ' ' +
    hours + ':' + mintues + ':' + seconds + (msSep || '.') + milliseconds;
}

example usage

...

```js
// accessLogDate
utils.accessLogDate(); // '16/Apr/2013:16:40:09 +0800'

// logDate,
// 'YYYY-MM-DD HH:mm:ss.SSS' format date string
utils.logDate(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(','); // '2013-04-17 14:43:02,674'

// 'YYYY-MM-DD HH:mm:ss' format date string
utils.YYYYMMDDHHmmss(); // '2013-04-17 14:43:02'
utils.YYYYMMDDHHmmss(new Date(), {dateSep: '.'}); // '2013.04.17 14:43:02'
...

function utility.map (obj)

description and source-code

function map(obj) {
  var map = new EmptyObject();
  if (!obj) {
    return map;
  }

  for (var key in obj) {
    map[key] = obj[key];
  }
  return map;
}

example usage

...
### map

Create a `real` map in javascript.

use `Object.create(null)`

```js
const map = utils.map({a: 1});

// should.not.exist(map.constractor);
// should.not.exist(map.__proto__);
// should.not.exist(map.toString);
// should not exist any property

console.log(map); // {a: 1}
...

function utility.md5 (s, format)

description and source-code

function md5(s, format) {
  return exports.hash('md5', s, format);
}

example usage

...
```js
const utils = require('utility');
```

### md5

```js
utils.md5('苏千').should.equal('5f733c47c58a077d61257102b2d44481');
utils.md5(new Buffer('苏千')).should.equal('5f733c47c58a077d61257102b2d44481');
// md5 base64 format
utils.md5('苏千', 'base64'); // 'X3M8R8WKB31hJXECstREgQ=='

// Object md5 hash. Sorted by key, and JSON.stringify. See source code for detail
utils.md5({foo: 'bar', bar: 'foo'}).should.equal(utils.md5({bar: 'foo', foo: 'bar'}));
```
...

function utility.noop ()

description and source-code
```
function noop() {}
```
example usage
```
n/a
```

function utility.random (lower, upper)

description and source-code

function random(lower, upper) {
  if (lower === undefined && upper === undefined) {
    return 0;
  }
  if (upper === undefined) {
    upper = lower;
    lower = 0;
  }
  var temp;
  if (lower > upper) {
    temp = lower;
    lower = upper;
    upper = temp;
  }
  return Math.floor(lower + Math.random() * (upper - lower));
}

example usage

...
utils.isSafeNumberString('9007199254740993'); // false

// Convert string to number safe:
utils.toSafeNumber('9007199254740991'); // 9007199254740991
utils.toSafeNumber('9007199254740993'); // '9007199254740993'

// Produces a random integer between the inclusive `lower` and exclusive `upper` bounds.
utils.random(100); // [0, 100)
utils.random(2, 1000); // [2, 1000)
utils.random(); // 0
```

### Timers

```js
...

function utility.randomSlice (arr, num)

description and source-code

function randomSlice(arr, num) {
  if (!num || num >= arr.length) {
    return arr.slice();
  }
  var index = Math.floor(Math.random() * arr.length);
  var a = [];
  for (var i = 0, j = index; i < num; i++) {
    a.push(arr[j++]);
    if (j === arr.length) {
      j = 0;
    }
  }
  return a;
}

example usage
```
n/a
```

function utility.randomString (length, charSet)

description and source-code

function randomString(length, charSet) {
  var result = [];
  length = length || 16;
  charSet = charSet || 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

  while (length--) {
    result.push(charSet[Math.floor(Math.random() * charSet.length)]);
  }
  return result.join('');
}

example usage

...
___[WARNNING] getIP() remove, PLEASE use `https://github.com/node-modules/address` module instead.___

```js
// get a function parameter's names
utils.getParamNames(function (key1, key2) {}); // ['key1', 'key2']

// get a random string, default length is 16.
utils.randomString(32, '1234567890'); //18774480824014856763726145106142

// check if object has this property
utils.has({hello: 'world'}, 'hello'); //true

// empty function
utils.noop = function () {}
}
...

function utility.replace (str, substr, newSubstr)

description and source-code

function replace(str, substr, newSubstr) {
  var replaceFunction = newSubstr;
  if (typeof replaceFunction !== 'function') {
    replaceFunction = function () {
      return newSubstr;
    };
  }
  return str.replace(substr, replaceFunction);
}

example usage

...
### String utils

```js
// split string by sep
utils.split('foo,bar,,,', ','); // ['foo', 'bar']

// replace string work with special chars which `String.prototype.replace` can't handle
utils.replace('<body> hi', '<body>', '$&#
x26; body'); // '$& body hi'

// replace http header invalid characters
utils.replaceInvalidHttpHeaderChar('abc你好11'); // {invalid: true, val: 'abc  11'}
```

### Try
...

function utility.replaceInvalidHttpHeaderChar (val, replacement)

description and source-code

function replaceInvalidHttpHeaderChar(val, replacement) {
  replacement = replacement || ' ';
  var invalid = false;

  if (!val || typeof val !== 'string') {
    return {
      val: val,
      invalid: invalid,
    };
  }

  var replacementType = typeof replacement;
  var chars;
  for (var i = 0; i < val.length; ++i) {
    if (!validHdrChars[val.charCodeAt(i)]) {
      // delay create chars
      chars = chars || val.split('');
      if (replacementType === 'function') {
        chars[i] = replacement(chars[i]);
      } else {
        chars[i] = replacement;
      }
    }
  }

  if (chars) {
    val = chars.join('');
    invalid = true;
  }

  return {
    val: val,
    invalid: invalid,
  };
}

example usage

...
// split string by sep
utils.split('foo,bar,,,', ','); // ['foo', 'bar']

// replace string work with special chars which `String.prototype.replace` can't handle
utils.replace('<body> hi', '<body>', '$& body'); // '$& body hi
'

// replace http header invalid characters
utils.replaceInvalidHttpHeaderChar('abc你好11'); // {invalid: true, val: '
;abc  11'}
```

### Try

```js
const res = utils.try(function () {
return JSON.parse(str);
...

function utility.setImmediate ()

description and source-code

setImmediate = function () {
/*
 * this function will do nothing
 */
    return;
}

example usage

...
utils.random(2, 1000); // [2, 1000)
utils.random(); // 0
```

### Timers

```js
utils.setImmediate(function () {
  console.log('hi');
});
```

### map

Create a `real` map in javascript.
...

function utility.sha1 (s, format)

description and source-code

function sha1(s, format) {
  return exports.hash('sha1', s, format);
}

example usage

...
// Object md5 hash. Sorted by key, and JSON.stringify. See source code for detail
utils.md5({foo: 'bar', bar: 'foo'}).should.equal(utils.md5({bar: 'foo', foo: 'bar'}));
```

### sha1

```js
utils.sha1('苏千').should.equal('0a4aff6bab634b9c2f99b71f25e976921fcde5a5
');
utils.sha1(new Buffer('苏千')).should.equal('0a4aff6bab634b9c2f99b71f25e976921fcde5a5');
// sha1 base64 format
utils.sha1('苏千', 'base64'); // 'Ckr/a6tjS5wvmbcfJel2kh/N5aU='

// Object sha1 hash. Sorted by key, and JSON.stringify. See source code for detail
utils.sha1({foo: 'bar', bar: 'foo'}).should.equal(utils.sha1({bar: 'foo', foo: 'bar'}));
```
...

function utility.sha256 (s, format)

description and source-code

function sha1(s, format) {
  return exports.hash('sha256', s, format);
}

example usage

...
// Object sha1 hash. Sorted by key, and JSON.stringify. See source code for detail
utils.sha1({foo: 'bar', bar: 'foo'}).should.equal(utils.sha1({bar: 'foo', foo: 'bar'}));
```

### sha256

```js
utils.sha256(new Buffer('苏千')).should.equal('75dd03e3fcdbba7d5bec07900bae740cc8e361d77e7df8949de421d3df5d3635
');
```

### hmac

```js
// hmac-sha1 with base64 output encoding
utils.hmac('sha1', 'I am a key', 'hello world'); // 'pO6J0LKDxRRkvSECSEdxwKx84L0='
...

function utility.spliceOne (arr, index)

description and source-code

function spliceOne(arr, index) {
  if (index < 0) {
    index = arr.length + index;
    // still negative, not found element
    if (index < 0) {
      return arr;
    }
  }

  // don't touch
  if (index >= arr.length) {
    return arr;
  }

  for (var i = index, k = i + 1, n = arr.length; k < n; i += 1, k += 1) {
    arr[i] = arr[k];
  }
  arr.pop();
  return arr;
}

example usage
```
n/a
```

function utility.split (str, sep)

description and source-code

function split(str, sep) {
  str = str || '';
  sep = sep || ',';
  var items = str.split(sep);
  var needs = [];
  for (var i = 0; i < items.length; i++) {
    var s = items[i].trim();
    if (s.length > 0) {
      needs.push(s);
    }
  }
  return needs;
}

example usage

...
console.log(map); // {a: 1}
```

### String utils

```js
// split string by sep
utils.split('foo,bar,,,', ','); // ['foo', 'bar'
;]

// replace string work with special chars which `String.prototype.replace` can't handle
utils.replace('<body> hi', '<body>', '$& body'); // '$& body hi
'

// replace http header invalid characters
utils.replaceInvalidHttpHeaderChar('abc你好11'); // {invalid: true, val: 'abc  11'}
```
...

function utility.splitAlwaysOptimized ()

description and source-code

function splitAlwaysOptimized() {
  var str = '';
  var sep = ',';
  if (arguments.length === 1) {
    str = arguments[0] || '';
  } else if (arguments.length === 2) {
    str = arguments[0] || '';
    sep = arguments[1] || ',';
  }
  var items = str.split(sep);
  var needs = [];
  for (var i = 0; i < items.length; i++) {
    var s = items[i].trim();
    if (s.length > 0) {
      needs.push(s);
    }
  }
  return needs;
}

example usage
```
n/a
```

function utility.strictJSONParse (str)

description and source-code

strictJSONParse = function (str) {
  var obj = JSON.parse(str);
  if (!obj || typeof obj !== 'object') {
    throw new Error('JSON string is not object');
  }
  return obj;
}

example usage
```
n/a
```

function utility.timestamp (t)

description and source-code

function timestamp(t) {
  if (t) {
    var v = t;
    if (typeof v === 'string') {
      v = Number(v);
    }
    if (String(t).length === 10) {
      v *= 1000;
    }
    return new Date(v);
  }
  return Math.round(Date.now() / 1000);
}

example usage

...
utils.YYYYMMDD(''); // '20130417'
utils.YYYYMMDD(','); // '2013,04,17'

// datestruct
utils.datestruct(); // { YYYYMMDD: 20130416, H: 8 }

// Unix's timestamp
utils.timestamp(); // 1378153226

// Parse timestamp
// seconds
utils.timestamp(1385091596); // Fri Nov 22 2013 11:39:56 GMT+0800 (CST)
// millseconds
utils.timestamp(1385091596000); // Fri Nov 22 2013 11:39:56 GMT+0800 (CST)
```
...

function utility.toSafeNumber (s)

description and source-code

function toSafeNumber(s) {
  if (typeof s === 'number') {
    return s;
  }

  return exports.isSafeNumberString(s) ? Number(s) : s;
}

example usage

...

```js
// Detect a number string can safe convert to Javascript Number.: `-9007199254740991 ~ 9007199254740991`
utils.isSafeNumberString('9007199254740991'); // true
utils.isSafeNumberString('9007199254740993'); // false

// Convert string to number safe:
utils.toSafeNumber('9007199254740991'); // 9007199254740991
utils.toSafeNumber('9007199254740993'); // '9007199254740993'

// Produces a random integer between the inclusive `lower` and exclusive `upper` bounds.
utils.random(100); // [0, 100)
utils.random(2, 1000); // [2, 1000)
utils.random(); // 0
```
...

function utility.try (fn)

description and source-code

try = function (fn) {
  var res = {
    error: undefined,
    value: undefined
  };

  try {
    res.value = fn();
  } catch (err) {
    res.error = err instanceof Error
      ? err
      : new Error(err);
  }

  return res;
}

example usage

...
// replace http header invalid characters
utils.replaceInvalidHttpHeaderChar('abc你好11'); // {invalid: true, val: 'abc  11'}
```

### Try

```js
const res = utils.try(function () {
  return JSON.parse(str);
});

// {error: undefined, value: {foo: 'bar'}}
// {error: Error, value: undefined}
```
...

module utility.array

function utility.array.randomSlice (arr, num)

description and source-code

function randomSlice(arr, num) {
  if (!num || num >= arr.length) {
    return arr.slice();
  }
  var index = Math.floor(Math.random() * arr.length);
  var a = [];
  for (var i = 0, j = index; i < num; i++) {
    a.push(arr[j++]);
    if (j === arr.length) {
      j = 0;
    }
  }
  return a;
}

example usage
```
n/a
```

function utility.array.spliceOne (arr, index)

description and source-code

function spliceOne(arr, index) {
  if (index < 0) {
    index = arr.length + index;
    // still negative, not found element
    if (index < 0) {
      return arr;
    }
  }

  // don't touch
  if (index >= arr.length) {
    return arr;
  }

  for (var i = index, k = i + 1, n = arr.length; k < n; i += 1, k += 1) {
    arr[i] = arr[k];
  }
  arr.pop();
  return arr;
}

example usage
```
n/a
```

module utility.crypto

function utility.crypto.base64decode (encodeStr, urlsafe, encoding)

description and source-code

function base64decode(encodeStr, urlsafe, encoding) {
  if (urlsafe) {
    encodeStr = encodeStr.replace(/\-/g, '+').replace(/_/g, '/');
  }
  var buf = new Buffer(encodeStr, 'base64');
  if (encoding === 'buffer') {
    return buf;
  }
  return buf.toString(encoding || 'utf8');
}

example usage

...
```

### decode and encode

```js
// base64 encode
utils.base64encode('你好￥'); // '5L2g5aW977+l'
utils.base64decode('5L2g5aW977+l') // '你好￥'

// urlsafe base64 encode
utils.base64encode('你好￥', true); // '5L2g5aW977-l'
utils.base64decode('5L2g5aW977-l', true); // '你好￥'

// html escape
utils.escape('<script/>"& &amp;'); // '&lt;script/&gt;&quot;&amp; &#
x26;amp;'
...

function utility.crypto.base64encode (s, urlsafe)

description and source-code

function base64encode(s, urlsafe) {
  if (!Buffer.isBuffer(s)) {
    s = new Buffer(s);
  }
  var encode = s.toString('base64');
  if (urlsafe) {
    encode = encode.replace(/\+/g, '-').replace(/\//g, '_');
  }
  return encode;
}

example usage

...
utils.hmac('sha1', 'I am a key', 'hello world'); // 'pO6J0LKDxRRkvSECSEdxwKx84L0='
```

### decode and encode

```js
// base64 encode
utils.base64encode('你好￥'); // '5L2g5aW977+l'
utils.base64decode('5L2g5aW977+l') // '你好￥'

// urlsafe base64 encode
utils.base64encode('你好￥', true); // '5L2g5aW977-l'
utils.base64decode('5L2g5aW977-l', true); // '你好￥'

// html escape
...

function utility.crypto.hash (method, s, format)

description and source-code

function hash(method, s, format) {
  var sum = crypto.createHash(method);
  var isBuffer = Buffer.isBuffer(s);
  if (!isBuffer && typeof s === 'object') {
    s = JSON.stringify(sortObject(s));
  }
  sum.update(s, isBuffer ? 'binary' : 'utf8');
  return sum.digest(format || 'hex');
}

example usage

...
*
* @param {String|Buffer} s
* @param {String} [format] output string format, could be 'hex' or 'base64'. default is 'hex'.
* @return {String} md5 hash string
* @public
*/
exports.md5 = function md5(s, format) {
 return exports.hash('md5', s, format);
};

/**
* sha1 hash
*
* @param {String|Buffer} s
* @param {String} [format] output string format, could be 'hex' or 'base64'. default is 'hex'.
...

function utility.crypto.hmac (algorithm, key, data, encoding)

description and source-code

function hmac(algorithm, key, data, encoding) {
  encoding = encoding || 'base64';
  var hmac = crypto.createHmac(algorithm, key);
  hmac.update(data, Buffer.isBuffer(data) ? 'binary' : 'utf8');
  return hmac.digest(encoding);
}

example usage

...
utils.sha256(new Buffer('苏千')).should.equal('75dd03e3fcdbba7d5bec07900bae740cc8e361d77e7df8949de421d3df5d3635'
;);
```

### hmac

```js
// hmac-sha1 with base64 output encoding
utils.hmac('sha1', 'I am a key', 'hello world'); // '
;pO6J0LKDxRRkvSECSEdxwKx84L0='
```

### decode and encode

```js
// base64 encode
utils.base64encode('你好￥'); // '5L2g5aW977+l'
...

function utility.crypto.md5 (s, format)

description and source-code

function md5(s, format) {
  return exports.hash('md5', s, format);
}

example usage

...
```js
const utils = require('utility');
```

### md5

```js
utils.md5('苏千').should.equal('5f733c47c58a077d61257102b2d44481');
utils.md5(new Buffer('苏千')).should.equal('5f733c47c58a077d61257102b2d44481');
// md5 base64 format
utils.md5('苏千', 'base64'); // 'X3M8R8WKB31hJXECstREgQ=='

// Object md5 hash. Sorted by key, and JSON.stringify. See source code for detail
utils.md5({foo: 'bar', bar: 'foo'}).should.equal(utils.md5({bar: 'foo', foo: 'bar'}));
```
...

function utility.crypto.sha1 (s, format)

description and source-code

function sha1(s, format) {
  return exports.hash('sha1', s, format);
}

example usage

...
// Object md5 hash. Sorted by key, and JSON.stringify. See source code for detail
utils.md5({foo: 'bar', bar: 'foo'}).should.equal(utils.md5({bar: 'foo', foo: 'bar'}));
```

### sha1

```js
utils.sha1('苏千').should.equal('0a4aff6bab634b9c2f99b71f25e976921fcde5a5
');
utils.sha1(new Buffer('苏千')).should.equal('0a4aff6bab634b9c2f99b71f25e976921fcde5a5');
// sha1 base64 format
utils.sha1('苏千', 'base64'); // 'Ckr/a6tjS5wvmbcfJel2kh/N5aU='

// Object sha1 hash. Sorted by key, and JSON.stringify. See source code for detail
utils.sha1({foo: 'bar', bar: 'foo'}).should.equal(utils.sha1({bar: 'foo', foo: 'bar'}));
```
...

function utility.crypto.sha256 (s, format)

description and source-code

function sha1(s, format) {
  return exports.hash('sha256', s, format);
}

example usage

...
// Object sha1 hash. Sorted by key, and JSON.stringify. See source code for detail
utils.sha1({foo: 'bar', bar: 'foo'}).should.equal(utils.sha1({bar: 'foo', foo: 'bar'}));
```

### sha256

```js
utils.sha256(new Buffer('苏千')).should.equal('75dd03e3fcdbba7d5bec07900bae740cc8e361d77e7df8949de421d3df5d3635
');
```

### hmac

```js
// hmac-sha1 with base64 output encoding
utils.hmac('sha1', 'I am a key', 'hello world'); // 'pO6J0LKDxRRkvSECSEdxwKx84L0='
...

module utility.date

function utility.date.YYYYMMDD (d, sep)

description and source-code

function YYYYMMDD(d, sep) {
  if (typeof d === 'string') {
    // YYYYMMDD(sep)
    sep = d;
    d = new Date();
  } else {
    // YYYYMMDD(d, sep)
    d = d || new Date();
    if (typeof sep !== 'string') {
      sep = '-';
    }
  }
  var date = d.getDate();
  if (date < 10) {
    date = '0' + date;
  }
  var month = d.getMonth() + 1;
  if (month < 10) {
    month = '0' + month;
  }
  return d.getFullYear() + sep + month + sep + date;
}

example usage

...
utils.YYYYMMDDHHmmssSSS(','); // '2013-04-17 14:43:02,674'

// 'YYYY-MM-DD HH:mm:ss' format date string
utils.YYYYMMDDHHmmss(); // '2013-04-17 14:43:02'
utils.YYYYMMDDHHmmss(new Date(), {dateSep: '.'}); // '2013.04.17 14:43:02'

// 'YYYY-MM-DD' format date string
utils.YYYYMMDD(); // '2013-04-17'
utils.YYYYMMDD(''); // '20130417'
utils.YYYYMMDD(','); // '2013,04,17'

// datestruct
utils.datestruct(); // { YYYYMMDD: 20130416, H: 8 }

// Unix's timestamp
...

function utility.date.YYYYMMDDHHmmss (d, options)

description and source-code

YYYYMMDDHHmmss = function (d, options) {
  d = d || new Date();
  if (!(d instanceof Date)) {
    d = new Date(d);
  }

  var dateSep = '-';
  var timeSep = ':';
  if (options) {
    if (options.dateSep) {
      dateSep = options.dateSep;
    }
    if (options.timeSep) {
      timeSep = options.timeSep;
    }
  }
  var date = d.getDate();
  if (date < 10) {
    date = '0' + date;
  }
  var month = d.getMonth() + 1;
  if (month < 10) {
    month = '0' + month;
  }
  var hours = d.getHours();
  if (hours < 10) {
    hours = '0' + hours;
  }
  var mintues = d.getMinutes();
  if (mintues < 10) {
    mintues = '0' + mintues;
  }
  var seconds = d.getSeconds();
  if (seconds < 10) {
    seconds = '0' + seconds;
  }
  return d.getFullYear() + dateSep + month + dateSep + date + ' ' +
    hours + timeSep + mintues + timeSep + seconds;
}

example usage

...
// logDate,
// 'YYYY-MM-DD HH:mm:ss.SSS' format date string
utils.logDate(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(','); // '2013-04-17 14:43:02,674'

// 'YYYY-MM-DD HH:mm:ss' format date string
utils.YYYYMMDDHHmmss(); // '2013-04-17 14:43:02'
utils.YYYYMMDDHHmmss(new Date(), {dateSep: '.'}); // '2013.04.17 14:43:02'

// 'YYYY-MM-DD' format date string
utils.YYYYMMDD(); // '2013-04-17'
utils.YYYYMMDD(''); // '20130417'
utils.YYYYMMDD(','); // '2013,04,17'
...

function utility.date.YYYYMMDDHHmmssSSS (d, msSep)

description and source-code

YYYYMMDDHHmmssSSS = function (d, msSep) {
  if (typeof d === 'string') {
    // logDate(msSep)
    msSep = d;
    d = new Date();
  } else {
    // logDate(d, msSep)
    d = d || new Date();
  }
  var date = d.getDate();
  if (date < 10) {
    date = '0' + date;
  }
  var month = d.getMonth() + 1;
  if (month < 10) {
    month = '0' + month;
  }
  var hours = d.getHours();
  if (hours < 10) {
    hours = '0' + hours;
  }
  var mintues = d.getMinutes();
  if (mintues < 10) {
    mintues = '0' + mintues;
  }
  var seconds = d.getSeconds();
  if (seconds < 10) {
    seconds = '0' + seconds;
  }
  var milliseconds = d.getMilliseconds();
  if (milliseconds < 10) {
    milliseconds = '00' + milliseconds;
  } else if (milliseconds < 100) {
    milliseconds = '0' + milliseconds;
  }
  return d.getFullYear() + '-' + month + '-' + date + ' ' +
    hours + ':' + mintues + ':' + seconds + (msSep || '.') + milliseconds;
}

example usage

...
```js
// accessLogDate
utils.accessLogDate(); // '16/Apr/2013:16:40:09 +0800'

// logDate,
// 'YYYY-MM-DD HH:mm:ss.SSS' format date string
utils.logDate(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(','); // '2013-04-17 14:43:02,674'

// 'YYYY-MM-DD HH:mm:ss' format date string
utils.YYYYMMDDHHmmss(); // '2013-04-17 14:43:02'
utils.YYYYMMDDHHmmss(new Date(), {dateSep: '.'}); // '2013.04.17 14:43:02'

// 'YYYY-MM-DD' format date string
...

function utility.date.accessLogDate (d)

description and source-code

accessLogDate = function (d) {
  // 16/Apr/2013:16:40:09 +0800
  d = d || new Date();
  var date = d.getDate();
  if (date < 10) {
    date = '0' + date;
  }
  var hours = d.getHours();
  if (hours < 10) {
    hours = '0' + hours;
  }
  var mintues = d.getMinutes();
  if (mintues < 10) {
    mintues = '0' + mintues;
  }
  var seconds = d.getSeconds();
  if (seconds < 10) {
    seconds = '0' + seconds;
  }
  return date + '/' + MONTHS[d.getMonth()] + '/' + d.getFullYear() +
    ':' + hours + ':' + mintues + ':' + seconds + TIMEZONE;
}

example usage

...
}
```

### Date utils

```js
// accessLogDate
utils.accessLogDate(); // '16/Apr/2013:16:40:09 +0800'

// logDate,
// 'YYYY-MM-DD HH:mm:ss.SSS' format date string
utils.logDate(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(','); // '2013-04-17 14:43:02,674'
...

function utility.date.datestruct (now)

description and source-code

datestruct = function (now) {
  now = now || new Date();
  return {
    YYYYMMDD: now.getFullYear() * 10000 + (now.getMonth() + 1) * 100 + now.getDate(),
    H: now.getHours()
  };
}

example usage

...

// 'YYYY-MM-DD' format date string
utils.YYYYMMDD(); // '2013-04-17'
utils.YYYYMMDD(''); // '20130417'
utils.YYYYMMDD(','); // '2013,04,17'

// datestruct
utils.datestruct(); // { YYYYMMDD: 20130416, H: 8 }

// Unix's timestamp
utils.timestamp(); // 1378153226

// Parse timestamp
// seconds
utils.timestamp(1385091596); // Fri Nov 22 2013 11:39:56 GMT+0800 (CST)
...

function utility.date.logDate (d, msSep)

description and source-code

logDate = function (d, msSep) {
  if (typeof d === 'string') {
    // logDate(msSep)
    msSep = d;
    d = new Date();
  } else {
    // logDate(d, msSep)
    d = d || new Date();
  }
  var date = d.getDate();
  if (date < 10) {
    date = '0' + date;
  }
  var month = d.getMonth() + 1;
  if (month < 10) {
    month = '0' + month;
  }
  var hours = d.getHours();
  if (hours < 10) {
    hours = '0' + hours;
  }
  var mintues = d.getMinutes();
  if (mintues < 10) {
    mintues = '0' + mintues;
  }
  var seconds = d.getSeconds();
  if (seconds < 10) {
    seconds = '0' + seconds;
  }
  var milliseconds = d.getMilliseconds();
  if (milliseconds < 10) {
    milliseconds = '00' + milliseconds;
  } else if (milliseconds < 100) {
    milliseconds = '0' + milliseconds;
  }
  return d.getFullYear() + '-' + month + '-' + date + ' ' +
    hours + ':' + mintues + ':' + seconds + (msSep || '.') + milliseconds;
}

example usage

...

```js
// accessLogDate
utils.accessLogDate(); // '16/Apr/2013:16:40:09 +0800'

// logDate,
// 'YYYY-MM-DD HH:mm:ss.SSS' format date string
utils.logDate(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(); // '2013-04-17 14:43:02.674'
utils.YYYYMMDDHHmmssSSS(','); // '2013-04-17 14:43:02,674'

// 'YYYY-MM-DD HH:mm:ss' format date string
utils.YYYYMMDDHHmmss(); // '2013-04-17 14:43:02'
utils.YYYYMMDDHHmmss(new Date(), {dateSep: '.'}); // '2013.04.17 14:43:02'
...

function utility.date.timestamp (t)

description and source-code

function timestamp(t) {
  if (t) {
    var v = t;
    if (typeof v === 'string') {
      v = Number(v);
    }
    if (String(t).length === 10) {
      v *= 1000;
    }
    return new Date(v);
  }
  return Math.round(Date.now() / 1000);
}

example usage

...
utils.YYYYMMDD(''); // '20130417'
utils.YYYYMMDD(','); // '2013,04,17'

// datestruct
utils.datestruct(); // { YYYYMMDD: 20130416, H: 8 }

// Unix's timestamp
utils.timestamp(); // 1378153226

// Parse timestamp
// seconds
utils.timestamp(1385091596); // Fri Nov 22 2013 11:39:56 GMT+0800 (CST)
// millseconds
utils.timestamp(1385091596000); // Fri Nov 22 2013 11:39:56 GMT+0800 (CST)
```
...

module utility.function

function utility.function.getParamNames (func, cache)

description and source-code

function getParamNames(func, cache) {
  cache = cache !== false;
  if (cache && func.__cache_names) {
    return func.__cache_names;
  }
  var str = func.toString();
  var names = str.slice(str.indexOf('(') + 1, str.indexOf(')')).match(/([^\s,]+)/g) || [];
  func.__cache_names = names;
  return names;
}

example usage

...

### others

___[WARNNING] getIP() remove, PLEASE use `https://github.com/node-modules/address` module instead.___

```js
// get a function parameter's names
utils.getParamNames(function (key1, key2) {}); // ['key1', 'key2']

// get a random string, default length is 16.
utils.randomString(32, '1234567890'); //18774480824014856763726145106142

// check if object has this property
utils.has({hello: 'world'}, 'hello'); //true
...

function utility.function.noop ()

description and source-code
```
function noop() {}
```
example usage
```
n/a
```

module utility.json

function utility.json.strictJSONParse (str)

description and source-code

strictJSONParse = function (str) {
  var obj = JSON.parse(str);
  if (!obj || typeof obj !== 'object') {
    throw new Error('JSON string is not object');
  }
  return obj;
}

example usage
```
n/a
```

module utility.number

function utility.number.isSafeNumberString (s)

description and source-code

function isSafeNumberString(s) {
  if (s[0] === '-') {
    s = s.substring(1);
  }
  if (s.length < MAX_SAFE_INTEGER_STR_LENGTH ||
    (s.length === MAX_SAFE_INTEGER_STR_LENGTH && s <= MAX_SAFE_INTEGER_STR)) {
    return true;
  }
  return false;
}

example usage

...
utils.timestamp(1385091596000); // Fri Nov 22 2013 11:39:56 GMT+0800 (CST)
```

### Number utils

```js
// Detect a number string can safe convert to Javascript Number.: `-9007199254740991 ~ 9007199254740991`
utils.isSafeNumberString('9007199254740991'); // true
utils.isSafeNumberString('9007199254740993'); // false

// Convert string to number safe:
utils.toSafeNumber('9007199254740991'); // 9007199254740991
utils.toSafeNumber('9007199254740993'); // '9007199254740993'

// Produces a random integer between the inclusive `lower` and exclusive `upper` bounds.
...

function utility.number.random (lower, upper)

description and source-code

function random(lower, upper) {
  if (lower === undefined && upper === undefined) {
    return 0;
  }
  if (upper === undefined) {
    upper = lower;
    lower = 0;
  }
  var temp;
  if (lower > upper) {
    temp = lower;
    lower = upper;
    upper = temp;
  }
  return Math.floor(lower + Math.random() * (upper - lower));
}

example usage

...
utils.isSafeNumberString('9007199254740993'); // false

// Convert string to number safe:
utils.toSafeNumber('9007199254740991'); // 9007199254740991
utils.toSafeNumber('9007199254740993'); // '9007199254740993'

// Produces a random integer between the inclusive `lower` and exclusive `upper` bounds.
utils.random(100); // [0, 100)
utils.random(2, 1000); // [2, 1000)
utils.random(); // 0
```

### Timers

```js
...

function utility.number.toSafeNumber (s)

description and source-code

function toSafeNumber(s) {
  if (typeof s === 'number') {
    return s;
  }

  return exports.isSafeNumberString(s) ? Number(s) : s;
}

example usage

...

```js
// Detect a number string can safe convert to Javascript Number.: `-9007199254740991 ~ 9007199254740991`
utils.isSafeNumberString('9007199254740991'); // true
utils.isSafeNumberString('9007199254740993'); // false

// Convert string to number safe:
utils.toSafeNumber('9007199254740991'); // 9007199254740991
utils.toSafeNumber('9007199254740993'); // '9007199254740993'

// Produces a random integer between the inclusive `lower` and exclusive `upper` bounds.
utils.random(100); // [0, 100)
utils.random(2, 1000); // [2, 1000)
utils.random(); // 0
```
...

module utility.object

function utility.object.assign (target, objects)

description and source-code

assign = function (target, objects) {
  if (!Array.isArray(objects)) {
    objects = [ objects ];
  }

  for (var i = 0; i < objects.length; i++) {
    var obj = objects[i];
    if (obj) {
      var keys = Object.keys(obj);
      for (var j = 0; j < keys.length; j++) {
        var key = keys[j];
        target[key] = obj[key];
      }
    }
  }
  return target;
}

example usage

...
```

### Object.assign


```js
// assign object
utility.assign({}, { a: 1 });

// assign multiple object
utility.assign({}, [ { a: 1 }, { b: 1 } ]);
```

## benchmark
...

function utility.object.has (obj, prop)

description and source-code

function has(obj, prop) {
  return Object.prototype.hasOwnProperty.call(obj, prop);
}

example usage

...
// get a function parameter's names
utils.getParamNames(function (key1, key2) {}); // ['key1', 'key2']

// get a random string, default length is 16.
utils.randomString(32, '1234567890'); //18774480824014856763726145106142

// check if object has this property
utils.has({hello: 'world'}, 'hello'); //true

// empty function
utils.noop = function () {}
}
```

### Date utils
...

function utility.object.map (obj)

description and source-code

function map(obj) {
  var map = new EmptyObject();
  if (!obj) {
    return map;
  }

  for (var key in obj) {
    map[key] = obj[key];
  }
  return map;
}

example usage

...
### map

Create a `real` map in javascript.

use `Object.create(null)`

```js
const map = utils.map({a: 1});

// should.not.exist(map.constractor);
// should.not.exist(map.__proto__);
// should.not.exist(map.toString);
// should not exist any property

console.log(map); // {a: 1}
...

module utility.optimize

function utility.optimize.argumentsToArray (args)

description and source-code

argumentsToArray = function (args) {
  var res = new Array(args.length);
  for (var i = 0; i < args.length; i++) {
    res[i] = args[i];
  }
  return res;
}

example usage

...
// {error: Error, value: undefined}
```

### argumentsToArray

```js
function() {
  const arr = utility.argumentsToArray(arguments);
  console.log(arr.join(', '));
}
```

### JSON

```js
...

function utility.optimize.dig (obj)

description and source-code

dig = function (obj) {
  if (!obj) {
    return;
  }
  if (arguments.length <= 1) {
    return obj;
  }

  var value = obj[arguments[1]];
  for (var i = 2; i < arguments.length; i++) {
    if (!value) {
      break;
    }
    value = value[arguments[i]];
  }

  return value;
}

example usage
```
n/a
```

function utility.optimize.try (fn)

description and source-code

try = function (fn) {
  var res = {
    error: undefined,
    value: undefined
  };

  try {
    res.value = fn();
  } catch (err) {
    res.error = err instanceof Error
      ? err
      : new Error(err);
  }

  return res;
}

example usage

...
// replace http header invalid characters
utils.replaceInvalidHttpHeaderChar('abc你好11'); // {invalid: true, val: 'abc  11'}
```

### Try

```js
const res = utils.try(function () {
  return JSON.parse(str);
});

// {error: undefined, value: {foo: 'bar'}}
// {error: Error, value: undefined}
```
...

module utility.polyfill

function utility.polyfill.setImmediate ()

description and source-code

setImmediate = function () {
/*
 * this function will do nothing
 */
    return;
}

example usage

...
utils.random(2, 1000); // [2, 1000)
utils.random(); // 0
```

### Timers

```js
utils.setImmediate(function () {
  console.log('hi');
});
```

### map

Create a `real` map in javascript.
...

module utility.string

function utility.string.includesInvalidHttpHeaderChar (val)

description and source-code

function includesInvalidHttpHeaderChar(val) {
  if (!val || typeof val !== 'string') {
    return false;
  }

  for (var i = 0; i < val.length; ++i) {
    if (!validHdrChars[val.charCodeAt(i)]) {
      return true;
    }
  }

  return false;
}

example usage
```
n/a
```

function utility.string.randomString (length, charSet)

description and source-code

function randomString(length, charSet) {
  var result = [];
  length = length || 16;
  charSet = charSet || 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

  while (length--) {
    result.push(charSet[Math.floor(Math.random() * charSet.length)]);
  }
  return result.join('');
}

example usage

...
___[WARNNING] getIP() remove, PLEASE use `https://github.com/node-modules/address` module instead.___

```js
// get a function parameter's names
utils.getParamNames(function (key1, key2) {}); // ['key1', 'key2']

// get a random string, default length is 16.
utils.randomString(32, '1234567890'); //18774480824014856763726145106142

// check if object has this property
utils.has({hello: 'world'}, 'hello'); //true

// empty function
utils.noop = function () {}
}
...

function utility.string.replace (str, substr, newSubstr)

description and source-code

function replace(str, substr, newSubstr) {
  var replaceFunction = newSubstr;
  if (typeof replaceFunction !== 'function') {
    replaceFunction = function () {
      return newSubstr;
    };
  }
  return str.replace(substr, replaceFunction);
}

example usage

...
### String utils

```js
// split string by sep
utils.split('foo,bar,,,', ','); // ['foo', 'bar']

// replace string work with special chars which `String.prototype.replace` can't handle
utils.replace('<body> hi', '<body>', '$&#
x26; body'); // '$& body hi'

// replace http header invalid characters
utils.replaceInvalidHttpHeaderChar('abc你好11'); // {invalid: true, val: 'abc  11'}
```

### Try
...

function utility.string.replaceInvalidHttpHeaderChar (val, replacement)

description and source-code

function replaceInvalidHttpHeaderChar(val, replacement) {
  replacement = replacement || ' ';
  var invalid = false;

  if (!val || typeof val !== 'string') {
    return {
      val: val,
      invalid: invalid,
    };
  }

  var replacementType = typeof replacement;
  var chars;
  for (var i = 0; i < val.length; ++i) {
    if (!validHdrChars[val.charCodeAt(i)]) {
      // delay create chars
      chars = chars || val.split('');
      if (replacementType === 'function') {
        chars[i] = replacement(chars[i]);
      } else {
        chars[i] = replacement;
      }
    }
  }

  if (chars) {
    val = chars.join('');
    invalid = true;
  }

  return {
    val: val,
    invalid: invalid,
  };
}

example usage

...
// split string by sep
utils.split('foo,bar,,,', ','); // ['foo', 'bar']

// replace string work with special chars which `String.prototype.replace` can't handle
utils.replace('<body> hi', '<body>', '$& body'); // '$& body hi
'

// replace http header invalid characters
utils.replaceInvalidHttpHeaderChar('abc你好11'); // {invalid: true, val: '
;abc  11'}
```

### Try

```js
const res = utils.try(function () {
return JSON.parse(str);
...

function utility.string.split (str, sep)

description and source-code

function split(str, sep) {
  str = str || '';
  sep = sep || ',';
  var items = str.split(sep);
  var needs = [];
  for (var i = 0; i < items.length; i++) {
    var s = items[i].trim();
    if (s.length > 0) {
      needs.push(s);
    }
  }
  return needs;
}

example usage

...
console.log(map); // {a: 1}
```

### String utils

```js
// split string by sep
utils.split('foo,bar,,,', ','); // ['foo', 'bar'
;]

// replace string work with special chars which `String.prototype.replace` can't handle
utils.replace('<body> hi', '<body>', '$& body'); // '$& body hi
'

// replace http header invalid characters
utils.replaceInvalidHttpHeaderChar('abc你好11'); // {invalid: true, val: 'abc  11'}
```
...

function utility.string.splitAlwaysOptimized ()

description and source-code

function splitAlwaysOptimized() {
  var str = '';
  var sep = ',';
  if (arguments.length === 1) {
    str = arguments[0] || '';
  } else if (arguments.length === 2) {
    str = arguments[0] || '';
    sep = arguments[1] || ',';
  }
  var items = str.split(sep);
  var needs = [];
  for (var i = 0; i < items.length; i++) {
    var s = items[i].trim();
    if (s.length > 0) {
      needs.push(s);
    }
  }
  return needs;
}

example usage
```
n/a
```

module utility.web

function utility.web.decodeURIComponent (encodeText)

description and source-code

function decodeURIComponent_(encodeText) {
  try {
    return decodeURIComponent(encodeText);
  } catch (e) {
    return encodeText;
  }
}

example usage

...
utils.base64encode('你好￥', true); // '5L2g5aW977-l'
utils.base64decode('5L2g5aW977-l', true); // '你好￥'

// html escape
utils.escape('<script/>"& &amp;'); // '&lt;script/&gt;&quot;&amp; &#
x26;amp;'

// Safe encodeURIComponent and decodeURIComponent
utils.decodeURIComponent(utils.encodeURIComponent('你好, nodejs')).should.equal
('你好, nodejs');
```

### others

___[WARNNING] getIP() remove, PLEASE use `https://github.com/node-modules/address` module instead.___

```js
...

function utility.web.encodeURIComponent (text)

description and source-code

function encodeURIComponent_(text) {
  try {
    return encodeURIComponent(text);
  } catch (e) {
    return text;
  }
}

example usage

...
utils.base64encode('你好￥', true); // '5L2g5aW977-l'
utils.base64decode('5L2g5aW977-l', true); // '你好￥'

// html escape
utils.escape('<script/>"& &amp;'); // '&lt;script/&gt;&quot;&amp; &#
x26;amp;'

// Safe encodeURIComponent and decodeURIComponent
utils.decodeURIComponent(utils.encodeURIComponent('你好, nodejs')).should.equal
('你好, nodejs');
```

### others

___[WARNNING] getIP() remove, PLEASE use `https://github.com/node-modules/address` module instead.___

```js
...

function utility.web.escape (string)

description and source-code

function escapeHtml(string) {
  var str = '' + string;
  var match = matchHtmlRegExp.exec(str);

  if (!match) {
    return str;
  }

  var escape;
  var html = '';
  var index = 0;
  var lastIndex = 0;

  for (index = match.index; index < str.length; index++) {
    switch (str.charCodeAt(index)) {
      case 34: // "
        escape = '&quot;';
        break;
      case 38: // &
        escape = '&amp;';
        break;
      case 39: // '
        escape = '&#39;';
        break;
      case 60: // <
        escape = '&lt;';
        break;
      case 62: // >
        escape = '&gt;';
        break;
      default:
        continue;
    }

    if (lastIndex !== index) {
      html += str.substring(lastIndex, index);
    }

    lastIndex = index + 1;
    html += escape;
  }

  return lastIndex !== index
    ? html + str.substring(lastIndex, index)
    : html;
}

example usage

...
utils.base64decode('5L2g5aW977+l') // '你好￥'

// urlsafe base64 encode
utils.base64encode('你好￥', true); // '5L2g5aW977-l'
utils.base64decode('5L2g5aW977-l', true); // '你好￥'

// html escape
utils.escape('<script/>"& &amp;'); // '&
lt;script/&gt;&quot;&amp; &amp;'

// Safe encodeURIComponent and decodeURIComponent
utils.decodeURIComponent(utils.encodeURIComponent('你好, nodejs')).should.equal('你好, nodejs');
```

### others
...

api documentation for utility (v1.12.0)

A collection of useful utilities.

table of contents