Miscelaneous functions¶
Error handling¶
Apart from the constructor functions (the functions returning pointers to the
chemfiles types); all the functions return a status code from the
chfl_status
enum:
-
enum chfl_status¶
chfl_status
list the possible values for the return status code of chemfiles functions.Values:
-
enumerator CHFL_SUCCESS¶
Status code for successful operations.
-
enumerator CHFL_MEMORY_ERROR¶
Status code for error concerning memory: out of memory, wrong size for pre-allocated buffers, etc.
-
enumerator CHFL_FILE_ERROR¶
Status code for error concerning files: the file do not exist, the user does not have rights to open it, etc.
-
enumerator CHFL_FORMAT_ERROR¶
Status code for error in file formating, i.e. for invalid files.
-
enumerator CHFL_SELECTION_ERROR¶
Status code for invalid selection strings.
-
enumerator CHFL_CONFIGURATION_ERROR¶
Status code for configuration files errors.
-
enumerator CHFL_OUT_OF_BOUNDS¶
Status code for out of bounds errors.
-
enumerator CHFL_PROPERTY_ERROR¶
Status code for errors related to properties.
-
enumerator CHFL_GENERIC_ERROR¶
Status code for any other error from Chemfiles.
-
enumerator CHFL_CXX_ERROR¶
Status code for error in the C++ standard library.
-
enumerator CHFL_SUCCESS¶
-
const char *chfl_last_error(void)¶
Get the last error message.
The last error message is a thread local variable, so you need to call this function in the thread from where the error happened.
- Returns:
A null-terminated string containing the last error message
-
chfl_status chfl_clear_errors(void)¶
Clear the thread local last error message.
The last error message is a thread local variable, so this function will only clear it in the thread where it is called.
- Returns:
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.
Format list and Metadata¶
-
chfl_status chfl_guess_format(const char *path, char *format, uint64_t buffsize)¶
Get the format that chemfiles would use to read a file at the given
path
in the string bufferformat
.The buffer size must be passed in
buffsize
. This function will returnCHFL_MEMORY_ERROR
if the format does not fit in the buffer.Most of the time, the format is only guessed from the filename extension, without reading the file to guess the format. When two or more format can share the same extension (for example CIF and mmCIF), chemfiles tries to read the file to distinguish between them. If reading fails, the default format for this extension is returned.
Opening the file using the returned format string might still fail. For example, it will fail if the file is not actually formatted according to the guessed format; or the format/compression combination is not supported (e.g.
XTC / GZ
will not work since the XTC reader does not support compressed files).The format is represented in a way compatible with the various
Trajectory
constructors, i.e."<format name> [/ <compression>]"
, where compression is optional.- Returns:
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.
-
chfl_status chfl_formats_list(chfl_format_metadata **metadata, uint64_t *count)¶
Get the list of formats known by chemfiles, as well as all associated metadata.
This function allocate memory for all known formats, and set
metadata
to this new array. Users of this function are responsible with cleaning up this memory usingchfl_free
. The number of known formats (and thus the size of the metadata array) is set incount
.- Returns:
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.
-
struct chfl_format_metadata¶
A
chfl_format_metadata
contains metadata associated with one format.Public Members
-
const char *name¶
Name of the format.
-
const char *extension¶
Extension associated with the format, or
NULL
if there is no extension associated.
-
const char *description¶
Extended, user-facing description of the format.
-
const char *reference¶
URL pointing to the format definition/reference.
-
bool read¶
Is reading files in this format implemented?
-
bool write¶
Is writing files in this format implemented?
-
bool memory¶
Does this format support in-memory IO?
-
bool positions¶
Does this format support storing atomic positions?
-
bool velocities¶
Does this format support storing atomic velocities?
-
bool unit_cell¶
Does this format support storing unit cell information?
-
bool atoms¶
Does this format support storing atom names or types?
-
bool bonds¶
Does this format support storing bonds between atoms?
-
bool residues¶
Does this format support storing residues?
-
const char *name¶
Warnings¶
The chemfiles library send warnings when it encounters malformed files, or any
other condition that the user might want to know about. By default, these
warnings are printed to the standard error stream.
chfl_set_warning_callback()
allow to redirect these warning by giving
it a callback function to be called on each warning event.
-
typedef void (*chfl_warning_callback)(const char *message)¶
Callback type that can be used to process warning events.
-
chfl_status chfl_set_warning_callback(chfl_warning_callback callback)¶
Set the global warning
callback
to be used for each warning event.- Returns:
CHFL_SUCCESS
Configuration files¶
You can add more configuration file to chemfiles with
chfl_add_configuration()
.
-
chfl_status chfl_add_configuration(const char *path)¶
Read configuration data from the file at
path
.By default, chemfiles reads configuration from any file named
.chemfiles.toml
orchemfiles.toml
in the current directory or any parent directory. This function can be used to add data from another configuration file.This function will fail if there is no file at
path
, or if the file is incorrectly formatted. Data from the new configuration file will overwrite any existing data.- Returns:
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.