.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.08)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SWISS::ListBase 3pm"
.TH SWISS::ListBase 3pm "2006-01-26" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "Name"
.IX Header "Name"
SWISS::ListBase.pm
.SH "Description"
.IX Header "Description"
Base class for list oriented classes in the \s-1SWISS::\s0 hierarchy. It provides a set of quite general list manipulation methods to inheriting classes.
.SH "Attributes"
.IX Header "Attributes"
.IP "list" 4
.IX Item "list"
Holds an array, the essential content of the object. Array elements can be, and are in fact frequently, arrays themselves.
.SH "Methods"
.IX Header "Methods"
.SS "Standard methods"
.IX Subsection "Standard methods"
.IP "new" 4
.IX Item "new"
.PD 0
.IP "initialize" 4
.IX Item "initialize"
.PD
.SS "Reading methods"
.IX Subsection "Reading methods"
.IP "head" 4
.IX Item "head"
Return the first element of the list
.IP "tail" 4
.IX Item "tail"
Return all but the first element of the list
.IP "get pattern" 4
.IX Item "get pattern"
Return a list of all elements matched by \f(CW$pattern\fR. Only exact matches are returned, but you can use Perls regular expressions. Example:
.Sp
.Vb 2
\&  $listBaseObject\->set(\*(AqEMBL\*(Aq, \*(AqTREMBL\*(Aq, \*(AqSWISSPROT\*(Aq); 
\&  $listBaseObject\->get(\*(Aq.*EMBL\*(Aq);
.Ve
.Sp
returns ('\s-1EMBL\s0', '\s-1TREMBL\s0')
.ie n .IP "get @patternList" 4
.el .IP "get \f(CW@patternList\fR" 4
.IX Item "get @patternList"
To be used if the ListBase elements are arrays. An array is returned if all its elements are matched exactly by the elements from \f(CW@patternList\fR with the same index. Empty elements in \f(CW@patternList\fR always match. Example:
.Sp
.Vb 5
\& $listBaseObject\->set([\*(AqEMBL\*(Aq, \*(AqM1\*(Aq, \*(AqG1\*(Aq, \*(Aq\-\*(Aq],
\&                      [\*(AqEMBL\*(Aq, \*(AqM2\*(Aq, \*(AqA2\*(Aq, \*(Aq\-\*(Aq],
\&                      [\*(AqEMBL\*(Aq, \*(AqM2\*(Aq, \*(AqG3\*(Aq, \*(AqALT_TERM\*(Aq],
\&                      [\*(AqPROSITE\*(Aq, \*(AqP00001\*(Aq, \*(Aq1433_2\*(Aq, \*(Aq1\*(Aq]);
\& $listBaseObject\->get(\*(AqEMBL\*(Aq);
\&
\& returns ([\*(AqEMBL\*(Aq, \*(AqM1\*(Aq, \*(AqG1\*(Aq, \*(Aq\-\*(Aq],
\&          [\*(AqEMBL\*(Aq, \*(AqM2\*(Aq, \*(AqA2\*(Aq, \*(Aq\-\*(Aq],
\&          [\*(AqEMBL\*(Aq, \*(AqM2\*(Aq, \*(AqG3\*(Aq, \*(AqALT_TERM\*(Aq])
\& 
\& $listBaseObject\->get(\*(Aq\*(Aq,M2);
\&
\& returns ([\*(AqEMBL\*(Aq, \*(AqM2\*(Aq, \*(AqA2\*(Aq, \*(Aq\-\*(Aq],
\&          [\*(AqEMBL\*(Aq, \*(AqM2\*(Aq, \*(AqG3\*(Aq, \*(AqALT_TERM\*(Aq]);
.Ve
.Sp
Offering get in the interface is not particularly nice because it exports implementation details into the interface, but it is a powerful method which may save a lot of programming time. As an alternative, the 'filter' concept is available.
.IP "getObject pattern" 4
.IX Item "getObject pattern"
.PD 0
.ie n .IP "getObject @patternList" 4
.el .IP "getObject \f(CW@patternList\fR" 4
.IX Item "getObject @patternList"
.PD
Same as get, but returns the results wrapped in a new ListBase object.
.IP "filter" 4
.IX Item "filter"
Returns a new object containing all of the elements that match a search criteria. It takes a function as the only parameter. This function should expect a list element, and return true or false depending on whether the element matches the criteria. If the object is not a ListBase object but member of a subclass, a new object of that subclass will be returned.
.Sp
Example:
.Sp
.Vb 1
\& $tmp = $entry\->CCs\->filter(&ccTopic(\*(AqFUNCTION\*(Aq));
.Ve
.Sp
returns a SWISS::CCs object containing all \s-1CC\s0 blocks from \f(CW$entry\fR which have the topic '\s-1FUNCTION\s0'.
.Sp
Functions can also be anonymous functions.
.IP "attributeEquals(string attributeName, string attributeValue)" 4
.IX Item "attributeEquals(string attributeName, string attributeValue)"
Filter function. If the elements of a ListBase object are objects, they will be returned by this function if they have the attribute and it equals the attributeValue.
.Sp
.Vb 1
\& Example:
.Ve
.Sp
\&\f(CW$matchedKWs\fR = \f(CW$entry\fR\->KWs\->filter(SWISS::ListBase::attributeEquals('text', \f(CW$kw\fR));
.IP "attributeMatchedBy(string attributeName, string pattern)" 4
.IX Item "attributeMatchedBy(string attributeName, string pattern)"
Filter function. If the elements of a ListBase object are objects, they will be returned by this function if they have the attribute and the attribute is matched by the pattern.
.Sp
.Vb 1
\& Example:
.Ve
.Sp
\&\f(CW$matchedKWs\fR = \f(CW$entry\fR\->KWs\->filter(SWISS::ListBase::attributeMatchedBy('text', \f(CW$kw\fR));
.IP "isEmpty" 4
.IX Item "isEmpty"
.PD 0
.IP "size" 4
.IX Item "size"
.PD
The number of list elements in the object
.IP "elements" 4
.IX Item "elements"
Returns the array of elements
.ie n .IP "hasEvidenceTag $arrayPointer $tag" 4
.el .IP "hasEvidenceTag \f(CW$arrayPointer\fR \f(CW$tag\fR" 4
.IX Item "hasEvidenceTag $arrayPointer $tag"
Returns true if the array pointed to by \f(CW$arrayPointer\fR has the evidence tag \f(CW$tag\fR
.ie n .IP "getEvidenceTags $arrayPointer" 4
.el .IP "getEvidenceTags \f(CW$arrayPointer\fR" 4
.IX Item "getEvidenceTags $arrayPointer"
returns the array of evidence tags of \f(CW$arrayPointer\fR
.ie n .IP "getEvidenceTagsString $arrayPointer" 4
.el .IP "getEvidenceTagsString \f(CW$arrayPointer\fR" 4
.IX Item "getEvidenceTagsString $arrayPointer"
returns a string containing the evidence tags of \f(CW$arrayPointer\fR
.SS "Writing methods"
.IX Subsection "Writing methods"
.IP "item offset[, newValue]" 4
.IX Item "item offset[, newValue]"
returns the list element at a specific offset, and optionally sets it to a new value. Negative offsets are relative to the end of the list.
.IP "push list" 4
.IX Item "push list"
.PD 0
.IP "pop" 4
.IX Item "pop"
.IP "shift" 4
.IX Item "shift"
.IP "unshift list" 4
.IX Item "unshift list"
.IP "splice [offset[, length[, list]]]" 4
.IX Item "splice [offset[, length[, list]]]"
.IP "set list" 4
.IX Item "set list"
.PD
Sets the list attribute to \f(CW@list\fR
.IP "add list" 4
.IX Item "add list"
Synonym for push
.IP "merge (ListBase)" 4
.IX Item "merge (ListBase)"
Appends the elements of ListBase to the object
.IP "sort [function]" 4
.IX Item "sort [function]"
Applies a sort function to the list attribute, or by default, alphabetical sorting. Should be overwritten in derived classes with an adapted sort function.
.IP "del pattern" 4
.IX Item "del pattern"
Deletes all items fully matching \f(CW$pattern\fR. Example:
.Sp
.Vb 2
\&  $listBaseObject\->set(\*(AqEMBL\*(Aq,\*(AqTREMBL\*(Aq, \*(AqSWISSPROT\*(Aq);
\&  $listBaseObject\->del(\*(AqEMBL\*(Aq);
\&
\&  $listBaseObject\->list();
\&
\&  returns (\*(AqTREMBL\*(Aq,\*(AqSWISSPROT\*(Aq).
.Ve
.Sp
If you want to delete more, use something like
.Sp
.Vb 1
\&  $listBaseObject\->del(\*(Aq.*EMBL\*(Aq)
.Ve
.Sp
which deletes '\s-1EMBL\s0' and '\s-1TREMBL\s0'.
.ie n .IP "del @patternList" 4
.el .IP "del \f(CW@patternList\fR" 4
.IX Item "del @patternList"
To be used if the ListBase objects are arrays. An array is deleted if all its elements are matched by the elements from \f(CW@patternList\fR with the same index.
.Sp
\&\fBWarning: Empty elements in \f(CB@patternList\fB always match!\fR
.Sp
Using the data from the get example above,
.Sp
.Vb 1
\&  $listBaseObject\->del(\*(Aq\*(Aq,\*(Aq\*(Aq, \*(AqA2\*(Aq)
.Ve
.Sp
results in
.Sp
.Vb 3
\&  ([\*(AqEMBL\*(Aq, \*(AqM1\*(Aq, \*(AqG1\*(Aq, \*(Aq\-\*(Aq],
\&   [\*(AqEMBL\*(Aq, \*(AqM2\*(Aq, \*(AqG3\*(Aq, \*(AqALT_TERM\*(Aq],
\&   [\*(AqPROSITE\*(Aq, \*(AqP00001\*(Aq, \*(Aq1433_2\*(Aq, \*(Aq1\*(Aq])
.Ve
.IP "update" 4
.IX Item "update"
.PD 0
.IP "unique" 4
.IX Item "unique"
.PD
Makes sure each element is contained only once in a ListBase object. The second and subsequent occurrences of the same object are deleted. Example:
.Sp
.Vb 3
\&  $listBaseObject\->set(EMBL, TREMBL, SWISSPROT);
\&  $listBaseObject\->add(EMBL, MGD, EMBL);
\&  $listBaseObject\->unique();
.Ve
.Sp
results in (\s-1EMBL\s0, \s-1TREMBL\s0, \s-1SWISSPROT\s0, \s-1MGD\s0)
.ie n .IP "setEvidenceTags $arrayPointer @array" 4
.el .IP "setEvidenceTags \f(CW$arrayPointer\fR \f(CW@array\fR" 4
.IX Item "setEvidenceTags $arrayPointer @array"
sets the evidence Tags of the array pointed to by \f(CW$arrayPointer\fR to the contents of \f(CW@array\fR
.Sp
To be used if the ListBase elements are themselves arrays. A typical construct would be
.Sp
.Vb 3
\&  foreach $dr ($entry\->DRs\->elements()) {
\&    $entry\->DRs\->setEvidenceTags($dr, \*(AqE2\*(Aq, \*(AqE3\*(Aq);
\&  }
.Ve
.Sp
Returns \f(CW$arrayPointer\fR.
.ie n .IP "addEvidenceTag $arrayPointer $tag" 4
.el .IP "addEvidenceTag \f(CW$arrayPointer\fR \f(CW$tag\fR" 4
.IX Item "addEvidenceTag $arrayPointer $tag"
adds \f(CW$tag\fR to the evidence tags of \f(CW$arrayPointer\fR
.Sp
To be used if the ListBase elements are themselves arrays. See documentation of setEvidenceTags.
.Sp
Returns \f(CW$arrayPointer\fR.
.ie n .IP "deleteEvidenceTags $arrayPointer $evidenceTag" 4
.el .IP "deleteEvidenceTags \f(CW$arrayPointer\fR \f(CW$evidenceTag\fR" 4
.IX Item "deleteEvidenceTags $arrayPointer $evidenceTag"
deletes \f(CW$evidenceTag\fR from the array pointed to by \f(CW$arrayPointer\fR
.Sp
To be used if the ListBase elements are themselves arrays. A typical construct would be
.Sp
.Vb 3
\&  foreach $dr ($entry\->DRs\->elements()) {
\&    $entry\->DRs\->deleteEvidenceTags($dr, \*(AqEC2\*(Aq);
\&  }
.Ve
.Sp
Returns \f(CW$arrayPointer\fR.