Some
A JavaScript library that adds some helper functions to strings and arrays for fun and profit. Built on top of my very cool reservoir library.
Installation
Node.js
For Node.js, use npm
:
npm install some
..then require
Some:
var Some = ;
In the browser, traditional
For the browser, add the following to your pages:
In the browser, using AMD (require.js)
...Or using AMD in the browser:
;
Usage
Some
is an object that contains two decorator functions: Array
and String
. The purpose of the decorator functions is to add some new methods to an existing Array
or String
.
Basic
We can use these functions to decorate a single string or array object:
var myString = Some; var myArray = Some;
Now, using those objects we can use some of the new functions:
// replace 3 occurances of the letter "i" followed by at least two letters// with the letter "a"var newString = myString; "A simple wash in the wind is like a bard on the dash." // Calculate the average value of 3 randomly chosen valuesvar average = myArray; 4333333333333333
Advanced Usage
If you want to use these decorations with all strings and arrays within your script they can be applied to the String.prototype
and Array.prototype
objects:
Some;Some;
Decorations
There are two decorators included within Some object:
[stringToDecorate]
)
Some.String(Returns
stringToDecorate
if provided otherwise a new empty String
with the following function added to it:
regexp|substr, numToReplace, newSubStr|function
)
String#replaceSome(Replaces numToReplace
number of regexp|substr
matches with newSubStr|function
.
Parameters
regexp
A RegExp object. The match is replaced by the return value of parameter #2.
substr
A String that is to be replaced by newSubStr.
numToReplace
A Number. Maximum number of replacements to make.
newSubStr
The String that replaces the substring received from parameter #1. A number of special replacement patterns are supported; see the "Specifying a string as a parameter" section below.
function
A function to be invoked to create the new substring (to put in place of the substring received from parameter #1). The arguments supplied to this function are described in the "Specifying a function as a parameter" section below.
Returns
The new String
that is the result of performing the requested number of replacements.
[arrayToDecorate]
)
Some.Array(Returns
arrayToDecorate
if provided otherwise a new empty Array
with the following functions added to it:
- Array#sliceSome
- Array#filterSome
- Array#forSome
- Array#everySome
- Array#someSome
- Array#reduceSome
- Array#reduceRightSome
- Array#mapSome
- Array#mapSomeSparse
numToReturn[, begin][, end]
)
Array#sliceSome(Returns a one-level deep copy of a portion of an array.
Parameters
numToReturn
Number of array elements to randomly select for the new Array
.
begin
Zero-based index at which to begin extraction. As a negative index, begin
indicates an offset from the end of the sequence. sliceSome(number, -2)
extracts up to numToReturn
elements starting from the second-to-last element in the sequence. If begin
is omitted, sliceSome
extracts from the beginning of the sequence.
end
Zero-based index at which to end extraction. sliceSome
extracts up to but not including end
. slice(number, 1, 4)
extracts up to numToReturn
elements starting from the second element through the fourth element (elements indexed 1, 2, and 3). As a negative index, end
indicates an offset from the end of the sequence. sliceSome(number, 2,-1)
extracts up to numToReturn
elements from the third element through the second-to-last element in the sequence. If end
is omitted, sliceSome
extracts to the end of the sequence.
Returns
A new Array
containing a random sample of numToReturn
elements from begin
to end
.
numToEvaluate, callback[, thisArg]
)
Array#filterSome(Creates a new array with all elements that pass the test implemented by the provided function.
Parameters
numToEvaluate
Number of array elements to randomly select for the callback
.
callback
Function to test each element of the array.
thisArg
Object to use as this
when executing callback
.
Returns
A new Array
containing the values returned from callback
.
numToEvaluate, callback[, thisArg]
)
Array#forSome(Executes a provided callback
once per chosen array element.
Parameters
numToEvaluate
Number of array elements to randomly select for the callback
.
callback
Function to execute for each element.
thisArg
Object to use as this
when executing callback
.
Returns
Nothing.
numToEvaluate, callback[, thisArg]
)
Array#everySome(Tests whether the chosen elements in the array pass the test implemented by the provided function.
Parameters
numToEvaluate
Number of array elements to randomly select for the callback
.
callback
Function to test for each element.
thisArg
Object to use as this
when executing callback
.
Returns
A boolean. True if all chosen elements of the array passed the test in callback
. Otherwise, false.
numToEvaluate, callback[, thisArg]
)
Array#someSome(Tests whether some element in the array passes the test implemented by the provided function.
Parameters
numToEvaluate
Number of array elements to randomly select for the callback
.
callback
Function to test for each element.
thisArg
Object to use as this
when executing callback
.
Returns
A boolean. True if any of the chosen elements of the array passed the test in callback
. Otherwise, false.
numToEvaluate, callback[, initialValue]
)
Array#reduceSome(Apply a function against an accumulator and each value of the array (from left-to-right) as to reduce it to a single value.
Parameters
callback
Function to execute on each value in the array, taking four arguments:
previousValue
The value previously returned in the last invocation of the callback, or initialValue, if supplied. (See below.)
currentValue
The current element being processed in the array.
index
The index of the current element being processed in the array.
array
The array reduce was called upon.
initialValue
Object to use as the first argument to the first call of the callback.
numToEvaluate, callback[, initialValue]
)
Array#reduceRightSome(Apply a function against an accumulator and each value of the array (from right-to-left) as to reduce it to a single value.
Parameters
callback
Function to execute on each value in the array, taking four arguments:
previousValue
The value previously returned in the last invocation of the callback, or initialValue, if supplied. (See below.)
currentValue
The current element being processed in the array.
index
The index of the current element being processed in the array.
array
The array reduce was called upon.
initialValue
Object to use as the first argument to the first call of the callback.
numToEvaluate, callback[, thisArg]
)
Array#mapSome(Creates a new array with the results of calling a provided function on every element in this array.
Parameters
numToEvaluate
Number of array elements to randomly select for the callback
.
callback
Function that produces an element of the new Array from an element of the current one.
thisArg
Object to use as this
when executing callback
.
Returns
A new Array
containing the values returned from callback
.
numToEvaluate, callback[, thisArg]
)
Array#mapSomeSparse(Creates a new array with the results of calling a provided function on every element in this array.
Note The returned array will have the same length as the original array. All elements except for the chosen subset of elements returned will be undefined.
Parameters
numToEvaluate
Number of array elements to randomly select for the callback
.
callback
Function that produces an element of the new Array from an element of the current one.
thisArg
Object to use as this
when executing callback
.
Returns
A new Array
containing the values returned from callback
.