diff --git a/doc/src/pg_developer.rst b/doc/src/pg_developer.rst index f3d532df07..1886a15af6 100644 --- a/doc/src/pg_developer.rst +++ b/doc/src/pg_developer.rst @@ -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 @@ -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 @@ -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. @@ -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 @@ -869,8 +872,8 @@ Potential file functions .. doxygenfunction:: open_potential :project: progguide -Argument processing functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Argument processing +^^^^^^^^^^^^^^^^^^^ .. doxygenfunction:: bounds :project: progguide diff --git a/src/utils.h b/src/utils.h index e53781585d..17b507d157 100644 --- a/src/utils.h +++ b/src/utils.h @@ -133,62 +133,59 @@ namespace LAMMPS_NS { /** Convert a string to an integer number while checking * if it is a valid integer number (tagint) * - * \param file name of source file for error message - * \param line line number in source file for error message - * \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) - */ + * \param file name of source file for error message + * \param line line number in source file for error message + * \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) */ + 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; + * + * \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 + * \param nmin smallest possible lower bound + * \param nmax largest allowed upper bound + * \param nlo lower bound + * \param nhi upper bound + * \param error pointer to Error class for out-of-bounds messages */ -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 - - * \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 - * \param nmin smallest possible lower bound - * \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 - */ 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 + * \param nmin smallest possible lower bound + * \param nmax largest allowed upper bound + * \param nlo lower bound + * \param nhi upper bound + * \param error pointer to Error class for out-of-bounds messages */ - * \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 - * \param nmin smallest possible lower bound - * \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 - */ void boundsbig(const char *file, int line, char *str, bigint nmin, bigint nmax, bigint &nlo, bigint &nhi, Error *error); @@ -209,15 +206,15 @@ and *nhi* according to the following five cases: * caller. Otherwise arg and earg will point to the same address * and no explicit de-allocation is needed by the caller. * - * \param file name of source file for error message - * \param line line number in source file for error message - * \param narg number of arguments in current list - * \param arg argument list, possibly containing wildcards - * \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 - */ + * \param file name of source file for error message + * \param line line number in source file for error message + * \param narg number of arguments in current list + * \param arg argument list, possibly containing wildcards + * \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 */ + int expand_args(const char *file, int line, int narg, char **arg, int mode, char **&earg, LAMMPS *lmp); @@ -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 @@ -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 ` 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). * - * \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 - */ + * 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 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