SDS_EXTRACT_SUBSET(3)

NAME

     sds_extract_subset - extract a multi-dimensional  contiguous
     subset an sds

SYNOPSIS

     #include <soi_fun.h>

     int sds_extract_subset  (sds, start, size);

     SDS *sds;
     int *start, *size;

DESCRIPTION

     sds_extract_subset() extracts a contiguous subset  from  the
     data  in  a SDS starting at the array index values specified
     in the array start and of lengths along each axis as  speci-
     fied  in  the array size.  The data structure is modified in
     place.

     It is possible to specify the  end  point  rather  than  the
     starting  point along a given axis by making the correspond-
     ing size value negative.

     The rank of the extracted data set is unchanged, even if one
     or more axes of the extracted subset are of length 1.

EXAMPLES

     With start[0] = 1023, start[1] =  256,  start[2]  =  0,  and
     size[0]    =   -256,   size[1]   =   1,   size[2]   =   256,
     sds_extract_subset() will extract from a  1024*512*256  data
     cube  a  256*1*256  cube  corresponding to the ``rightmost''
     quarter of the x-z plane through y = 256.

DIAGNOSTICS

     If the requested offset and/or size arrays  contains  values
     inconsistent with the original data set, such as zero length
     or end points outside the axis ranges, the function  returns
     1;  otherwise  it returns 0.  size values of 0 are converted
     to 1; end points are converted to keep the subset within the
     original data set.

SEE ALSO

     sds_bin(3), sds_slice(3)

AUTHOR

     Rick Bogart

BUGS

     There is no checking for appropriate lengths of  the  arrays
     specifying the extraction parameters.

     sds_extract_subset()   may   be   superfluous;    same    as
     sds_slice().

HISTORY

     1997-04-22                      SOI Version 2.1