# Array

These are extensions to JavaScript's Array. [See this documentation for all standard Array methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#).\
All of the methods that Rulecube has added return an array leave the original array intact and return a new array.

```javascript
// To get the sum of the value of every real estate in London, you might use this:
realEstates
   .where(re => re.City === 'London')
   .sum(re => re.Value)
```

### Methods

#### where

```javascript
where(predicate: Function)
```

Filters based on the given predicate and returns the filtered array. Essentially an alias for [filter()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter).

**Parameters**

    **predicate *****Function***

        Predicate function for filtering data. This function is called with 3 parameters: value, index and the array itself.

**Return type**

    array

**Examples**

```javascript
persons.where(p => p.City === 'London')        // A new array containing only people who live in London
[1,12,300,6000].where(p => p > 100)            // [300, 6000] - filtered based on the value
[1,12,300,6000].where((p, idx) => idx > 1)     // [300, 6000] - filtered based on the index
```

#### whereIn

```javascript
whereIn(predicate?: Function, otherList: array)
```

Filters the collection based cross-checking every item using the predicate, with another list. Also known as an Intersect.

**Parameters**

    **predicate *****Function***

        (optional) Predicate for selecting the data. This function is called with 3 parameters: value, index and the array itself.

    **otherList *****array***

        The other list to compare with.

**Return type**

    array

**Examples**

```javascript
addresses.whereIn(p => p.City, LIST_OF_CAPITALS)     // Result will only contain addresses that are in capital cities
addresses.intersect(p => p.City, LIST_OF_CAPITALS)   // Same as the previous, intersect is an alias for whereIn
addresses.whereIn('City', LIST_OF_CAPITALS)          // Instead of a predicate you can use a property name string
[1,12,300,6000].whereIn(p => p, [299, 300, 301])     // => [300], as only 300 was present in the other list
[1,12,300,6000].whereIn([299, 300, 301])             // Same as the previous, but demonstrates that the predicate can be skipped if
                                                     //  the predicate is an identity predicate (p => p)
```

#### whereNotIn

```javascript
whereNotIn(predicate?: Function, otherList: array)
```

This is the inverse operation of the whereIn. Also known as an Except.

**Parameters**

    **predicate *****Function***

        (optional) Predicate for selecting the data. This function is called with 3 parameters: value, index and the array itself.

    **otherList *****array***

        The other list to compare with.

**Return type**

    array

**Examples**

```javascript
addresses.whereNotIn(p => p.City, LIST_OF_CAPITALS)  // Result will only contain addresses that are NOT in capital cities
addresses.except(p => p.City, LIST_OF_CAPITALS)      // Same as the previous, except is an alias for whereNotIn
[1,12,300,6000].whereNotIn(p => p, [299, 300, 301])  // => [1,12,6000], as only 300 was in the other list
[1,12,300,6000].whereNotIn([299, 300, 301])          // Same as the previous, but demonstrates that the predicate can be skipped if
                                                     //  the predicate is an identity predicate (a => a)
```

#### ofType

```javascript
ofType(type: Type)
```

Filters based on the given type and returns the filtered typed array.

**Parameters**

    **type *****Type***

        The type to filter by.

**Return type**

    array

**Examples**

```javascript
items.ofType(Mortgage)             // A new array containing only items of type 'Mortgage'
[1,12,'hi'].ofType(Number)         // [ 1, 12 ] 
[1,12,'hi'].ofType(String)         // [ 'hi' ] 
```

#### map

```javascript
map(predicate: Function)
```

Transforms the collection based on the given predicate. Actually one of the Array standard methods, but included here for reference. See also: [map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map).

**Parameters**

    **predicate *****Function***

        Predicate for transforming/mapping the data. This function is called with 3 parameters: value, index and the array itself.

**Return type**

    array

**Examples**

```javascript
[2,3,1].map(i => i + 1)                // [3, 4, 2]
[{val:2}, {val:1}].map(i => i.val)     // [2, 1]
```

#### orderBy

```javascript
orderBy(predicate?: Function)
```

Sorts the collection in an ascending order.

**Parameters**

    **predicate *****Function***

        (optional) Predicate for ordering data. This function is called with 1 parameter: value.

**Return type**

    array

**Examples**

```javascript
[2,3,1].orderBy()                                      // => [1, 2, 3]
[{val:2}, {val:1}].orderBy(i => i.val)                 // => [{val: 1}, {val:2}]
```

#### orderByDesc

```javascript
orderByDesc(predicate?: Function)
```

Sorts the collection in an descending order.

**Parameters**

    **predicate *****Function***

        (optional) Predicate for ordering data. This function is called with 1 parameter: value.

**Return type**

    array

**Examples**

```javascript
[2,3,1].orderByDesc()                          // => [3, 2, 1]
[{val:2}, {val:1}].orderByDesc(i => i.val)     // => [{val: 2}, {val:1}]
```

#### copy

```javascript
copy()
```

Create a (shallow) copy of the collection.\
Note: functions the same as `.`[`slice()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice).

**Parameters**

**Return type**

    array

**Examples**

```javascript
[1, 2, 3].copy()                          // => [1, 2, 3] - different array, same values
```

#### reverse

```javascript
reverse()
```

Reverses the collection. Actually one of the Array standard methods, but included here for reference. See also: [reverse()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse).\
Note: this changes the order of the array and does not create a copy! Use `.copy().reverse()` or `.reverseCopy()` for that instead.

**Parameters**

**Return type**

    array

**Examples**

```javascript
[1,2,3].reverse()                          // => [3, 2, 1]
[{val:2}, {val:1}].reverse()               // => [{val: 1}, {val: 2}]
```

#### reverseCopy

```javascript
reverseCopy()
```

Reverses a copy of the collection, leaves the original intact.\
Note: This is different from the native: [reverse()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse).

**Parameters**

**Return type**

    array

**Examples**

```javascript
[1,2,3].reverseCopy()                          // => [3, 2, 1]
[{val:2}, {val:1}].reverseCopy()               // => [{val: 1}, {val: 2}]
```

#### take

```javascript
take(num: number)
```

Reduces the collection to the given amount of items from the start.

**Parameters**

    **num *****number***

        The number of items to take.

**Return type**

    array

**Examples**

```javascript
[5, 6, 7, 8, 9].take(3)    // [5, 6, 7]
```

#### skip

```javascript
skip(num: number)
```

Reduces the collection by removing the given amount of items.

**Parameters**

    **num *****number***

        The number of items to skip.

**Return type**

    array

**Examples**

```javascript
[5, 6, 7, 8, 9].skip(3)            // [8, 9]
[5, 6, 7, 8, 9].skip(1).take(3)    // [6, 7, 8]
```

#### distinct

```javascript
distinct(predicate?: Function)
```

Reduces the collection to contain only unique values.

**Parameters**

    **predicate *****Function***

        (optional) Predicate for comparing the data.

**Return type**

    array

**Examples**

```javascript
[ 1, 2, 3, 3, 2, 1  ].distinct()                          // [1, 2, 3]
[ 'a', 'A', 'b', 'a'].distinct()                          // ['a', 'A', 'b']
[ 'a', 'A', 'b', 'a'].distinct(s => s.toLowerCase())      // ['a', 'b']
[ {name: 'Joe' }, {name: 'Joe' }].distinct(s => s.name)   // [{ name: 'Joe' }]
```

#### groupBy

```javascript
groupBy(predicate: Function)
```

Groups the collection based on the given predicate.

**Parameters**

    **predicate *****Function***

        Predicate for grouping the data.

**Return type**

    array

**Examples**

```javascript
// Example 1:
[1, 2, 3, 4].groupBy(a => a % 2 === 0 ? 'even' : 'odd') 
// => [ [ 1, 3 ], [ 2, 4 ] ]

// Example 1b:
[1, 2, 3, 4].groupBy(a => a % 2 === 0 ? 'even' : 'odd').keys
// => { 'even': [ 2, 4 ], 'odd': [ 1, 3 ] }

// Example 2:
[1, 2, 3, 4].groupBy(a => a % 2 === 0 ? 'even' : 'odd')   // [ [ 1, 3 ], [ 2, 4 ] ]
            .map(b => b.sum())                            // [ 4, 6 ] - Sommated each sub-collection

// Example 3:
[1, 2, 3, 4].groupBy(a => a % 2 === 0 ? 'even' : 'odd')   // [ [ 1, 3 ], [ 2, 4 ] ]
            .map(b => b.key)                              // [ 'odd', 'even' ]

// Example 4: for demonstration purposes, do not use this code block literally in a Ruleset.
// For use in Rulesets, imagine using a rule with the name 'group' having this groupBy expression,
//  and every line after that as separate rules.
[1, 2, 3, 4].groupBy(a => a % 2 === 0 ? 'even' : 'odd')   // Same as in Example 1
group[0].key                                              // => 'odd' - the key of the first group
group[1].key                                              // => 'even' - the key of the second group
group[0]                                                  // => [1, 3] - the values of the first group
group[1]                                                  // => [2, 4] - the values of the second group
group.keys['odd']                                         // => [1, 3] - an alternative way to get the data
group.keys['even']                                        // => [2, 4] - an alternative way to get the data
```

#### groupMap

```javascript
groupMap(groupPredicate: Function, mapPredicate: Function)
```

Groups and maps the collection based on the given predicates.

**Parameters**

    **groupPredicate *****Function***

        Predicate for grouping the data.

    **mapPredicate *****Function***

        Predicate for transforming/mapping the data.

**Return type**

    array

**Examples**

```javascript
[1, 2, 3, 4].groupMap(a => a % 2, b => b.sum())    // [ 4, 6 ] - Group by even/odd numbers and sum the collection
```

#### find

```javascript
find(predicate: Function)
```

Finds an item in the collection based on the given predicate and returns the first item that matches. Actually one of the Array standard methods, but included here for reference. See also: [find()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find).

**Parameters**

    **predicate *****Function***

        Predicate for finding the item. This function is called with 3 parameters: value, index and the array itself.

**Return type**

    any

**Examples**

```javascript
[1,12,300,6000].find(p => p > 100)         // => 300
persons.find(p => AGE(p.Birthdate) > 50)   // Finds and returns the first person with an age over 50
```

#### findMin

```javascript
findMin(predicate?: Function)
```

Returns the item with the lowest-valued numeric value in the collection. A predicate may be used to transform/map the data. Note: This is similar to min() but returns the item instead of the value. See also:

* Array.min

**Parameters**

    **predicate *****Function***

        (optional) Predicate for transforming/mapping the data.

**Return type**

    T

**Examples**

```javascript
[2, 1, 3].findMin()                          // => 1
[{val:2}, {val:1}].findMin(i => i.val)       // => {val:1}

// Compared with min():
[{val:2}, {val:1}].min(i => i.val)           // => 1
```

#### findMax

```javascript
findMax(predicate?: Function)
```

Returns the item with the highest-valued numeric value in the collection. A predicate may be used to transform/map the data. Note: This is similar to max() but returns the item instead of the value. See also:

* Array.max

**Parameters**

    **predicate *****Function***

        (optional) Predicate for transforming/mapping data.

**Return type**

    T

**Examples**

```javascript
[2, 3, 1].findMax()                          // => 3
[{val:2}, {val:3}].findMax(i => i.val)       // => { val:3 }

// Compared with max():
[{val:2}, {val:3}].max(i => i.val)           // => 3
```

#### first

```javascript
first(predicate?: Function)
```

Returns the first item in the collection. When given a predicate, finds and returns the first item that matches, similar to find().

**Parameters**

    **predicate *****Function***

        (optional) Predicate for finding the item. When not provided, this method will return the first item in the collection.

**Return type**

    T

**Examples**

```javascript
[1,12,300,6000].first()                    // => 1
[1,12,300,6000].first(p => p > 100)        // => 300
persons.first()                            // Returns the first item in the collection
persons.first(p => AGE(p.Birthdate) > 50)  // Finds and returns the first person with an age over 50
```

#### last

```javascript
last(predicate?: Function)
```

Returns the last item in the collection. When given a predicate, finds and returns the last item that matches.

**Parameters**

    **predicate *****Function***

        (optional) Predicate for finding the item. When not provided, this method will return the last item in the collection.

**Return type**

    T

**Examples**

```javascript
[1,12,300,6000].last()                     // => 6000
[1,12,300,6000].last(p => p < 1000)        // => 300
persons.last()                             // Returns the last person in the collection
persons.last(p => AGE(p.Birthdate) > 50)   // Finds and returns the last person with an age over 50
```

#### sum

```javascript
sum(predicate?: Function)
```

Computes the sum of the collection based on the given predicate.

**Parameters**

&#x20;   **predicate&#x20;*****Function***

&#x20;       (optional) Predicate for selecting data.

**Return type**

&#x20;   number

**Examples**

```javascript
[1,2,3].sum()                          // => 6
[{val:10}, {val:20}].sum(i => i.val)   // => 30
```

#### min

```javascript
min(predicate?: Function)
```

Returns the lowest-valued numeric value in the collection. A predicate may be used to transform/map the data. See also:

* Array.findMin

**Parameters**

&#x20;   **predicate&#x20;*****Function***

&#x20;       (optional) Predicate for transforming/mapping the data.

**Return type**

&#x20;   number

**Examples**

```javascript
[2, 1, 3].min()                          // => 1
[{val:2}, {val:1}].min(i => i.val)       // => 1
```

#### max

```javascript
max(predicate?: Function)
```

Returns the highest-valued numeric value in the collection. A predicate may be used to transform/map the data. See also:

* Array.findMax

**Parameters**

&#x20;   **predicate&#x20;*****Function***

&#x20;       (optional) Predicate for transforming/mapping data.

**Return type**

&#x20;   number

**Examples**

```javascript
[2, 3, 1].max()                          // => 3
[{val:2}, {val:1}].max(i => i.val)       // => 2
```

#### avg

```javascript
avg(predicate?: Function)
```

Computes the average value of the collection based on the given predicate.

**Parameters**

&#x20;   **predicate&#x20;*****Function***

&#x20;       (optional) Predicate for selecting data.

**Return type**

&#x20;   number

**Examples**

```javascript
[1,2,3].avg()                          // => 2
[{val:10}, {val:20}].avg(i => i.val)   // => 15
```

#### any

```javascript
any(predicate?: Function)
```

Returns whether any item in the collection matches the given predicate. Essentially an alias for [some()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some).

**Parameters**

&#x20;   **predicate&#x20;*****Function***

&#x20;       (optional) Predicate function for evaluating data. This function is called with 3 parameters: value, index and the array itself.

**Return type**

&#x20;   boolean

**Examples**

```javascript
[false, true, false].any()                     // => true
[false, false, false].any()                    // => false
[].any()                                       // => false
[1,2,3].any(i => i > 2)                        // => true - 3 is greater than 2
[1,2,3].any(i => i > 3)                        // => false - nothing in the collection is > 3
[{val:10}, {val:20}].any(i => i.val === 10)    // => true
[1,2,3].any((i, idx) => idx > 2)               // => false - no index higher than 2 exists (index starts at 0)
```

#### all

```javascript
all(predicate?: Function)
```

Returns whether every item in the collection matches the given predicate. Essentially an alias for [every()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every).

**Parameters**

&#x20;   **predicate&#x20;*****Function***

&#x20;       (optional) Predicate for matching data.

**Return type**

&#x20;   boolean

**Examples**

```javascript
[true, true, true].all()                       // => true
[true, false, true].all()                      // => false
[].all()                                       // => true
[1,2,3].all(i => i > 2)                        // => false - not every item is greater than 2
[1,2,3].all(i => i > 0)                        // => true - every item is greater than 3
[{val:10}, {val:20}].all(i => i.val === 10)    // => false
```

#### none

```javascript
none(predicate?: Function)
```

Returns whether none of the items in the collection matches the given predicate. The inverse of any().

**Parameters**

&#x20;   **predicate&#x20;*****Function***

&#x20;       (optional) Predicate function for evaluating data. This function is called with 3 parameters: value, index and the array itself.

**Return type**

&#x20;   boolean

**Examples**

```javascript
[false, true, false].none()                     // => false
[false, false, false].none()                    // => true
[].none()                                       // => true
[1,2,3].none(i => i > 2)                        // => false - 3 is greater than 2
[1,2,3].none(i => i > 3)                        // => true - nothing in the collection is > 3
[{val:10}, {val:20}].none(i => i.val === 10)    // => false
[1,2,3].none((i, idx) => idx > 2)               // => true - no index higher than 2 exists (index starts at 0)
```

#### contains

```javascript
contains(item: any)
```

Returns whether the given item is included in the collection. Essentially an alias for [includes()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes).

**Parameters**

&#x20;   **item&#x20;*****any***

&#x20;       The item to look for in the collection.

**Return type**

&#x20;   number

**Examples**

```javascript
[1,12,300,6000].contains(12)         // => true
[1,12,300,6000].contains(123)        // => false
```

#### count

```javascript
count(predicate?: Function)
```

Filters the collection based on the given predicate and returns the number of items left.

**Parameters**

&#x20;   **predicate&#x20;*****Function***

&#x20;       (optional) Predicate for filtering data.

**Return type**

&#x20;   number

**Examples**

```javascript
[1,12,300,6000].count()                    // => 4
[1,12,300,6000].count(p => p > 100)        // => 2
```

#### to

```javascript
to(otherType: any)
```

Casts collection to a different type. Has no effect during run-time, but helps with autocompletion.

**Parameters**

&#x20;   **otherType&#x20;*****any***

&#x20;       Type to cast to.

**Return type**

&#x20;   array

**Examples**

```javascript
[0,0,1,0,1].to(Boolean)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rulecube.com/language-reference/array.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.