1 /** 2 * @file ElementFilter.h 3 * @brief Base class of element filters. 4 * @author Frank T. Bergmann 5 * 6 * <!-------------------------------------------------------------------------- 7 * This file is part of libSBML. Please visit http://sbml.org for more 8 * information about SBML, and the latest version of libSBML. 9 * 10 * Copyright (C) 2020 jointly by the following organizations: 11 * 1. California Institute of Technology, Pasadena, CA, USA 12 * 2. University of Heidelberg, Heidelberg, Germany 13 * 3. University College London, London, UK 14 * 15 * Copyright (C) 2019 jointly by the following organizations: 16 * 1. California Institute of Technology, Pasadena, CA, USA 17 * 2. University of Heidelberg, Heidelberg, Germany 18 * 19 * Copyright (C) 2013-2018 jointly by the following organizations: 20 * 1. California Institute of Technology, Pasadena, CA, USA 21 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 22 * 3. University of Heidelberg, Heidelberg, Germany 23 * 24 * Copyright (C) 2009-2013 jointly by the following organizations: 25 * 1. California Institute of Technology, Pasadena, CA, USA 26 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 27 * 28 * Copyright (C) 2006-2008 by the California Institute of Technology, 29 * Pasadena, CA, USA 30 * 31 * Copyright (C) 2002-2005 jointly by the following organizations: 32 * 1. California Institute of Technology, Pasadena, CA, USA 33 * 2. Japan Science and Technology Agency, Japan 34 * 35 * This library is free software; you can redistribute it and/or modify it 36 * under the terms of the GNU Lesser General Public License as published by 37 * the Free Software Foundation. A copy of the license agreement is provided 38 * in the file named "LICENSE.txt" included with this software distribution 39 * and also available online as http://sbml.org/software/libsbml/license.html 40 * ---------------------------------------------------------------------- --> 41 * 42 * @class ElementFilter 43 * @sbmlbrief{core} Base class for filter functions. 44 * 45 * @htmlinclude libsbml-facility-only-warning.html 46 * 47 * Some libSBML objects provide the ability to return lists of components. 48 * To provide callers with greater control over exactly what is 49 * returned, these methods take optional arguments in the form of filters. 50 * The ElementFilter class is the parent class for these filters. 51 */ 52 53 /** 54 * <!-- ~ ~ ~ ~ ~ Start of common documentation strings ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ 55 * The following text is used as common documentation blocks copied multiple 56 * times elsewhere in this file. The use of @class is a hack needed because 57 * Doxygen's @copydetails command has limited functionality. Symbols 58 * beginning with "doc_" are marked as ignored in our Doxygen configuration. 59 * ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ --> 60 * 61 * @class doc_what_is_user_data 62 * 63 * @par 64 * The user data associated with an SBML object can be used by an application 65 * developer to attach custom information to that object in the model. In case 66 * of a deep copy, this data will passed as-is. The data attribute will never 67 * be interpreted by libSBML. 68 */ 69 70 #ifndef ElementFilter_h 71 #define ElementFilter_h 72 73 74 #ifdef __cplusplus 75 76 #include <sbml/common/extern.h> 77 #include <sbml/common/libsbml-namespace.h> 78 79 LIBSBML_CPP_NAMESPACE_BEGIN 80 81 #define ADD_FILTERED_LIST(pResult,pSublist,list,pFilter)\ 82 {\ 83 if (list.size() > 0) {\ 84 if (pFilter == NULL || pFilter->filter(&list))\ 85 pResult->add(&list);\ 86 pSublist = list.getAllElements(pFilter);\ 87 pResult->transferFrom(pSublist);\ 88 delete pSublist;\ 89 }\ 90 } 91 92 #define ADD_FILTERED_PLIST(pResult,pSublist,pList,pFilter)\ 93 {\ 94 if (pList != NULL && pList->size() > 0) {\ 95 if (pFilter == NULL || pFilter->filter(pList))\ 96 pResult->add(pList);\ 97 pSublist = pList->getAllElements(pFilter);\ 98 pResult->transferFrom(pSublist);\ 99 delete pSublist;\ 100 }\ 101 } 102 103 #define ADD_FILTERED_POINTER(pResult,pSublist,pElement,pFilter)\ 104 {\ 105 if (pElement != NULL) {\ 106 if (pFilter == NULL || pFilter->filter(pElement))\ 107 pResult->add(pElement);\ 108 pSublist = pElement->getAllElements(pFilter);\ 109 pResult->transferFrom(pSublist);\ 110 delete pSublist;\ 111 }\ 112 } 113 114 #define ADD_FILTERED_ELEMENT(pResult,pSublist,element,pFilter)\ 115 {\ 116 {\ 117 if (pFilter == NULL || pFilter->filter(&element))\ 118 pResult->add(&element);\ 119 pSublist = element.getAllElements(pFilter);\ 120 pResult->transferFrom(pSublist);\ 121 delete pSublist;\ 122 }\ 123 } 124 125 #define ADD_FILTERED_FROM_PLUGIN(pResult,pSublist,pFilter)\ 126 {\ 127 pSublist = getAllElementsFromPlugins(pFilter);\ 128 pResult->transferFrom(pSublist);\ 129 delete pSublist;\ 130 } 131 132 class SBase; 133 134 class LIBSBML_EXTERN ElementFilter 135 { 136 public: 137 138 /** 139 * Creates a new ElementFilter object. 140 */ 141 ElementFilter(); 142 143 144 /** 145 * Destroys this ElementFilter. 146 */ 147 virtual ~ElementFilter(); 148 149 150 /** 151 * Predicate to test elements. 152 * 153 * This is the central predicate of the ElementFilter class. In subclasses 154 * of ElementFilter, callers should implement this method such that it 155 * returns @c true for @p element arguments that are "desirable" and 156 * @c false for those that are "undesirable" in whatever filtering context the 157 * ElementFilter subclass is designed to be used. 158 * 159 * @param element the element to be tested. 160 * 161 * @return @c true if the @p element is desirable or should be kept, 162 * @c false otherwise. 163 */ 164 virtual bool filter(const SBase* element); 165 166 167 /** 168 * Returns the user data that has been previously set via setUserData(). 169 * 170 * Callers can attach private data to ElementFilter objects using 171 * setUserData(). This user data can be used by an application to store 172 * custom information to be accessed by the ElementFilter in its work. In 173 * case of a deep copy, the data will passed as it is. The attribute will 174 * never be interpreted by libSBML. 175 * 176 * @return the user data of this node, or @c NULL if no user data has been 177 * set. 178 * 179 * @warning This <em>user data</em> is specific to an ElementFilter object 180 * instance, and is not the same as the user data that may be attached to 181 * an SBML object using SBase::setUserData(). 182 * 183 * @see setUserData() 184 */ 185 void* getUserData(); 186 187 188 /** 189 * Sets the user data of this element. 190 * 191 * Callers can attach private data to ElementFilter objects using this 192 * method, and retrieve them using getUserData(). Such user data can be 193 * used by an application to store information to be accessed by the 194 * ElementFilter in its work. In case of a deep copy, this data will 195 * passed as it is. The attribute will never be interpreted by libSBML. 196 * 197 * @param userData specifies the new user data. 198 * 199 * @copydetails doc_returns_success_code 200 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 201 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 202 * 203 * @warning This <em>user data</em> is specific to an ElementFilter object 204 * instance, and is not the same as the user data that may be attached to 205 * an SBML object using SBase::setUserData(). 206 * 207 * @see getUserData() 208 */ 209 void setUserData(void* userData); 210 211 212 private: 213 /** @cond doxygenLibsbmlInternal */ 214 void* mUserData; 215 216 /** @endcond */ 217 }; 218 219 LIBSBML_CPP_NAMESPACE_END 220 221 #endif /* __cplusplus */ 222 #endif /* ElementFilter_h */ 223