Stack operations for the jQuery chain

[gibson042]

Since the jQuery chain is functionally a stack, it might be useful (for both documentation and development) to explicitly recognize it as such and expose stack operations upon it. To that purpose, I propose standardizing peek/pop nomenclature as "back" instead of "end", with the following implications:

stack	jQuery	implementation	notes
stack.push	.pushStack( elements [, name, selector] )		already present and used by filters/traversing/etc.
stack.peek stack.pop	.back( [depth] )	var ret = this; do { ret = ret.prevObject; } while ( ret && --depth >= 0 ); return ret || this.constructor();	new method: .end should alias to this
stack.push( stack.peek() + stack.peek(1) )	.addBack( [depth] [, filter] )	if ( typeof depth !== "number" ) { filter = depth; depth = 0; } var back = this.back( depth ); return this.add( filter == null ? back : back.filter( filter ) );	new method: .andSelf should alias to this
stack.length	depth		not implemented unless we replace .prevObject with an array

[cowboy]

The "jQuery chain" is functionally a singly linked list, not a stack.

[gibson042]

It is a linear collection restricting addition and removal to the same end. The linked list implementation is not relevant to the stack interface, which is the subject of this ticket.

[addyosmani]

@gibson042: even if it's a collection that restricts addition and removal to the same end, could you justify why this set of changes would be useful?

[gibson042]

These changes are useful for the same reasons as #9800, only moreso.

We already implement the stack operations, but their naming and use is haphazard. Consistent terminology will support predictable and intuitive understanding.
Example: Instead of $elements.andSelf() as a shortcut for $elements.add( $elements.end() ), we have $elements.addBack() as a shortcut for $elements.add( $elements.back() ).

The depth parameters could be dropped (and I'd still support these changes even if they were), but they are an obvious modifier to the "back" operation: how far back?
Example:

// highlight matching definitions and their corresponding terms,
// skipping non-matching definitions of the same term
jQuery( "dd", context ) // all <dd>s
  .filter( matches ) // matching <dd>s

  .prevUntil("dt") // intervening <dd>s
  .addBack() // all <dd>s for matching <dt>s
  .prev("dt") // matching <dt>s

  .addBack(2) // matching <dd>s plus their <dt>s

  .each( highlight ); // add styling/data/listeners/etc.

[dmethvin]

I like the idea of renaming .andSelf() to something more logical, which is also proposed in #9800, and the .addBack() name is better than .andPrior() IMO, especially since we are truly adding things to the set.

On the rest, I don't see a compelling reason to add anything. There may be things you want to do to a generic stack that aren't commonly needed for our chain of jQuery .prevObjects. I agree these let you do more things with chaining, but they aren't things people have clamored to do over the past five years.

[dmethvin]

It doesn't sound like there's a lot of enthusiasm for adding these to core, although #9800 remains open for the rename of .andSelf().