astCmpRegion

Create a CmpRegion

Description:

This function creates a new CmpRegion and optionally initialises its attributes.

A CmpRegion is a Region which allows two component Regions (of any class) to be combined to form a more complex Region. This combination may be performed a boolean AND, OR or XOR (exclusive OR) operator. If the AND operator is used, then a position is inside the CmpRegion only if it is inside both of its two component Regions. If the OR operator is used, then a position is inside the CmpRegion if it is inside either (or both) of its two component Regions. If the XOR operator is used, then a position is inside the CmpRegion if it is inside one but not both of its two component Regions. Other operators can be formed by negating one or both component Regions before using them to construct a new CmpRegion.

The two component Region need not refer to the same coordinate Frame, but it must be possible for the astConvert function to determine a Mapping between them (an error will be reported otherwise when the CmpRegion is created). For instance, a CmpRegion may combine a Region defined within an ICRS SkyFrame with a Region defined within a Galactic SkyFrame. This is acceptable because the SkyFrame class knows how to convert between these two systems, and consequently the astConvert function will also be able to convert between them. In such cases, the second component Region will be mapped into the coordinate Frame of the first component Region, and the Frame represented by the CmpRegion as a whole will be the Frame of the first component Region.

Since a CmpRegion is itself a Region, it can be used as a component in forming further CmpRegions. Regions of arbitrary complexity may be built from simple individual Regions in this way.

Synopsis

AstCmpRegion astCmpRegion( AstRegion region1, AstRegion region2, int oper, const char options, ... )

Parameters:

region1
Pointer to the first component Region.
region2
Pointer to the second component Region. This Region will be transformed into the coordinate Frame of the first region before use. An error will be reported if this is not possible.
oper
The boolean operator with which to combine the two Regions. This must be one of the symbolic constants AST__AND, AST__OR or AST__XOR.
options
Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new CmpRegion. The syntax used is identical to that for the astSet function and may include " printf" format specifiers identified by " %" symbols in the normal way.
...
If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function).

Returned Value

astCmpRegion()
A pointer to the new CmpRegion.

Notes: