From 80b30272cb0990ae5db6a6b5dd0430c750553be9 Mon Sep 17 00:00:00 2001 From: Sam Hatchett Date: Thu, 16 Jul 2020 15:23:26 -0400 Subject: [PATCH] modifies function declarations with unambiguous "out_" prefixes where output parameters are passed. This is a minor change that does not affect the API or any function implementations, but has great benefits to both readability and SWIG-wrapping. (#605) Co-authored-by: Sam Hatchett --- include/epanet2_2.h | 110 ++++++++++++++++++++++---------------------- 1 file changed, 55 insertions(+), 55 deletions(-) diff --git a/include/epanet2_2.h b/include/epanet2_2.h index 4760986..18ef127 100644 --- a/include/epanet2_2.h +++ b/include/epanet2_2.h @@ -161,7 +161,7 @@ typedef struct Project *EN_Project; @param ph an EPANET project handle. @param object a type of object (either EN_NODE, EN_LINK, EN_TIMEPAT or EN_CURVE) @param index the object's index starting from 1 - @param[out] comment the comment string assigned to the object + @param comment the comment string assigned to the object @return an error code */ int DLLEXPORT EN_setcomment(EN_Project ph, int object, int index, char *comment); @@ -173,7 +173,7 @@ typedef struct Project *EN_Project; @param[out] count number of objects of the specified type @return an error code */ - int DLLEXPORT EN_getcount(EN_Project ph, int object, int *count); + int DLLEXPORT EN_getcount(EN_Project ph, int object, int *out_count); /** @brief Saves a project's data to an EPANET-formatted text file. @@ -299,7 +299,7 @@ typedef struct Project *EN_Project; See ::EN_nextH for an example of using this function. */ - int DLLEXPORT EN_runH(EN_Project ph, long *currentTime); + int DLLEXPORT EN_runH(EN_Project ph, long *out_currentTime); /** @brief Determines the length of time until the next hydraulic event occurs in an @@ -333,7 +333,7 @@ typedef struct Project *EN_Project; EN_closeH(ph); \endcode */ - int DLLEXPORT EN_nextH(EN_Project ph, long *tStep); + int DLLEXPORT EN_nextH(EN_Project ph, long *out_tStep); /** @brief Transfers a project's hydraulics results from its temporary hydraulics file @@ -449,7 +449,7 @@ typedef struct Project *EN_Project; hydraulic analysis that preceded the water quality analysis. Treat it as a read-only variable. */ - int DLLEXPORT EN_runQ(EN_Project ph, long *currentTime); + int DLLEXPORT EN_runQ(EN_Project ph, long *out_currentTime); /** @brief Advances a water quality simulation over the time until the next hydraulic event. @@ -481,7 +481,7 @@ typedef struct Project *EN_Project; EN_closeQ(ph); \endcode */ - int DLLEXPORT EN_nextQ(EN_Project ph, long *tStep); + int DLLEXPORT EN_nextQ(EN_Project ph, long *out_tStep); /** @brief Advances a water quality simulation by a single water quality time step. @@ -497,7 +497,7 @@ typedef struct Project *EN_Project; Use the argument \b timeLeft to determine when no more calls to ::EN_runQ are needed because the end of the simulation period has been reached (i.e., when \b timeLeft = 0). */ - int DLLEXPORT EN_stepQ(EN_Project ph, long *timeLeft); + int DLLEXPORT EN_stepQ(EN_Project ph, long *out_timeLeft); /** @brief Closes the water quality solver, freeing all of its allocated memory. @@ -616,7 +616,7 @@ typedef struct Project *EN_Project; The version number is to be interpreted with implied decimals, i.e., "20100" == "2(.)01(.)00" */ - int DLLEXPORT EN_getversion(int *version); + int DLLEXPORT EN_getversion(int *out_version); /** @brief Returns the text of an error message generated by an error code. @@ -636,7 +636,7 @@ typedef struct Project *EN_Project; @param[out] value the value of the statistic. @return an error code */ - int DLLEXPORT EN_getstatistic(EN_Project ph, int type, double* value); + int DLLEXPORT EN_getstatistic(EN_Project ph, int type, double* out_value); /** @brief Retrieves the order in which a node or link appears in an @ref OutFile "output file". @@ -652,7 +652,7 @@ typedef struct Project *EN_Project; after the order of nodes or links in a network's database has been changed due to editing operations. */ - int DLLEXPORT EN_getresultindex(EN_Project ph, int type, int index, int *value); + int DLLEXPORT EN_getresultindex(EN_Project ph, int type, int index, int *out_value); /******************************************************************** @@ -667,7 +667,7 @@ typedef struct Project *EN_Project; @param[out] value the current value of the option. @return an error code */ - int DLLEXPORT EN_getoption(EN_Project ph, int option, double *value); + int DLLEXPORT EN_getoption(EN_Project ph, int option, double *out_value); /** @brief Sets the value for an anlysis option. @@ -688,7 +688,7 @@ typedef struct Project *EN_Project; Flow units in liters or cubic meters implies that SI metric units are used for all other quantities in addition to flow. Otherwise US Customary units are employed. */ - int DLLEXPORT EN_getflowunits(EN_Project ph, int *units); + int DLLEXPORT EN_getflowunits(EN_Project ph, int *out_units); /** @brief Sets a project's flow units. @@ -708,7 +708,7 @@ typedef struct Project *EN_Project; @param[out] value the current value of the time parameter (in seconds). @return an error code. */ - int DLLEXPORT EN_gettimeparam(EN_Project ph, int param, long *value); + int DLLEXPORT EN_gettimeparam(EN_Project ph, int param, long *out_value); /** @brief Sets the value of a time parameter. @@ -728,8 +728,8 @@ typedef struct Project *EN_Project; @param[out] traceNode index of the node being traced (if applicable). @return an error code. */ - int DLLEXPORT EN_getqualinfo(EN_Project ph, int *qualType, char *out_chemName, - char *out_chemUnits, int *traceNode); + int DLLEXPORT EN_getqualinfo(EN_Project ph, int *out_qualType, char *out_chemName, + char *out_chemUnits, int *out_traceNode); /** @brief Retrieves the type of water quality analysis to be run. @@ -738,7 +738,7 @@ typedef struct Project *EN_Project; @param[out] traceNode the index of node being traced, if qualType = EN_TRACE. @return an error code. */ - int DLLEXPORT EN_getqualtype(EN_Project ph, int *qualType, int *traceNode); + int DLLEXPORT EN_getqualtype(EN_Project ph, int *out_qualType, int *out_traceNode); /** @brief Sets the type of water quality analysis to run. @@ -773,7 +773,7 @@ typedef struct Project *EN_Project; When a new node is created all of its properties (see @ref EN_NodeProperty) are set to 0. */ - int DLLEXPORT EN_addnode(EN_Project ph, char *id, int nodeType, int *index); + int DLLEXPORT EN_addnode(EN_Project ph, char *id, int nodeType, int *out_index); /** @brief Deletes a node from a project. @@ -797,7 +797,7 @@ typedef struct Project *EN_Project; @param[out] index the node's index (starting from 1). @return an error code */ - int DLLEXPORT EN_getnodeindex(EN_Project ph, char *id, int *index); + int DLLEXPORT EN_getnodeindex(EN_Project ph, char *id, int *out_index); /** @brief Gets the ID name of a node given its index. @@ -828,7 +828,7 @@ typedef struct Project *EN_Project; @param[out] nodeType the node's type (see @ref EN_NodeType). @return an error code. */ - int DLLEXPORT EN_getnodetype(EN_Project ph, int index, int *nodeType); + int DLLEXPORT EN_getnodetype(EN_Project ph, int index, int *out_nodeType); /** @brief Retrieves a property value for a node. @@ -841,7 +841,7 @@ typedef struct Project *EN_Project; Values are returned in units that depend on the units used for flow rate (see @ref Units). */ - int DLLEXPORT EN_getnodevalue(EN_Project ph, int index, int property, double *value); + int DLLEXPORT EN_getnodevalue(EN_Project ph, int index, int property, double *out_value); /** @brief Sets a property value for a node. @@ -895,7 +895,7 @@ typedef struct Project *EN_Project; @param[out] y the node's Y-coordinate value. @return an error code. */ - int DLLEXPORT EN_getcoord(EN_Project ph, int index, double *x, double *y); + int DLLEXPORT EN_getcoord(EN_Project ph, int index, double *out_x, double *out_y); /** @brief Sets the (x,y) coordinates of a node. @@ -924,8 +924,8 @@ typedef struct Project *EN_Project; Parameters pmin, preq, and \b pexp are only used when the demand model is \b EN_PDA. */ - int DLLEXPORT EN_getdemandmodel(EN_Project ph, int *type, double *pmin, - double *preq, double *pexp); + int DLLEXPORT EN_getdemandmodel(EN_Project ph, int *out_type, double *out_pmin, + double *out_preq, double *out_pexp); /** @brief Sets the type of demand model to use and its parameters. @@ -983,7 +983,7 @@ typedef struct Project *EN_Project; @return an error code */ int DLLEXPORT EN_getdemandindex(EN_Project ph, int nodeIndex, char *demandName, - int *demandIndex); + int *out_demandIndex); /** @brief Retrieves the number of demand categories for a junction node. @@ -992,7 +992,7 @@ typedef struct Project *EN_Project; @param[out] numDemands the number of demand categories assigned to the node. @return an error code. */ - int DLLEXPORT EN_getnumdemands(EN_Project ph, int nodeIndex, int *numDemands); + int DLLEXPORT EN_getnumdemands(EN_Project ph, int nodeIndex, int *out_numDemands); /** @brief Gets the base demand for one of a node's demand categories. @@ -1003,7 +1003,7 @@ typedef struct Project *EN_Project; @return an error code. */ int DLLEXPORT EN_getbasedemand(EN_Project ph, int nodeIndex, int demandIndex, - double *baseDemand); + double *out_baseDemand); /** @brief Sets the base demand for one of a node's demand categories. @@ -1028,7 +1028,7 @@ typedef struct Project *EN_Project; demand category. */ int DLLEXPORT EN_getdemandpattern(EN_Project ph, int nodeIndex, int demandIndex, - int *patIndex); + int *out_patIndex); /** @brief Sets the index of a time pattern used for one of a node's demand categories. @@ -1099,7 +1099,7 @@ typedef struct Project *EN_Project; See @ref EN_LinkProperty. */ int DLLEXPORT EN_addlink(EN_Project ph, char *id, int linkType, char *fromNode, - char *toNode, int *index); + char *toNode, int *out_index); /** @brief Deletes a link from the project. @@ -1121,7 +1121,7 @@ typedef struct Project *EN_Project; @param[out] index the link's index (starting from 1). @return an error code. */ - int DLLEXPORT EN_getlinkindex(EN_Project ph, char *id, int *index); + int DLLEXPORT EN_getlinkindex(EN_Project ph, char *id, int *out_index); /** @brief Gets the ID name of a link given its index. @@ -1152,7 +1152,7 @@ typedef struct Project *EN_Project; @param[out] linkType the link's type (see @ref EN_LinkType). @return an error code. */ - int DLLEXPORT EN_getlinktype(EN_Project ph, int index, int *linkType); + int DLLEXPORT EN_getlinktype(EN_Project ph, int index, int *out_linkType); /** @brief Changes a link's type. @@ -1177,7 +1177,7 @@ typedef struct Project *EN_Project; @param[out] node2 the index of the link's end node (starting from 1). @return an error code. */ - int DLLEXPORT EN_getlinknodes(EN_Project ph, int index, int *node1, int *node2); + int DLLEXPORT EN_getlinknodes(EN_Project ph, int index, int *out_node1, int *out_node2); /** @brief Sets the indexes of a link's start- and end-nodes. @@ -1199,7 +1199,7 @@ typedef struct Project *EN_Project; Values are returned in units that depend on the units used for flow rate (see @ref Units). */ - int DLLEXPORT EN_getlinkvalue(EN_Project ph, int index, int property, double *value); + int DLLEXPORT EN_getlinkvalue(EN_Project ph, int index, int property, double *out_value); /** @brief Sets a property value for a link. @@ -1235,7 +1235,7 @@ typedef struct Project *EN_Project; @param[out] count the number of vertex points that describe the link's shape. @return an error code. */ - int DLLEXPORT EN_getvertexcount(EN_Project ph, int index, int *count); + int DLLEXPORT EN_getvertexcount(EN_Project ph, int index, int *out_count); /** @brief Retrieves the coordinates of a vertex point assigned to a link. @@ -1246,7 +1246,7 @@ typedef struct Project *EN_Project; @param[out] y the vertex's Y-coordinate value. @return an error code. */ - int DLLEXPORT EN_getvertex(EN_Project ph, int index, int vertex, double *x, double *y); + int DLLEXPORT EN_getvertex(EN_Project ph, int index, int vertex, double *out_x, double *out_y); /** @brief Sets the coordinates of a vertex point assigned to a link. @@ -1285,7 +1285,7 @@ typedef struct Project *EN_Project; @param[out] pumpType the type of head curve used by the pump (see @ref EN_PumpType). @return an error code. */ - int DLLEXPORT EN_getpumptype(EN_Project ph, int linkIndex, int *pumpType); + int DLLEXPORT EN_getpumptype(EN_Project ph, int linkIndex, int *out_pumpType); /** @brief Retrieves the curve assigned to a pump's head curve. @@ -1294,7 +1294,7 @@ typedef struct Project *EN_Project; @param[out] curveIndex the index of the curve assigned to the pump's head curve. @return an error code. */ - int DLLEXPORT EN_getheadcurveindex(EN_Project ph, int linkIndex, int *curveIndex); + int DLLEXPORT EN_getheadcurveindex(EN_Project ph, int linkIndex, int *out_curveIndex); /** @brief Assigns a curve to a pump's head curve. @@ -1336,7 +1336,7 @@ typedef struct Project *EN_Project; @param[out] index the time pattern's index (starting from 1). @return an error code. */ - int DLLEXPORT EN_getpatternindex(EN_Project ph, char *id, int *index); + int DLLEXPORT EN_getpatternindex(EN_Project ph, char *id, int *out_index); /** @brief Retrieves the ID name of a time pattern given its index. @@ -1367,7 +1367,7 @@ typedef struct Project *EN_Project; @param[out] len the number of time periods in the pattern. @return an error code. */ - int DLLEXPORT EN_getpatternlen(EN_Project ph, int index, int *len); + int DLLEXPORT EN_getpatternlen(EN_Project ph, int index, int *out_len); /** @brief Retrieves a time pattern's factor for a given time period. @@ -1377,7 +1377,7 @@ typedef struct Project *EN_Project; @param[out] value the pattern factor for the given time period. @return an error code. */ - int DLLEXPORT EN_getpatternvalue(EN_Project ph, int index, int period, double *value); + int DLLEXPORT EN_getpatternvalue(EN_Project ph, int index, int period, double *out_value); /** @brief Sets a time pattern's factor for a given time period. @@ -1396,7 +1396,7 @@ typedef struct Project *EN_Project; @param[out] value The average of all of the time pattern's factors. @return an error code. */ - int DLLEXPORT EN_getaveragepatternvalue(EN_Project ph, int index, double *value); + int DLLEXPORT EN_getaveragepatternvalue(EN_Project ph, int index, double *out_value); /** @brief Sets the pattern factors for a given time pattern. @@ -1444,7 +1444,7 @@ typedef struct Project *EN_Project; @param[out] index The curve's index (starting from 1). @return an error code. */ - int DLLEXPORT EN_getcurveindex(EN_Project ph, char *id, int *index); + int DLLEXPORT EN_getcurveindex(EN_Project ph, char *id, int *out_index); /** @brief Retrieves the ID name of a curve given its index. @@ -1475,7 +1475,7 @@ typedef struct Project *EN_Project; @param[out] len The number of data points assigned to the curve. @return an error code. */ - int DLLEXPORT EN_getcurvelen(EN_Project ph, int index, int *len); + int DLLEXPORT EN_getcurvelen(EN_Project ph, int index, int *out_len); /** @brief Retrieves a curve's type. @@ -1484,7 +1484,7 @@ typedef struct Project *EN_Project; @param[out] type the curve's type (see @ref EN_CurveType). @return an error code. */ - int DLLEXPORT EN_getcurvetype(EN_Project ph, int index, int *type); + int DLLEXPORT EN_getcurvetype(EN_Project ph, int index, int *out_type); /** @brief Sets a curve's type. @@ -1505,7 +1505,7 @@ typedef struct Project *EN_Project; @return an error code. */ int DLLEXPORT EN_getcurvevalue(EN_Project ph, int curveIndex, int pointIndex, - double *x, double *y); + double *out_x, double *out_y); /** @brief Sets the value of a single data point for a curve. @@ -1533,8 +1533,8 @@ typedef struct Project *EN_Project; to hold `nPoints` number of data points and for sizing `id` to hold at least @ref EN_SizeLimits "EN_MAXID" characters. */ - int DLLEXPORT EN_getcurve(EN_Project ph, int index, char *out_id, int *nPoints, - double *xValues, double *yValues); + int DLLEXPORT EN_getcurve(EN_Project ph, int index, char *out_id, int *out_nPoints, + double *out_xValues, double *out_yValues); /** @brief assigns a set of data points to a curve. @@ -1573,7 +1573,7 @@ typedef struct Project *EN_Project; @return an error code. */ int DLLEXPORT EN_addcontrol(EN_Project ph, int type, int linkIndex, - double setting, int nodeIndex, double level, int *index); + double setting, int nodeIndex, double level, int *out_index); /** @brief Deletes an existing simple control. @@ -1596,8 +1596,8 @@ typedef struct Project *EN_Project; that triggers the control. @return an error code. */ - int DLLEXPORT EN_getcontrol(EN_Project ph, int index, int *type, int *linkIndex, - double *setting, int *nodeIndex, double *level); + int DLLEXPORT EN_getcontrol(EN_Project ph, int index, int *out_type, int *out_linkIndex, + double *out_setting, int *out_nodeIndex, double *out_level); /** @brief Sets the properties of an existing simple control. @@ -1651,8 +1651,8 @@ typedef struct Project *EN_Project; @param[out] priority the rule's priority value. @return an error code. */ - int DLLEXPORT EN_getrule(EN_Project ph, int index, int *nPremises, - int *nThenActions, int *nElseActions, double *priority); + int DLLEXPORT EN_getrule(EN_Project ph, int index, int *out_nPremises, + int *out_nThenActions, int *out_nElseActions, double *out_priority); /** @brief Gets the ID name of a rule-based control given its index. @@ -1682,8 +1682,8 @@ typedef struct Project *EN_Project; @return an error code. */ int DLLEXPORT EN_getpremise(EN_Project ph, int ruleIndex, int premiseIndex, - int *logop, int *object, int *objIndex, int *variable, - int *relop, int *status, double *value); + int *out_logop, int *out_object, int *out_objIndex, int *out_variable, + int *out_relop, int *out_status, double *out_value); /** @brief Sets the properties of a premise in a rule-based control. @@ -1749,7 +1749,7 @@ typedef struct Project *EN_Project; @return an error code. */ int DLLEXPORT EN_getthenaction(EN_Project ph, int ruleIndex, int actionIndex, - int *linkIndex, int *status, double *setting); + int *out_linkIndex, int *out_status, double *out_setting); /** @brief Sets the properties of a THEN action in a rule-based control. @@ -1775,7 +1775,7 @@ typedef struct Project *EN_Project; @return an error code. */ int DLLEXPORT EN_getelseaction(EN_Project ph, int ruleIndex, int actionIndex, - int *linkIndex, int *status, double *setting); + int *out_linkIndex, int *out_status, double *out_setting); /** @brief Sets the properties of an ELSE action in a rule-based control.