A PermMap is a Mapping which permutes the order of coordinates, and possibly also changes the number of coordinates, between its input and output.
In addition to permuting the coordinate order, a PermMap may also assign constant values to coordinates. This is useful when the number of coordinates is being increased as it allows fixed values to be assigned to any new ones.
" nin" elements which, for each input coordinate, should contain the number
of the output coordinate whose value is to be used (note that this array therefore
defines the inverse coordinate transformation). Coordinates are numbered starting from
1.
For details of additional special values that may be used in this array, see the
description of the " constant" parameter.
If a NULL pointer is supplied instead of an array, each input coordinate will obtain its value from the corresponding output coordinate (or will be assigned the value AST__BAD if there is no corresponding output coordinate).
" nout"
elements which, for each output coordinate, should contain the number of the input
coordinate whose value is to be used (note that this array therefore defines the
forward coordinate transformation). Coordinates are numbered starting from
1.
For details of additional special values that may be used in this array, see the
description of the " constant" parameter.
If a NULL pointer is supplied instead of an array, each output coordinate will obtain its value from the corresponding input coordinate (or will be assigned the value AST__BAD if there is no corresponding input coordinate).
" inperm"
or " outperm" arrays contains a negative value, it is used to address this "
constant" array (such that -1 addresses the first element, -2 addresses the second
element, etc.) and the value obtained is used as the corresponding coordinate
value.
Care should be taken to ensure that locations lying outside the extent of this array
are not accidentally addressed. The array is not used if the " inperm" and " outperm"
arrays do not contain negative values.
If a NULL pointer is supplied instead of an array, the behaviour is as if the array were of infinite length and filled with the value AST__BAD.
" printf" format specifiers identified
by " %" symbols in the normal way. " 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). If either of the " inperm" or " outperm" arrays contains a zero value (or a positive
value which does not identify a valid output/input coordinate, as appropriate), then
the value AST__BAD is assigned as the new coordinate value.
This function does not attempt to ensure that the forward and inverse transformations performed by the PermMap are self-consistent in any way. You are therefore free to supply coordinate permutation arrays that achieve whatever effect is desired.
A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.