Prototype JavaScript framework - Enumerable

inGroupsOf

2007-03-18T17:09:00Z

inGroupsOf(size[, filler = null]) -> [group...]

Groups items in fixed-size chunks, using a specific value to fill up the last chunk if necessary.

Example


var students = [
  { name: 'Sunny', age: 20 },  { name: 'Audrey', age: 21 },
  { name: 'Matt', age: 20 },   { name: 'Élodie', age: 26 },
  { name: 'Will', age: 21 },   { name: 'David', age: 23 },
  { name: 'Julien', age: 22 }, { name: 'Thomas', age: 21 },
  { name: 'Serpil', age: 22 }
];

students.pluck('name').inGroupsOf(4) {
// -> [ ['Sunny', 'Audrey', 'Matt', 'Élodie'],
//      ['Will', 'David', 'Julien', 'Thomas'],
//      ['Serpil', null, null, null] ]

eachSlice

2007-03-18T17:00:00Z

eachSlice(size[, iterator = Prototype.K[, context]]) -> [slice...]

Groups items in chunks based on a given size, with last chunk being possibly smaller.

Sometimes, you want to cut collections into chunks. Roughly equal-sized. Maybe you want to put it into multiple columns, or some other stylish layout. Maybe you can only pass so many at a time to a back-end processing layer (aaaah, those hard-coded, arbitrary limits in legacy software… ). Maybe you just feel like it. Just use eachSlice or its fixed-size variant, inGroupsOf.

The optional context parameter is what the iterator function will be bound to. If used, the this keyword inside the iterator will point to the object given by the argument.

Example


var students = [
  { name: 'Sunny', age: 20 },  { name: 'Audrey', age: 21 },
  { name: 'Matt', age: 20 },   { name: 'Élodie', age: 26 },
  { name: 'Will', age: 21 },   { name: 'David', age: 23 },
  { name: 'Julien', age: 22 }, { name: 'Thomas', age: 21 },
  { name: 'Serpil', age: 22 }
];

students.eachSlice(4, function(toon) {
  return toon.pluck('name');
})
// -> [ ['Sunny', 'Audrey', 'Matt', 'Élodie'],
//      ['Will', 'David', 'Julien', 'Thomas'],
//      ['Serpil'] ]

students.eachSlice(2).first()
// -> [{ name: 'Sunny', age: 20 }, { name: 'Audrey', age: 21 }]

size

2007-01-06T12:18:00Z

size() -> Number

Returns the size of the enumeration.

Examples


$R(1, 10).size()
// -> 10

['hello', 42, true].size()
// -> 3

$H().size()
// -> 0

Performance considerations

This method exists solely to provide a generic size-getting behavior for all objects enumerable. The default implementation actually performs the loop, which means it has exact linear complexity. Most objects that mix in Enumerable will try to optimize this by redefining their own version of size; this is, for instance, the case of Array, which redefines size to delegate to arrays’ native length property.

each

2006-10-29T22:16:00Z

each(iterator[, context]) -> Enumerable

The cornerstone of Enumerable. It lets you iterate over all the elements in a generic fashion, then returns the Enumerable, thereby allowing chain-calling.

Iterations based on each are the core of Enumerable. The iterator function you pass will be called with two parameters:

The current element in the iteration.
The numerical index, starting at zero, of the current cycle. This second parameter is unused (and therefore undeclared) most of the time, but can come in handy sometimes.

The optional context parameter is what the iterator function will be bound to. If used, the this keyword inside the iterator will point to the object given by the argument.

`$break` and `$continue`

The usage of $continue is deprecated. This feature will not be available in releases after Prototype 1.5 in favor of speed. Instead—since your blocks are in fact functions—simply issue a return statement. This will skip the rest of the block, jumping to the next iteration.

Regular loops can be short-circuited in JavaScript using the break and continue statements. However, when using iterator functions, your code is outside of the loop scope: the looping code happens behind the scene.

In order to provide you with equivalent (albeit less optimal) functionality, Prototype provides two global exception objects, $break and $continue. Throwing these is equivalent to using the corresponding native statement in a vanilla loop. These exceptions are properly caught internally by the each method.

Examples

['one', 'two', 'three'].each(function(s) {
  alert(s);
});

[ 'hello', 'world'].each(function(s, index) {
  alert(index + ': ' + s);
});
// alerts -> '0: hello' then '1: world'

// This could be done better with an accumulator using inject, but humor me
// here...
var result = [];
$R(1,10).each(function(n) {
  if (0 == n % 2)
    throw $continue;
  if (n > 6)
    throw $break;
  result.push(n);
});
// result -> [1, 3, 5]

`each` vs. `_each`

If you read the main Enumerable page, you may recall that in order for a class to mix in Enumerable, it has to provide the fundamental looping code appropriate to its internal structure. This basic iteration method must be called _each, and it only receives one argument: the iterator function. You’ll find further details on the main page.

Basically, Enumerable.each wraps the actual looping code provided by _each with:

Support for break/continue, as described above.
Proper maintenance and passing of the value/index arguments.

Optimized version

There is a very common use-case that will probably be better taken care of by a specialized variant: the method-calling scenario.

Say you want to invoke the same method on all elements, possibly with arguments. You may or may not want to use the result values. This can be achieved easily with invoke.

This variant usually performs better than each, since it avoids lexical closure costs. However, it does accumulate the result values in an array, which you might not need. At any rate, you might want to benchmark both options in your specific use case.

zip

2006-10-29T19:15:00Z

zip(Sequence...[, iterator = Prototype.K]) -> Array

Zips together (think of the zip on a pair of trousers) 2+ sequences, providing an array of tuples. Each tuple contains one value per original sequence. Tuples can be converted to something else by applying the optional iterator on them.

For those who never encountered a zip function before (i.e. have not worked enough with languages such as Haskell or Ruby ;-)), the exact behavior of this method might be difficult to grasp. Here are a few examples that should clear it up.

Examples


var firstNames = ['Justin', 'Mislav', 'Tobie', 'Christophe'];
var lastNames = ['Palmer', 'Marohnić', 'Langel', 'Porteneuve'];

firstNames.zip(lastNames)
// -> [['Justin', 'Palmer'], ['Mislav', 'Marohnić'], ['Tobie', 'Langel'], ['Christophe', 'Porteneuve']]

firstNames.zip(lastNames, function(a) { return a.join(' '); })
// -> ['Justin Palmer', 'Mislav Marohnić', 'Tobie Langel', 'Christophe Porteneuve']

var cities = ['Memphis', 'Zagreb', 'Montreal', 'Paris'];
firstNames.zip(lastNames, cities, function(p) {
  return p[0] + ' ' + p[1] + ', ' + p[2];
})
// -> ['Justin Palmer, Memphis', 'Mislav Marohnić, Zagreb', 'Tobie Langel, Montreal', 'Christophe Porteneuve, Paris']

firstNames.zip($R(1, 100), function(a) { return a.reverse().join('. '); })
// -> ['1. Justin', '2. Mislav', '3. Tobie', '4. Christophe']

toArray

2006-10-29T19:14:00Z

toArray() -> Array

Returns an Array representation of the enumeration. Aliased as entries.

Note: this makes any object that mixes in Enumerable amenable to the $A utility function.

Examples


$R(1, 5).toArray()
// -> [1, 2, 3, 4, 5]

Performance considerations

Obviously, objects that mix in Enumerable may override the default code, as Array does.

sortBy

2006-10-29T19:13:00Z

sortBy(iterator[, context]) -> Array

Provides a custom-sorted view of the elements based on the criteria computed, for each element, by the iterator.

Elements of equivalent criterion value are left in existing order. Computed criteria must have well-defined strict weak ordering semantics (i.e. the < operator must exist between any two criteria).

Note that arrays already feature a native sort method, which relies on natural ordering of the array's elements (i.e. the semantics of the < operator when applied to two such elements). You should use sortBy only whe natural ordering is nonexistent or otherwise unsatisfactory.

The optional context parameter is what the iterator function will be bound to. If used, the this keyword inside the iterator will point to the object given by the argument.

Examples


['hello', 'world', 'this', 'is', 'nice'].sortBy(function(s) { return s.length; })
// -> 'is', 'this', 'nice', 'hello', 'world']

['hello', 'world', 'this', 'is', 'cool'].sortBy(function(s) {
  var md = s.match(/[aeiouy]/g);
  return null == md ? 0 : md.length;
})
// -> [ 'world', 'this', 'is', 'hello', 'cool'] (sorted by vowel count)

reject

2006-10-29T19:12:00Z

reject(iterator[, context]) -> Array

Returns all the elements for which the iterator returned false.

The optional context parameter is what the iterator function will be bound to. If used, the this keyword inside the iterator will point to the object given by the argument.

Examples


$R(1, 10).reject(function(n) { return 0 == n % 2; })
// -> [1, 3, 5, 7, 9]

[ 'hello', 'world', 'this', 'is', 'nice'].reject(function(s) {
  return s.length >= 5;
})
// -> ['this', 'is', 'nice']

select

2006-10-29T19:12:00Z

select(iterator) -> Array

Alias for the findAll method.

pluck

2006-10-29T19:11:00Z

pluck(propertyName) -> Array

Optimization for a common use-case of collect: fetching the same property for all the elements. Returns the property values.

Since it avoids the cost of a lexical closure over an anonymous function (like you would do with collect), this performs much better.

Perhaps more importantly, it definitely makes for more concise and more readable source code.

Examples


['hello', 'world', 'this', 'is', 'nice'].pluck('length')
// -> [5, 5, 4, 2, 4]

document.getElementsByClassName('superfluous').pluck('tagName').sort().uniq()
// -> sorted list of unique canonical tag names for elements with this
// specific CSS class...

partition

2006-10-29T19:10:00Z

partition([iterator = Prototype.K[, context]]) -> [TrueArray, FalseArray]

Partitions the elements in two groups: those regarded as true, and those considered false. By default, regular JavaScript boolean equivalence is used, but an iterator can be provided, that computes a boolean representation of the elements.

This is a preferred solution to using both findAll/select and reject: it only loops through the elements once!

The optional context parameter is what the iterator function will be bound to. If used, the this keyword inside the iterator will point to the object given by the argument.

Examples

['hello', null, 42, false, true, , 17].partition()
// -> [['hello', 42, true, 17], [null, false, undefined]]

$R(1, 10).partition(function(n) {
  return 0 == n % 2;
})
// -> [[2, 4, 6, 8, 10], [1, 3, 5, 7, 9]]

member

2006-10-29T19:07:00Z

member(object) -> Boolean

Determines whether a given object is in the Enumerable or not, based on the == comparison operator. Convenience alias for include.

min

2006-10-29T19:07:00Z

min([iterator = Prototype.K[, context]]) -> minValue

Returns the minimum element (or element-based computation), or undefined if the enumeration is empty. Elements are either compared directly, or by first applying the iterator and comparing returned values.

Note: for equivalent elements, the earliest one is returned.

The optional context parameter is what the iterator function will be bound to. If used, the this keyword inside the iterator will point to the object given by the argument.

Examples


$R(1,10).min()
// -> 1

['hello', 'world', 'gizmo'].min()
// -> 'gizmo'

function Person(name, age) {
   this.name = name;
   this.age = age;
}

var john = new Person('John', 20);
var mark = new Person('Mark', 35);
var daisy = new Person('Daisy', 22);

[john, mark, daisy].min(function(person) {
  return person.age;
})
// -> 20

map

2006-10-29T19:06:00Z

map(iterator) -> Array

Returns the results of applying the iterator to each element. Convenience alias for collect.

max

2006-10-29T19:02:00Z

max([iterator = Prototype.K[, context]]) -> maxValue

Returns the maximum element (or element-based computation), or undefined if the enumeration is empty. Elements are either compared directly, or by first applying the iterator and comparing returned values.

Note: for equivalent elements, the latest one is returned.

The optional context parameter is what the iterator function will be bound to. If used, the this keyword inside the iterator will point to the object given by the argument.

Examples


$R(1,10).max()
// -> 10

['hello', 'world', 'gizmo'].max()
// -> 'world'

function Person(name, age) {
   this.name = name;
   this.age = age;
}

var john = new Person('John', 20);
var mark = new Person('Mark', 35);
var daisy = new Person('Daisy', 22);

[john, mark, daisy].max(function(person) {
  return person.age;
})
// -> 35

Prototype JavaScript framework - Enumerable

inGroupsOf

Example

See also

eachSlice

Example

See also

size

Examples

Performance considerations

each

`$break` and `$continue`

Examples

`each` vs. `_each`

Optimized version

zip

Examples

toArray

Examples

Performance considerations

sortBy

Examples

reject

Examples

See also

select

pluck

Examples

See also

partition

Examples

member

min

Examples

map

max

Examples

Prototype JavaScript framework - Enumerable

inGroupsOf

Example

See also

eachSlice

Example

See also

size

Examples

Performance considerations

each

$break and $continue

Examples

each vs. _each

Optimized version

zip

Examples

toArray

Examples

Performance considerations

sortBy

Examples

reject

Examples

See also

select

pluck

Examples

See also

partition

Examples

member

min

Examples

map

max

Examples

`$break` and `$continue`

`each` vs. `_each`