See Getting Started for installation, inclusion, and initializiation.
By default the following attributes are as follows:
A.throwExceptions := true
Wherever typeif errors can be detected, biga.ahk will throw an exception pointing out the location the error occurred. Set this to false
if you would like your script to continue without being stopped by exceptions.
A.limit := -1
Determines the number of times strings will be replaced when using .replace with a string argument. Set this to 1
to get closer to a javascript experience.
Creates an array of elements split into groups the length of size
. If array can't be split evenly, the final chunk will be the remaining elements.
array (Array): The array to process.
[size:=1] (number): The length of each chunk
(Array): Returns the new array of chunks.
A.chunk(["a", "b", "c", "d"], 2)
; => [["a", "b"], ["c", "d"]]
A.chunk(["a", "b", "c", "d"], 3)
; => [["a", "b", "c"], ["d"]]
Creates an array with all falsey values removed. The values false
, 0
, and ""
are falsey.
array (Array): The array to compact.
(Array): Returns the new array of filtered values.
A.compact([0, 1, false, 2, "", 3])
; => [1, 2, 3]
Creates a new array concatenating array
with any additional arrays and/or values.
array (Array): The array to concatenate.
[values] (...*): The values to concatenate.
(Array): Returns the new concatenated array.
array := [1]
A.concat(array, 2, [3], [[4]])
; => [1, 2, 3, [4]]
A.concat(array)
; => [1]
This method is explores array
and returns the maximum depth.
array (Array): The array to inspect.
(number): Returns the maximum depth.
A.depthOf([1])
; => 1
A.depthOf([1, [2]])
; => 2
A.depthOf([1, [[2]]])
; => 3
A.depthOf([1, [2, [3, [4]], 5]])
; => 4
Creates an array of array
values not included in the other given arrays. The order of result values are determined by the first array.
array (Array): The array to inspect.
values (...Array): The values to exclude.
(Array): Returns the new array of filtered values.
A.difference([2, 1], [2, 3])
; => [1]
Creates a slice of array
with n
elements dropped from the beginning.
array (Array): The array to query.
[n:=1] (number): The number of elements to drop.
(Array): Returns the slice of array.
A.drop([1, 2, 3])
; => [2, 3]
A.drop([1, 2, 3], 2)
; => [3]
A.drop([1, 2, 3], 5)
; => []
A.drop([1, 2, 3], 0)
; => [1, 2, 3]
A.drop("fred")
; => ["r", "e", "d"]
A.drop(100)
; => ["0", "0"]
Creates a slice of array
with n
elements dropped from the end.
array (Array): The array to query.
[n:=1] (number): The number of elements to drop.
(Array): Returns the slice of array.
A.dropRight([1, 2, 3])
; => [1, 2]
A.dropRight([1, 2, 3], 2)
; => [1]
A.dropRight([1, 2, 3], 5)
; => []
A.dropRight([1, 2, 3], 0)
; => [1, 2, 3]
A.dropRight("fred")
; => ["f", "r", "e"]
A.dropRight(100)
; => ["1", "0"]
Creates a slice of array
excluding elements dropped from the end. Elements are dropped until predicate
returns falsey. The predicate is invoked with three arguments: (value, index, array).
array (Array): The array to query.
[predicate:=.identity] (Function): The function invoked per iteration.
(Array): Returns the slice of array.
users := [ {"user": "barney", "active": true}
, {"user": "fred", "active": false}
, {"user": "pebbles", "active": false} ]
A.dropRightWhile(users, func("fn_dropRightWhile"))
; => [{"user": "barney", "active": true }]
fn_dropRightWhile(o)
{
return !o.active
}
; The A.matches iteratee shorthand.
A.dropRightWhile(users, {"user": "pebbles", "active": false})
; => [ {"user": "barney", "active": true }, {"user": "fred", "active": false} ]
; The A.matchesProperty iteratee shorthand.
A.dropRightWhile(users, ["active", false])
; => [ {"user": "barney", "active": true } ]
; The A.property iteratee shorthand.
A.dropRightWhile(users, "active")
; => [ {"user": "barney", "active": true }, {"user": "fred", "active": false }, {"user": "pebbles", "active": false} ]
Creates a slice of array
excluding elements dropped from the beginning. Elements are dropped until predicate
returns falsey. The predicate is invoked with three arguments: (value, index, array).
array (Array): The array to query.
[predicate:=.identity] (Function): The function invoked per iteration.
(Array): Returns the slice of array.
users := [ {"user": "barney", "active": false }
, { "user": "fred", "active": false }
, { "user": "pebbles", "active": true } ]
A.dropWhile(users, func("fn_dropWhile"))
; => [{ "user": "pebbles", "active": true }]
fn_dropWhile(o)
{
return !o.active
}
; The A.matches iteratee shorthand.
A.dropWhile(users, {"user": "barney", "active": false})
; => [ { "user": "fred", "active": false }, { "user": "pebbles", "active": true } ]
; The A.matchesProperty iteratee shorthand.
A.dropWhile(users, ["active", false])
; => [ {"user": "pebbles", "active": true } ]
; The A.property iteratee shorthand.
A.dropWhile(users, "active")
; => [ {"user": "barney", "active": false }, { "user": "fred", "active": false }, { "user": "pebbles", "active": true } ]
Fills elements of array
with value from start
up to, but not including, end
.
Note
Unlike it's Lodash counterpart, this method does NOT mutate the array.
array (Array): The array to fill.
value (*): The value to fill array with.
[start:=1] (number): The start position.
[end:=array.length] (number): The end position.
(Array): Returns array.
array := [1, 2, 3]
A.fill(array, "a")
; => ["a", "a", "a"]
A.fill([4, 6, 8, 10], "*", 2, 3)
; => [4, "*", "*", 10]
This method is like A.find except that it returns the index of the first element predicate
returns truthy for instead of the element itself.
array (Array): The array to inspect.
[predicate:=.identity] (Function): The function invoked per iteration.
[fromIndex:=1] (number): The index to search from.
(number): Returns the index of the found element, else -1.
users := [ { "user": "barney", "age": 36, "active": true }
, { "user": "fred", "age": 40, "active": false }
, { "user": "pebbles", "age": 1, "active": true } ]
; The A.matches iteratee shorthand.
A.findIndex(users, { "age": 1, "active": true })
; => 3
; The A.matchesProperty iteratee shorthand.
A.findIndex(users, ["active", false])
; => 2
; The A.property iteratee shorthand.
A.findIndex(users, "active")
; => 1
This method is like A.findIndex except that it iterates over elements of collection from right to left.
array (Array): The array to inspect.
[predicate:=.identity] (Function): The function invoked per iteration.
[fromIndex:=array.count()] (number): The index to search from.
(key): Returns the key of the found element, else -1.
users := [{"user": "barney", "active": true}
, {"user": "fred", "active": false}
, {"user": "pebbles", "active": false}]
A.findLastIndex(users, {"user": "barney", "active": true})
; => 1
A.findLastIndex(users, ["active", true])
; => 1
A.findLastIndex(users, "active")
; => 1
Flattens array
a single level deep.
array (Array): The array to flatten.
(Array): Returns the new flattened array.
A.flatten([1, [2, [3, [4]], 5]])
; => [1, 2, [3, [4]], 5]
A.flatten([[1, 2, 3], [4, 5, 6]])
; => [1, 2, 3, 4, 5, 6]
Recursively flattens array
.
array (Array): The array to flatten.
(Array): Returns the new flattened array.
A.flattenDeep([1])
; => [1]
A.flattenDeep([1, [2]])
; => [1, 2]
A.flattenDeep([1, [2, [3, [4]], 5]])
; => [1, 2, 3, 4, 5]
Recursively flatten array
up to depth times.
array (Array): The array to flatten.
[depth:=1] (number): The maximum recursion depth.
(Array): Returns the new flattened array.
A.flattenDepth([1, [2, [3, [4]], 5]], 1)
; => [1, 2, [3, [4]], 5]
A.flattenDepth([1, [2, [3, [4]], 5]], 2)
; => [1, 2, 3, [4], 5]
The inverse of A.toPairs; this method returns an object composed from key-value pairs.
pairs (Array): The key-value pairs.
(Object): Returns the new object.
A.fromPairs([["a", 1], ["b", 2]])
; => {"a": 1, "b": 2}
Gets the first element of array
.
.first
array (Array): The array to query.
(*): Returns the first element of array.
A.head([1, 2, 3])
; => 1
A.head([])
; => ""
A.head("fred")
; => "f"
A.head(100)
; => "1"
Gets the index at which the first occurrence of value
is found in array
. If fromIndex
is negative, it's used as the offset from the end of array
.
array (Array): The array to inspect.
value (*): The value to search for.
[fromIndex:=1] (number): The index to search from.
(number): Returns the index of the matched value, else -1.
A.indexOf([1, 2, 1, 2], 2)
; => 2
; Search from the `fromIndex`.
A.indexOf([1, 2, 1, 2], 2, 3)
; => 4
A.indexOf(["fred", "barney"], "pebbles")
; => -1
StringCaseSense, On
A.indexOf(["fred", "barney"], "Fred")
; => -1
Gets all but the last element of array
.
array (Array): The array to query.
(Array): Returns the slice of array.
A.initial([1, 2, 3])
; => [1, 2]
A.initial("fred")
; => ["f", "r", "e"]
A.initial(100)
; => ["1", "0"]
Creates an array of unique values that are included in all given arrays. The order of result values are determined by the first array.
[arrays*] (...Array): The arrays to inspect.
(Array): Returns the new array of intersecting values.
A.intersection([2, 1], [2, 3])
; => [2]
Converts all elements in array
into a string separated by separator
.
array (Array): The array to convert.
[separator:=","] (string): The element separator.
(string): Returns the joined string.
A.join(["a", "b", "c"], "~")
; => "a~b~c"
A.join(["a", "b", "c"])
; => "a,b,c"
Gets the last element of array
.
array (Array): The array to query.
(*): Returns the last element of array.
A.last([1, 2, 3])
; => 3
A.last([])
; => ""
<a href='https://github.com/biga-ahk/biga.ahk/blob/master/src/array/lastIndexOf.ahk' class='text-muted'>source</a>
This method is like [A.indexOf](/?id=indexof) except that it iterates over elements of `array` from right to left.
#### Arguments
array (Array): The array to inspect.
value (*): The value to search for.
[fromIndex:=array.count()] (number): The index to search from.
#### Returns
(number): Returns the index of the matched value, else -1.
#### Example
```autohotkey
A.lastIndexOf([1, 2, 1, 2], 2)
; => 4
; Search from the `fromIndex`.
A.lastIndexOf([1, 2, 1, 2], 1, 2)
; => 1
StringCaseSense, On
A.lastIndexOf(["fred", "barney"], "Fred")
; => -1
Gets the element at index n
of array
. If n
is negative, the nth element from the end is returned.
array (Array): The array to query.
[n:=1] (number): The index of the element to return.
(*): Returns the nth element of array.
A.nth([1, 2, 3])
; => 1
A.nth([1, 2, 3], -3)
; => 1
A.nth([1, 2, 3], 5)
; => ""
A.nth("fred")
; => "f"
A.nth(100)
; => "1"
A.nth([1, 2, 3], 0)
; => 1
Reverses array
so that the first element becomes the last, the second element becomes the second to last, and so on.
array (Array): The array to modify.
(Array): Returns array.
A.reverse(["a", "b", "c"])
; => ["c", "b", "a"]
A.reverse([{"foo": "bar"}, "b", "c"])
; => ["c", "b", {"foo": "bar"}]
A.reverse([[1, 2, 3], "b", "c"])
; => ["c", "b", [1, 2, 3]]
Creates a slice of array
from start
up to, but not including, end
.
array (Array): The array to slice.
[start:=1] (number): The start position.
[end:=array.count()] (number): The end position.
(Array): Returns the slice of array.
A.slice([1, 2, 3], 1, 2)
; => [1, 2]
A.slice([1, 2, 3], 1)
; => [1, 2, 3]
A.slice([1, 2, 3], 5)
; => []
A.slice("fred")
; => ["f", "r", "e", "d"]
A.slice(100)
; => ["1", "0", "0"]
Uses a binary search to determine the lowest index at which value should be inserted into array
in order to maintain its sort order.
array (Array): The sorted array to inspect.
value (*): The value to evaluate.
(number): Returns the index at which value should be inserted into array.
A.sortedIndex([30, 50], 40)
; => 2
This method is like A.indexOf except that it performs a binary search on a sorted array
.
array (Array): The sorted array to inspect.
value (*): The value to search for.
(number): Returns the index of the matched value, else -1
.
A.sortedIndexOf([4, 5, 5, 6], 5)
; => 2
This method is like A.uniq except that it's optimized for sorted arrays.
array (Array): The sorted array to inspect.
(array): Returns the new duplicate free array.
A.sortedUniq([1, 1, 2])
; => [1, 2]
Gets all but the first element of array
.
array (Array): The array to query.
(Array): Returns the slice of array.
A.tail([1, 2, 3])
; => [2, 3]
A.tail("fred")
; => ["r", "e", "d"]
A.tail(100)
; => ["0", "0"]
Creates a slice of array
with n
elements taken from the beginning.
array (Array): The array to query.
[n:=1] (number): The number of elements to take.
(Array): Returns the slice of array.
A.take([1, 2, 3])
; => [1]
A.take([1, 2, 3], 2)
; => [1, 2]
A.take([1, 2, 3], 5)
; => [1, 2, 3]
A.take([1, 2, 3], 0)
; => []
A.take("fred")
; => ["f"]
A.take(100)
; => ["1"]
Creates a slice of array
with n
elements taken from the end.
array (Array): The array to query.
[n:=1] (number): The number of elements to take.
(Array): Returns the slice of array.
A.takeRight([1, 2, 3])
; => [3]
A.takeRight([1, 2, 3], 2)
; => [2, 3]
A.takeRight([1, 2, 3], 5)
; => [1, 2, 3]
A.takeRight([1, 2, 3], 0)
; => []
A.takeRight("fred")
; => ["d"]
A.takeRight(100)
; => ["0"]
Creates an array of unique values, in order, from all given arrays.
[arrays] (...Array): The arrays to inspect.
(Array): Returns the new array of combined values.
A.union([2], [1, 2])
; => [2, 1]
Creates a duplicate-free version of an array
, in which only the first occurrence of each element is kept. The order of result values is determined by the order they occur in the array.
array (Array): The array to inspect.
(Array): Returns the new duplicate free array.
A.uniq([2, 1, 2])
; => [2, 1]
This method is like A.zip except that it accepts an array of grouped elements and creates an array regrouping the elements to their pre-zip configuration.
array (Array): The array of grouped elements to process.
(Array): Returns the new array of regrouped elements.
zipped := A.zip(["a", "b"], [1, 2], [true, false])
; => [["a", 1, true], ["b", 2, true]]
A.unzip(zipped)
; => [["a", "b"], [1, 2], [true, false]]
Creates an array excluding all given values.
array (Array): The array to inspect.
[values] (...*): The values to exclude.
(Array): Returns the new array of filtered values.
A.without([2, 1, 2, 3], 1, 2)
; => [3]
Creates an array of grouped elements, the first of which contains the first elements of the given arrays, the second of which contains the second elements of the given arrays, and so on.
[arrays*] (...Array): The arrays to process.
(Array): Returns the new array of grouped elements.
A.zip(["a", "b"], [1, 2], [true, true])
; => [["a", 1, true], ["b", 2, true]]
This method is like A.fromPairs except that it accepts two arrays, one of property identifiers and one of corresponding values.
[props:=[]] (Array): The property identifiers.
[values:=[]] (Array): The property values.
(Object): Returns the new object.
A.zipObject(["a", "b"], [1, 2])
; => {"a": 1, "b": 2}
Gets the number of occurrences of value
if found in collection
, else 0
collection (Array|Object|string): The collection to inspect.
value (*): The value to count
[fromIndex:=1] (number): The index to search from
(number): Returns the number of occurances.
A.count([1, 2, 3], 2)
; => 1
A.count("pebbles", "b")
; => 2
A.count(["fred", "barney", "pebbles"], "barney")
; => 1
users := [ {"user": "fred", "age": 40, "active": true}
, {"user": "barney", "age": 36, "active": false}
, {"user": "pebbles", "age": 1, "active": false} ]
; The A.matches iteratee shorthand.
A.count(users, {"age": 1, "active": false})
; => 1
; The A.matchesProperty iteratee shorthand.
A.count(users, ["active", false])
; => 2
; The A.property iteratee shorthand.
A.count(users, "active")
; => 1
Creates an object composed of keys generated from the results of running each element of collection
thru iteratee
. The corresponding value of each key is the number of times the key was returned by iteratee
. The iteratee is invoked with one argument: (value).
object (Array|Object): The collection to iterate over.
[iteratee:=.identity] (Function): The iteratee to transform keys.
(Object): Returns the composed aggregate object.
A.countBy([6.1, 4.2, 6.3], func("floor"))
; => {"4": 1, "6": 2}
; The A.property iteratee shorthand.
A.countBy(["one", "two", "three"], A.size)
; => {"3": 2, "5": 1}
Checks if predicate
returns truthy for all elements of collection
. Iteration is stopped once predicate
returns falsey. The predicate is invoked with three arguments: (value, index|key, collection).
Note
This method returns true for empty collections because everything is true of elements of empty collections.
collection (Array|Object): The collection to iterate over.
[predicate:=.identity] (Function): The function invoked per iteration.
(boolean): Returns true if all elements pass the predicate check, else false.
A.every([true, 1, false, "yes"], A.isBoolean)
; => false
users := [{ "user": "barney", "age": 36, "active": false }
, { "user": "fred", "age": 40, "active": false }]
; The A.matches iteratee shorthand.
A.every(users, {"user": "barney", "age": 36, "active": false})
; => false
; The A.matchesProperty iteratee shorthand.
A.every(users, ["active", false])
; => true
; The A.property iteratee shorthand.
A.every(users, "active")
; => false
Iterates over elements of collection
, returning an array of all elements predicate
returns truthy for. The predicate is invoked with three arguments: (value, index|key, collection).
collection (Array|Object): The collection to iterate over.
[predicate:=.identity] (Function): The function invoked per iteration.
(Array): Returns the new filtered array.
users := [{"user":"barney", "age":36, "active":true}, {"user":"fred", "age":40, "active":false}]
A.filter(users, func("fn_filterFunc"))
; => [{"user":"barney", "age":36, "active":true}]
fn_filterFunc(param_iteratee)
{
if (param_iteratee.active) {
return true
}
}
; The A.matches shorthand
A.filter(users, {"age":36, "active":true})
; => [{"user":"barney", "age":36, "active":true}]
; The A.matchesProperty shorthand
A.filter(users, ["active", false])
; => [{"user":"fred", "age":40, "active":false}]
; The A.property shorthand
A.filter(users, "active")
; => [{"user":"barney", "age":36, "active":true}]
Iterates over elements of collection
, returning the first element predicate
returns truthy for.
collection (Array|Object): The collection to inspect.
[predicate:=.identity] (Function): The function invoked per iteration.
[fromIndex:=1] (number): The index to search from.
(*): Returns the matched element, else false.
users := [ {"user": "barney", "age": 36, "active": true}
, {"user": "fred", "age": 40, "active": false}
, {"user": "pebbles", "age": 1, "active": true} ]
A.find(users, func("fn_findFunc"))
; => { "user": "barney", "age": 36, "active": true }
fn_findFunc(o)
{
return o.active
}
; The A.matches iteratee shorthand.
A.find(users, { "age": 1, "active": true })
; => { "user": "pebbles", "age": 1, "active": true }
; The A.matchesProperty iteratee shorthand.
A.find(users, ["active", false])
; => { "user": "fred", "age": 40, "active": false }
; The A.property iteratee shorthand.
A.find(users, "active")
; => { "user": "barney", "age": 36, "active": true }
This method is like A.find except that it iterates over elements of collection
from right to left.
collection (Array|Object): The collection to inspect.
function (Function): The function invoked per iteration.
(*): Returns the matched element, else false.
A.findLast([1, 2, 3, 4], func("fn_findLastFunc"))
; => 3
fn_findLastFunc(n)
{
return mod(n, 2) == 1
}
Iterates over elements of collection
and invokes iteratee
for each element. The iteratee is invoked with three arguments: (value, index|key, collection). Iteratee functions may exit iteration early by explicitly returning false.
.each
collection (Array|Object): The collection to iterate over.
[iteratee:=.identity] (Function): The function invoked per iteration.
(*): Returns collection.
A.forEach([1, 2], func("fn_forEachFunc1"))
fn_forEachFunc1(value)
{
msgbox, % value
}
; msgboxes 1 then 2
A.forEach({ "a": 1, "b": 2 }, func("fn_forEachFunc2"))
fn_forEachFunc2(value, key)
{
msgbox, % key
}
; msgboxes "a" then "b"
This method is like A.forEach except that it iterates over elements of collection
from right to left.
.eachRight
collection (Array|Object): The collection to iterate over.
[iteratee:=.identity] (Function): The function invoked per iteration.
(*): Returns collection.
A.forEach([1, 2], func("fn_forEachFunc1"))
fn_forEachFunc1(value)
{
msgbox, % value
}
; msgboxes 2 then 1
A.forEach({ "a": 1, "b": s2 }, func("fn_forEachFunc2"))
fn_forEachFunc2(value, key)
{
msgbox, % key
}
; msgboxes "b" then "a"
Creates an object composed of keys generated from the results of running each element of collection
thru iteratee
. The order of grouped values is determined by the order they occur in collection
. The corresponding value of each key is an array of elements responsible for generating the key. The iteratee is invoked with one argument: (value).
collection (Array|Object): The collection to iterate over.
[iteratee:=.identity] (Function): The iteratee to transform keys.
(Object): Returns the composed aggregate object.
A.groupBy([6.1, 4.2, 6.3], A.floor)
; => {4: [4.2], 6: [6.1, 6.3]}
A.groupBy(["one", "two", "three"], A.size)
; => {3: ["one", "two"], 5: ["three"]}
A.groupBy([6.1, 4.2, 6.3], func("ceil"))
; => {5: [4.2], 7: [6.1, 6.3]}
Checks if value
is in collection
. If collection
is a string, it's checked for a substring of value.
collection (Array|Object|string): The collection to inspect.
value (*): The value to search for.
[fromIndex:=1] (number): The index to search from.
(boolean): Returns true if value is found, else false.
A.includes([1, 2, 3], 1)
; => true
A.includes({ "a": 1, "b": 2 }, 1)
; => true
A.includes("inStr", "Str")
; => true
StringCaseSense, On
A.includes("inStr", "str")
; => false
; RegEx object
A.includes("hello!", "/\D/")
; => true
Creates an object composed of keys generated from the results of running each element of collection
thru iteratee
. The corresponding value of each key is the last element responsible for generating the key. The iteratee is invoked with one argument: (value).
collection (Array|Object): The collection to iterate over.
[iteratee:=.identity] (Function): The iteratee to transform keys.
(Object): Returns the composed aggregate object.
array := [ {"dir": "left", "code": 97}
, {"dir": "right", "code": 100}]
A.keyBy(array, func("fn_keyByFunc"))
; => {"left": {"dir": "left", "code": 97}, "right": {"dir": "right", "code": 100}}
fn_keyByFunc(value)
{
return value.dir
}
; The A.property iteratee shorthand.
A.keyBy(array, "dir")
; => {"left": {"dir": "left", "code": 97}, "right": {"dir": "right", "code": 100}}
Creates an array of values by running each element in collection
thru iteratee
. The iteratee is invoked with three arguments: (value, index|key, collection).
collection (Array|Object): The collection to iterate over.
[iteratee:=.identity] (Function): The function invoked per iteration.
(Array): Returns the new mapped array.
fn_square(n)
{
return n * n
}
A.map([4, 8], func("fn_square"))
; => [16, 64]
A.map({ "a": 4, "b": 8 }, func("fn_square"))
; => [16, 64]
A.map({ "a": 4, "b": 8 })
; => [4, 8]
; The A.property shorthand
users := [{ "user": "barney" }, { "user": "fred" }]
A.map(users, "user")
; => ["barney", "fred"]
Creates an array of elements split into two groups, the first of which contains elements predicate
returns truthy for, the second of which contains elements predicate
returns falsey for. The predicate is invoked with one argument: (value).
collection (Array|Object): The collection to iterate over.
[predicate:=.identity] (Function): The function invoked per iteration.
(Array): Returns the array of grouped elements.
users := [ { "user": "barney", "age": 36, "active": false }
, { "user": "fred", "age": 40, "active": true }
, { "user": "pebbles", "age": 1, "active": false } ]
A.partition(users, func("fn_partitionFunc"))
; => [[{ "user": "fred", "age": 40, "active": true }], [{ "user": "barney", "age": 36, "active": false }, { "user": "pebbles", "age": 1, "active": false }]]
fn_partitionFunc(o)
{
return o.active
}
; The A.matches iteratee shorthand.
A.partition(users, {"age": 1, "active": false})
; => [[{ "user": "pebbles", "age": 1, "active": false }], [{ "user": "barney", "age": 36, "active": false }, { "user": "fred", "age": 40, "active": true }]]
; The A.propertyMatches iteratee shorthand.
A.partition(users, ["active", false])
; => [[{ "user": "barney", "age": 36, "active": false }, { "user": "pebbles", "age": 1, "active": false }] ,[{ "user": "fred", "age": 40, "active": true }]]
; The A.property iteratee shorthand.
A.partition(users, "active")
; => [[{ "user": "fred", "age": 40, "active": true }], [{ "user": "barney", "age": 36, "active": false }, { "user": "pebbles", "age": 1, "active": false }]]
The opposite of A.filter this method returns the elements of collection
that predicate
does not return truthy for.
collection (Array|Object): The collection to iterate over.
[predicate:=.identity] (Function): The function invoked per iteration.
(Array): Returns the new filtered array.
users := [{"user":"barney", "age":36, "active":false}, {"user":"fred", "age":40, "active":true}]
A.reject(users, func("fn_rejectFunc"))
; => [{"user":"fred", "age":40, "active":true}]
fn_rejectFunc(o)
{
return !o.active
}
; The A.matches shorthand
A.reject(users, {"age":40, "active":true})
; => [{"user":"barney", "age":36, "active":false}]
; The A.matchesProperty shorthand
A.reject(users, ["active", false])
; => [{"user":"fred", "age":40, "active":true}]
; The A.property shorthand
A.reject(users, "active")
; => [{"user":"barney", "age":36, "active":false}]
Gets a single random element from collection
.
collection (Array|Object|String): The collection to sample.
(*): Returns the random element.
A.sample([1, 2, 3, 4])
; => 2
Gets n
random elements at unique keys from collection
up to the size of collection
.
collection (Array|Object|String): The collection to sample.
[n:=1] (number): The number of elements to sample.
(Array): Returns the random elements.
A.sampleSize([1, 2, 3], 2)
; => [3, 1]
A.sampleSize([1, 2, 3], 4)
; => [2, 3, 1]
Creates an array of shuffled values, using a version of the Fisher-Yates shuffle.
collection (Array|Object): The collection to shuffle.
(Array): Returns the new shuffled array.
A.shuffle([1, 2, 3, 4])
; => [4, 1, 3, 2]
A.shuffle(["barney", "fred", "pebbles"])
; => ["pebbles", "barney", "fred"]
Gets the size of collection
by returning its length for array-like values or the number of own enumerable string keyed properties for objects.
collection (Array|Object|string): The collection to inspect.
(number): Returns the collection size.
A.size([1, 2, 3])
; => 3
A.size({ "a": 1, "b": 2 })
; => 2
A.size("pebbles")
; => 7
Checks if predicate
returns truthy for any element of collection
. Iteration is stopped once predicate
returns truthy. The predicate is invoked with three arguments: (value, index|key, collection).
collection (Array|Object): The collection to iterate over.
[iteratees:=.identity] (Function): The function invoked per iteration.
(Array): Returns true if any element passes the predicate check, else false.
users := [{ "user": "barney", "active": true }, { "user": "fred", "active": false }]
; The A.matches iteratee shorthand.
A.some(users, { "user": "barney", "active": false })
; => false
; The A.matchesProperty iteratee shorthand.
A.some(users, ["active", false])
; => true
; The A.property iteratee shorthand.
A.some(users, "active")
; => true
Creates an array of elements, sorted in ascending order by the results of running each element in a collection thru each iteratee. This method performs a stable sort, that is, it preserves the original sort order of equal elements. The iteratees are invoked with one argument: (value).
collection (Array|Object): The collection to iterate over.
[iteratees:=.identity] (Function): The iteratees to sort by.
(Array): Returns the new sorted array.
A.sortBy(["b", "f", "e", "c", "d", "a"])
; => ["a", "b", "c", "d", "e", "f"]
users := [{ "name": "fred", "age": 40 }
, { "name": "barney", "age": 34 }
, { "name": "bernard", "age": 36 }
, { "name": "zoey", "age": 40 }]
A.sortBy(users, "age")
; => [{"age":34, "name":"barney"}, {"age":36, "name":"bernard"}, {"age":40, "name":"zoey"}, {"age":40, "name":"fred"}]
A.sortBy(users, ["age", "name"])
; => [{"age":34, "name":"barney"}, {"age":36, "name":"bernard"}, {"age":40, "name":"fred"}, {"age":40, "name":"zoey"}]
A.sortBy(users, func("fn_sortByFunc"))
; => [{"age":34, "name":"barney"}, {"age":36, "name":"bernard"}, {"age":40, "name":"fred"}, {"age":40, "name":"zoey"}]
fn_sortByFunc(o)
{
return o.name
}
; sort using result of another method
A.sortBy(["ab", "a", " abc", "abc"], A.size)
; => ["a", "ab", "abc", " abc"]
Gets the timestamp of the number of milliseconds that have elapsed since the Unix epoch (1 January 1970 00:00:00 UTC).
Note
The returned timestamp is only accurate to the second.
(number): Returns the timestamp.
A.now()
; => 1636159584000
Creates a function that invokes func
, with up to n
arguments, ignoring any additional arguments.
func (Function): The function to cap arguments for.
[n:=func.maxParams] (number): The arity cap.
(Function): Returns the new capped function.
aryFunc := A.ary(Func("fn_aryFunc"), 2)
aryFunc.call("a", "b", "c", "d")
; => ["a", "b"]
fn_aryFunc(arguments*) {
return arguments
}
Invokes func
after wait
milliseconds. Any additional arguments are provided to func when it's invoked.
func (Function): The function to delay.
wait (number): The number of milliseconds to delay invocation.
[args] (...*): The arguments to invoke func with.
(boolean): Returns true.
A.delay(Func("fn_delayFunc"), 1000, "later")
fn_delayFunc(text) {
msgbox, % text
}
; => msgboxes 'later' after one second.
Creates a function that invokes func
with arguments reversed.
func (Function): The function to flip arguments for.
(Function): Returns the new flipped function.
flippedFunc1 := A.flip(Func("inStr"))
flippedFunc1.call("s", "string")
; => 1
flippedFunc2 := A.flip(Func("fn_flipFunc"))
flippedFunc2.call("a", "b", "c", "d")
; => ["d", "c", "b", "a"]
fn_flipFunc(arguments*) {
return biga.toArray(arguments)
}
Creates a function that memoizes the result of func
. If resolver
is provided, it determines the cache key for storing the result based on the arguments provided to the memoized function.
func (Function): The function to have its output memoized.
[resolver] (Function): The function to resolve the cache key.
(Function): Returns the new memoized function.
memoizedFibonacci := A.memoize(func("fn_fibonacci"))
memoizedFibonacci.call(10)
; => 55
; Subsequent calls with the same argument will use the cached result
memoizedFibonacci.call(10)
; => 55
fn_fibonacci(n) {
if (n <= 1) {
return n
}
return fn_fibonacci(n - 1) + fn_fibonacci(n - 2)
}
Creates a function that negates the result of the predicate
func. The func predicate
is invoked with the this binding and arguments of the created function.
predicate (Function): The predicate to negate.
(Function): Returns the new negated function.
fn_isEven(n) {
return (mod(n, 2) = 0)
}
A.filter[1, 2, 3, 4, 5, 6], A.negate(func("fn_isEven"))
; => [1, 3, 5]
Creates a function that is restricted to invoking func
once. Repeat calls to the function return the value of the first invocation.
func (Function): The function to restrict.
(Function): Returns the new restricted function.
initialize = A.once(func("fn_createApplication"))
initialize.call()
initialize.call()
; => `fn_createApplication` is invoked once
Creates a throttled function that only invokes func
at most once per every wait
milliseconds. The function is invoked with the last arguments provided to the throttled function. Subsequent calls to the throttled function return the result of the last invocation.
func (Function): The function to throttle.
[wait:=0] (number): The number of milliseconds to throttle invocations to.
(Function): Returns the new throttled function.
refresh := A.throttle(func("fn_updateGUI"), 1000)
refresh.call()
refresh.call()
; => `fn_updateGUI` is invokable once every 1000ms but will return the last value anytime called
Casts value
as an array if it's not one.
value (*): The value to inspect.
(Array): Returns the cast array.
A.castArray(1)
; => [1]
A.castArray({"a": 1})
; => {"a": 1}
A.castArray("abc")
; => ["abc"]
A.castArray("")
; => [""]
Creates a shallow clone of value
. Supports cloning arrays, objects, numbers, strings.
value (*): The value to clone.
(*): Returns the cloned value.
object := [{ "a": 1 }, { "b": 2 }]
shallowclone := A.clone(object)
object.a := 2
object
; => [{ "a": 2 }, { "b": 2 }]
shallowclone
; => [{ "a": 1 }, { "b": 2 }]
This method is like A.clone except that it recursively clones value
.
value (*): The value to recursively clone.
(*): Returns the deep cloned value.
object := [{ "a": [[1, 2, 3]] }, { "b": 2 }]
deepclone := A.cloneDeep(object)
object[1].a := 2
; object
; => [{ "a": 2 }, { "b": 2 }]
; deepclone
; => [{ "a": [[1, 2, 3]] }, { "b": 2 }]
Checks if object
conforms to source by invoking the predicate properties of source
with the corresponding property values of object
.
object (Object): The object to inspect.
source (Object): The object of property predicates to conform to.
(boolean): Returns true if object conforms, else false.
object := {"a": 1, "b": 2}
A.conformsTo(object, {"b": func("fn_conformsToFunc1")})
; => true
A.conformsTo(object, {"b": func("fn_conformsToFunc2")})
; => false
fn_conformsToFunc1(n)
{
return n > 1
}
fn_conformsToFunc2(n)
{
return n > 2
}
Performs a shallow comparison between two values to determine if they are equivalent.
value (*): The value to compare.
other (*): The other value to compare.
(boolean): Returns true if the values are equivalent, else false.
object := {"a": 1}
other := {"a": 1}
A.eq(object, other)
; => true
A.eq("a", "a")
; => true
A.eq("", "")
; => true
Checks if value
is greater than other.
value (*): The value to compare.
other (*): The other value to compare.
(boolean): Returns true if value is greater than other, else false.
A.gt(3, 1)
; => true
A.gt(3, 3)
; => false
A.gt(1, 3)
; => false
Checks if value
is greater than or equal to other.
value (*): The value to compare.
other (*): The other value to compare.
(boolean): Returns true if value is greater than or equal to other, else false.
A.gte(3, 1)
; => true
A.gte(3, 3)
; => true
A.gte(1, 3)
; => false
Checks if value
is an alnum.
value (*): The value to check.
(boolean): Returns true if value is an alnum, else false.
A.isAlnum(1)
; => true
A.isAlnum("hello")
; => true
A.isAlnum([])
; => false
A.isAlnum({})
; => false
Checks if value
is an Array object.
value (*): The value to check.
(boolean): Returns true if value is an array, else false.
A.isArray([1, 2, 3])
; => true
A.isArray("abc")
; => false
A.isArray({"key": "value"})
; => true
Checks if value
is classified as a boolean.
value (*): The value to check.
(boolean): Returns true if value is a boolean, else false.
A.isBoolean(true)
; => true
A.isBoolean(1)
; => true
A.isBoolean(false)
; => true
A.isBoolean(0)
; => true
Checks if value
is an empty object. Objects are considered empty if they have no own enumerable string keyed properties.
value (*): The value to check.
(boolean): Returns true
if value is empty, else false
.
A.isEmpty("")
; => true
A.isEmpty(true)
; => true
A.isEmpty(1)
; => true
A.isEmpty([1, 2, 3])
; => false
A.isEmpty({"a": 1})
; => false
Performs a deep comparison between two values to determine if they are equivalent.
This method supports comparing numbers, strings, and objects.
value (*): The value to compare.
other (...*): The other value to compare.
(boolean): Returns true if the values are equivalent, else false.
A.isEqual(1, 1)
; => true
A.isEqual({ "a": 1 }, { "a": 1 })
; => true
A.isEqual(1, 1, 2)
; => false
StringCaseSense, On
A.isEqual({ "a": "a" }, { "a": "A" })
; => false
Checks if value
is an exception error object.
value (*): The value to check.
(boolean): Returns true if value is an exception object, else false.
A.isError(Exception("something broke"))
; => true
A.isFloat(1) ; => false
## .isFunction
<a href='https://github.com/biga-ahk/biga.ahk/blob/master/src/lang/isFunction.ahk' class='text-muted'>source</a>
Checks if `value` is callable as a function object, bound function, or object method.
#### Arguments
value (*): The `value` to check.
#### Returns
(boolean): Returns `true` if `value` is callable, else `false`.
#### Example
```autohotkey
boundFunc := func("strLen").bind()
A.isFunction(boundFunc)
; => true
IsFunc(boundFunc)
; => false
A.isFunction(A.isString)
; => true
A.isFunction(A.matchesProperty("a", 1))
; => true
A.isFunction([1, 2, 3])
; => false
Checks if value
is an integer.
value (*): The value to check.
(boolean): Returns true if value is an integer, else false.
A.isInteger(1)
; => true
A.isInteger("1")
; => false
Performs a partial deep comparison between object
and source
to determine if object contains equivalent property values.
Partial comparisons will match empty array and empty object source values against any array or object value, respectively. See A.isEqual for a list of supported value comparisons.
object (Object): The object to inspect.
source (Object): The object of property values to match.
(boolean): Returns true if object is a match, else false.
object := { "a": 1, "b": 2, "c": 3 }
A.isMatch(object, {"b": 2})
; => true
A.isMatch(object, {"b": 2, "c": 3})
; => true
A.isMatch(object, {"b": 1})
; => false
A.isMatch(object, {"b": 2, "z": 99})
; => false
Checks if value
is a number.
value (*): The value to check.
(boolean): Returns true if value is a number, else false.
A.isNumber(1)
; => true
A.isNumber("1")
; => true
A.isNumber("1.001")
; => true
Checks if value
is an object.
value (*): The value to check.
(boolean): Returns true if value is an object, else false.
A.isObject({})
; => true
A.isObject([1, 2, 3])
; => true
A.isObject("")
; => false
Checks if value
is classified as a string.
value (*): The value to check.
(boolean): Returns true if value is a string, else false.
A.isString("abc")
; => true
A.isString(1)
; => false
Checks if value
is undefined or blank.
value (*): The value to check.
(boolean): Returns true if value is undefined, else false.
A.isUndefined("")
; => true
A.isUndefined(non_existant_var)
; => true
A.isUndefined({})
; => false
A.isUndefined(" ")
; => false
A.isUndefined(0)
; => false
A.isUndefined(false)
; => false
Checks if value
is less than other.
value (*): The value to compare.
other (*): The other value to compare.
(boolean): Returns true if value is less than other, else false.
A.lt(1, 3)
; => true
A.lt(3, 3)
; => false
A.lt(3, 1)
; => false
Checks if value
is less than or equal to other.
value (*): The value to compare.
other (*): The other value to compare.
(boolean): Returns true if value is less than or equal to other, else false.
A.lte(1, 3)
; => true
A.lte(3, 3)
; => true
A.lte(3, 1)
; => false
Converts value
to an array.
value (*): The value to convert.
(Array): Returns the converted array.
A.toArray({"a": 1, "b": 2})
; => [1, 2]
A.toArray("abc")
; => ["a", "b", "c"]
A.toArray(1)
; => []
A.toArray("")
; => []
Converts value
to an integer suitable for use as the length of an array-like object.
value (*): The value to convert.
(number): Returns the converted integer.
A.toLength(3.2)
; => 3
A.toLength("3.2")
; => 3
Converts value
to a string. An empty string is returned for undefined values. The sign of -0
is preserved.
value (*): The value to convert.
(boolean): Returns the converted string.
A.toString(non_existant_var)
; => ""
A.toString(-0)
; => "-0"
A.toString([1, 2, 3])
; => "1,2,3"
This method returns a string indicating the type of value
.
value (*): the value to check.
(string): Returns value's type.
A.typeOf(42)
; => "integer"
A.typeOf(0.25)
; => "float"
A.typeOf("blubber")
; => "string"
A.typeOf([])
; => "object"
A.typeOf(undeclaredVariable)
; => "undefined"
Adds two numbers.
augend (number): The first number in an addition.
addend (number): The second number in an addition.
(number): Returns the total.
A.add(6, 4)
; => 10
Computes number
rounded up to precision
.
number (number): The number to round up.
[precision:=0] (number): The precision to round up to.
(number): Returns the rounded up number.
A.ceil(4.006)
; => 5
A.ceil(6.004, 2)
; => 6.01
A.ceil(6040, -2)
; => 6100
Divide two numbers.
dividend (number): The first number in a division.
divisor (number): The second number in a division.
(number): Returns the quotient.
A.divide(6, 4)
; => 1.5
Computes number
rounded down to precision
.
number (number): The number to round down.
[precision:=0] (number): The precision to round down to.
(number): Returns the rounded down number.
A.floor(4.006)
; => 4
A.floor(0.046, 2)
; => 0.04
A.floor(4060, -2)
; => 4000
Computes the maximum value of array
. If array
is empty or falsey, ""
is returned.
array (Array): The array to iterate over.
(*): Returns the maximum value.
A.max([4, 2, 8, 6])
; => 8
A.max([])
; => ""
This method is like A.max except that it accepts iteratee
which is invoked for each element in array
to generate the criterion by which the value is ranked. The iteratee is invoked with one argument: (value).
array (Array): The array to iterate over.
[iteratee:=.identity] (Function): The iteratee invoked per element.
(*): Returns the maximum value.
objects := [ {"n": 4 }, { "n": 2 }, { "n": 8 }, { "n": 6 } ]
A.maxBy(objects, func("fn_maxByFunc"))
; => { "n": 8 }
fn_maxByFunc(o)
{
return o.n
}
; The A.property iteratee shorthand
A.maxBy(objects, "n")
; => { "n": 8 }
Computes the mean of the values in array
.
array (Array): The array to iterate over.
(number): Returns the mean.
A.mean([4, 2, 8, 6])
; => 5
This method is like A.mean except that it accepts iteratee
which is invoked for each element in array
to generate the value to be averaged. The iteratee is invoked with one argument: (value).
array (Array): The array to iterate over.
[iteratee:=.identity] (Function): The iteratee invoked per element.
(number): Returns the mean.
objects := [{"n": 4}, {"n": 2}, {"n": 8}, {"n": 6}]
A.meanBy(objects, func("fn_meanByFunc"))
; => 5
fn_meanByFunc(o)
{
return o.n
}
; The A.property iteratee shorthand.
A.meanBy(objects, "n")
; => 5
Computes the minimum value of array
. If array is empty or falsey, ""
is returned.
array (Array): The array to iterate over.
(*): Returns the minimum value.
A.min([4, 2, 8, 6])
; => 2
A.min([])
; => ""
This method is like A.min except that it accepts iteratee
which is invoked for each element in array
to generate the criterion by which the value is ranked. The iteratee is invoked with one argument: (value).
array (Array): The array to iterate over.
[iteratee:=.identity] (Function): The iteratee invoked per element.
(*): Returns the minimum value.
objects := [ {"n": 4 }, { "n": 2 }, { "n": 8 }, { "n": 6 } ]
A.minBy(objects, func("fn_minByFunc"))
; => { "n": 2 }
fn_minByFunc(o)
{
return o.n
}
; The A.property iteratee shorthand
A.minBy(objects, "n")
; => { "n": 2 }
Multiply two numbers.
multiplier (number): The first number in a multiplication.
multiplicand (number): The second number in a multiplication.
(number): Returns the product.
A.multiply(6, 4)
; => 24
Computes number
rounded to precision
.
number (number): The number to round.
[precision:=0] (number): The precision to round to.
(number): Returns the rounded number.
A.round(4.006)
; => 4
A.round(4.006, 2)
; => 4.01
A.round(4060, -2)
; => 4100
Subtract two numbers.
minuend (number): The first number in a subtraction.
subtrahend (number): The second number in a subtraction.
(number): Returns the difference.
A.subtract(6, 4)
; => 2
Computes the sum of the values in array
.
array (Array): The array to iterate over.
(number): Returns the sum.
A.sum([4, 2, 8, 6])
; => 20
This method is like A.sum except that it accepts iteratee
which is invoked for each element in array
to generate the value to be summed. The iteratee is invoked with one argument: (value).
array (Array): The array to iterate over. [iteratee:=.identity] (Function): The iteratee invoked per element.
(number): Returns the sum.
objects := [ {"n": 4 }, { "n": 2 }, { "n": 8 }, { "n": 6 } ]
A.sumBy(objects, func("fn_sumByFunc"))
; => 20
fn_sumByFunc(o)
{
return o.n
}
; The A.property iteratee shorthand
A.sumBy(objects, "n")
; => 20
Clamps number
within the inclusive lower
and upper
bounds.
number (number): The number to clamp.
lower (number): The lower bound.
upper (number): The upper bound.
(number): Returns the clamped number.
A.clamp(-10, -5, 5)
; => -5
A.clamp(10, -5, 5)
; => 5
Checks if n
is between start
and up to, but not including, end
. If end is not specified, it's set to start with start then set to 0. If start is greater than end the params are swapped to support negative ranges.
number (number): The number to check.
start (number): The start of the range.
end (number): The end of the range.
(boolean): Returns true if number is in the range, else false.
A.inRange(3, 2, 4)
; => true
A.inRange(4, 8)
; => true
A.inRange(4, 2)
; => false
A.inRange(2, 2)
; => false
A.inRange(1.2, 2)
; => true
A.inRange(5.2, 4)
; => false
A.inRange(-3, -2, -6)
; => true
Produces a random number between the inclusive lower
and upper
bounds. If floating
is true, or either lower or upper are floats, a floating-point number is returned instead of an integer. Uses AutoHotkey's pseudo-random Random command.
[lower:=0] (number): The lower bound.
[upper:=1] (number): The upper bound.
[floating:=false] (boolean): Specify returning a floating-point number.
(number): Returns the random number.
A.random(0, 5)
; => an integer between 0 and 5
A.random(5)
; => an integer between 0 and 5
A.random(1.2, 5.2)
; => a floating-point number between 1.2 and 5.2
Creates an array of values corresponding to paths
of object
.
object (Object): The object to iterate over.
[paths] (...(string|string[])): The property paths to pick.
(Array): Returns the picked values.
object := {"a": [{ "b": {"c": 3} }, 4]}
A.at(object, ["a[1].b.c", "a[2]"])
; => [3, 4]
Assigns own and inherited enumerable string keyed properties of source
objects to the destination object for all destination properties. Source objects are applied from left to right. Once a property is set, additional values of the same property are ignored.
Note
Unlike it's Lodash counterpart, this method does NOT mutate the object.
object (Object): The destination object.
[sources] (...Object*): The source objects.
(Object): Returns object.
A.defaults({"a": 1}, {"b": 2}, {"a": 3})
; => {"a": 1, "b": 2}
This method is like A.find except that it returns the key of the first element predicate
returns truthy for instead of the element itself.
collection (Array|Object): The collection to inspect.
function (Function): The function invoked per iteration.
[fromIndex:=1] (number): The index to search from.
(*): Returns the matched element, else false.
users := { "barney": {"age": 36, "active": true}
, "fred": {"age": 40, "active": false}
, "pebbles": {"age": 1, "active": true} }
A.findKey(users, func("fn_findKeyFunc"))
; => "barney"
fn_findKeyFunc(o)
{
return o.age < 40
}
; The A.matches iteratee shorthand.
A.findKey(users, {"age": 1, "active": true})
; => "pebbles"
; The A.matchesProperty iteratee shorthand.
A.findKey(users, ["active", false])
; => "fred"
; The A.property iteratee shorthand.
A.findKey(users, "active")
; => "barney"
Iterates over own enumerable keys of object
and invokes iteratee
for each property. The iteratee is invoked with three arguments: (value, key, object). Iteratee functions may exit iteration early by explicitly returning false
.
object (Object): The object to iterate over.
[iteratee:=.identity] (Function): The function invoked per iteration.
(*): Returns the resolved value.
object := {"a": 1, "b": 2}
A.forIn(object, func("fn_forInFunc"))
fn_forInFunc(value, key) {
msgbox, % key
}
;Â => msgboxes "a" then "b"
This method is like A.forIn except that it iterates over properties of object
in the opposite order.
object (Object): The object to iterate over.
[iteratee:=.identity] (Function): The function invoked per iteration.
(*): Returns the resolved value.
object := [1, 2, 3]
A.forInRight(object, func("fn_forInRightFunc")
fn_forInRightFunc(value, key) {
msgbox, % value
}
;Â => msgboxes "3", "2", then "1"
Gets the value at path of object
. If the resolved value is ""
, the defaultValue
is returned in its place.
object (Object): The object to query.
path (Array|string): The path of the property to get.
[defaultValue:=""] (*): The value returned for undefined resolved values.
(*): Returns the resolved value.
object := {"a": [{ "b": {"c": 3} }]}
A.get(object, "a[1].b.c")
; => 3
A.get(object, ["a", "1", "b", "c"])
; => 3
A.get(object, "a.b.c", "default")
; => "default"
Checks if path
is a property of object
.
object (Object): The object to query.
path (Array|string): The path to check.
(boolean): Returns true if path exists, else false.
object := {"a": { "b": ""}}
A.has(object, "a")
; => true
A.has(object, "a.b")
; => true
A.has(object, ["a", "b"])
; => true
A.has(object, "a.b.c")
; => false
Creates an object composed of the inverted keys and values of object. If object contains duplicate values, subsequent values overwrite property assignments of previous values.
object (Object): The object to invert.
(Array): Returns the new inverted object.
object := {"a": 1, "b": 2, "c": 1}
A.invert(object)
; => {"1": "c", "2": "b"}
A.invert({1: "a", 2: "A"})
; => {"a": 2}
This method is like A.invert except that the inverted object is generated from the results of running each element of object thru iteratee
. The corresponding inverted value of each inverted key is an array of keys responsible for generating the inverted value. The iteratee is invoked with one argument: (value).
object (Object): The object to invert.
[iteratee:=.identity] (Function): The iteratee invoked per element.
(Array): Returns the new inverted object.
object := {"a": 1, "b": 2, "c": 1}
A.invertBy(object)
; => {"1": ["a", "c"], "2":["b"]}
A.invertBy(object, func("invertByFunc"))
; => {"group1": ["a", "c"], "group2": ["b"]}
invertByFunc(value)
{
return "group" value
}
Creates an array of the own enumerable properties of object.
object (Object): The object to query.
(Array): Returns the array of property names.
object := {"a": 1, "b": 2, "c": 3}
A.keys(object)
; => ["a", "b", "c"]
A.keys("hi")
; => [1, 2]
The opposite of A.mapValues this method creates an object with the same values as object and keys generated by running each own enumerable string keyed property of object thru iteratee
. The iteratee is invoked with three arguments: (value, index|key, object).
object (Object): The object to iterate over.
[iteratee:=.identity] (Function): The function invoked per iteration.
(Object): Returns the new mapped object.
A.mapKeys({"a": 1, "b": 2}, func("fn_mapKeysFunc"))
; => {"a+1": 1, "b+2": 2}
fn_mapKeysFunc(value, key)
{
return key "+" value
}
Creates an object with the same keys as object and values generated by running each own enumerable string keyed property of object thru iteratee
. The iteratee is invoked with three arguments: (value, index|key, object).
object (Object): The object to iterate over.
[iteratee:=.identity] (Function): The function invoked per iteration.
(Object): Returns the new mapped object.
users := {"fred": {"user": "fred", "age": 40}
,"pebbles": {"user": "pebbles", "age": 1}}
A.mapValues(users, func("fn_mapValuesFunc"))
; => {"fred": 40, "pebbles": 1}
fn_mapValuesFunc(o)
{
return o.age
}
; The A.property iteratee shorthand.
A.mapValues(users, "age")
; => {"fred": 40, "pebbles": 1}
This method recursively merges own and inherited enumerable string keyed properties of source objects into the destination object. Array and plain object properties are merged recursively. Other objects and value types are overridden by assignment. Source objects are applied from left to right. Subsequent sources overwrite property assignments of previous sources.
object (Object): The destination object.
[sources] (...Object): The source objects.
(Object): Returns object.
object := {"options": [{"option1": true}]}
other := {"options": [{"option2": false}]}
A.merge(object, other)
; => {"options": [{"option1": true, "option2": false}]}
object := { "a": [{ "b": 2 }, { "d": 4 }] }
other := { "a": [{ "c": 3 }, { "e": 5 }] }
A.merge(object, other)
; => { "a": [{ "b": "2", "c": 3 }, { "d": "4", "e": 5 }] }
The opposite of A.pick this method creates an object composed of the own and inherited enumerable property paths of object that are not omitted.
object (Object): The source object.
[paths] (...(string|string[])): The property paths to omit.
(Object): Returns the new object.
object := {"a": 1, "b": "2", "c": 3}
A.omit(object, ["a", "c"])
; => {"b": "2"}
Creates an object composed of the picked object properties.
object (Object): The source object.
[paths] (...(string|string[])): The property paths to pick.
(Object): Returns the new object.
object := {"a": 1, "b": "2", "c": 3}
A.pick(object, ["a", "c"])
; => {"a": 1, "c": 3}
Creates an object composed of the object properties predicate
returns truthy for. The predicate is invoked with two arguments: (value, key).
object (Object): The source object.
[predicate:=.identity] (Function): The function invoked per property.
(Object): Returns the new object.
object := {"a": 1, "b": "two", "c": 3}
A.pickBy(object, A.isNumber)
; => {"a": 1, "c": 3}
Sets the value at path
of object
. If a portion of path
doesn't exist, it's created. Objects are created for all missing properties.
object (Object): The object to modify.
path (Array|string): The path of the property to set.
value (*): The value to set.
(Object): Returns object.
object := {"a": [{ "b": {"c": 3} }]}
A.set(object, "a[1].b.c", 4)
; => {"a": [{ "b": {"c": 4} }]}
A.get(object, "a[1].b.c")
; => 4
A.set(object, ["x", "1", "y", "z"], 5)
A.get(object, ["x", "1", "y", "z"])
; => 5
Creates an array of own enumerable string keyed-value pairs for object which can be consumed by A.fromPairs.
.entries
object (Object): The object to query.
(Array): Returns the key-value pairs.
A.toPairs({"a": 1, "b": 2})
; => [["a", 1], ["b", 2]]
Creates an array of the own enumerable string keyed property values of object
.
object (Object): The object to query.
(Array): Returns the array of property values.
object := {"a": 1, "b": 2}
object.c := 3
A.values(object)
; => [1, 2, 3]
A.values("hi")
; => ["h", "i"]
Converts string to camel case.
[string:=""] (string): The string to convert.
(string): Returns the camel cased string.
A.camelCase("--foo-bar--")
; => "fooBar"
A.camelCase("fooBar")
; => "fooBar"
A.camelCase("__FOO_BAR__")
; => "fooBar"
Checks if string
ends with the given target string.
string (string): The string to inspect.
[target] (string): The string to search for.
[position:=strLen()] (number): The position to search up to.
(boolean): Returns true if string ends with target, else false.
A.endsWith("abc", "c")
; => true
A.endsWith("abc", "b")
; => false
A.endsWith("abc", "b", 2)
; => true
Converts the characters "&", "<", ">", '"', and "'" in string
to their corresponding HTML entities.
Note
No other characters are escaped. To escape additional characters use a third-party library.
Though the ">" character is escaped for symmetry, characters like ">" and "/" don't need escaping in HTML and have no special meaning unless they're part of a tag or unquoted attribute value. See Mathias Bynens's article (under "semi-related fun fact") for more details.
When working with HTML you should always quote attribute values to reduce XSS vectors.
[string:=""] (string): The string to escape.
(string): Returns the escaped string.
string := "fred, barney, & pebbles"
A.escape(string)
; => "fred, barney, & pebbles"
Converts string
to kebab case.
[string:=""] (string): The string to convert.
(string): Returns the kebab cased string.
A.kebabCase("Foo Bar")
; => "foo-bar"
A.kebabCase("fooBar")
; => "foo-bar"
A.kebabCase("--FOO_BAR--")
; => "foo-bar"
Converts string
, as space separated words, to lower case.
[string:=""] (string): The string to convert.
(string): Returns the lower cased string.
A.lowerCase("--Foo-Bar--")
; => "foo bar"
A.lowerCase("fooBar")
; => "foo bar"
A.lowerCase("__FOO_BAR__")
; => "foo bar"
Converts the first character of string
to lower case.
[string:=""] (string): The string to convert.
(string): Returns the converted string.
A.lowerFirst("Fred")
; => "fred"
A.lowerFirst("FRED")
; => "fRED"
Pads string
on the left and right sides if it's shorter than length
. Padding characters are truncated if they can't be evenly divided by length.
[string:=""] (string): The string to pad.
[length:=0] (number): The padding length.
[chars:=" "] (string): The string used as padding.
(string): Returns the padded string.
A.pad("abc", 8)
; => " abc "
A.pad("abc", 8, "_-")
; => "_-abc_-_"
A.pad("abc", 3)
; => "abc"
Pads string
on the right side if it's shorter than length
. Padding characters are truncated if they exceed length.
[string:=""] (string): The string to pad.
[length:=0] (number): The padding length.
[chars:=" "] (string): The string used as padding.
(string): Returns the padded string.
A.padEnd("abc", 6)
; => "abc "
A.padEnd("abc", 6, "_-")
; => "abc_-_"
A.padEnd("abc", 3)
; => "abc"
Pads string
on the left side if it's shorter than length
. Padding characters are truncated if they exceed length.
[string:=""] (string): The string to pad.
[length:=0] (number): The padding length.
[chars:=" "] (string): The string used as padding.
(string): Returns the padded string.
A.padStart("abc", 6)
; => " abc"
A.padStart("abc", 6, "_-")
; => "_-_abc"
A.padStart("abc", 3)
; => "abc"
Converts string to an integer of the specified radix. If radix is ""
undefined or 0
, a radix of 10
is used unless value is a hexadecimal, in which case a radix of 16
is used.
string (string): The string to convert.
[radix:=10] (number): The radix to interpret value by.
(number): Returns the converted integer.
A.parseInt("08")
; => 8
A.map(["6", "08", "10"], A.parseInt)
; => [6, 8, 10]
Repeats the given string n
times.
[string:=""] (string): The string to repeat.
[n:=1] (number): The number of times to repeat the string.
(string): Returns the repeated string.
A.repeat("*", 3)
; => "***"
A.repeat("abc", 2)
; => "abcabc"
A.repeat("abc", 0)
; => ""
Replaces matches for pattern
in string
with replacement
.
string (string): The string to modify.
pattern (RegExp|string): The pattern to replace.
replacement (string): The match replacement.
(string): Returns the modified string.
A.replace("Hi Fred", "Fred", "Barney")
; => "Hi Barney"
A.replace("1234", "/(\d+)/", "numbers")
; => "numbers"
Converts string
to snake case.
[string:=""] (string): The string to convert.
(string): Returns the snake cased string.
A.snakeCase("Foo Bar")
; => "foo_bar"
A.snakeCase("fooBar")
; => "foo_bar"
A.snakeCase("--FOO-BAR--")
; => "foo_bar"
Splits string
by separator
.
[string:=""] (string): The string to split.
[separator:=","] (RegExp|string): The separator pattern to split by.
[limit:=0] (number): The length to truncate results to.
(Array): Returns the string segments.
A.split("a-b-c", "-", 2)
; => ["a", "b"]
A.split("a--b-c", "/[\-]+/")
; => ["a", "b", "c"]
Converts string
to start case.
[string:=""] (string): The string to convert.
(string): Returns the start cased string.
A.startCase("--foo-bar--")
; => "Foo Bar"
A.startCase("fooBar")
; => "Foo Bar"
A.startCase("__FOO_BAR__")
; => "Foo Bar"
Checks if string
starts with the given target string.
string (string): The string to inspect.
[target] (string): The string to search for.
[position:=1] (number): The position to search from.
(boolean): Returns true if string starts with target, else false.
A.startsWith("abc", "a")
; => true
A.startsWith("abc", "b")
; => false
A.startsWith("abc", "b", 2)
; => true
StringCaseSense, On
A.startsWith("abc", "A")
; => false
Converts string
, as a whole, to lower case.
string (string): The string to convert.
(string): Returns the lower cased string.
A.toLower("--Foo-Bar--")
; => "--foo-bar--"
A.toLower("fooBar")
; => "foobar"
A.toLower("__FOO_BAR__")
; => "__foo_bar__"
Converts string
, as a whole, to upper case
string (string): The string to convert.
(string): Returns the upper cased string.
A.toUpper("--foo-bar--")
; => "--FOO-BAR--"
A.toUpper("fooBar")
; => "FOOBAR"
A.toUpper("__foo_bar__")
; => "__FOO_BAR__"
Removes leading and trailing whitespace or specified characters from string
.
[string:=""] (string): The string to trim.
[chars:=whitespace] (string): The characters to trim.
(string): Returns the trimmed string.
A.trim(" abc ")
; => "abc"
A.trim("-_-abc-_-", "_-")
; => "abc"
A.map([" foo ", " bar "], A.trim)
; => ["foo", "bar"]
Removes trailing whitespace or specified characters from string
.
[string:=""] (string): The string to trim.
[chars:=whitespace] (string): The characters to trim.
(string): Returns the trimmed string.
A.trimEnd(" abc ")
; => " abc"
A.trimEnd("-_-abc-_-", "_-")
; => "-_-abc"
Removes leading whitespace or specified characters from string
.
[string:=""] (string): The string to trim.
[chars:=whitespace] (string): The characters to trim.
(string): Returns the trimmed string.
A.trimStart(" abc ")
; => "abc "
A.trimStart("-_-abc-_-", "_-")
; => "abc-_-"
Truncates string
if it's longer than the given maximum string length. The last characters of the truncated string are replaced with the omission string which defaults to "...".
[string:=""] (string): The string to truncate.
[options:={}] (Object): The options object.
[options.length:=30] (number): The maximum string length.
[options.omission:="..."] (string): The string to indicate text is omitted.
[options.separator] (RegExp|string): The separator pattern to truncate to.
(string): Returns the truncated string.
string := "hi-diddly-ho there, neighborino"
A.truncate(string)
; => "hi-diddly-ho there, neighbor..."
A.truncate(string, {"length": 24, "separator": " "})
; => "hi-diddly-ho there,..."
A.truncate(string, {"length": 24, "separator": "/, /"})
; => "hi-diddly-ho there..."
The inverse of A.escape this method converts the HTML entities &, <, >, ", and ' in string
to their corresponding characters.
Note
No other HTML entities are unescaped. To unescape additional HTML entities use a dedicated third-party library.
[string:=""] (string): The string to unescape.
(string): Returns the unescaped string.
string := "fred, barney, & pebbles"
A.unescape(string)
; => "fred, barney, & pebbles"
Converts string
, as space separated words, to upper case.
[string:=""] (string): The string to convert.
(string): Returns the upper cased string.
A.upperCase("--Foo-Bar--")
; => "FOO BAR"
A.upperCase("fooBar")
; => "FOO BAR"
A.upperCase("__FOO_BAR__")
; => "FOO BAR"
Converts the first character of string
to upper case.
[string:=""] (string): The string to convert.
(string): Returns the converted string.
A.upperFirst("fred")
; => "Fred"
A.upperFirst("FRED")
; => "FRED"
Splits string
into an array of its words.
string:="" (string): The string to inspect.
[pattern] (RegExp|string): The pattern to match words.
(Array): Returns the words of string.
A.words("fred, barney, & pebbles")
; => ["fred", "barney", "pebbles"]
A.words("fred, barney, & pebbles", "/[^, ]+/")
; => ["fred", "barney", "&", "pebbles"]
Creates a function that invokes the predicate properties of source
with the corresponding property values of a given object, returning true if all predicates return truthy, else false.
source (Object): The object of property predicates to conform to.
(Function): Returns the new spec function.
objects := [{"a": 2, "b": 1}
, {"a": 1, "b": 2}]
A.filter(objects, A.conforms({"b": func("fn_conformsFunc")}))
; => [{"a": 1, "b": 2}]
fn_conformsFunc(n)
{
return n > 1
}
Creates a function that returns value
.
value (*): The value to return from the new function.
(Function): Returns the new constant function.
object := A.times(2, A.constant({"a": 1}))
; => [{"a": 1}, {"a": 1}]
This method returns the first argument it receives.
value (*): Any value.
(*): Returns value.
object := {"a": 1}
A.identity(object)
; => {"a": 1}
Creates a function that performs a shallow comparison between a given object and source, returning true
if the given object has equivalent property values, else false
.
source (Object): The object of property values to match.
(Function): Returns the new spec function.
objects := [{ "a": 1, "b": 2, "c": 3 }, { "a": 4, "b": 5, "c": 6 }]
A.filter(objects, A.matches({ "a": 4, "c": 6 }))
; => [{ "a": 4, "b": 5, "c": 6 }]
functor := A.matches({ "a": 4 })
A.filter(objects, functor)
; => [{ "a": 4, "b": 5, "c": 6 }]
functor.call({ "a": 1 })
; => false
Creates a function that performs a partial deep comparison between the value at path
of a given object to srcValue
, returning true if the object value is equivalent, else false.
path (Array|string): The path of the property to get.
srcValue (*): The value to match.
(Function): Returns the new spec function.
objects := [{ "a": 1, "b": 2, "c": 3 }, { "a": 4, "b": 5, "c": 6 }]
A.find(objects, A.matchesProperty("a", 4))
; => { "a": 4, "b": 5, "c": 6 }
A.filter(objects, A.matchesProperty("a", 4))
; => [{ "a": 4, "b": 5, "c": 6 }]
objects := [{ "a": {"b": 2} }, { "a": {"b": 1} }]
A.find(objects, A.matchesProperty(["a", "b"], 1))
; => { "a": {"b": 1} }
This method returns AutoHotkey's closest undefined equivilant; ""
.
A.times(2, A.stubObject)
; => [ {}, {} ]
Creates a function that gets the argument at index n
. If n is negative, the nth argument from the end is returned.
[n:=1] (number): The index of the argument to return.
(Function): Returns the new pass-thru function.
func := A.nthArg(2)
func.call("a", "b", "c", "d")
; => "b"
func := A.nthArg(-2)
func.call("a", "b", "c", "d")
; => "c"
Creates a function that invokes iteratees
with the arguments it receives and returns their results.
[iteratees:=.identity] (Function|Function[]*): The iteratees to invoke.
(Function): Returns the new function.
func := A.over([func("min"), func("max")])
func.call(1, 2, 3, 4)
; => [1, 4]
func := A.over([A.isBoolean, A.isNumber])
func.call(10)
; => [false, true]
Prints values
to terminal or other standard output device. Can be a string, or any other object to be converted into a string before written.
values* (*): The values to print.
(string): Returns values in one string; stringifying any objects.
A.print([1, 2, 3])
; => "1:1, 2:2, 3:3"
msgbox, % A.print("object: ", [1, 2, 3])
; => msgboxes "object: 1:1, 2:2, 3:3"
objects := [{ "a": {"b": 2} }, { "a": {"b": 1} }]
A.map(objects, A.property("a.b"))
; => [2, 1]
A.map(objects, A.property(["a", "b"]))
; => [2, 1]
objects := [{"name": "fred"}, {"name": "barney"}]
A.map(objects, A.property("name"))
; => ["fred", "barney"]
The opposite of A.property this method creates a function that returns the value at a given path of object
.
object (Object): The object to query.
(Function): Returns the new accessor function.
array := [0, 1, 2]
object := {"a": array, "b": array, "c": array}
A.map(["a[3]", "c[1]"], A.propertyOf(object))
; => [2, 0]
A.map([["a", 3], ["c", 1]], A.propertyOf(object))
; => [2, 0]
Creates an array of numbers (positive and/or negative) progressing from start
up to, but not including, end
. A step of -1 is used if a negative start is specified without an end or step. If end is not specified, it's set to start with start then set to 0
. The array's size is used as the end when a step of 0
is specified.
[start:=0] (number): The start of the range. end (number): The end of the range. [step:=1] (number): The value to increment or decrement by.
(Array): Returns the range of numbers.
A.range(4)
; => [0, 1, 2, 3]
A.range(-4)
; => [0, -1, -2, -3]
A.range(1, 5)
; => [1, 2, 3, 4]
A.range(0, 20, 5)
; => [0, 5, 10, 15]
A.range(0, -4, -1)
; => [0, -1, -2, -3]
A.range(1, 4, 0)
; => [1, 1, 1]
A.range(0)
; => []
This method is like A.range except that it populates values in descending order.
[start:=0] (number): The start of the range. end (number): The end of the range. [step:=1] (number): The value to increment or decrement by.
(Array): Returns the range of numbers.
A.rangeRight(4)
; => [3, 2, 1, 0]
A.rangeRight(-4)
; => [-3, -2, -1, 0]
A.rangeRight(1, 5)
; => [4, 3, 2, 1]
A.rangeRight(0, 20, 5)
; => [15, 10, 5, 0]
A.rangeRight(0, -4, -1)
; => [-3, -2, -1, 0]
A.rangeRight(1, 4, 0)
; => [1, 1, 1]
A.rangeRight(0)
; => []
This method returns a new empty array.
(Array): Returns the new empty array.
A.times(2, A.stubArray)
; => [[], []]
This method returns false
.
(boolean): Returns false
.
A.times(2, A.stubFalse)
; => [false, false]
This method returns a new empty object.
(Object): Returns the new empty object.
A.times(2, A.stubObject)
; => [ {}, {} ]
This method returns an empty string ""
.
(string): Returns the empty string.
A.times(2, A.stubString)
; => ["", ""]
This method returns true
.
(boolean): Returns true
.
A.times(2, A.stubTrue)
; => [true, true]
Invokes the iteratee
n
times, returning an array of the results of each invocation. The iteratee is invoked with one argument; (index).
n (number): The number of times to invoke iteratee.
[iteratee:=.identity] (Function): The function invoked per iteration.
(Array): Returns the array of results.
A.times(4, A.constant(0))
; => [0, 0, 0, 0]
; make an array with random numbers
boundFunc := A.random.bind(A, 1, 1000, 0)
array := A.times(5, boundFunc)
; => [395, 364, 809, 904, 449]
Converts value
to a property path array.
value (*): The value to convert.
(Array): Returns the new property path array.
A.toPath("a.b.c")
; => ["a", "b", "c"]
A.toPath("a[1].b.c")
; => ["a", "1", "b", "c"]
Generates a unique ID. If prefix
is given, the ID is appended to it.
[prefix:=""] (string): The value to prefix the ID with.
(string): Returns the unique ID.
A.uniqueId("contact_")
; => "contact_1"
A.uniqueId()
; => 2