--- name: "SWISS::ListBase" section: "3pm" platform: "linux" package: "libswiss-perl" version: "1.80-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/SWISS::ListBase" --- # SWISS::ListBase(3pm) ## Name SWISS::ListBase.pm ## Description Base class for list oriented classes in the SWISS:: hierarchy. It provides a set of quite general list manipulation methods to inheriting classes. ## Attributes - list Holds an array, the essential content of the object. Array elements can be, and are in fact frequently, arrays themselves. ## Methods ### Standard methods - new - initialize ### Reading methods - head Return the first element of the list - tail Return all but the first element of the list - get pattern Return a list of all elements matched by `$pattern`. Only exact matches are returned, but you can use Perls regular expressions. Example: ``` $listBaseObject->set('EMBL', 'TREMBL', 'SWISSPROT'); $listBaseObject->get('.*EMBL'); ``` returns ('EMBL', 'TREMBL') - 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 `@patternList` with the same index. Empty elements in `@patternList` always match. Example: ``` $listBaseObject->set(['EMBL', 'M1', 'G1', '-'], ['EMBL', 'M2', 'A2', '-'], ['EMBL', 'M2', 'G3', 'ALT_TERM'], ['PROSITE', 'P00001', '1433_2', '1']); $listBaseObject->get('EMBL'); returns (['EMBL', 'M1', 'G1', '-'], ['EMBL', 'M2', 'A2', '-'], ['EMBL', 'M2', 'G3', 'ALT_TERM']) $listBaseObject->get('',M2); returns (['EMBL', 'M2', 'A2', '-'], ['EMBL', 'M2', 'G3', 'ALT_TERM']); ``` 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. - getObject pattern - getObject @patternList Same as get, but returns the results wrapped in a new ListBase object. - 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. Example: ``` $tmp = $entry->CCs->filter(&ccTopic('FUNCTION')); ``` returns a SWISS::CCs object containing all CC blocks from `$entry` which have the topic 'FUNCTION'. Functions can also be anonymous functions. - 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. ``` Example: ``` `$matchedKWs` = `$entry`-\>KWs-\>filter(SWISS::ListBase::attributeEquals('text', `$kw`)); - 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. ``` Example: ``` `$matchedKWs` = `$entry`-\>KWs-\>filter(SWISS::ListBase::attributeMatchedBy('text', `$kw`)); - isEmpty - size The number of list elements in the object - elements Returns the array of elements - hasEvidenceTag $arrayPointer $tag Returns true if the array pointed to by `$arrayPointer` has the evidence tag `$tag` - getEvidenceTags $arrayPointer returns the array of evidence tags of `$arrayPointer` - getEvidenceTagsString $arrayPointer returns a string containing the evidence tags of `$arrayPointer` ### Writing methods - 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. - push list - pop - shift - unshift list - splice \[offset\[, length\[, list\]\]\] - set list Sets the list attribute to `@list` - add list Synonym for push - merge (ListBase) Appends the elements of ListBase to the object - 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. - del pattern Deletes all items fully matching `$pattern`. Example: ``` $listBaseObject->set('EMBL','TREMBL', 'SWISSPROT'); $listBaseObject->del('EMBL'); $listBaseObject->list(); returns ('TREMBL','SWISSPROT'). ``` If you want to delete more, use something like ``` $listBaseObject->del('.*EMBL') ``` which deletes 'EMBL' and 'TREMBL'. - 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 `@patternList` with the same index. **Warning: Empty elements in @patternList always match!** Using the data from the get example above, ``` $listBaseObject->del('','', 'A2') ``` results in ``` (['EMBL', 'M1', 'G1', '-'], ['EMBL', 'M2', 'G3', 'ALT_TERM'], ['PROSITE', 'P00001', '1433_2', '1']) ``` - update - unique Makes sure each element is contained only once in a ListBase object. The second and subsequent occurrences of the same object are deleted. Example: ``` $listBaseObject->set(EMBL, TREMBL, SWISSPROT); $listBaseObject->add(EMBL, MGD, EMBL); $listBaseObject->unique(); ``` results in (EMBL, TREMBL, SWISSPROT, MGD) - setEvidenceTags $arrayPointer @array sets the evidence Tags of the array pointed to by `$arrayPointer` to the contents of `@array` To be used if the ListBase elements are themselves arrays. A typical construct would be ``` foreach $dr ($entry->DRs->elements()) { $entry->DRs->setEvidenceTags($dr, 'E2', 'E3'); } ``` Returns `$arrayPointer`. - addEvidenceTag $arrayPointer $tag adds `$tag` to the evidence tags of `$arrayPointer` To be used if the ListBase elements are themselves arrays. See documentation of setEvidenceTags. Returns `$arrayPointer`. - deleteEvidenceTags $arrayPointer $evidenceTag deletes `$evidenceTag` from the array pointed to by `$arrayPointer` To be used if the ListBase elements are themselves arrays. A typical construct would be ``` foreach $dr ($entry->DRs->elements()) { $entry->DRs->deleteEvidenceTags($dr, 'EC2'); } ``` Returns `$arrayPointer`.