Difference between revisions of "API:EPrints/List"

From EPrints Documentation
Jump to: navigation, search
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- Pod2Wiki=_preamble_  
 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
−
  -->
+
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/List.pm|package_name=EPrints::List}}[[Category:API|LIST]][[Category:API:EPrints/List|LIST]]<div><!-- Edit below this comment -->
−
__NOTOC__
 
−
{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/List.pm|package_name=EPrints::List}}[[Category:API|List]]<div><!-- Edit below this comment -->
 
  
  
−
<!-- Pod2Wiki=head_name --></div>
+
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 
==NAME==
 
==NAME==
 
'''EPrints::List''' - List of data objects, usually a search result.
 
'''EPrints::List''' - List of data objects, usually a search result.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=head_synopsis --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_synopsis -->
 
==SYNOPSIS==
 
==SYNOPSIS==
−
  use EPrints::List;
 
−
 
 
−
  $list = EPrints::List-&gt;new( session =&gt; $session, dataset =&gt; $dataset, ids =&gt; $ids); # ref to an array of ids to populate the list with
 
−
 
 
 
   $new_list = $list-&gt;reorder( "-creation_date" ); # makes a new list ordered by reverse order creation_date
 
   $new_list = $list-&gt;reorder( "-creation_date" ); # makes a new list ordered by reverse order creation_date
 
    
 
    
Line 38: Line 34:
 
    
 
    
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=head_description --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_description -->
 
==DESCRIPTION==
 
==DESCRIPTION==
 
This class represents an ordered list of objects, all from the same dataset. Usually this is the results of a search.  
 
This class represents an ordered list of objects, all from the same dataset. Usually this is the results of a search.  
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_see_also_l_eprints_search -->
 +
==SEE ALSO [[API:EPrints/Search|EPrints::Search]]==
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=head_see_also_l_eprints_search --></div>
+
<!-- Pod2Wiki= -->
−
==SEE ALSO ==
+
</div>
 +
<!-- Pod2Wiki=head_methods -->
 +
==METHODS==
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_new --></div>
+
<!-- Pod2Wiki= -->
−
===$list = EPrints::List-&gt;new( session =&gt; $session, dataset =&gt; $dataset, [desc =&gt; $desc], [desc_order =&gt; $desc_order], ids =&gt; $ids, [encoded =&gt; $encoded], [keep_cache =&gt; $keep_cache], [order =&gt; $order] );===
+
</div>
 +
<!-- Pod2Wiki=item_new -->
 +
===new===
  
 +
$list = EPrints::List-&gt;new( session =&gt; $session, dataset =&gt; $dataset, [desc =&gt; $desc], [desc_order =&gt; $desc_order], ids =&gt; $ids, [encoded =&gt; $encoded], [keep_cache =&gt; $keep_cache], [order =&gt; $order] );
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_new --></div>
+
<!-- Pod2Wiki= -->
−
===$list = EPrints::List-&gt;new( session =&gt; $session, dataset =&gt; $dataset, [desc =&gt; $desc], [desc_order =&gt; $desc_order], cache_id =&gt; $cache_id );===
+
</div>
 +
<!-- Pod2Wiki=item_new -->
 +
===new===
  
 +
$list = EPrints::List-&gt;new( session =&gt; $session, dataset =&gt; $dataset, [desc =&gt; $desc], [desc_order =&gt; $desc_order], cache_id =&gt; $cache_id );
 
Creates a new list object in memory only. Lists will be cached if anything method requiring order is called, or an explicit  cache() method is called.
 
Creates a new list object in memory only. Lists will be cached if anything method requiring order is called, or an explicit  cache() method is called.
  
 
encoded is the serialised version of the searchExpression which created this list, if there was one.
 
encoded is the serialised version of the searchExpression which created this list, if there was one.
  
−
If keep_cache is set then the cache will not be disposed of at the end of the current $session. If cache_id is set then keep_cache is automatically true.
+
If keep_cache is set then the cache will not be disposed of at the end of the current $repository operation. If cache_id is set then keep_cache is automatically true.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_new --></div>
+
<!-- Pod2Wiki= -->
−
===$list = EPrints::List-&gt;new( session =&gt; $session, dataset =&gt; $dataset, ids =&gt; $ids, # a ref to the array of ids [order =&gt; $order] ); # the field on which to order the list===
+
</div>
 +
<!-- Pod2Wiki=item_new -->
 +
===new===
  
 +
$list = EPrints::List-&gt;new( session =&gt; $session, dataset =&gt; $dataset, ids =&gt; $ids, [order =&gt; $order] );
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_new --></div>
+
<!-- Pod2Wiki= -->
−
===$list = EPrints::List-&gt;new( session =&gt; $session, dataset =&gt; $dataset, [desc =&gt; $desc], [desc_order =&gt; $desc_order], cache_id =&gt; $cache_id );===
+
</div>
 +
<!-- Pod2Wiki=item_new -->
 +
===new===
 +
 
 +
$list = EPrints::List-&gt;new( session =&gt; $session, dataset =&gt; $dataset, [desc =&gt; $desc], [desc_order =&gt; $desc_order], cache_id =&gt; $cache_id );
 +
Note the new() method will be called very rarely since lists will usually created by an EPrints::Search.
  
 
Creates a new list object in memory only. Lists will be cached if any method requiring order is called, or an explicit  cache() method is called.
 
Creates a new list object in memory only. Lists will be cached if any method requiring order is called, or an explicit  cache() method is called.
Line 98: Line 121:
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_reorder --></div>
+
<!-- Pod2Wiki= -->
−
===$new_list = $list-&gt;reorder( $new_order );===
+
</div>
 +
<!-- Pod2Wiki=item_reorder -->
 +
===reorder===
  
 +
$new_list = $list-&gt;reorder( $new_order );
 
Create a new list from this one, but sorted in a new way.
 
Create a new list from this one, but sorted in a new way.
  
Line 110: Line 136:
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_union --></div>
+
<!-- Pod2Wiki= -->
−
===$new_list = $list-&gt;union( $list2, [$order] );===
+
</div>
 +
<!-- Pod2Wiki=item_union -->
 +
===union===
  
 +
$new_list = $list-&gt;union( $list2, [$order] );
 
Create a new list from this one plus another one. If order is not set then this list will not be in any certain order.
 
Create a new list from this one plus another one. If order is not set then this list will not be in any certain order.
  
Line 124: Line 153:
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_remainder --></div>
+
<!-- Pod2Wiki= -->
−
===$new_list = $list-&gt;remainder( $list2, [$order] );===
+
</div>
 +
<!-- Pod2Wiki=item_remainder -->
 +
===remainder===
  
−
Create a new list from this one minus another one. If order is not set then this list will not be in any certain order.
+
$new_list = $list-&gt;remainder( $list2, [$order] );
 +
Create a new list from $list with elements from $list2 removed. If order is not set then this list will not be in any certain order.
  
 
Remove all items in $list2 from $list and return the result as a new EPrints::List.
 
Remove all items in $list2 from $list and return the result as a new EPrints::List.
Line 140: Line 172:
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_intersect --></div>
+
<!-- Pod2Wiki= -->
−
===$new_list = $list-&gt;intersect( $list2, [$order] );===
+
</div>
 +
<!-- Pod2Wiki=item_intersect -->
 +
===intersect===
  
 +
$new_list = $list-&gt;intersect( $list2, [$order] );
 
Create a new list containing only the items which are in both lists. If order is not set then this list will not be in any certain order.
 
Create a new list containing only the items which are in both lists. If order is not set then this list will not be in any certain order.
  
Line 154: Line 189:
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_cache --></div>
+
<!-- Pod2Wiki= -->
−
===$list-&gt;cache===
+
</div>
 +
<!-- Pod2Wiki=item_cache -->
 +
===cache===
  
 +
$list-&gt;cache
 
Cause this list to be cached in the database.
 
Cause this list to be cached in the database.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=end -->
 +
InternalDoc<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_get_cache_id --></div>
+
<!-- Pod2Wiki= -->
−
===$cache_id = $list-&gt;get_cache_id===
+
</div>
 +
<!-- Pod2Wiki=item_get_cache_id -->
 +
===get_cache_id===
  
 +
$cache_id = $list-&gt;get_cache_id
 
Return the ID of the cache table for this list, or undef.
 
Return the ID of the cache table for this list, or undef.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_dispose --></div>
+
<!-- Pod2Wiki= -->
−
===$list-&gt;dispose===
+
</div>
 +
<!-- Pod2Wiki=end -->
 +
InternalDoc<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_dispose -->
 +
===dispose===
 +
 +
$list-&gt;dispose
 
Clean up the cache table if appropriate.
 
Clean up the cache table if appropriate.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=end -->
 +
InternalDoc<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_count --></div>
+
<!-- Pod2Wiki= -->
−
===$n = $list-&gt;count ===
+
</div>
 +
<!-- Pod2Wiki=item_count -->
 +
===count===
  
 +
$n = $list-&gt;count
 
Return the number of values in this list.
 
Return the number of values in this list.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_item --></div>
+
<!-- Pod2Wiki= -->
−
===$dataobj = $list-&gt;item( $offset )===
+
</div>
 +
<!-- Pod2Wiki=item_item -->
 +
===item===
  
 +
$dataobj = $list-&gt;item( $offset )
 
Returns the item at offset $offset.
 
Returns the item at offset $offset.
  
Line 206: Line 280:
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_slice --></div>
+
<!-- Pod2Wiki= -->
−
===@dataobjs = $list-&gt;slice( [$offset], [$count] )===
+
</div>
 +
<!-- Pod2Wiki=item_slice -->
 +
===slice===
  
 +
@dataobjs = $list-&gt;slice( [$offset], [$count] )
 
Returns the DataObjs in this list as an array.  $offset - what index through the list to start from. $count - the maximum to return.
 
Returns the DataObjs in this list as an array.  $offset - what index through the list to start from. $count - the maximum to return.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_ids --></div>
+
<!-- Pod2Wiki= -->
−
===$ids = $list-&gt;ids( [$offset], [$count] )===
+
</div>
 +
<!-- Pod2Wiki=item_ids -->
 +
===ids===
  
−
Return a reference to an array containing the ids of the specified range from the list. This is more efficient if you just need the ids.
+
$ids = $list-&gt;ids( [$offset], [$count] )
 +
Return a reference to an array containing the object ids of the items  in the list. You can specify a range of ids using $offset and $count. This is more efficient if you just need the ids.
  
 
$offset - what index through the list to start from. $count - the maximum to return.
 
$offset - what index through the list to start from. $count - the maximum to return.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_map --></div>
+
<!-- Pod2Wiki= -->
−
===$list-&gt;map( $function, $info )===
+
</div>
 +
<!-- Pod2Wiki=item_map -->
 +
===map===
  
 +
$list-&gt;map( $function, $info )
 
Map the given function pointer to all the items in the list, in order. This loads the items in batches of 100 to reduce memory  requirements.
 
Map the given function pointer to all the items in the list, in order. This loads the items in batches of 100 to reduce memory  requirements.
  
Line 256: Line 339:
 
    
 
    
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_export --></div>
+
<!-- Pod2Wiki= -->
−
===$plugin_output = $list-&gt;export( $plugin_id, %params )===
+
</div>
 +
<!-- Pod2Wiki=item_export -->
 +
===export===
  
 +
$plugin_output = $list-&gt;export( $plugin_id, %params )
 
Apply an output plugin to this list of items. If the param "fh" is set it will send the results to a filehandle rather than return them as a string.  
 
Apply an output plugin to this list of items. If the param "fh" is set it will send the results to a filehandle rather than return them as a string.  
  
Line 271: Line 357:
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
−
<!-- Edit below this comment -->
 
−
 
 
−
 
 
−
<!-- Pod2Wiki=item_get_dataset --></div>
 
−
===$dataset = $list-&gt;get_dataset===
 
−
 
 
−
Return the EPrints::DataSet which this list relates to.
 
−
 
 
−
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
−
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
−
<!-- Pod2Wiki=item_render_description --></div>
+
<!-- Pod2Wiki= -->
−
===$xhtml = $list-&gt;render_description===
+
</div>
 +
<!-- Pod2Wiki=item_render_description -->
 +
===render_description===
  
 +
$xhtml = $list-&gt;render_description
 
Return a DOM XHTML description of this list, if available, or an empty fragment.
 
Return a DOM XHTML description of this list, if available, or an empty fragment.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 +
<!-- Pod2Wiki= -->
 +
</div>
 
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->
 
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->

Revision as of 17:25, 31 December 2010

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects

API: Core API

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki


NAME

EPrints::List - List of data objects, usually a search result.

User Comments


SYNOPSIS

 $new_list = $list->reorder( "-creation_date" ); # makes a new list ordered by reverse order creation_date
 
 $new_list = $list->union( $list2, "creation_date" ) # makes a new list by adding the contents of $list to $list2. the resulting list is ordered by "creation_date"
 
 $new_list = $list->remainder( $list2, "title" ); # makes a new list by removing the contents of $list2 from $list orders the resulting list by title
 
 $n = $list->count() # returns the number of items in the list
 
 @dataobjs = $list->slice( 0, 20 );  #get the first 20 DataObjs from the list in an array
 
 $list->map( $function, $info ) # performs a function on every item in the list. This is very useful go and look at the detailed description.
 
 $plugin_output = $list->export( "BibTeX" ); #calls Plugin::Export::BibTeX on the list.
 
 $dataset = $list->get_dataset(); #returns the dataset in which the containing objects belong

User Comments


DESCRIPTION

This class represents an ordered list of objects, all from the same dataset. Usually this is the results of a search.

User Comments


SEE ALSO EPrints::Search

User Comments


METHODS

User Comments


new

$list = EPrints::List->new( 			session => $session,			dataset => $dataset,			[desc => $desc],			[desc_order => $desc_order],			ids => $ids,			[encoded => $encoded],			[keep_cache => $keep_cache],			[order => $order] );

User Comments


new

$list = EPrints::List->new( 			session => $session,			dataset => $dataset,			[desc => $desc],			[desc_order => $desc_order],			cache_id => $cache_id );

Creates a new list object in memory only. Lists will be cached if anything method requiring order is called, or an explicit cache() method is called.

encoded is the serialised version of the searchExpression which created this list, if there was one.

If keep_cache is set then the cache will not be disposed of at the end of the current $repository operation. If cache_id is set then keep_cache is automatically true.

User Comments


new

$list = EPrints::List->new( 			session => $session,			dataset => $dataset,			ids => $ids, 			[order => $order] );

User Comments


new

$list = EPrints::List->new( 			session => $session,			dataset => $dataset,			[desc => $desc],			[desc_order => $desc_order],			cache_id => $cache_id );

Note the new() method will be called very rarely since lists will usually created by an EPrints::Search.

Creates a new list object in memory only. Lists will be cached if any method requiring order is called, or an explicit cache() method is called.

encoded is the serialised version of the searchExpression which created this list, if there was one.

If keep_cache is set then the cache will not be disposed of at the end of the current $session. If cache_id is set then keep_cache is automatically true.

User Comments


reorder

$new_list = $list->reorder( $new_order );

Create a new list from this one, but sorted in a new way.

$new_list = $list->reorder( "-creation_date" ); # makes a new list ordered by reverse order creation_date

User Comments


union

$new_list = $list->union( $list2, [$order] );

Create a new list from this one plus another one. If order is not set then this list will not be in any certain order.

$list2 - the list which is to be combined to the calling list

$order - a field which the the resulting list will be ordered on. (optional)

User Comments


remainder

$new_list = $list->remainder( $list2, [$order] );

Create a new list from $list with elements from $list2 removed. If order is not set then this list will not be in any certain order.

Remove all items in $list2 from $list and return the result as a new EPrints::List.

$list2 - the eprints you want to remove from the calling list

$order - the field the remaining list is to be ordered by

User Comments


intersect

$new_list = $list->intersect( $list2, [$order] );

Create a new list containing only the items which are in both lists. If order is not set then this list will not be in any certain order.

$list2 - a list to intersect with the calling list

$order - the field the resulting list will be ordered on

User Comments


cache

$list->cache

Cause this list to be cached in the database.

User Comments


InternalDoc

User Comments


get_cache_id

$cache_id = $list->get_cache_id

Return the ID of the cache table for this list, or undef.

User Comments


InternalDoc

User Comments


dispose

$list->dispose

Clean up the cache table if appropriate.

User Comments


InternalDoc

User Comments


count

$n = $list->count

Return the number of values in this list.

User Comments


item

$dataobj = $list->item( $offset )

Returns the item at offset $offset.

Returns undef if $offset is out of range of the current list of items.

User Comments


slice

@dataobjs = $list->slice( [$offset], [$count] )

Returns the DataObjs in this list as an array. $offset - what index through the list to start from. $count - the maximum to return.

User Comments


ids

$ids = $list->ids( [$offset], [$count] )

Return a reference to an array containing the object ids of the items in the list. You can specify a range of ids using $offset and $count. This is more efficient if you just need the ids.

$offset - what index through the list to start from. $count - the maximum to return.

User Comments


map

$list->map( $function, $info )

Map the given function pointer to all the items in the list, in order. This loads the items in batches of 100 to reduce memory requirements.

$info is a datastructure which will be passed to the function each time and is useful for holding or collecting state.

Example: 

my $info = { matches => 0 };
$list->map( \&deal, $info );
print "Matches: ".$info->{matches}."\n";
 

sub deal
{
  my( $session, $dataset, $eprint, $info ) = @_;

  if( $eprint->get_value( "a" ) eq $eprint->get_value( "b" ) ) {
    $info->{matches} += 1;
  }
}

User Comments


export

$plugin_output = $list->export( $plugin_id, %params )

Apply an output plugin to this list of items. If the param "fh" is set it will send the results to a filehandle rather than return them as a string.

$plugin_id - the ID of the Export plugin which is to be used to process the list. e.g. "BibTeX"

$param{"fh"} = "temp_dir/my_file.txt"; - the file the results are to be output to, useful for output too large to fit into memory.


User Comments


render_description

$xhtml = $list->render_description

Return a DOM XHTML description of this list, if available, or an empty fragment.

User Comments


Retrieved from ‘https://wiki.eprints.org/w/index.php?title=API:EPrints/List&oldid=9724’