# Documentation for gololang.StandardAugmentations

This module defines the set of standard augmentations.

## Augmentations

### gololang.FunctionReference¶

Augment functions to make them behave more like objects from java.util.function

#### accept(this, args...)¶

Alias for `FunctionReference::invoke`

#### apply(this, args...)¶

Alias for `FunctionReference::invoke`

#### get(this)¶

Call this function with no arguments.

### gololang.Tuple¶

Augmentations for Golo tuples.

#### filter(this, func)¶

Filters elements using a predicate, returning a new tuple.

#### find(this, pred)¶

Returns the first element that satisfies a predicate, or `null` if none matches.

#### join(this, separator)¶

Joins the elements of a tuple into a string and using a separator.

#### map(this, func)¶

Maps the elements of a tuple, and returns a tuple with the transformed values.

### java.lang.CharSequence¶

Augmentations over `CharSequence` to view it as a “real” `char` collection.

#### head(this)¶

Returns the first `char` of the sequence, of `null` if empty.

#### isEmpty(this)¶

Checks if the sequence is empty.

#### tail(this)¶

Returns the remaining subsequence as a String (i.e. an immutable sequence)

### java.lang.Iterable¶

Augmentations over iterable collections.

#### count(this, pred)¶

Counts the number of elements that satisfy a predicate:

    println([1, 2, 3, 4]: count(|n| -> (n % 2) == 0))

- `this`: an iterable.
- `pred`: a predicate function, taking an element and returning a boolean.

#### each(this, func)¶

Applies a function over each element:

    [1, 2, 3]: each(|e| -> println(e))

- `this`: an iterable.
- `func`: the function to apply, taking the current element as a parameter.

#### exists(this, pred)¶

Checks whether any element satisfied a predicate:

    println([1, 2, 3, 4]: exists(|n| -> n > 3))

- `this`: an iterable.
- `pred` a predicate function, taking an element and returning a boolean.

#### reduce(this, initialValue, func)¶

General purpose reducing operation:

    let data = [1, 2, 3, 4, 5]
    println("sum = " + data: reduce(0, |acc, next| -> acc + next))

- `this`: an iterable.
- `initialValue`: the initial accumulator value for the reducing operation.
- `func`: the function to apply over an accumulator and the next value.

### java.lang.Number¶

Number augmentations.

#### downTo(high, low, func)¶

Similar to `upTo`, except that the interval iteration is made from `high` down to `low`.

#### times(count, func)¶

Repeats a function many times, as in:

    3: times(-> println("Hey!")
    4: times(|i| -> println(i))

- `count`: how many times the `func` function must be repeated.
- `func`: a function to execute.

The `func` function may take 0 or 1 argument. In the later case the argument is the iteration count index.

#### upTo(low, high, func)¶

Repeats a function over a discrete interval:

    1: upTo(3, -> println("Hello"))
    1: upTo(3, |i| ->println(i))

- `low`: the start value (inclusive).
- `high`: the end value (inclusive).
- `func`: the function to execute.

As in the case of `times`, `func` may take an optional index parameter. See also `downTo`.

### java.lang.String¶

Useful string augmentations.

#### format(this, args...)¶

Convenience wrapper over `java.lang.String.format(...)`.

#### toDouble(this)¶

Wrapper over `java.lang.Integer.parseDouble`.

#### toFloat(this)¶

Wrapper over `java.lang.Integer.parseFloat`.

#### toInt(this)¶

Wrapper over `java.lang.Integer.parseInt`.

#### toInteger(this)¶

rapper over `java.lang.Integer.parseInt`.

#### toLong(this)¶

Wrapper over `java.lang.Integer.parseLong`.

### java.util.Collection¶

Java collections augmentations.

#### destruct(this)¶

Destructuration helper.

- return a tuple of the values

#### newWithSameType(this)¶

Returns an empty collection of the same type as `this`.

### java.util.List¶

Java lists augmentations.

#### append(this, element)¶

Appends an element to a list.

#### append(this, head, tail...)¶

Appends a variable number of arguments to a list.

- `head`: an element to append.
- `tail`: a variable number of elements to append.

#### filter(this, pred)¶

Filters elements based on a predicate:

    println(list[1, 2, 3, 4]: filter(|n| -> (n % 2) == 0))

- `this`: a list.
- `pred`: a predicate function taking an element and returning a boolean.

`filter` returns a new collection of the same type as the original one, hence the original list is kept intact.

#### find(this, pred)¶

Finds the first element of a list matching a predicate:

    println(list[1, 2, 3, 4]: find(|n| -> n > 3))

- `this`: a list.
- `pred`: a predicate function taking an element and returning a boolean.

`find` returns `null` when no element satisfies `pred`.

#### head(this)¶

Returns a list first element, of `null` if empty.

#### insert(this, index, element)¶

Inserts an element at some index.

#### join(this, separator)¶

Join the elements into a string:

    println(list[1, 2, 3]: join(", "))

- `this`: a list.
- `separator`: the element separator string.

The returned string is `""` when the list is empty.

#### last(this)¶

Returns a list last element.

#### map(this, func)¶

Maps elements of a list using a function:

    println(list[1, 2, 3]: map(|n| -> n * 10))

- `this`: a list.
- `func`: a transformation function.

`map` returns a new list with the same type, keeping the original list intact.

#### order(this)¶

Sorts the list elements and returns the list.

#### order(this, comparator)¶

Sorts the element using a comparator, see `java.util.Collections.sort(...)`.

#### ordered(this)¶

Returns a new list where the elements have been sorted.

#### ordered(this, comparator)¶

Returns a new list where the elements have been sorted using a comparator. See `java.util.Collections.sort`.

#### prepend(this, element)¶

Prepends an element to a list.

#### prepend(this, head, tail...)¶

Prepends a variable number of arguments to a list.

#### removeAt(this, idx)¶

Removes the element at the specified position.

This method has the same behaviour as `java.util.List.remove(int)`, but is needed since for Golo everything is an `Object` and `remove` is overloaded.

#### reverse(this)¶

Reverse the elements of the list and returns the list.

See also `reversed`.

#### reversed(this)¶

Same as `reverse`, but the returned list is a new one, leaving the original list order intact.

#### tail(this)¶

Returns the rest of a list after its head, as an unmodifiable list.

#### unmodifiableView(this)¶

Convenience wrapper over `java.util.Collections.unmodifiableList`.

### java.util.Map¶

Augmentations over maps.

#### add(this, kv)¶

Adds a tuple `[key, value]` or a map entry and returns the map.

#### add(this, key, value)¶

Alias for `put` that returns the map.

#### addIfAbsent(this, key, value)¶

Adds an element to the map only if there is no entry for that key.

- `this`: a map.
- `key`: the element key.
- `value`: the element value or a function to evaluate to get a value.

The fact that `value` can be a function allows for delayed evaluation which can be useful for performance reasons. So instead of:

    map: addIfAbsent(key, expensiveOperation())

one may delay the evaluation as follows:

    map: addIfAbsent(key, -> expensiveOperation())

`addIfAbsent` returns the map.

#### count(this, pred)¶

Counts the number of elements satisfying a predicate.

#### delete(this, key)¶

Alias for `remove` that returns the map.

#### each(this, func)¶

Iterates over each entry of a map.

`func` takes 2 arguments: the entry key and its value.

#### exists(this, pred)¶

Returns `true` if there is any value satisfying `pred`, `false` otherwise.

#### filter(this, pred)¶

Filters elements using a predicate, and returns a new map.

`pred` takes 2 arguments: a key and a value, and returns a boolean.

#### find(this, pred)¶

Returns the first element that satisfies a predicate, or `null` if none matches.

`pred` takes 2 arguments: a key and a value, and returns a boolean.

#### getOrElse(this, key, replacement)¶

Returns a value from a key or a default value if the entry is not defined.

- `this`: a map.
- `key`: the key to look for.
- `replacement`: the default value, or a function giving the default value.

As it is the case for `addIfAbsent`, one can take advantage of delayed evaluation:

    println(map: getOrElse(key, "n/a"))
    println(map: getOrElse(key, -> expensiveOperation())

Note that `replacement` yields the return value also when there is an entry for `key` but the value is `null`.

#### map(this, func)¶

Maps entries of the map using a function.

`func` takes 2 arguments: a key and a value. The returned value must have `getKey()` and `getValue()` to represent a map entry. We suggest using the predefined `mapEntry(key, value)` function as it returns such object.

#### newWithSameType(this)¶

Returns a new empty map of the same type.

#### reduce(this, initialValue, func)¶

Reduces the entries of a map.

`func` takes 3 arguments:

- an accumulator whose initial value is `initialValue`,
- a key for the next entry,
- a value for the next entry.

#### unmodifiableView(this)¶

Wrapper for `java.util.Collections.unmodifiableMap(...)`.

### java.util.Map$Entry¶

#### destruct(this)¶

Destructurate a map entry in key and value

#### toArray(this)¶

Convert then entry into an array containing the key and the value.

### java.util.Set¶

Augmentations over set collections.

#### exclude(this, element)¶

Alias for `remove` that returns the set.

#### exclude(this, first, rest...)¶

Excludes a variable number of elements, and returns the set.

#### filter(this, pred)¶

Filters the elements using a predicate, and returns a new collection.

#### find(this, pred)¶

Finds the first element that satisfies a predicate `pred`, and returns it, or `null` if no element matches.

#### has(this, element)¶

Alias for `contains`.

#### has(this, first, rest...)¶

Alias for `contains` over a variable number of elements.

#### include(this, element)¶

Alias for `add` that returns the set.

#### include(this, first, rest...)¶

Includes a variable number of elements, and returns the set.

#### map(this, func)¶

Transform each value using the `func` function, and returns a new set.

#### unmodifiableView(this)¶

Convenience wrapper for `java.util.Collections.unmodifiableSet(...)`.