contrib/cube/CHANGES

   1 ********************************************************************************
   2 Changes that were made in July 2006 by Joshua Reich I.
   3 ********************************************************************************
   4
   5 Code Cleanup:
   6
   7 Update the calling convention for all external facing functions. By external
   8 facing, I mean all functions that are directly referenced in cube.sql. Prior
   9 to my update, all functions used the older V0 calling convention. They now
  10 use V1.
  11
  12 New Functions:
  13
  14 cube(float[]), which makes a zero volume cube from a float array
  15
  16 cube(float[], float[]), which allows the user to create a cube from
  17 two float arrays; one for the upper right and one for the lower left
  18 coordinate.
  19
  20 cube_subset(cube, int4[]), to allow you to reorder or choose a subset of
  21 dimensions from a cube, using index values specified in the array.
  22
  23 ********************************************************************************
  24 Changes that were made in August/September 2002 by Bruno Wolff III.
  25 ********************************************************************************
  26
  27 Note that this was based on a 7.3 development version and changes may not
  28 directly work with earlier versions.
  29
  30 I fixed a bug in cubescan.pl that prevented signed numbers with no digits
  31 before a decimal point from being accepted. This was submitted as a separate
  32 patch and may already be applied.
  33
  34 cube_inter should really return NULL if the two cubes don't overlap. However
  35 this requires changing to the new calling sequence and I don't know enough
  36 about how to do it to make the change.
  37
  38 I changed all floats to doubles except for g_cube_penalty which I don't
  39 think can be changed to return double. This might cause the penalty to
  40 overflow sooner than one might expect, but overflow could have happened
  41 even with floats.
  42
  43 I changed the output format (in cube_out) to use %.16g instead of %g, since the
  44 default is only 6 digits of precision.
  45
  46 I changed all of the functions declared with (isstrict) to use the current
  47 method of declaring this.
  48
  49 I changed all of the externally visible functions to be immutable which
  50 they are. I don't think this matters for the gist functions and didn't
  51 try to declare them immutable in case there was something tricky about them
  52 that I don't understand.
  53
  54 I changed the regression tests to use some larger exponents to test output
  55 in exponential form. 1e7 was too small for this.
  56
  57 I added some regression tests to check for 16 digits of precision. This
  58 may or may not be a good idea.
  59
  60 I got rid of the swap_corners function. It created scratch boxes that
  61 were iterated through and deleted. This is slower than just getting the
  62 larger or smaller coordinate as needed, since swap_corners was doing the
  63 same thing with the overhead of a function call and memory allocation.
  64
  65 I added memset calls to zero out newly allocated NDBOXes as the documentation
  66 on functions indicates should be done. This still doesn't allow a hash
  67 index for equality since there are multiple representations of the
  68 same cube.
  69
  70 I got rid of a call to cube_same in cube_lt and cube_gt since the test
  71 was redundant with other checks being made. The call to cube_same would
  72 only be faster if most of the time you were comparing equivalent cubes.
  73
  74 In cube_lt and cube_gt, the second (UR) for loop for comparing
  75 extra coordinates to 0 had the wrong range.
  76
  77 Note that the cube_distance function wasn't mentioned in the README.cube file.
  78
  79 I added regression tests for the cube_distance function.
  80
  81 I added the following new functions:
  82 cube
  83 cube_dim
  84 cube_ll_coord
  85 cube_ur_coord
  86 cube_is_point
  87 cube_enlarge
  88
  89 cube takes text input and returns a cube. This is useful for making cubes
  90 from computed strings.
  91
  92 cube_dim returns the number of dimensions stored in the data structure
  93 for a cube. This is useful for constraints on the dimensions of a cube.
  94
  95 cube_ll_coord returns the nth coordinate value for the lower left corner
  96 of a cube. This is useful for doing coordinate transformations.
  97
  98 cube_ur_coord returns the nth coordinate value for the upper right corner
  99 of a cube. This is useful for doing coordinate transformations.
 100
 101 cube_is_point returns true if a cube is also a point. This is true when the
 102 two defining corners are the same.
 103
 104 cube_enlarge increases the size of a cube by a specified radius in at least
 105 n dimensions. If the radius is negative the box is shrunk instead. This
 106 is useful for creating bounding boxes around a point for searching for
 107 nearby points. All defined dimensions are changed by the radius. If n
 108 is greater than the number of defined dimensions and the cube is being
 109 increased (r >= 0) then 0 is used as the base for the extra coordinates.
 110 LL coordinates are decreased by r and UR coordinates are increased by r. If a
 111 LL coordinate is increased to larger than the corresponding UR coordinate
 112 (this can only happen when r < 0) than both coordinates are set to their
 113 average.
 114
 115 I added regression tests for the new functions.
 116
 117 I added documentation for cube_distance and the new functions to README.cube
 118 as well as making a few other minor changes.
 119
 120 I changed create function to create or replace function in the install
 121 script.
 122
 123 I limited the number of dimensions allowed in cube_enlarge and cube_in
 124 to 100 to make it harder for people to mess up the database. The constant
 125 is defined in cubedata.h and can be increased if you need something larger.
 126
 127 I added grant statements to the install script to make the functions
 128 executable to everyone.
 129
 130 Bruno Wolff III <bruno@wolff.to>