# Helpers

// usage
{{capitalize(string)}}

Capitalize the first letter of a word

{{capitalize('bread')}}
=> 'Bread'

// usage
{{mixin(<Object>)}}

Mixins are a very powerful way to extend Chance to fit the needs of your specific application.

First, if you are thinking of using a mixin for Chance, please consider first whether your use is something from which others may benefit. If so, please submit a pull request rather than using a mixin!

Spread the love and give everyone the benefit of your awesome generator :)

Now, that said, there are bound to be times when you want to generate something random that is specific to your application but not widely applicable. Enter mixins!

Chance mixins allow you to add one-off methods to Chance which you can use later.

For example, let's say I have a user object which consists of first, last, and email.

var user = {
first: 'John',
last: 'Smith',
email: '[email protected]'
};

Let's say I want to be able to randomly generate these user objects.

This is not the type of thing which would be widely applicable as it's specific to my application so it's perfect for a mixin!

To create a mixin, build an object whose keys are the names of the methods, and whose values are the functions to be called.

Note: Within each function, you will have access to chance itself!

For example, to create a user mixin:

chance.mixin({
'user': function() {
return {
first: {{first()}},
last: {{last()}},
email: {{email()}}
};
}
});

// Then you can call your mixin
{{user()}};

=> {first: 'Eli', last: 'Benson', email: '[email protected]'}

Mixins can even include other mixins!

For example, to "extend" the user object:

chance.mixin({
'user': function () {
return {
first: {{first()}},
last: {{last()}},
email: {{email()}}
};
},
'social_user': function () {
var user = {{user()}};
user.network = {{pick(['facebook', 'twitter'])}};
return user;
}
});

So we have a second mixin here, social_user which is using the user mixin and adding to it! Note, these mixins can be defined in any order on the object if both declared at once.

// usage
{{pad(number, width)}}
{{pad(number, width, padder)}}

Pad a number with some string until it reaches a desired width.

By default, {{pad()}} will pad with zeroes. For example, to zero-pad numbers such that the outcome width is 5, do the following.

{{pad(45, 5)}}
=> '00045'

{{pad(284, 5)}}
=> '00284'

{{pad(82843, 5)}}
=> '82843'

Notice how every item returned is a string with leading zeroes until the width is 5 for each one.

Can optionally specify a character if the desire is to pad with something other than zero.

{{pad(81, 5, 'Z')}}
=> 'ZZZ81'

{{pad(692, 5, 'Z')}}
=> 'ZZ692'

{{pad(52859, 5)}}
=> '52859'

// usage
{{pick(array)}}
{{pick(array, count)}}

pick() is now deprecated in favor of pickone() and pickset()

// usage
{{pickone(array)}}

Given an array, pick a random element and return it

{{pickone(['alpha', 'bravo', 'charlie', 'delta', 'echo'])}};
=> 'delta'

// usage
{{pickset(array, quantity)}}

Given an array, pick some random elements and return them in a new array

{{pickset(['alpha', 'bravo', 'charlie', 'delta', 'echo'], 3)}};
=> ['echo', 'alpha', 'bravo']

Optionally omit the quantity to retrieve a set with length 1

{{pickset(['alpha', 'bravo', 'charlie', 'delta', 'echo'])}};
=> ['delta']

// usage
{{set(key, value)}}

Used for overriding the default data used by Chance.

For example, if instead of the default set of last names (which were pulled from the U.S. census data and therefore obviously American biased), you could replace the data for the first names with something more suited to your task. For example, if you want instead to pick from last names of houses in A Song of Ice and Fire, you could do something like:

{{set('lastNames', ['Arryn', 'Baratheon', 'Bolton', 'Frey', 'Greyjoy', 'Lannister', 'Martell', 'Stark', 'Targaryen', 'Tully', 'Tyrell'])}};

// then
{{last()}}
=> 'Lannister'

This is very handy for internationalization.

Available keys for datasets to override: firstNames, lastNames, provinces, us_states_and_dc, territories, armed_forces, street_suffixes, months, cc_types, currency_types

// usage
{{shuffle(array)}}

Given an array, scramble the order and return it.

{{shuffle(['alpha', 'bravo', 'charlie', 'delta', 'echo'])}};
=> ['echo', 'delta', 'alpha', 'charlie', 'bravo']