uk.ac.starlink.ast
Class KeyMap

java.lang.Object
  uk.ac.starlink.ast.AstObject
      uk.ac.starlink.ast.KeyMap

public class KeyMap
extends AstObject

Java interface to the AST KeyMap class - store a set of key/value pairs. The KeyMap class is used to store a set of values with associated keys which identify the values. The keys are strings. These may be case sensitive or insensitive as selected by the KeyCase attribute, and trailing spaces are ignored. The value associated with a key can be integer (signed 4 and 2 byte, or unsigned 1 byte), floating point (single or double precision), void pointer, character string or AST Object pointer. Each value can be a scalar or a one-dimensional vector. A KeyMap is conceptually similar to a Mapping in that a KeyMap transforms an input into an output - the input is the key, and the output is the value associated with the key. However, this is only a conceptual similarity, and it should be noted that the KeyMap class inherits from the Object class rather than the Mapping class. The methods of the Mapping class cannot be used with a KeyMap.

Licence

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public Licence as published by the Free Software Foundation; either version 2 of the Licence, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Licence for more details.

You should have received a copy of the GNU General Public Licence along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street,Fifth Floor, Boston, MA 02110-1301, USA

In Java, you are probably better off using a Map.

See Also:

AST KeyMap

Field Summary

static int	AST__BADTYPE Type constant represening no known type.
static int	AST__DOUBLETYPE Type constant representing double type.
static int	AST__INTTYPE Type constant representing int type.
static int	AST__OBJECTTYPE Type constant representing AstObject type.
static int	AST__STRINGTYPE Type constant representing String type.

Fields inherited from class uk.ac.starlink.ast.AstObject

AST__BAD, AST__TUNULL, pointer

Constructor Summary

KeyMap()
Create a KeyMap.

Method Summary

AstObject	mapGet0A(String key) Retrieve an AstObject.
String	mapGet0C(String key) Retrieve a string value.
Double	mapGet0D(String key) Retrieve a double value.
Integer	mapGet0I(String key) Retrieve an integer value.
AstObject[]	mapGet1A(String key) Retrieve an array of AstObjects.
String[]	mapGet1C(String key, int sleng) Retrieve a string array.
double[]	mapGet1D(String key) Retrieve a double array.
int[]	mapGet1I(String key) Retrieve an integer array.
boolean	mapHasKey(String key) Check if an entry with a given key exists in a KeyMap.
String	mapKey(int index) Get the key at a given index within the KeyMap.
int	mapLength(String key) Get the vector length of an entry in a KeyMap.
void	mapPut0A(String key, AstObject value, String comment) Store an AstObject.
void	mapPut0C(String key, String value, String comment) Store a string value.
void	mapPut0D(String key, double value, String comment) Store a double value.
void	mapPut0I(String key, int value, String comment) Store an integer value.
void	mapPut1A(String key, AstObject[] value, String comment) Store an AstObject array.
void	mapPut1C(String key, String[] value, String comment) Store a string array.
void	mapPut1D(String key, double[] value, String comment) Store a double array.
void	mapPut1I(String key, int[] value, String comment) Store an integer array.
void	mapRemove(String key) Removed a named entry from a KeyMap.
int	mapSize() Get the number of entries in a KeyMap.
int	mapType(String key) Get the data type of an entry in a KeyMap.

Methods inherited from class uk.ac.starlink.ast.AstObject

annul, clear, copy, delete, equals, finalize, getAstConstantI, getB, getC, getD, getF, getI, getID, getIdent, getL, getNobject, getObjSize, getRefCount, hashCode, isThreaded, reportVersions, sameObject, set, setB, setC, setD, setF, setI, setID, setIdent, setL, show, test, tune

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

AST__INTTYPE

public static final int AST__INTTYPE

Type constant representing int type.

AST__DOUBLETYPE

public static final int AST__DOUBLETYPE

Type constant representing double type.

AST__STRINGTYPE

public static final int AST__STRINGTYPE

Type constant representing String type.

AST__OBJECTTYPE

public static final int AST__OBJECTTYPE

Type constant representing AstObject type.

AST__BADTYPE

public static final int AST__BADTYPE

Type constant represening no known type.

Constructor Detail

KeyMap

public KeyMap()

Create a KeyMap.

Throws:

AstException - if an error occurred in the AST library

Method Detail

mapRemove

public void mapRemove(String key)

Removed a named entry from a KeyMap. This function removes a named entry from a KeyMap. It returns without action if the KeyMap does not contain the specified key.

Throws:

AstException - if an error occurred in the AST library

mapSize

public int mapSize()

Get the number of entries in a KeyMap. This function returns the number of entries in a KeyMap.

Notes

- A function value of zero will be returned if an error has already occurred, or if this function should fail for any reason.

Returns:

The number of entries in the KeyMap.

Throws:

AstException - if an error occurred in the AST library

mapLength

public int mapLength(String key)

Get the vector length of an entry in a KeyMap. This function returns the vector length of a named entry in a KeyMap, (that is, how many values are associated with the entry).

Notes

- A function value of zero will be returned if an error has already occurred, or if this function should fail for any reason.

Parameters:

key - The character string identifying the KeyMap entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

Returns:

The length of the entry. One for a scalar, greater than one for a vector. A value of zero is returned if the KeyMap does not contain the named entry.

Throws:

AstException - if an error occurred in the AST library

mapHasKey

public boolean mapHasKey(String key)

Check if an entry with a given key exists in a KeyMap. This function returns a flag indicating if the KeyMap contains an entry with the given key.

Notes

- A non-zero function value is returned if the key exists but has an undefined value (that is, the returned value does not depend on whether the entry has a defined value or not).
- A function value of zero will be returned if an error has already occurred, or if this function should fail for any reason.

Parameters:

key - The character string identifying the KeyMap entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

Returns:

true iff this map contains an entry for key

Throws:

AstException - if an error occurred in the AST library

mapKey

public String mapKey(int index)

Get the key at a given index within the KeyMap. This function returns a string holding the key for the entry with the given index within the KeyMap.

This function is intended primarily as a means of iterating round all the elements in a KeyMap. For this purpose, the number of entries in the KeyMap should first be found using astMapSize and this function should then be called in a loop, with the index value going from zero to one less than the size of the KeyMap. The index associated with a given entry is determined by the SortBy attribute.

Notes

- The returned pointer is guaranteed to remain valid and the string to which it points will not be over-written for a total of 50 successive invocations of this function. After this, the memory containing the string may be re-used, so a copy of the string should be made if it is needed for longer than this.
- A NULL pointer will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

Parameters:

index - The index into the KeyMap. The first entry has index zero, and the last has index "size-1", where "size" is the value returned by the astMapSize function.

Returns:

A pointer to a null-terminated string containing the key.

Throws:

AstException - if an error occurred in the AST library

mapType

public int mapType(String key)

Get the data type of an entry in a KeyMap. This function returns a value indicating the data type of a named entry in a KeyMap. This is the data type which was used when the entry was added to the KeyMap.

Notes

- A function value of AST__BADTYPE will be returned if an error has already occurred, or if this function should fail for any reason.

Parameters:

key - The character string identifying the KeyMap entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

Returns:

One of AST__INTTYPE (for integer), AST__SINTTYPE (for short int), AST__BYTETYPE (for unsigned bytes
- i.e. unsigned chars ) AST__DOUBLETYPE (for double precision floating point), AST__FLOATTYPE (for single precision floating point), AST__STRINGTYPE (for character string), AST__OBJECTTYPE (for AST Object pointer), AST__POINTERTYPE (for arbitrary C pointer) or AST__UNDEFTYPE (for undefined values created by astMapPutU). AST__BADTYPE is returned if the supplied key is not found in the KeyMap.

Throws:

AstException - if an error occurred in the AST library

mapPut0D

public void mapPut0D(String key,
                     double value,
                     String comment)

Store a double value.

Parameters:

key - A character string to be stored with the value, which can later be used to identify the value. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

value - value to store

comment - A pointer to a null-terminated comment string to be stored with the value. A NULL pointer may be supplied, in which case no comment is stored.

Throws:

AstException - if an error occurred in the AST library

mapPut0I

public void mapPut0I(String key,
                     int value,
                     String comment)

Store an integer value.

Parameters:

key - A character string to be stored with the value, which can later be used to identify the value. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

value - value to store

comment - A pointer to a null-terminated comment string to be stored with the value. A NULL pointer may be supplied, in which case no comment is stored.

Throws:

AstException - if an error occurred in the AST library

mapPut0C

public void mapPut0C(String key,
                     String value,
                     String comment)

Store a string value.

Parameters:

key - A character string to be stored with the value, which can later be used to identify the value. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

value - value to store

comment - A pointer to a null-terminated comment string to be stored with the value. A NULL pointer may be supplied, in which case no comment is stored.

Throws:

AstException - if an error occurred in the AST library

mapPut0A

public void mapPut0A(String key,
                     AstObject value,
                     String comment)

Store an AstObject.

Parameters:

key - A character string to be stored with the value, which can later be used to identify the value. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

value - value to store

comment - A pointer to a null-terminated comment string to be stored with the value. A NULL pointer may be supplied, in which case no comment is stored.

Throws:

AstException - if an error occurred in the AST library

mapGet0D

public Double mapGet0D(String key)

Retrieve a double value.

Parameters:

key - The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

Returns:

object holding value stored in this map under key, or null if key was not present

Throws:

AstException - if an error occurred in the AST library

mapGet0I

public Integer mapGet0I(String key)

Retrieve an integer value.

Parameters:

key - The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

Returns:

object holding value stored in this map under key, or null if key was not present

Throws:

AstException - if an error occurred in the AST library

mapGet0C

public String mapGet0C(String key)

Retrieve a string value.

Parameters:

key - The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

Returns:

object holding value stored in this map under key, or null if key was not present

Throws:

AstException - if an error occurred in the AST library

mapGet0A

public AstObject mapGet0A(String key)

Retrieve an AstObject.

Parameters:

key - The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

Returns:

object holding value stored in this map under key, or null if key was not present

Throws:

AstException - if an error occurred in the AST library

mapPut1D

public void mapPut1D(String key,
                     double[] value,
                     String comment)

Store a double array.

Parameters:

key - A character string to be stored with the values, which can later be used to identify the values. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

value - array to store

comment - A pointer to a null-terminated comment string to be stored with the values. A NULL pointer may be supplied, in which case no comment is stored.

Throws:

AstException - if an error occurred in the AST library

mapPut1I

public void mapPut1I(String key,
                     int[] value,
                     String comment)

Store an integer array.

Parameters:

key - A character string to be stored with the values, which can later be used to identify the values. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

value - array to store

comment - A pointer to a null-terminated comment string to be stored with the values. A NULL pointer may be supplied, in which case no comment is stored.

Throws:

AstException - if an error occurred in the AST library

mapPut1C

public void mapPut1C(String key,
                     String[] value,
                     String comment)

Store a string array.

Parameters:

key - A character string to be stored with the values, which can later be used to identify the values. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

value - array to store

comment - A pointer to a null-terminated comment string to be stored with the values. A NULL pointer may be supplied, in which case no comment is stored.

Throws:

AstException - if an error occurred in the AST library

mapPut1A

public void mapPut1A(String key,
                     AstObject[] value,
                     String comment)

Store an AstObject array.

Parameters:

key - A character string to be stored with the values, which can later be used to identify the values. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

value - array to store

comment - A pointer to a null-terminated comment string to be stored with the values. A NULL pointer may be supplied, in which case no comment is stored.

Throws:

AstException - if an error occurred in the AST library

mapGet1D

public double[] mapGet1D(String key)

Retrieve a double array.

Parameters:

key - The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

Returns:

value stored in this map under key as a double array, or null

Throws:

AstException - if an error occurred in the AST library

mapGet1I

public int[] mapGet1I(String key)

Retrieve an integer array.

Parameters:

key - The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

Returns:

value stored in this map under key as an integer array, or null

Throws:

AstException - if an error occurred in the AST library

mapGet1C

public String[] mapGet1C(String key,
                         int sleng)

Retrieve a string array.

Parameters:

key - The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

sleng - maximum length of any of the strings in the returned array; any longer strings will be truncated

Returns:

value stored in this map under key as a String array, or null

Throws:

AstException - if an error occurred in the AST library

mapGet1A

public AstObject[] mapGet1A(String key)

Retrieve an array of AstObjects.

Parameters:

key - The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.

Returns:

value stored in this map under key as an AstObject array, or null

Throws:

AstException - if an error occurred in the AST library