Function manipulating CHFL_SELECTION

typedef struct CHFL_SELECTION CHFL_SELECTION

An opaque type handling a selection.

CHFL_SELECTION allow to select atoms in a CHFL_FRAME, from a selection language. The selection language is built by combining basic operations. Each basic operation follows the <selector>[(<variable>)] <operator> <value> structure, where <operator> is a comparison operator in == != < <= > >=.

CHFL_SELECTION *chfl_selection(const char *selection)

Create a new selection from the given selection string.

The caller of this function should free the associated memory using chfl_selection_free.

Return
A pointer to the selection, or NULL in case of error. You can use chfl_last_error to learn about the error.

CHFL_SELECTION *chfl_selection_copy(const CHFL_SELECTION *selection)

Get a copy of a selection.

The copy does not contains any state, and chfl_selection_evaluate must be called again before using chfl_selection_matches.

The caller of this function should free the associated memory using chfl_selection_free.

Return
A pointer to the new selection, or NULL in case of error. You can use chfl_last_error to learn about the error.

chfl_status chfl_selection_size(const CHFL_SELECTION *selection, uint64_t *size)

Get the size of a selection in size.

The size of a selection is the number of atoms we are selecting together. This value is 1 for the ‘atom’ context, 2 for the ‘pair’ and ‘bond’ context, 3 for the ‘three’ and ‘angles’ contextes and 4 for the ‘four’ and ‘dihedral’ contextes.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_selection_string(const CHFL_SELECTION *selection, char *string, uint64_t buffsize)

Get the selection string used to create a given selection in the string buffer.

The buffer size must be passed in buffsize. This function will truncate the selection string to fit in the buffer.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_selection_evaluate(CHFL_SELECTION *selection, const CHFL_FRAME *frame, uint64_t *n_matches)

Evaluate a selection for a given frame, and store the number of matches in n_matches.

Use the chfl_selection_matches function to get the matches for this selection.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_selection_matches(const CHFL_SELECTION *selection, chfl_match matches[], uint64_t n_matches)

Get the matches for a selection after a call to chfl_selection_evaluate, in matches.

The size of the matches array must be passed in n_matches.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_selection_free(const CHFL_SELECTION *selection)

Free the memory associated with a selection.

Return
CHFL_SUCCESS

struct chfl_match

A chfl_match is a set of atomic indexes matching a given selection. The size of a match depends on the associated selection, and can vary from 1 to CHFL_MAX_SELECTION_SIZE.

Public Members

uint64_t size

The actual size of the match. Elements in atoms are significant up to this value, and filled with (uint64_t)-1 for all the other values.

uint64_t atoms[CHFL_MAX_SELECTION_SIZE]

Atomic indexes matching the associated selection.

CHFL_MAX_SELECTION_SIZE

Maximal size for a selection match.