IIterableExtension STATIC CLASS

Provides extension methods to IIterable interface. Therefore these methods also become available for string, array and other container classes.

Throughout this documentation page, the word iterable refers to an object of IIterable type.

All of the extension methods do not mutate the existing iterable (the this argument).

Parent Class

• Object

All Members

---

Type	Name	Signature
method S	all	public static bool all(System.Util.IIterable, Function)
method S	any	public static bool any(System.Util.IIterable, Function)
method S	append	public static IIterable append(System.Util.IIterable, var)
method S	concat	public static IIterable concat(System.Util.IIterable, var)
method S	count	public static int count(System.Util.IIterable)
method S	distinct	public static IIterable distinct(System.Util.IIterable)
method S	except	public static IIterable except(System.Util.IIterable, System.Util.IIterable)
method S	filter	public static IIterable filter(System.Util.IIterable, Function)
method S	first	public static var first(System.Util.IIterable)
method S	first	public static var first(System.Util.IIterable, bool)
method S	flatten	public static IIterable flatten(System.Util.IIterable, Function)
method S	intersect	public static IIterable intersect(System.Util.IIterable, System.Util.IIterable)
method S	last	public static var last(System.Util.IIterable)
method S	last	public static var last(System.Util.IIterable, bool)
method S	map	public static IIterable map(System.Util.IIterable, Function)
method S	reduce	public static var reduce(System.Util.IIterable, var, Function)
method S	skip	public static IIterable skip(System.Util.IIterable, int)
method S	take	public static IIterable take(System.Util.IIterable, int)
method S	toArray	public static var toArray(System.Util.IIterable)
method S	toList	public static System.Collection.List toList(System.Util.IIterable)
method S	toMap	public static System.Collection.Map toMap(System.Util.IIterable, Function)
method S	toMap	public static System.Collection.Map toMap(System.Util.IIterable, Function, Function)
method S	union	public static IIterable union(System.Util.IIterable, System.Util.IIterable)
method S	zip	public static IIterable zip(System.Util.IIterable, System.Util.IIterable, Function)

Methods

---

public static bool all(IIterable this, Function predicate)

Check if all of the items in the iterable can be asserted positively by the specified predicate. Returns false if at least one of them failed to pass the predicate.

Parameters

• this The iterable to check.
• predicate A function (bool fun(var)) that asserts each item. The method returns as soon as this predicate returns false.

Returns

• true if the predicate yields true for all of the items from the iterable; false if the predicate retruns false for at least one item thereof.

Throws

• System.Lang.RuntimeCheckException If the given function doesn't satisfy the required signature. This is a rather weak type enforcement to be performed at the beginning of this method to make it fail early. Even if it does pass this check, the function may very well fail later when being actually invoked, throwing various other exceptions indicative of type incompatibility.
• System.NullReferenceException If the given iterable is null.

public static bool any(IIterable this, Function predicate)

Check if at least one of the items in the iterable can be asserted positively by the specified predicate. Returns false if all of them failed to pass the predicate.

Parameters

• this The iterable to check.
• predicate A function (bool fun(var)) that asserts each item. The method returns as soon as this predicate returns true.

Returns

• true if the predicate yields true for at least one of the items from the iterable; false if the predicate retruns false for all of the constituent items.

Throws

• System.Lang.RuntimeCheckException If the given function doesn't satisfy the required signature. This is a rather weak type enforcement to be performed at the beginning of this method to make it fail early. Even if it does pass this check, the function may very well fail later when being actually invoked, throwing various other exceptions indicative of type incompatibility.
• System.NullReferenceException If the given iterable is null.

public static IIterable append(IIterable this, var extra)

Append one more item into this iterable to form a new iterable.

Unlike concat(), this method will always treat the argument extra as a single object. No matter what type or value it has, it will end up being added as the last item of the result iterable.

Parameters

• this The iterable to be appended to.
• extra The extra object to be appended to this iterable.

Returns

• A new iterable which combines all of its original items and the new item (extra).

Throws

• System.NullReferenceException If the given iterable is null.

public static IIterable concat(IIterable this, var extra)

Concatenate more items into this iterable to form a new iterable.

If the argument extra is an IIterable that is not a String, this method will add all of its items into the new iterable. This means if the extra iterable is empty, then nothing will be added.

If the argument is not an IIterable or is a String, then this method functions exactly like append().

Parameters

• this The iterable to filter from.
• extra The extra object to be concatenate into the new iterable.

Returns

• A new iterable which combines all of its original items and the new items.

Throws

• System.NullReferenceException If the given iterable is null.

public static int count(IIterable this)

Get the total number of items in the iterable.

Parameters

• this The iterable to count.

Returns

• The total number of items.

Throws

• System.NullReferenceException If the given iterable is null.

public static IIterable distinct(IIterable this)

Get a new iterable which only consists of the distinct elements from this iterable.

The distinction is determined by equals() if it's an Object, or the natural equality for primitive values.

Parameters

• this The source iterable.

Returns

• A new iterable which only consists of the distinct elements from this iterable.

Throws

• System.NullReferenceException If the given iterable is null.

public static IIterable except(IIterable this, IIterable another)

Get a new iterable which is a set-difference from this and another iterable.

The difference contains distinct elements which appear in the first (this) iterable but not the other one. In other words, (1) the result only contains elements coming from this iterable, and (2) these elements also do not appear in the other iterable. For example, set-{A, B, C, X, Y} except set-{C, E, F, X} = set-{A, B, Y}.

Duplicate elements, whether coming from the same iterable or not, are eliminated. The distinction is determined by equals() if it's an Object, or the natural equality for primitive values.

Parameters

• this The source iterable.
• another The other iterable.

Returns

• A new iterable which is the set-difference by deducting the second iterable from this one.

Throws

• System.NullReferenceException If the given iterable is null. Notably, the other iterable can be null, which is semantically equivalent to an empty iterable.

public static IIterable filter(IIterable this, Function predicate)

Invoke the predicate function aginst each item, and return an iterable that is comprised of only those items that are positively asserted by the predicate.

Parameters

• this The iterable to filter from.
• predicate A function (bool fun(var)) that decides if the item should be kept in the result iterable (true) or be discarded (false).

Returns

• A new Iterable with items filtered out by the predicate out of this Iterable.

Throws

• System.Lang.RuntimeCheckException If the given function doesn't satisfy the required signature. This is a rather weak type enforcement to be performed at the beginning of this method to make it fail early. Even if it does pass this check, the function may very well fail later when being actually invoked, throwing various other exceptions indicative of type incompatibility.
• System.NullReferenceException If the given iterable is null.

public static var first(IIterable this)

Returns the first item of the given iterable, or null if it is empty.

Parameters

• this The iterable to return the first item from.

Returns

• The first item of the given iterable if present, otherwise null.

Throws

• System.NullReferenceException If the given iterable is null.

public static var first(IIterable this, bool throwOnEmpty)

Returns the first item of the given iterable. Depending on throwOnEmpty, either returns null or throw an exception if the the iterable is empty.

Parameters

• this The iterable to return the first item from.
• throwOnEmpty If true, throw a System.IllegalStateException when the iterable is empty; if false, returns null instead.

Returns

• The first item of the given iterable if present, or null if throwOnEmpty is false.

Throws

• System.NullReferenceException If the given iterable is null.
• System.IllegalStateException If the iterable is empty, and throwOnEmpty is true.

public static IIterable flatten(IIterable this, Function mapper)

Project each item from the iterable to zero or more using the specified function. If the mapper returns a value of IIterable, then each constituent item will be added to the resultant iterable. Beware that if the mapper, for a given item, somehow returns an iterable that contains nothing, such as a zero-length array. That item would contribute no new items into the resultant iterable. So it's possible that this method returns an iterable that has an even smaller size than the input.

If the mapper returns a value that is not of IIterable, or if it returns a String, then the whole return value is added as a single item, exactly like what map() does.

Despite of implementing IIterable that consists of the characters, the String type will not be flattened by this method. This is a special treatment, since it is less likely one would want to create an iterable of chars. If such break-down is indeed desired, the user may convert the string to an array of char to explicitly return from the mapper function.

Parameters

• this The iterable to project from.
• mapper A function (var fun(var)) that projects one item to zero or more.

Returns

• A new iterable with items flatly projected from this iterable.

Throws

• System.Lang.RuntimeCheckException If the given function doesn't satisfy the required signature. This is a rather weak type enforcement to be performed at the beginning of this method to make it fail early. Even if it does pass this check, the function may very well fail later when being actually invoked, throwing various other exceptions indicative of type incompatibility.
• System.NullReferenceException If the given iterable is null.

public static IIterable intersect(IIterable this, IIterable another)

Get a new iterable which is a set-intersection from this and another iterable.

The intersection contains distinct elements which appear at least once in both iterables. Duplicate elements, whether coming from the same iterable or not, are eliminated. The distinction is determined by equals() if it's an Object, or the natural equality for primitive values.

Parameters

• this The source iterable.
• another The other iterable.

Returns

• A new iterable which is the set-intersection from the two iterables.

Throws

• System.NullReferenceException If the given iterable is null. Notably, the other iterable can be null, which is semantically equivalent to an empty iterable.

public static var last(IIterable this)

Returns the last item of the given iterable, or null if it is empty.

Parameters

• this The iterable to return the last item from.

Returns

• The last item of the given iterable if present, otherwise null.

Throws

• System.NullReferenceException If the given iterable is null.

public static var last(IIterable this, bool throwOnEmpty)

Returns the last item of the given iterable. Depending on throwOnEmpty, either returns null or throw an exception if the the iterable is empty.

Parameters

• this The iterable to return the last item from.
• throwOnEmpty If true, throw a System.IllegalStateException when the iterable is empty; if false, returns null instead.

Returns

• The last item of the given iterable if present, or null if throwOnEmpty is false.

Throws

• System.NullReferenceException If the given iterable is null.
• System.IllegalStateException If the iterable is empty, and throwOnEmpty is true.

public static IIterable map(IIterable this, Function mapper)

Project each item from the iterable to another using the specified function.

Parameters

• this The iterable to project from.
• mapper A function (var fun(var)) that projects one item to another.

Returns

• A new iterable with items projected from this iterable. Therefore the size remains the same.

Throws

• System.Lang.RuntimeCheckException If the given function doesn't satisfy the required signature. This is a rather weak type enforcement to be performed at the beginning of this method to make it fail early. Even if it does pass this check, the function may very well fail later when being actually invoked, throwing various other exceptions indicative of type incompatibility.
• System.NullReferenceException If the given iterable is null.

public static var reduce(IIterable this, var seed, Function reducer)

Performs a series of "folding" operation over the entire item set to produce a single value at the termination.

This method applies the reduction function (reducer) against each item with the result of the previous invocation. The first call uses the seed value (seed) as the previous result.

An example of using this method to calculate the sum of all elements in an int array:

  int[] array = new int[]{ ... };
  int result = array.reduce(0, (a, b) => a + b);

Parameters

• this The source iterable.
• seed Used as the first argument when the reducer is called for the first time.
• reducer A function (T fun(T, item)) that produces a value of arbitrary but consistent type T.

Returns

• The final result of applying the funciton to each item on top of the previous result.

Throws

• System.Lang.RuntimeCheckException If the given function doesn't satisfy the required signature. This is a rather weak type enforcement to be performed at the beginning of this method to make it fail early. Even if it does pass this check, the function may very well fail later when being actually invoked, throwing various other exceptions indicative of type incompatibility.
• System.NullReferenceException If the given iterable is null.

public static IIterable skip(IIterable this, int count)

Create a new iterable that consists of all the items of the given source iterable except the first N, where N is specified by count.

If the count is more than or equal to the length of the source iterable, the resultant iterable will contain nothing.

Parameters

• this The source iterable.
• count The number of items to skip from the source.

Returns

• A new iterable which contains all but the first count (or less) items of the source iterable.

Throws

• System.NullReferenceException If the given iterable is null.

public static IIterable take(IIterable this, int count)

Create a new iterable that consists of the first N items of the given source iterable, where N is specified by count.

If the count is more than the length of the source iterable, the resultant iterable will only contain all of whose that make up of te source. Therefore the new iterable's length can be less than count.

Parameters

• this The source iterable.
• count The number of items to take from the source.

Returns

• A new iterable which contains the first count (or less) items of the source iterable.

Throws

• System.NullReferenceException If the given iterable is null.

public static var toArray(IIterable this)

Convert the given iterable into an Array.

If the given iterable is already an array, this method creates a new array of the same type and copies each item over. Otherwise, usually an untyped array (var[]) is created to hold the copied items. For certain types such as System.Collection.Map a more precise array type may be used, but the caller must NOT count on this behavior.

Parameters

• this The source iterable.

Returns

• An array of appropriate type that contains all of the items from the source.

Throws

• System.NullReferenceException If the given iterable is null.

public static List toList(IIterable this)

Convert the given iterable into an System.Collection.List.

Parameters

• this The source iterable.

Returns

• A List that contains all of the items from the source.

Throws

• System.NullReferenceException If the given iterable is null.

public static Map toMap(IIterable this, Function toKey)

Convert the given iterable into a System.Collection.Map.

The caller must provide a function to produce a key from the item. The item itself will be stored as the value.

If more than one item produces the same key, only the first one will be added to the map, while the rest gets discarded.

Parameters

• this The source iterable.
• toKey A required function (var fun(var)) that converts an item to an object to be used as the map's key.

Returns

• A map in which the key is converted from each item by the provided function and the value is the item itself.

Throws

• System.Lang.RuntimeCheckException If the given function doesn't satisfy the required signature. This is a rather weak type enforcement to be performed at the beginning of this method to make it fail early. Even if it does pass this check, the function may very well fail later when being actually invoked, throwing various other exceptions indicative of type incompatibility.
• System.NullReferenceException If the given iterable, or the function (toKey) is null.

public static Map toMap(IIterable this, Function toKey, Function toValue)

Convert the given iterable into a System.Collection.Map.

The caller must provide a function to produce a key from the item, and may provide another function that converts the same item into a value. The key-value pair will be stored into the resultant map. If the value-producing function is null, a default one will be used which simply treats the item itself as the value.

If more than one item produces the same key, only the first one will be added to the map, while the rest gets discarded.

Parameters

• this The source iterable.
• toKey A required function (var fun(var)) that converts an item to an object to be used as the map's key.
• toValue An optional function (var fun(var)) that converts an item to an object to be used as the map's value.

Returns

• A map that contains key-value pairs converted from each item by the provided functions.

Throws

• System.Lang.RuntimeCheckException If either of the given functions doesn't satisfy the required signature. This is a rather weak type enforcement to be performed at the beginning of this method to make it fail early. Even if a function does pass this check, it may very well fail later when being actually invoked, throwing various other exceptions indicative of type incompatibility.
• System.NullReferenceException If the given iterable, or the key-producer function (toKey) is null.

public static IIterable union(IIterable this, IIterable another)

Get a new iterable which is a set-union from this and another iterable.

The union contains distinct elements from both iterables. Duplicate elements, whether coming from the same iterable or not, are eliminated. The distinction is determined by equals() if it's an Object, or the natural equality for primitive values.

Parameters

• this The source iterable.
• another The other iterable.

Returns

• A new iterable which is the set-union from the two iterables.

Throws

• System.NullReferenceException If the given iterable is null. Notably, the other iterable can be null, which is semantically equivalent to an empty iterable.

public static IIterable zip(IIterable this, IIterable second, Function zipper)

Invokes the specified function with each orderly matching pair of elements from the two iterables and yields the result into the resultant iterable, until either of the input iterables reaches the end. So if the two iterables are of different lengths, the returned iterable would have the same number of items as the shorter one.

Parameters

• this The first iterable to zip from.
• second The second iterable to zip from.
• zipper A function (var fun(var, var)) that yields a result out of the two paired items.

Returns

• A new iterable with items produced by the function from the pairs of the input iterables. Has the same size as the shorter one.

Throws

• System.Lang.RuntimeCheckException If the given function doesn't satisfy the required signature. This is a rather weak type enforcement to be performed at the beginning of this method to make it fail early. Even if it does pass this check, the function may very well fail later when being actually invoked, throwing various other exceptions indicative of type incompatibility.
• System.NullReferenceException If the given iterable is null.