API:EPrints/List

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

 use EPrints::List;
 
 $list = EPrints::List->new( handle => $handle, dataset => $dataset, ids => $ids); # ref to an array of ids to populate the list with
 
 $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->get_records( 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

User Comments

$list = EPrints::List->new( handle => $handle, dataset => $dataset, ids => $ids, # a ref to the array of ids [order => $order] ); # the field on which to order the list

User Comments

$list = EPrints::List->new( handle => $handle, 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 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 $handle. If cache_id is set then keep_cache is automatically true.

User Comments

$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

$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

$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.

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

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

User Comments

$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

$n = $list->count

Return the number of values in this list.

User Comments

@dataobjs = $list->get_records( [$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 = $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.

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

User Comments

$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( $handle, $dataset, $eprint, $info ) = @_; # params passed to the function by $list->map

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

User Comments

$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 out put to, useful for output too big to put into memory.

User Comments

$dataset = $list->get_dataset

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

User Comments

$xhtml = $list->render_description

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

User Comments