DS(3)

PACKAGE
ds - Routines to manipulate the general data structure

PURPOSE
These routines provide the base functionality for the recursive, heirarchical data structure supported in Karma. This package both defines the (transparent) data structure and the various allocation, deallocation and manipulation routines. Transfer of data structures to/ from disc/ connections is supplied by the <-dsxfr-> routines.

LIBRARY
karma

LINK WITH
-lkarma

FUNCTIONS

ds_alloc_multi
    Allocate a multi_array descriptor.

ds_alloc_packet_desc
    Allocate a packet descriptor.

ds_alloc_data
    Allocate packet data recursively.

ds_alloc_packet_subdata
    Allocate packet sub-data.

ds_alloc_packet
    Allocate packet.

ds_alloc_array_desc
    Allocate array descriptor.

ds_alloc_tiling_info
    Allocate array tiling information.

ds_alloc_dim_desc
    Allocate a dimension descriptor.

ds_alloc_list_head
    Allocate a linked list header.

ds_alloc_list_entry
    Allocate a linked list entry.

ds_alloc_array
    Allocate an array.

ds_alloc_contiguous_list
    Allocate a contiguous list of linked list entries.

ds_find_1D_extremes
    Find the minimum and maximum of a 1D array.

ds_find_2D_extremes
    Find the minimum and maximum of a 2D array.

ds_find_contiguous_extremes
    Find the minimum and maximum of a contiguous array.

ds_find_single_histogram
    Find the histogram of a 1D array.

ds_complex_to_real_1D
    Convert a 1 dimensional array of complex values to real values.

ds_find_1D_sum
    Find the sum of a 1D array.

ds_find_1D_stats
    Compute simple statistics for a 1D array.

ds_find_2D_stats
    Compute simple statistics for a 2D array.

ds_put_unique_named_value
    Add a unique named value to a Karma general data structure.

ds_put_unique_named_string
    Add a unique named string to a Karma general data structure.

ds_get_unique_named_value
    Get a unique named value from a Karma general data structure.

ds_get_unique_named_string
    Get a unique named string from a Karma general data structure.

ds_copy_unique_named_element
    Copy a unique named element from one packet to another.

ds_get_fits_axis
    Get the FITS axis number of a dimension.

ds_element_is_fits_compatible
    Test if an element is FITS-compatible.

ds_get_data_scaling
    Get the scale and offset for a data element in a packet.

ds_set_data_scaling
    Set the data scale and offset for a data element in a packet.

ds_get_data_range
    Get the data range for a data element in a packet.

ds_set_data_range
    Set the data range for a data element in a packet.

ds_remove_unique_named_element
    Remove a unique named element from a Karma general data structure

ds_find_centroid
    Find the centroid inside an ellipse.

ds_cmap_alloc_colourmap
    Allocate a Karma data structure to hold a colourmap.

ds_cmap_find_colourmap
    Search a Karma data structure for an instance of a colourmap.

ds_cmap_get_all_colourmaps
    Search an array of Karma data structures for colourmaps.

ds_compare_packet_desc
    Recursively compare two packet descriptors.

ds_compare_array_desc
    Recursively compare two array descriptors.

ds_compare_dim_desc
    Compare two dimension descriptors.

ds_contour
    Extract contours from a 2-dimensional array.

ds_copy_packet
    Copy a packet.

ds_copy_desc_until
    Recursively copy a packet descriptor.

ds_copy_array_desc_until
    Recursively copy an array descriptor.

ds_copy_dim_desc
    Copy a dimension descriptor.

ds_copy_data
    Copy data between Karma data structures.

ds_copy_array
    Recursively copy array data.

ds_copy_list
    Recursively copy linked lists.

ds_select_arrays
    Select data structures in a multi_array descriptor.

ds_dealloc_multi
    Deallocate a multi_array data structure.

ds_dealloc_packet
    Recursively deallocate a packet.

ds_dealloc_data
    Recursively deallocate packet data.

ds_dealloc_packet_subdata
    Recursively deallocate packet data.

ds_dealloc_array_desc
    Recursively deallocate an array.

ds_dealloc_list
    Recursively deallocate a linked list.

ds_dealloc_list_entries
    Recursively deallocate list entries.

ds_dealloc2_list
    Deallocate linked list entries.

ds_dealloc_array
    Recursively deallocate array.

ds_draw_ellipse
    Draw an ellipse into a 2 dimensional Karma array.

ds_draw_polygon
    Draw a polygon into a 2 dimensional array.

ds_easy_alloc_array
    Allocate a data structure with a simple array.

ds_easy_alloc_n_element_array
    Allocate a data structure with a simple, multi element array.

ds_wrap_preallocated_n_element_array
    Wrap a data structure around an array.

ds_easy_alloc_array_desc
    Allocate a simple array descriptor.

ds_easy_alloc_array_from_array_desc
    Wrap a data structure around an array.

ds_alloc_vm_array
    Allocate storage for an array using ordinary virtual memory.

ds_alloc_shm_array
    Allocate storage for an array using shared memory.

ds_alloc_mmap_array
    Allocate storage for an array using shared anon mmap.

ds_event_register_func
    Register a multi_array event function.

ds_event_dispatch
    Dispatch a multi_array event.

ds_identify_name
    Search a data structure for a name.

ds_f_array_name
    Search a the top level of a data structure for a name.

ds_f_name_in_packet
    Recursively search for named item under a packet.

ds_f_name_in_array
    Recursively search for named item under an array.

ds_f_elem_in_packet
    Search for a named element in a packet, without recursion.

ds_find_hole
    Recursively search packet for a hole.

ds_f_dim_in_array
    Find dimension in array.

ds_check_for_descriptor
    Check if descriptor pointer lies in data structure.

ds_find_descriptor_parent
    Find the index of the data structure containing a descriptor.

ds_fitgauss_list
    Fit a gaussian to a list of points.

ds_fitgauss_profile
    Fit a gaussian to a 1-dimensional profile.

ds_gausscurve
    Write gaussian curve to an array.

ds_convert_atomic
    Convert an atomic datum to a double precision value.

ds_get_coordinate
    Get a co-ordinate along a dimension.

ds_convert_coordinates
    Convert co-ordinate values for a dimension.

ds_get_element_offset
    Calculate the offset of the start of a data element in a packet.

ds_get_packet_size
    Calculate size in bytes of a packet.

ds_get_array_size
    Calculate the number of co-ordinate points in an array.

ds_check_array_can_fit
    Check if the array data can fit in the machine.

ds_packet_all_data
    Test if packet contains only atomic data elements.

ds_element_is_atomic
    Test if an element is atomic.

ds_element_is_named
    Test if an element is a named data type.

ds_element_is_legal
    Test if an element is legal.

ds_get_array_offset
    Compute offset of a co-ordinate in an array.

ds_get_coord_num
    Get index of a co-ordinate along a dimension.

ds_get_element
    Convert an atomic datum to a double precision complex value.

ds_get_elements
    Convert atomic data values to double precision complex values.

ds_get_coordinate_array
    Get co-ordinate array for a dimension.

ds_element_is_complex
    Test if the type of an element is complex or not.

ds_get_scattered_elements
    Convert scattered atomic data to double precision complex values.

ds_can_transfer_element_as_block
    Test if an element can be transferred in one block.

ds_can_transfer_packet_as_block
    Test if a packet can be transferred in one block.

ds_can_swaptransfer_element
    Test if an element can be swapped and transferred in one block.

ds_get_handle_in_packet
    Find sub-structure in a general data structure.

ds_get_handle_in_array
    Find sub-structure in a multi-dimensional array.

ds_get_handle_in_list
    Find sub-structure in a linked list.

ds_history_append_string
    Add a history string to a Karma data structure.

ds_history_copy
    Copy history information.

ds_list_insert
    Insert an entry into the fragmented section of a linked list.

ds_list_append
    Append an entry to a linked list.

ds_list_delete
    Delete an entry from the fragmented section of a linked list.

ds_list_unfragment
    Unfragment a linked list.

ds_list_fragment
    Fragment a linked list.

ds_format_unit
    Format a unit string.

ds_format_value
    Format a data value into a string.

ds_remove_named_elements
    Remove a list of named elements from a packet.

ds_remove_dim_desc
    Remove dimension from an array.

ds_append_dim_desc
    Append a dimension to an array.

ds_prepend_dim_desc
    Prepend a dimension to an array.

ds_compute_array_offsets
    Compute array address offsets for each dimension in an array.

ds_remove_tiling_info
    Remove any tiling information from an array descriptor.

ds_append_gen_struct
    Append a general data structure to a multi_array structure.

ds_autotile_array
    Choose tiling scheme automatically.

ds_put_element
    Write out an element of data.

ds_put_elements
    Convert array of double precision complex data to atomic data.

ds_put_element_many_times
    Write a double precision complex value to atomic data many times.

ds_put_named_element
    Update a named element in a specified packet.

ds_reorder_array
    Re-order a multi-dimensional array.

ds_foreach_occurrence
    Recursively traverse a data structure, searching for an item.

ds_foreach_in_array
    Recursively traverse an array, searching for an item.

ds_foreach_in_list
    Recursively traverse a linked list, searching for an item.

ds_traverse_and_process
    Recursively traverse a pair of data structures.

ds_traverse_array
    Recursively traverse a pair of arrays.

ds_traverse_list
    Recursively traverse a pair of linked lists.

ds_PROTO_foreach_func
    Process an occurrence of an item in a data structure.

ds_PROTO_traverse_func
    Process an occurrence of a divergence between two data structures

ds_PROTO_event_func
    Process an event.

TABLE ds_COMPLEX_CONVERSIONS
List of complex conversion types
Name Meaning
CONV_CtoR_REAL Take the real component
CONV_CtoR_IMAG Take the imaginary component
CONV_CtoR_ABS Take the absolute value
CONV_CtoR_SQUARE_ABS Take the square of the absolute value
CONV_CtoR_PHASE Take the phase
CONV_CtoR_CONT_PHASE Take the continuous phase
CONV_CtoR_ENVELOPE Use the positive and negative of the
absolute value

TABLE ds_KARMA_DATA_TYPES
List of Karma data types
Name Meaning C data type
K_FLOAT Single precision floating point float
K_DOUBLE Double precision floating point double
K_BYTE Signed byte (character) signed char
K_INT Signed integer signed int
K_SHORT Signed short integer signed short
K_COMPLEX Complex float float[2]
K_DCOMPLEX Complex double double[2]
K_BCOMPLEX Complex signed byte signed char[2]
K_ICOMPLEX Complex signed integer signed int[2]
K_SCOMPLEX Complex signed short integer signed short[2]
K_LONG Signed long integer signed long
K_LCOMPLEX Complex signed long integer signed long[2]
K_UBYTE Unsigned byte unsigned char
K_UINT Unsigned integer unsigned int
K_USHORT Unsigned short integer unsigned short
K_ULONG Unsigned long integer unsigned long
K_UBCOMPLEX Complex unsigned byte unsigned char[2]
K_UICOMPLEX Complex unsigned integer unsigned int[2]
K_USCOMPLEX Complex unsigned short integer unsigned short[2]
K_ULCOMPLEX Complex unsigned long integer unsigned long[2]

TABLE ds_IDENT_TABLE
List of identification codes
Name Meaning
IDENT_NOT_FOUND Name not found
IDENT_GEN_STRUCT Name of general data structure
IDENT_DIMENSION Name of dimension
IDENT_ELEMENT Name of atomic data element
IDENT_MULTIPLE Name has multiple occurrences

TABLE ds_SEARCH_BIASES
List of co-ordinate search biases
Name Meaning
SEARCH_BIAS_LOWER Pick lower co-ordinate
SEARCH_BIAS_CLOSEST Pick closest co-ordinate
SEARCH_BIAS_UPPER Pick upper co-ordinate

TABLE ds_HANDLE_TYPES
List of handle types
Name Meaning
NONE if the item's parent is a packet.
K_ARRAY if the item's parent is an array.
LISTP if the item's parent is a linked list header.

TABLE ds_PARENT_TYPES
List of parent descriptor types
Name Meaning
NONE parent is a packet descriptor
IDENT_DIMENSION parent is a dimension descriptor
K_ARRAY parent is an array descriptor
LISTP parent is a linked list descriptor

AUTHOR
Richard Gooch (rgooch@atnf.csiro.au)

AVAILABLITY
The Karma Distribution is available for anonymous ftp from: ftp://ftp.atnf.csiro.au/pub/software/karma/ ftp://wuarchive.wustl.edu/graphics/graphics/packages/karma/ ftp://ftp.pwr.wroc.pl/pub/karma/ The Karma Home Page is: http://www.atnf.csiro.au/karma/