API:EPrints/List

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.

DESCRIPTION

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

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] );

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 $session. If cache_id is set then keep_cache is automatically true.

reorder

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

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

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.

remainder

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

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.

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

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.

cache

 $list->cache

Cause this list to be cached in the database.

get_cache_id

 $cache_id = $list->get_cache_id

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

dispose

 $list->dispose

Clean up the cache table if appropriate.

count

 $n = $list->count 

Return the number of values in this list.

get_records

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

Return the objects described by this list. $count is the maximum to return. $offset is what index through the list to start from.

get_ids

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

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.

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;
  }
}  
 

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.

get_dataset

 $dataset = $list->get_dataset

Return the EPrints::DataSet which this list relates to.

render_description

 $xhtml = $list->render_description

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