dt_canstream

Daylight v4.9
Release Date: 1 February 2008

Name

dt_canstream - retrieve a stream of objects in canonical order

Generic Prototype

dt_canstream(dt_Handle, dt_Integer, dt_Boolean, dt_Boolean) => dt_Handle

C Prototype

#include "dt_smiles.h"

dt_Handle dt_canstream(dt_Handle object, dt_Integer type, dt_Boolean iso, dt_Boolean addh)

FORTRAN Prototype

include 'dt_f_smiles.inc'

integer*4 dt_f_canstream(object, type, iso, addh)

integer*4 object
integer*4 type
logical iso
logical addh

Description

Allocates a stream of type 'type', in canonical order, for the molecule or reaction 'object'. Calls to dt_next(3) over the new stream will return the constituent objects in the order defined by the string produced by dt_cansmiles(3).

The ordering of an atom stream is determined by the order in which the atoms appear in the canonical smiles string. The ordering of a bond stream occurs as follows: The atoms are first arranged in canonical order. Beginning with the lowest-order atom and going to the highest-order atom, each atom's bonds are added to the stream if they are not already part of the stream. Multiple bonds to an atom are further ordered by comparing the orders of the atom to which the bonds are attached.

For molecules, TYP_ATOM and TYP_BOND are allowed. For reactions, TYP_ATOM, TYP_BOND, and TYP_MOLECULE are allowed.

If 'iso' is TRUE, the stream produced is for the absolute SMILES (containing isomeric information); if 'iso' is FALSE, the stream is for the unique SMILES (no isomeric information). This corresponds to the 'iso' parameter for the function dt_cansmiles(3).

For an atom stream, if 'addh' is TRUE, ordinary hydrogens are added to the end of the stream, in canonical order. For each atom in the stream, explicit hydrogen atoms bonded to it are added, then an 'isohydro' is added for each implicit hydrogen (see dt_isohydro(3)). If 'addh' is FALSE, ordinary hydrogens do not appear in the stream, even if they are explicit atoms within the molecule.

Similarly for a bond stream, if 'addh' is TRUE, bonds to hydrogen are added to the end of the stream in canonical order. For each atom in the stream, bonds to explicit hydrogens are added followed by an 'isohydro' for each bond to an implicit hydrogen. If 'addh' is FALSE, bonds to ordinary hydrogens do not appear in the stream, even if they are explicit bonds within the molecule.

Note that if canonical labelings have not been computed for the molecule since it was created or last-modified, this potentially time-consuming step will be performed.

The stream is deallocated and its handle is revoked if the base molecule is modified or deallocated.

Return Value