readme

R 树

					 int numNeighbors,
					 HnPointArray *points_return,
					 HnDataArray *values_return
					 );

	    These functions run a nearest neighbor search, i.e., they
	    search the given number of points that are the nearest to
	    a given point.

		file              : the pointer to a data structure
				    associated with an SR-tree file
		coords            : the coordinates of a target point
	        numNeighbors      : the number of points to be found
		records_return    : records of nearest points
		numRecords_return : the number of nearest points

		point             : the target point
		points_return     : nearest points
		values_return     : attributes of nearest points

            The `numNeighbors' is not necessarily the maximum number
	    of points to be obtained. If the farthest point of a
	    result set has multiple points at the same rank, they are
	    also included in the result set.

	    In the C language interface, the type `HnSRTreeRecord' is
            used. It is defined in the header file `HnSRTree.h' as
	    follows:

		typedef struct {
		        double *coords;
		        void *data;
		        int size;
		} HnSRTreeRecord;

	    where `coords' is an array of coordinates of a point,
	    `data' is the pointer to its attribute, and `size' is the
	    size of the attribute. Records being returned by the
	    function `HnSRTreeGetNeighbors()' are allocated by that
	    function and released on its next invocation.

	    For example, the coordinates and the attributes of nearest
	    points can be obtained as follows:

		HnSRTree *file;
		double coords[DIMENSION];
		int numNeighbors;
		HnSRTreeRecord *records;
		int numRecords;
		int i, j;

		...

		(open an SR-tree and set `coords' and `numNeighbors')

		...

		HnSRTreeGetNeighbors(file, coords, numNeighbors,
				     &records, &numRecords);

		for (i=0; i<numRecords; i++) {
			double coords[DIMENSION];
			void *data;
			int size;

			for (j=0; j<DIMENSION; j++) {
				coords[j] = records[i].coords[j];
				....
			}
			....
			data = records[i].data;	
			size = records[i].size;
			....
		}

	    In the C++ language interface, the class `HnPointArray'
	    and `HnDataArray' are used. The former is the array of
	    instances of the class `HnPoint' and the latter is the
	    array of instances of the class `HnData'.

	    For example, the coordinates and the attributes of nearest
	    points can be obtained in the following way:

		HnSRTreeFile file;
		HnPoint target;
		int numNeighbors;
		HnPointArray points;
		HnDataArray values;
		int i, j;

		...

		(open an SR-tree and set `target' and `numNeighbors')

		...

		file.getNeighbors(target, numNeighbors, &points, &values);

		for (i=0; i<points.length(); i++) {
			double coords[DIMENSION];
		       	char *data;
			int size;

			for (j=0; j<DIMENSION; j++) {
				coords[j] = points[i].getCoord(j);
				....
			}
			....
			data = values[i].chars();
			size = values[i].length();
			....
		}

    (9) running a range search

	    (C  ) void HnSRTreeGetFirst(HnSRTree *file,
					const HnSRTreeRange ranges[],
				        HnSRTreeRecord **record_return
					);
	    	  void HnSRTreeGetNext(HnSRTree *file,
		     		       HnSRTreeRecord **record_return
				       );

	    (C++) void file.getFirst(HnPoint *point_return,
	                             HnData *value_return
			             );
		  void file.getFirst(const HnRect &region,
                                     HnPoint *point_return,
				     HnData *value_return
				     );
		  void file.getNext(HnPoint *point_return,
			            HnData *value_return
			            );

	    These functions run a range search, i.e., they search
	    points within a given region.

		file          : the pointer to a data structure associated
                                with an SR-tree file
		ranges        : the array of a range of the target region
		record_return : a record of an obtained point

		region        : the target region
		point_return  : an obtained point
		value_return  : an attribute of an obtained point

	    In the C language interface, the type `HnSRTreeRange' is
            used. It is defined in the header file `HnSRTree.h' as
	    follows:

		typedef struct {
		        double min;
		        double max;
		} HnSRTreeRange;

	    where `min' is the lowest bound and `max' is the highest
	    bound of a range. A record being returned by the function
	    `HnSRTreeGetFirst()' and `HnSRTreeGetNext()' is allocated
	    by these functions and released on their next invocation. 

	    For example, the coordinates and the attributes of points
	    within a region can be obtained as follows:

		HnSRTree *file;
		HnSRTreeRange ranges[DIMENSION];
		HnSRTreeRecord *record;
		int i;

		...

		(open an SR-tree and set `ranges')

		...

		HnSRTreeGetFirst(file, ranges, &record);

		while (record != NULL) {
			double coords[DIMENSION];
			void *data;
			int size;

			for (i=0; i<DIMENSION; i++) {
				coords[i] = record->coords[i];
				....
			}
			....
			data = record->data;	
			size = record->size;
			....

			HnSRTreeGetNext(file, &record);
		}

	    If the NULL is given to the second argument of
	    `HnSRTreeGetFirst()', every point in a tree is obtained.

	    In the C++ language interface, the class `HnRect' is
	    used. An object of the class `HnRect' can be created in
	    the following way:

		HnRect rect;

		rect = new_HnRect(dimension);
		for (i=0; i<dimension; i++)
			rect.setRange(min[i], HnRange::INCLUSIVE,
				      max[i], HnRange::INCLUSIVE,
				      i);

	    where it is supposed that the dimensionality of the object
	    is given by the variable `dimension' and its range of each
	    dimension is given by the array `min[]' and `max[]'.

	    For example, the coordinates and the attributes of points
	    within a region can be obtained in the following way:

		HnSRTreeFile file;
		HnRect region;
		HnPoint point;
		HnData value;
		int i;

		...

		(open an SR-tree and set `region')

		...

		file.getFirst(region, &point, &value);

		while (point != HnPoint::null) {
			double coords[DIMENSION];
			char *data;
			int size;

			for (i=0; i<DIMENSION; i++) {
				coords[i] = point.getCoord(i);
				....
			}
			....
			data = value.chars();
			size = value.length();
			....

			file.getNext(&point, &value);
		}

	    If the function `getFirst(&point, &values)' is used
	    instead of the function `getFirst(rect, &point, &value)',
	    every point in a tree is obtained.


History:

    10/15/96
	Version 1.0 is released.

    11/22/96
	The range query functions, HnSRTreeGetFirst() and
	HnSRTreeGetNext(), is added to the C language interface.

    11/22/96
	Version 1.1 is released.

    12/09/96
	The access mode is permitted and the diagnosis is returned on
	opening files.

    12/09/96
	Version 1.2 is released.

    06/02/97
	The GNU Library General Public License is applied.

    06/02/97
	Version 1.3 is released.

    12/02/97
	The file `README' is slightly modified.
	Version 1.3.1 is released.