<commit_before>Try Function
===
[![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coverage Status][codecov-image]][codecov-url] [![Dependencies][dependencies-image]][dependencies-url]

> Wraps a function in a try/catch block.


## Installation

``` bash
$ npm install utils-try-function
```


## Usage

``` javascript
var wrap = require( 'utils-try-function' );
```

#### wrap( fcn )

Wraps a `function` in a `try/catch` block.

``` javascript
function fcn() {
	throw new Error( 'beep boop' );
}

var f = wrap( fcn );

var out = f();
if ( out instanceof Error ) {
	console.error( out.message );
	// returns 'beep boop'
}
```

The returned `function` has the same signature as the wrapped `function`.

``` javascript
function fcn( a, b, c, d ) {
	var sum = a + b + c + d;
	if ( sum < 10 ) {
		throw new Error( 'invalid input arguments. Arguments must sum to a number greater than or equal to 10.' );
	}
	return sum;
}

var f = wrap( fcn );

var out = f( 5, 6, 7, 8 );
// returns 26

out = f( 1, 2, 3, 1 );
// returns <Error>
```

If provided an asynchronous `function`, the returned `function` only traps `errors` which occur during the current event loop tick.

``` javascript
function fcn( a, b, clbk ) {
	if ( !a ) {
		throw new Error( 'invalid input argument.' );
	}
	process.nextTick( onTick );
	function onTick() {
		if ( !b ) {
			throw new Error( 'invalid input argument.' );
		}
		clbk();
	}
}

function done() {
	console.log( 'beep' );
}

var f = wrap( fcn );

var out = f( null, 5, done );
// returns <Error>

out = f( true, null, done );
// returns undefined
```


## Notes

*	Isolating `try/catch` blocks in separate `functions` prevents a parent scope from entering optimization hell.


## Examples

``` javascript
var isString = require( 'validate.io-string-primitive' ),
	wrap = require( 'utils-try-function' );

function beep( str ) {
	if ( !isString( str ) ) {
		throw new TypeError( 'invalid input argument. Must provide a string primitive. Value: `' + str + '`.' );
	}
	return 'beep' + str;
}

function boop( str, clbk ) {
	if ( !isString( str ) ) {<commit_msg>Updates README copy re optimization<commit_after>Try Function
===
[![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coverage Status][codecov-image]][codecov-url] [![Dependencies][dependencies-image]][dependencies-url]

> Wraps a function in a try/catch block.


## Installation

``` bash
$ npm install utils-try-function
```


## Usage

``` javascript
var wrap = require( 'utils-try-function' );
```

#### wrap( fcn )

Wraps a `function` in a `try/catch` block.

``` javascript
function fcn() {
	throw new Error( 'beep boop' );
}

var f = wrap( fcn );

var out = f();
if ( out instanceof Error ) {
	console.error( out.message );
	// returns 'beep boop'
}
```

The returned `function` has the same signature as the wrapped `function`.

``` javascript
function fcn( a, b, c, d ) {
	var sum = a + b + c + d;
	if ( sum < 10 ) {
		throw new Error( 'invalid input arguments. Arguments must sum to a number greater than or equal to 10.' );
	}
	return sum;
}

var f = wrap( fcn );

var out = f( 5, 6, 7, 8 );
// returns 26

out = f( 1, 2, 3, 1 );
// returns <Error>
```

If provided an asynchronous `function`, the returned `function` only traps `errors` which occur during the current event loop tick.

``` javascript
function fcn( a, b, clbk ) {
	if ( !a ) {
		throw new Error( 'invalid input argument.' );
	}
	process.nextTick( onTick );
	function onTick() {
		if ( !b ) {
			throw new Error( 'invalid input argument.' );
		}
		clbk();
	}
}

function done() {
	console.log( 'beep' );
}

var f = wrap( fcn );

var out = f( null, 5, done );
// returns <Error>

out = f( true, null, done );
// returns undefined
```


## Notes

*	Isolating `try/catch` blocks as separate wrapped `functions` prevents a parent scope from permanently entering optimization hell.


## Examples

``` javascript
var isString = require( 'validate.io-string-primitive' ),
	wrap = require( 'utils-try-function' );

function beep( str ) {
	if ( !isString( str ) ) {
		throw new TypeError( 'invalid input argument. Must provide a string primitive. Value: `' + str + '`.' );
	}
	return 'beep' + str;
}

function boop( str, clbk ) {
	if ( !isString( str ) ) {
{'fraction_non_alphanumeric': 0.1611241217798595, 'fraction_numerical': 0.00702576112412178, 'mean_word_length': 3.5484558040468586, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7497856', 'n_tokens_mistral': 1575, 'n_tokens_neox': 1456, 'n_words': 506}