can-list

can-list

• can-list
  • new List([array])
  • new List(deferred)
    • List.extend([name,] [staticProperties,] instanceProperties)
    • Map can-map
    • list.attr()
    • list.attr(index)
    • list.attr(index, value)
    • list.attr(elements[, replaceCompletely])
    • list.filter(filterFunc, context)
    • list.splice(index[, howMany[, ...newElements]])
    • list.each( callback(item, index) )
    • list.reverse()
    • list.map( callback(item, index, listReference), context )

API

can-list

new List([array])

Create an observable array-like object.

1. array {Array}: Items to seed the List with.

• returns {can-list}: An instance of List with the elements from array.

new List(deferred)

1. deferred {can.Deferred}: A deferred that resolves to an array. When the deferred resolves, its values will be added to the list.

• returns {can-list}: An initially empty List.

List.extend([name,] [staticProperties,] instanceProperties)

Creates a new extended constructor function. Learn more at [can.Construct.extend].

var MyList = List.extend({}, {
	// silly unnecessary method
	count: function(){
		return this.attr('length');
	}
});

var list = new MyList([{}, {}]);
console.log(list.count()); // -> 2

1. name {String}: If provided, adds the extened List constructor function to the window at the given name.

2. staticProperties {Object}: Properties and methods directly on the constructor function. The most common property to set is Map.

3. instanceProperties {Object}: Properties and methods on instances of this list type.

Map {can-map}

Specify the Map type used to make objects added to this list observable.

can-map

When objects are added to a List, those objects are converted into can.Map instances. For example:

 var list = new List();
 list.push({name: "Justin"});

 var map = list.attr(0);
 map.attr("name") //-> "Justin"

By changing Map, you can specify a different type of Map instance to create. For example:

 var User = Map.extend({
   fullName: function(){
     return this.attr("first")+" "+this.attr("last")
   }
 });

 User.List = List.extend({
   Map: User
 }, {});

 var list = new User.List();
 list.push({first: "Justin", last: "Meyer"});

 var user = list.attr(0);
 user.fullName() //-> "Justin Meyer"

list.attr()

Gets an array of all the elements in this List.

• returns {Array}: An array with all the elements in this List.

list.attr(index)

Reads an element from this List.

1. index {Number}: The element to read.

• returns {*}: The value at index.

list.attr(index, value)

Assigns value to the index index on this List, expanding the list if necessary.

1. index {Number}: The element to set.
2. value {*}: The value to assign at index.

• returns {}: This list, for chaining.

list.attr(elements[, replaceCompletely])

Merges the members of elements into this List, replacing each from the beginning in order. If elements is longer than the current List, the current List will be expanded. If elements is shorter than the current List, the extra existing members are not affected (unless replaceCompletely is true). To remove elements without replacing them, use [can-map::removeAttr removeAttr].

1. elements {Array}: An array of elements to merge in.

2. replaceCompletely {bool}: whether to completely replace the elements of List

If replaceCompletely is true and elements is shorter than the List, the existing extra members of the List will be removed.

• returns {}: This list, for chaining.

list.filter(filterFunc, context)

1. filterFunc {function(item, index, undefined)}: A function to call with each element of the list. Returning false will remove the index.
2. context {Object}: The object to use as this inside the callback.

list.splice(index[, howMany[, ...newElements]])

1. index {Number}: where to start removing or inserting elements

2. howMany {Number}: the number of elements to remove If howMany is not provided, splice will remove all elements from index to the end of the List.

3. newElements {*}: elements to insert into the List

• returns {Array}: the elements removed by splice

list.each( callback(item, index) )

each iterates through the List, calling a function for each element.

var list = new List([1, 2, 3]);

list.each(function(elem){
	console.log(elem);
});

1. callback {function(*, Number)}: the function to call for each element The value and index of each element will be passed as the first and second arguments, respectively, to the callback. If the callback returns false, the loop will stop. The callback is not invoked for List elements that were never initialized.

• returns {}: this List, for chaining

list.reverse()

reverse reverses the elements of the List in place.

• returns {can-list}: the List, for chaining

list.map( callback(item, index, listReference), context )

1. callback {function(*, Number, undefined)}: A function to call with each element of the list.
2. context {Object}: An optional object to use as this inside the callback.

• returns {}: A new can.List instance.

Contributing

Making a Build

To make a build of the distributables into dist/ in the cloned repository run

npm install
node build

Running the tests

Tests can run in the browser by opening a webserver and visiting the test.html page. Automated tests that run the tests from the command line in Firefox can be run with

npm test