mirror of https://github.com/lammps/lammps.git
update and correct documentation for utils functions
This commit is contained in:
Axel Kohlmeyer
parent
9c404e02fd
commit
ceeaf1e988
|
|
@ -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
|
||||
|
|
|
|||
135
src/utils.h
135
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 <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).
|
||||
*
|
||||
* \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
|
||||
|
|
|
|||
Loading…
Reference in New Issue