angular.Array.filter.html

<h1>angular.Array.filter</h1>
<fieldset class="workInProgress">
  <legend>Work In Progress</legend>
  This page is currently being revised. It might be incomplete or contain inaccuracies.
  
</fieldset>
<h2>Description</h2>
<p>Selects a subset of items from <code>array</code> and returns it as a new array.</p>

<p>Note: this function is used to augment the Array type in angular expressions. See
<a href="#!angular.Array"><code>angular.Array</code></a> for more info.</p>
<h2>Usage</h2>
<tt ng:non-bindable>
angular.Array.filter(array, expression);
</tt>
<h3>Parameters</h3>
<ul>
    <li><tt>array</tt> –
      <tt>&#123;Array&#125;</tt>
      <tt></tt>
      – The source array.</li>
    <li><tt>expression</tt> –
      <tt>&#123;string|Object|function()&#125;</tt>
      <tt></tt>
      – The predicate to be used for selecting items from
  <code>array</code>.</p>
<p>Can be one of:</p>
<ul>
<li><p><code>string</code>: Predicate that results in a substring match using the value of <code>expression</code>
string. All strings or objects with string properties in <code>array</code> that contain this string
will be returned. The predicate can be negated by prefixing the string with <code>!</code>.</p></li>
<li><p><code>Object</code>: A pattern object can be used to filter specific properties on objects contained
by <code>array</code>. For example <code>{name:"M", phone:"1"}</code> predicate will return an array of items
which have property <code>name</code> containing "M" and property <code>phone</code> containing "1". A special
property name <code>$</code> can be used (as in <code>{$:"text"}</code>) to accept a match against any
property of the object. That's equivalent to the simple substring match with a <code>string</code>
as described above.</p></li>
<li><p><code>function</code>: A predicate function can be used to write arbitrary filters. The function is
called for each element of <code>array</code>. The final result is an array of those elements that
the predicate returned true for.</p></li>
</ul></li>
  </ul>
<h2>Example</h2>
<doc:example>
  <doc:source>
&lt;div ng:init="friends = [{name:'John', phone:'555-1276'},
                         {name:'Mary', phone:'800-BIG-MARY'},
                         {name:'Mike', phone:'555-4321'},
                         {name:'Adam', phone:'555-5678'},
                         {name:'Julie', phone:'555-8765'}]"&gt;&lt;/div&gt;

Search: &lt;input name="searchText"/&gt;
&lt;table id="searchTextResults"&gt;
  &lt;tr&gt;&lt;th&gt;Name&lt;/th&gt;&lt;th&gt;Phone&lt;/th&gt;&lt;tr&gt;
  &lt;tr ng:repeat="friend in friends.$filter(searchText)"&gt;
    &lt;td&gt;{{friend.name}}&lt;/td&gt;
    &lt;td&gt;{{friend.phone}}&lt;/td&gt;
  &lt;tr&gt;
&lt;/table&gt;
&lt;hr&gt;
Any: &lt;input name="search.$"/&gt; &lt;br&gt;
Name only &lt;input name="search.name"/&gt;&lt;br&gt;
Phone only &lt;input name="search.phone"/&gt;&lt;br&gt;
&lt;table id="searchObjResults"&gt;
  &lt;tr&gt;&lt;th&gt;Name&lt;/th&gt;&lt;th&gt;Phone&lt;/th&gt;&lt;tr&gt;
  &lt;tr ng:repeat="friend in friends.$filter(search)"&gt;
    &lt;td&gt;{{friend.name}}&lt;/td&gt;
    &lt;td&gt;{{friend.phone}}&lt;/td&gt;
  &lt;tr&gt;
&lt;/table&gt;
  </doc:source>
  <doc:scenario>     it('should search across all fields when filtering with a string', function() {
       input('searchText').enter('m');
       expect(repeater('#searchTextResults tr', 'friend in friends').column('name')).
         toEqual(['Mary', 'Mike', 'Adam']);
       input('searchText').enter('76');
       expect(repeater('#searchTextResults tr', 'friend in friends').column('name')).
         toEqual(['John', 'Julie']);
     });
     it('should search in specific fields when filtering with a predicate object', function() {
       input('search.$').enter('i');
       expect(repeater('#searchObjResults tr', 'friend in friends').column('name')).
         toEqual(['Mary', 'Mike', 'Julie']);
     });</doc:scenario>
</doc:example>