Loading doc/src/pg_developer.rst +23 −20 Original line number Diff line number Diff line Loading @@ -753,8 +753,8 @@ reading or writing to files with error checking or translation of strings into specific types of numbers with checking for validity. This reduces redundant implementations and encourages consistent behavior. I/O functions with validity check ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ I/O with status check ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ These are wrappers around the corresponding C library calls like ``fgets()`` or ``fread()``. They will check if there were errors Loading @@ -771,19 +771,21 @@ indicating the name of the problematic file, if possible. String to number conversions with validity check ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ These are functions equivalent to those in the ``Force`` class that were implemented with the aim to replace and supersede those. Unlike the versions in ``Force``, these can be used in cases where only a single MPI rank is trying to convert strings to numbers, as you can select through an argument, whether ``Error->all()`` or ``Error->one()`` should be called on improper strings. These functions are preferred over C library calls like ``atoi()`` or These functions should be used to convert strings to numbers. They are are strongly preferred over C library calls like ``atoi()`` or ``atof()`` since they check if the **entire** provided string is a valid (floating-point or integer) number, and will error out instead of silently return the result of a partial conversion or zero in cases where the string is not a valid number. This behavior allows to more easily detect typos or issues when processing input files. (floating-point or integer) number, and will error out instead of silently returning the result of a partial conversion or zero in cases where the string is not a valid number. This behavior allows to more easily detect typos or issues when processing input files. The *do_abort* flag should be set to ``true`` in case this function is called only on a single MPI rank, as that will then trigger the a call to ``Error::one()`` for errors instead of ``Error::all()`` and avoids a "hanging" calculation when run in parallel. Please also see :cpp:func:`is_integer` and :cpp:func:`is_double` for testing strings for compliance without conversion. .. doxygenfunction:: numeric :project: progguide Loading @@ -798,8 +800,9 @@ typos or issues when processing input files. :project: progguide String processing functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^ String processing ^^^^^^^^^^^^^^^^^ The following are functions to help with processing strings and parsing files or arguments. Loading Loading @@ -833,8 +836,8 @@ and parsing files or arguments. .. doxygenfunction:: is_double :project: progguide Filename and path functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File and path functions ^^^^^^^^^^^^^^^^^^^^^^^^^ .. doxygenfunction:: guesspath :project: progguide Loading Loading @@ -869,8 +872,8 @@ Potential file functions .. doxygenfunction:: open_potential :project: progguide Argument processing functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Argument processing ^^^^^^^^^^^^^^^^^^^ .. doxygenfunction:: bounds :project: progguide Loading src/utils.h +69 −66 Original line number Diff line number Diff line Loading @@ -138,24 +138,22 @@ namespace LAMMPS_NS { * \param str string to be converted to number * \param do_abort determines whether to call Error::one() or Error::all() * \param lmp pointer to top-level LAMMPS class instance * \return integer number (tagint) */ * \return integer number (tagint) */ tagint tnumeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp); /** Compute index bounds derived from a string with a possible wildcard * \verbatim embed:rst This functions processes the string in *str* and set the values of *nlo* and *nhi* according to the following five cases: #. a single number *i*: nlo = i; nhi = i; #. a single asterisk *\*\ *: nlo = nmin; nhi = nmax; #. a single number followed by an asterisk *i\*\ *: nlo = i; nhi = nmax; #. a single asterisk followed by a number *\*\ i*: nlo = nmin; nhi = i; #. two numbers with an asterisk in between *i\*\ j*: nlo = i; nhi = j; \endverbatim * This functions processes the string in *str* and set the values of *nlo* * and *nhi* according to the following five cases: * * - a single number *i*: nlo = i; nhi = i; * - a single asterisk \*: nlo = nmin; nhi = nmax; * - a single number followed by an asterisk *i*\*: nlo = i; nhi = nmax; * - a single asterisk followed by a number \**i*: nlo = nmin; nhi = i; * - two numbers with an asterisk in between *i\*j*: nlo = i; nhi = j; * * \param file name of source file for error message * \param line line number in source file for error message * \param str string to be processed Loading @@ -163,23 +161,22 @@ and *nhi* according to the following five cases: * \param nmax largest allowed upper bound * \param nlo lower bound * \param nhi upper bound * \param error pointer to Error class for out-of-bounds error message */ * \param error pointer to Error class for out-of-bounds messages */ void bounds(const char *file, int line, char *str, int nmin, int nmax, int &nlo, int &nhi, Error *error); /** Compute index bounds derived from a string with a possible wildcard * \verbatim embed:rst This functions processes the string in *str* and set the values of *nlo* and *nhi* according to the following five cases: #. a single number *i*: nlo = i; nhi = i; #. a single asterisk *\*\ *: nlo = nmin; nhi = nmax; #. a single number followed by an asterisk *i\*\ *: nlo = i; nhi = nmax; #. a single asterisk followed by a number *\*\ i*: nlo = nmin; nhi = i; #. two numbers with an asterisk in between *i\*\ j*: nlo = i; nhi = j; \endverbatim * This functions processes the string in *str* and set the values of *nlo* * and *nhi* according to the following five cases: * * - a single number *i*: nlo = i; nhi = i; * - a single asterisk \*: nlo = nmin; nhi = nmax; * - a single number followed by an asterisk *i*\*: nlo = i; nhi = nmax; * - a single asterisk followed by a number \**i*: nlo = nmin; nhi = i; * - two numbers with an asterisk in between *i\*j*: nlo = i; nhi = j; * * \param file name of source file for error message * \param line line number in source file for error message * \param str string to be processed Loading @@ -187,8 +184,8 @@ and *nhi* according to the following five cases: * \param nmax largest allowed upper bound * \param nlo lower bound * \param nhi upper bound * \param error pointer to Error class for out-of-bounds error message */ * \param error pointer to Error class for out-of-bounds messages */ void boundsbig(const char *file, int line, char *str, bigint nmin, bigint nmax, bigint &nlo, bigint &nhi, Error *error); Loading Loading @@ -216,8 +213,8 @@ and *nhi* according to the following five cases: * \param mode select between global vectors(=0) and arrays (=1) * \param earg new argument list with wildcards expanded * \param lmp pointer to top-level LAMMPS class instance * \return number of arguments in expanded list */ * \return number of arguments in expanded list */ int expand_args(const char *file, int line, int narg, char **arg, int mode, char **&earg, LAMMPS *lmp); Loading Loading @@ -326,7 +323,7 @@ and *nhi* according to the following five cases: bool file_is_readable(const std::string &path); /** Determine full path of potential file. If file is not found in current directory, * search LAMMPS_POTENTIALS folder * search directories listed in LAMMPS_POTENTIALS environment variable * * \param path file path * \return full path to potential file Loading Loading @@ -369,19 +366,25 @@ and *nhi* according to the following five cases: /** Open a potential file as specified by *name* * \verbatim embed:rst If opening the file directly fails, it will search for it in the folder(s) pointed to by the environment variable LAMMPS_POTENTIALS. If the potential file has a ``UNITS`` tag in the first line, its value is compared to the current :doc:`unit style <units>` setting. \endverbatim * If opening the file directly fails, the function will search for * it in the list of folder pointed to by the environment variable * LAMMPS_POTENTIALS (if it is set). * * If the potential file has a ``UNITS`` tag in the first line, the * tag's value is compared to the current unit style setting. * The behavior of the function then depends on the value of the * *auto_convert* parameter. If it is ``NULL``, then the unit values * must match or else the open will fail with an error. Otherwise * the bitmask that *auto_convert* points to is used check for * compatibility with possible automatic conversions by the calling * function. If compatible, the bitmask is set to the required * conversion or ``NOCONVERT``. * * \param name file- or pathname of the potential file * \param lmp pointer to top-level LAMMPS class instance * \param auto_convert pointer to automatic unit conversion bitmask * \return FILE pointer of the opened potential file or NULL */ * \param auto_convert pointer to unit conversion bitmask or NULL * \return FILE pointer of the opened potential file or NULL*/ FILE *open_potential(const std::string &name, LAMMPS *lmp, int *auto_convert); /** Convert a time string to seconds Loading Loading
doc/src/pg_developer.rst +23 −20 Original line number Diff line number Diff line Loading @@ -753,8 +753,8 @@ reading or writing to files with error checking or translation of strings into specific types of numbers with checking for validity. This reduces redundant implementations and encourages consistent behavior. I/O functions with validity check ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ I/O with status check ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ These are wrappers around the corresponding C library calls like ``fgets()`` or ``fread()``. They will check if there were errors Loading @@ -771,19 +771,21 @@ indicating the name of the problematic file, if possible. String to number conversions with validity check ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ These are functions equivalent to those in the ``Force`` class that were implemented with the aim to replace and supersede those. Unlike the versions in ``Force``, these can be used in cases where only a single MPI rank is trying to convert strings to numbers, as you can select through an argument, whether ``Error->all()`` or ``Error->one()`` should be called on improper strings. These functions are preferred over C library calls like ``atoi()`` or These functions should be used to convert strings to numbers. They are are strongly preferred over C library calls like ``atoi()`` or ``atof()`` since they check if the **entire** provided string is a valid (floating-point or integer) number, and will error out instead of silently return the result of a partial conversion or zero in cases where the string is not a valid number. This behavior allows to more easily detect typos or issues when processing input files. (floating-point or integer) number, and will error out instead of silently returning the result of a partial conversion or zero in cases where the string is not a valid number. This behavior allows to more easily detect typos or issues when processing input files. The *do_abort* flag should be set to ``true`` in case this function is called only on a single MPI rank, as that will then trigger the a call to ``Error::one()`` for errors instead of ``Error::all()`` and avoids a "hanging" calculation when run in parallel. Please also see :cpp:func:`is_integer` and :cpp:func:`is_double` for testing strings for compliance without conversion. .. doxygenfunction:: numeric :project: progguide Loading @@ -798,8 +800,9 @@ typos or issues when processing input files. :project: progguide String processing functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^ String processing ^^^^^^^^^^^^^^^^^ The following are functions to help with processing strings and parsing files or arguments. Loading Loading @@ -833,8 +836,8 @@ and parsing files or arguments. .. doxygenfunction:: is_double :project: progguide Filename and path functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File and path functions ^^^^^^^^^^^^^^^^^^^^^^^^^ .. doxygenfunction:: guesspath :project: progguide Loading Loading @@ -869,8 +872,8 @@ Potential file functions .. doxygenfunction:: open_potential :project: progguide Argument processing functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Argument processing ^^^^^^^^^^^^^^^^^^^ .. doxygenfunction:: bounds :project: progguide Loading
src/utils.h +69 −66 Original line number Diff line number Diff line Loading @@ -138,24 +138,22 @@ namespace LAMMPS_NS { * \param str string to be converted to number * \param do_abort determines whether to call Error::one() or Error::all() * \param lmp pointer to top-level LAMMPS class instance * \return integer number (tagint) */ * \return integer number (tagint) */ tagint tnumeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp); /** Compute index bounds derived from a string with a possible wildcard * \verbatim embed:rst This functions processes the string in *str* and set the values of *nlo* and *nhi* according to the following five cases: #. a single number *i*: nlo = i; nhi = i; #. a single asterisk *\*\ *: nlo = nmin; nhi = nmax; #. a single number followed by an asterisk *i\*\ *: nlo = i; nhi = nmax; #. a single asterisk followed by a number *\*\ i*: nlo = nmin; nhi = i; #. two numbers with an asterisk in between *i\*\ j*: nlo = i; nhi = j; \endverbatim * This functions processes the string in *str* and set the values of *nlo* * and *nhi* according to the following five cases: * * - a single number *i*: nlo = i; nhi = i; * - a single asterisk \*: nlo = nmin; nhi = nmax; * - a single number followed by an asterisk *i*\*: nlo = i; nhi = nmax; * - a single asterisk followed by a number \**i*: nlo = nmin; nhi = i; * - two numbers with an asterisk in between *i\*j*: nlo = i; nhi = j; * * \param file name of source file for error message * \param line line number in source file for error message * \param str string to be processed Loading @@ -163,23 +161,22 @@ and *nhi* according to the following five cases: * \param nmax largest allowed upper bound * \param nlo lower bound * \param nhi upper bound * \param error pointer to Error class for out-of-bounds error message */ * \param error pointer to Error class for out-of-bounds messages */ void bounds(const char *file, int line, char *str, int nmin, int nmax, int &nlo, int &nhi, Error *error); /** Compute index bounds derived from a string with a possible wildcard * \verbatim embed:rst This functions processes the string in *str* and set the values of *nlo* and *nhi* according to the following five cases: #. a single number *i*: nlo = i; nhi = i; #. a single asterisk *\*\ *: nlo = nmin; nhi = nmax; #. a single number followed by an asterisk *i\*\ *: nlo = i; nhi = nmax; #. a single asterisk followed by a number *\*\ i*: nlo = nmin; nhi = i; #. two numbers with an asterisk in between *i\*\ j*: nlo = i; nhi = j; \endverbatim * This functions processes the string in *str* and set the values of *nlo* * and *nhi* according to the following five cases: * * - a single number *i*: nlo = i; nhi = i; * - a single asterisk \*: nlo = nmin; nhi = nmax; * - a single number followed by an asterisk *i*\*: nlo = i; nhi = nmax; * - a single asterisk followed by a number \**i*: nlo = nmin; nhi = i; * - two numbers with an asterisk in between *i\*j*: nlo = i; nhi = j; * * \param file name of source file for error message * \param line line number in source file for error message * \param str string to be processed Loading @@ -187,8 +184,8 @@ and *nhi* according to the following five cases: * \param nmax largest allowed upper bound * \param nlo lower bound * \param nhi upper bound * \param error pointer to Error class for out-of-bounds error message */ * \param error pointer to Error class for out-of-bounds messages */ void boundsbig(const char *file, int line, char *str, bigint nmin, bigint nmax, bigint &nlo, bigint &nhi, Error *error); Loading Loading @@ -216,8 +213,8 @@ and *nhi* according to the following five cases: * \param mode select between global vectors(=0) and arrays (=1) * \param earg new argument list with wildcards expanded * \param lmp pointer to top-level LAMMPS class instance * \return number of arguments in expanded list */ * \return number of arguments in expanded list */ int expand_args(const char *file, int line, int narg, char **arg, int mode, char **&earg, LAMMPS *lmp); Loading Loading @@ -326,7 +323,7 @@ and *nhi* according to the following five cases: bool file_is_readable(const std::string &path); /** Determine full path of potential file. If file is not found in current directory, * search LAMMPS_POTENTIALS folder * search directories listed in LAMMPS_POTENTIALS environment variable * * \param path file path * \return full path to potential file Loading Loading @@ -369,19 +366,25 @@ and *nhi* according to the following five cases: /** Open a potential file as specified by *name* * \verbatim embed:rst If opening the file directly fails, it will search for it in the folder(s) pointed to by the environment variable LAMMPS_POTENTIALS. If the potential file has a ``UNITS`` tag in the first line, its value is compared to the current :doc:`unit style <units>` setting. \endverbatim * If opening the file directly fails, the function will search for * it in the list of folder pointed to by the environment variable * LAMMPS_POTENTIALS (if it is set). * * If the potential file has a ``UNITS`` tag in the first line, the * tag's value is compared to the current unit style setting. * The behavior of the function then depends on the value of the * *auto_convert* parameter. If it is ``NULL``, then the unit values * must match or else the open will fail with an error. Otherwise * the bitmask that *auto_convert* points to is used check for * compatibility with possible automatic conversions by the calling * function. If compatible, the bitmask is set to the required * conversion or ``NOCONVERT``. * * \param name file- or pathname of the potential file * \param lmp pointer to top-level LAMMPS class instance * \param auto_convert pointer to automatic unit conversion bitmask * \return FILE pointer of the opened potential file or NULL */ * \param auto_convert pointer to unit conversion bitmask or NULL * \return FILE pointer of the opened potential file or NULL*/ FILE *open_potential(const std::string &name, LAMMPS *lmp, int *auto_convert); /** Convert a time string to seconds Loading
