Config
Table of Contents

Class

O.ObservableArray

Extends
O.Object
Includes
O.ObservableRange, O.Enumerable, O.MutableEnumerable

The ObservableArray class provides an object with the same interface as the standard array but with the difference that properties or even ranges can be observed. Note, all access must be via getObjectAt/setObjectAt, not direct array[i].

"use strict";

( function ( NS, undefined ) {

var splice = Array.prototype.splice;
var slice = Array.prototype.slice;

var ObservableArray = NS.Class({

 Extends: NS.Object,

 Mixin: [ NS.ObservableRange, NS.Enumerable, NS.MutableEnumerable ],

Constructor

O.ObservableArray( array, mixin )

Parameters

arrayArray Optional The initial contents of the array.
mixinObject Optional
init: function ( array, mixin ) {
   this._array = array || [];
   this._length = this._array.length;

   ObservableArray.parent.init.call( this, mixin );
 },

Property

O.ObservableArray#[]

  • Array

The standard array underlying the object. Observers of this property will be notified any time any content changes in the array. Setting this property changes the entire contents of the array at once. The contents of the new array is checked for equality with that of the old array to ensure accurate notification of the changed range.

'[]': function ( array ) {
   if ( array ) {
     var oldArray = this._array,
       oldLength = this._length,
       newLength = array.length,
       start = 0,
       end = newLength;

     this._array = array;
     this._length = newLength;

     while ( ( start < newLength ) &&
         ( array[ start ] === oldArray[ start ] ) ) {
       start += 1;
     }
     if ( newLength === oldLength ) {
       var last = end - 1;
       while ( ( end > start ) &&
           ( array[ last ] === oldArray[ last ] ) ) {
         end = last;
         last -= 1;
       }
     } else {
       end = Math.max( oldLength, newLength );
       this.propertyDidChange( 'length', oldLength, newLength );
     }

     if ( start !== end ) {
       this.rangeDidChange( start, end );
     }
   }
   return this._array.slice();
 }.property(),

Method

O.ObservableArray#getObjectAt( index )

Returns the value at the index given in the array.

Parameters

indexNumber The index of the value to return.

Returns

* The value at index i in this array.

getObjectAt: function ( index ) {
   return this._array[ index ];
 },

Property

O.ObservableArray#length

  • Number

The length of the array.

length: function ( value ) {
   var length = this._length;
   if ( typeof value === 'number' && value !== length ) {
     this._array.length = value;
     this._length = value;
     if ( value < length ) {
       this.rangeDidChange( value, length );
     }
     length = value;
   }
   return length;
 }.property().nocache(),

Method

O.ObservableArray#setObjectAt( index, value )

Sets the value at a given index in the array.

Parameters

indexNumber The index at which to set the value.
value* The value to set it to.

Returns

O.ObservableArray Returns self.

setObjectAt: function ( index, value ) {
   this._array[ index ] = value;
   var length = this._length;
   if ( length <= index ) {
     this._length = index + 1;
     this.propertyDidChange( 'length', length, index + 1 );
   }
   this.rangeDidChange( index );
   return this;
 },

Method

O.ObservableArray#replaceObjectsAt( index, numberRemoved, newItems )

Removes a given number of objects from the array, starting at the index given, and inserts a number of objects in their place.

Parameters

indexNumber The index at which to remove/add objects.
numberRemovedNumber The number of objects to remove.
newItemsArray Optional The objects to insert.

Returns

Array Returns an array of the removed objects.

replaceObjectsAt: function ( index, numberRemoved, newItems ) {
   var oldLength = this._length,
     array = this._array,
     removed, newLength, i, l;

   newItems = newItems ? slice.call( newItems ) : [];

   if ( oldLength <= index ) {
     for ( i = 0, l = newItems.length; i < l; i += 1 ) {
       array[ index + i ] = newItems[i];
     }
   } else {
     newItems.unshift( index, numberRemoved );
     removed = splice.apply( array, newItems );
   }
   newLength = array.length;
   if ( oldLength !== newLength ) {
     this._length = newLength;
     this.propertyDidChange( 'length', oldLength, newLength );
     this.rangeDidChange( index, Math.max( oldLength, newLength ) );
   } else {
     this.rangeDidChange( index, index + numberRemoved );
   }
   return removed || [];
 },

 // :: Mutation methods =====================================================

Method

O.ObservableArray#sort( comparefn )

ECMAScript Array#sort.

Parameters

comparefnFunction Optional The function to use to compare two items in the array.

Returns

O.ObservableArray Returns self.

sort: function ( comparefn ) {
   this._array.sort( comparefn );
   this.rangeDidChange( 0, this._length );
   return this;
 },

Method

O.ObservableArray#reverse()

ECMAScript Array#reverse.

Returns

O.ObservableArray Returns self.

reverse: function () {
   this._array.reverse();
   this.rangeDidChange( 0, this._length );
   return this;
 },

 // :: Accessor methods =====================================================

Method

O.ObservableArray#concat( )

ECMAScript Array#concat.

Parameters

var_args...Array The arrays to concatenate with this array.

Returns

Array Returns new concatenated array.

concat: function () {
   var args = [],
     i, l, item;
   for ( i = 0, l = arguments.length; i < l; i += 1 ) {
     item = arguments[i];
     args[i] = item instanceof ObservableArray ? item._array : item;
   }
   return Array.prototype.concat.apply( this._array, args );
 },

Method

O.ObservableArray#join( separator )

ECMAScript Array#join.

Parameters

separatorString Optional The string to insert between each item (defaults to ',').

Returns

String Concatenated string of all items joined by separator string.

join: function ( separator ) {
   return this._array.join( separator );
 },

Method

O.ObservableArray#slice( start, end )

ECMAScript Array#slice.

Parameters

startNumber Optional The index of the first item to include.
endNumber Optional One past the index of the last item to include.

Returns

Array Shallow copy of the underlying array between the given indexes.

slice: function ( start, end ) {
   return this._array.slice( start, end );
 }
});

NS.ObservableArray = ObservableArray;

}( O ) );
Animation
Application
Core
DataStore
DOM
DragDrop
Foundation
IO
Localisation
Selection
Parser
TimeZones
Storage
Touch
CollectionViews
UA
ContainerViews
ControlViews
PanelViews
View