next up previous 264
Next: Testing, Clearing and Defaulting Attributes
Up: An AST Object Primer
Previous: Getting Attribute Values


Setting Attribute Values

Some attribute values are read-only and cannot be altered after an Object has been created. The Nin attribute of a ZoomMap (describing the number of coordinates) is like this. It is defined when the ZoomMap is created, but cannot then be altered.

Other attributes, however, can be modified whenever you want. A ZoomMap's Zoom attribute is like this. If we wanted to change it, this could be done simply as follows:

astSetD( zoommap, "Zoom", 99.6 );

which sets the value to 99.6. As when getting an attribute value ([*]), you have a choice of which data type you will use to supply the new value. For instance, you could use an integer value, as in:

astSetI( zoommap, "Zoom", 99 );

and the necessary data conversion would occur. You specify the data type you want to supply simply by replacing the final character of the astSetX function name with C (character string), D (double), F (float), I (int) or L (long). Setting a boolean attribute to any non-zero integer causes it to take the value 1.

An alternative way of setting attribute values for Objects is to use the astSet function (i.e. with no final character specifying a data type). In this case, you supply the attribute values in a character string. The big advantage of this method is that you can assign values to several attributes at once, separating them with commas. This also reads more naturally in programs. For example:

astSet( zoommap, "Zoom=99.6, Report=1" );

would set values for both the Zoom attribute and the Report attribute (about which more shortly--[*]). You don't really have to worry about data types with this method, as any character representation will do. Note, when using astSet, a literal comma may be included in an attribute value by enclosed the value in quotation marks:

      astSet( skyframe, 'SkyRef="12:13:32,-23:12:44"' );

Another attractive feature of astSet is that you can build the character string which contains the attribute settings in the same way as when using the C run time library ``printf'' function. This is most useful when the values you want to set are held in other variables. For example:

double zoom = 99.6;
int report = 1;

...

astSet( zoommap, "Zoom=%g, Report=%d", zoom, report );

would replace the ``%'' conversion specifications by the values supplied as additional arguments. Any number of additional arguments may be supplied and the formatting rules are exactly the same as for the C ``printf'' family of functions. This is a very flexible technique, but does contain one pitfall:

Pitfall. The default precision used by ``printf'' (and astSet) for floating point values is only 6 decimal digits, corresponding approximately to float on most machines, whereas the AST library stores such values internally as doubles. You should be careful to specify a larger precision (such as DBL_DIG, as defined in $<$float.h$>$) when necessary. For example:

#include <float.h>

...

astSet( zoommap, "Zoom=%.*g", DBL_DIG, double_value );

Substituted strings may contain commas and this is a useful way of assigning such strings as attribute values without the comma being interpreted as an assignment separator, for example:

astSet( object, "Attribute=%s", "A string, containing a comma" );

This is equivalent to using astSetC and one of these two methods should always be used when assigning string attribute values which might potentially contain a comma (e.g. strings obtained from an external source). However, you should not attempt to use astSet to substitute strings that contain newline characters, since these are used internally as separators between adjacent attribute assignments.

Finally, a very convenient way of setting attribute values is to do so at the same time as you create an Object. Every Object constructor function has a final character string argument which allows you to do this. Although you can simply supply an empty string, it is an ideal opportunity to initialise the Object to have just the attributes you want. For example, we might have created our original ZoomMap with:

zoommap = astZoomMap( 2, 5.0, "Report=1" );

and it would then start life with its Report attribute set to 1. The ``printf''-style substitution described above may also be used here.


next up previous 264
Next: Testing, Clearing and Defaulting Attributes
Up: An AST Object Primer
Previous: Getting Attribute Values

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
25th February 2013
E-mail:starlink@jiscmail.ac.uk

Copyright (C) 2014 Science \& Technology Facilities Council