rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Minor hacking on contrib/cube documentation. 

Improve markup, particularly of the table of functions; add or improve
examples for some of the functions; wordsmith some of the function
descriptions.
This commit is contained in:
Tom Lane 2015-12-29 21:21:04 -05:00
parent efe4c9d704
commit e5e5267a91
1 changed files with 128 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

187
doc/src/sgml/cube.sgml
View File

@ -25,6 +25,13 @@
<table id="cube-repr-table">
<title>Cube External Representations</title>
<tgroup cols="2">
<thead>
<row>
<entry>External Syntax</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal><replaceable>x</></literal></entry>
@ -80,7 +87,8 @@
</para>
<para>
White space is ignored, so <literal>[(<replaceable>x</>),(<replaceable>y</>)]</literal> is the same as
White space is ignored on input, so
<literal>[(<replaceable>x</>),(<replaceable>y</>)]</literal> is the same as
<literal>[ ( <replaceable>x</> ), ( <replaceable>y</> ) ]</literal>.
</para>
</sect2>
@ -98,11 +106,11 @@
<title>Usage</title>
<para>
<xref linkend="cube-operators"> shows the operators provided for type
<type>cube</>.
<xref linkend="cube-operators-table"> shows the operators provided for
type <type>cube</>.
</para>
<table id="cube-operators">
<table id="cube-operators-table">
<title>Cube Operators</title>
<tgroup cols="3">
<thead>
@ -240,9 +248,7 @@
For example, the nearest neighbor of the 3-D point (0.5, 0.5, 0.5)
could be found efficiently with:
<programlisting>
SELECT c FROM test
ORDER BY cube(array[0.5,0.5,0.5]) <-> c
LIMIT 1;
SELECT c FROM test ORDER BY c &lt;-&gt; cube(array[0.5,0.5,0.5]) LIMIT 1;
</programlisting>
</para>
@ -252,12 +258,12 @@ LIMIT 1;
For example, to get the first few cubes ordered by the first coordinate
(lower left corner) ascending one could use the following query:
<programlisting>
SELECT c FROM test ORDER BY c ~> 1 LIMIT 5;
SELECT c FROM test ORDER BY c ~&gt; 1 LIMIT 5;
</programlisting>
And to get 2-D cubes ordered by the first coordinate of the upper right
corner descending:
<programlisting>
SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5;
SELECT c FROM test ORDER BY c ~&gt; 3 DESC LIMIT 5;
</programlisting>
</para>
@ -267,128 +273,191 @@ SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5;
<table id="cube-functions-table">
<title>Cube Functions</title>
<tgroup cols="2">
<tgroup cols="4">
<thead>
<row>
<entry>Function</entry>
<entry>Result</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>cube(float8) returns cube</literal></entry>
<entry><literal>cube(float8)</literal></entry>
<entry><type>cube</type></entry>
<entry>Makes a one dimensional cube with both coordinates the same.
</entry>
<entry>
<literal>cube(1) == '(1)'</literal>
</entry>
</row>
<row>
<entry><literal>cube(float8, float8) returns cube</literal></entry>
<entry><literal>cube(float8, float8)</literal></entry>
<entry><type>cube</type></entry>
<entry>Makes a one dimensional cube.
</entry>
<entry>
<literal>cube(1,2) == '(1),(2)'</literal>
</entry>
</row>
<row>
<entry><literal>cube(float8[]) returns cube</literal></entry>
<entry><literal>cube(float8[])</literal></entry>
<entry><type>cube</type></entry>
<entry>Makes a zero-volume cube using the coordinates
defined by the array.
</entry>
<entry>
<literal>cube(ARRAY[1,2]) == '(1,2)'</literal>
</entry>
</row>
<row>
<entry><literal>cube(float8[], float8[]) returns cube</literal></entry>
<entry><literal>cube(float8[], float8[])</literal></entry>
<entry><type>cube</type></entry>
<entry>Makes a cube with upper right and lower left
coordinates as defined by the two arrays, which must be of the
same length.
<literal>cube('{1,2}'::float[], '{3,4}'::float[]) == '(1,2),(3,4)'
</entry>
<entry>
<literal>cube(ARRAY[1,2], ARRAY[3,4]) == '(1,2),(3,4)'
</literal>
</entry>
</row>
<row>
<entry><literal>cube(cube, float8) returns cube</literal></entry>
<entry>Makes a new cube by adding a dimension on to an
existing cube with the same values for both parts of the new coordinate.
This is useful for building cubes piece by piece from calculated values.
<literal>cube('(1)',2) == '(1,2),(1,2)'</literal>
<entry><literal>cube(cube, float8)</literal></entry>
<entry><type>cube</type></entry>
<entry>Makes a new cube by adding a dimension on to an existing cube,
with the same values for both endpoints of the new coordinate. This
is useful for building cubes piece by piece from calculated values.
</entry>
<entry>
<literal>cube('(1,2),(3,4)'::cube, 5) == '(1,2,5),(3,4,5)'</literal>
</entry>
</row>
<row>
<entry><literal>cube(cube, float8, float8) returns cube</literal></entry>
<entry>Makes a new cube by adding a dimension on to an
existing cube. This is useful for building cubes piece by piece from
calculated values. <literal>cube('(1,2)',3,4) == '(1,3),(2,4)'</literal>
<entry><literal>cube(cube, float8, float8)</literal></entry>
<entry><type>cube</type></entry>
<entry>Makes a new cube by adding a dimension on to an existing
cube. This is useful for building cubes piece by piece from calculated
values.
</entry>
<entry>
<literal>cube('(1,2),(3,4)'::cube, 5, 6) == '(1,2,5),(3,4,6)'</literal>
</entry>
</row>
<row>
<entry><literal>cube_dim(cube) returns int</literal></entry>
<entry>Returns the number of dimensions of the cube
<entry><literal>cube_dim(cube)</literal></entry>
<entry><type>integer</type></entry>
<entry>Returns the number of dimensions of the cube.
</entry>
<entry>
<literal>cube_dim('(1,2),(3,4)') == '2'</literal>
</entry>
</row>
<row>
<entry><literal>cube_ll_coord(cube, int) returns double </literal></entry>
<entry>Returns the n'th coordinate value for the lower left
corner of a cube
<entry><literal>cube_ll_coord(cube, integer)</literal></entry>
<entry><type>float8</type></entry>
<entry>Returns the <replaceable>n</>-th coordinate value for the lower
left corner of the cube.
</entry>
<entry>
<literal>cube_ll_coord('(1,2),(3,4)', 2) == '2'</literal>
</entry>
</row>
<row>
<entry><literal>cube_ur_coord(cube, int) returns double
</literal></entry>
<entry>Returns the n'th coordinate value for the
upper right corner of a cube
<entry><literal>cube_ur_coord(cube, integer)</literal></entry>
<entry><type>float8</type></entry>
<entry>Returns the <replaceable>n</>-th coordinate value for the
upper right corner of the cube.
</entry>
<entry>
<literal>cube_ur_coord('(1,2),(3,4)', 2) == '4'</literal>
</entry>
</row>
<row>
<entry><literal>cube_is_point(cube) returns bool</literal></entry>
<entry>Returns true if a cube is a point, that is,
<entry><literal>cube_is_point(cube)</literal></entry>
<entry><type>boolean</type></entry>
<entry>Returns true if the cube is a point, that is,
the two defining corners are the same.</entry>
<entry>
</entry>
</row>
<row>
<entry><literal>cube_distance(cube, cube) returns double</literal></entry>
<entry><literal>cube_distance(cube, cube)</literal></entry>
<entry><type>float8</type></entry>
<entry>Returns the distance between two cubes. If both
cubes are points, this is the normal distance function.
</entry>
<entry>
</entry>
</row>
<row>
<entry><literal>cube_subset(cube, int[]) returns cube
</literal></entry>
<entry><literal>cube_subset(cube, integer[])</literal></entry>
<entry><type>cube</type></entry>
<entry>Makes a new cube from an existing cube, using a list of
dimension indexes from an array. Can be used to find both the LL and UR
coordinates of a single dimension, e.g.
<literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) = '(3),(7)'</>.
Or can be used to drop dimensions, or reorder them as desired, e.g.
<literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) = '(5, 3,
1, 1),(8, 7, 6, 6)'</>.
dimension indexes from an array. Can be used to extract the endpoints
of a single dimension, or to drop dimensions, or to reorder them as
desired.
</entry>
<entry>
<literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) == '(3),(7)'</>
<literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) ==
'(5,3,1,1),(8,7,6,6)'</>
</entry>
</row>
<row>
<entry><literal>cube_union(cube, cube) returns cube</literal></entry>
<entry>Produces the union of two cubes
<entry><literal>cube_union(cube, cube)</literal></entry>
<entry><type>cube</type></entry>
<entry>Produces the union of two cubes.
</entry>
<entry>
</entry>
</row>
<row>
<entry><literal>cube_inter(cube, cube) returns cube</literal></entry>
<entry>Produces the intersection of two cubes
<entry><literal>cube_inter(cube, cube)</literal></entry>
<entry><type>cube</type></entry>
<entry>Produces the intersection of two cubes.
</entry>
<entry>
</entry>
</row>
<row>
<entry><literal>cube_enlarge(cube c, double r, int n) returns cube</literal></entry>
<entry>Increases the size of a cube by a specified radius in at least
n dimensions. If the radius is negative the cube is shrunk instead. This
is useful for creating bounding boxes around a point for searching for
nearby points. All defined dimensions are changed by the radius r.
LL coordinates are decreased by r and UR coordinates are increased by r.
If a LL coordinate is increased to larger than the corresponding UR
coordinate (this can only happen when r &lt; 0) than both coordinates
are set to their average. If n is greater than the number of defined
dimensions and the cube is being increased (r &gt;= 0) then 0 is used
as the base for the extra coordinates.
<entry><literal>cube_enlarge(c cube, r double, n integer)</literal></entry>
<entry><type>cube</type></entry>
<entry>Increases the size of the cube by the specified
radius <replaceable>r</> in at least <replaceable>n</> dimensions.
If the radius is negative the cube is shrunk instead.
All defined dimensions are changed by the radius <replaceable>r</>.
Lower-left coordinates are decreased by <replaceable>r</> and
upper-right coordinates are increased by <replaceable>r</>. If a
lower-left coordinate is increased to more than the corresponding
upper-right coordinate (this can only happen when <replaceable>r</>
&lt; 0) than both coordinates are set to their average.
If <replaceable>n</> is greater than the number of defined dimensions
and the cube is being enlarged (<replaceable>r</> &gt; 0), then extra
dimensions are added to make <replaceable>n</> altogether;
0 is used as the initial value for the extra coordinates.
This function is useful for creating bounding boxes around a point for
searching for nearby points.
</entry>
<entry>
<literal>cube_enlarge('(1,2),(3,4)', 0.5, 3) ==
'(0.5,1.5,-0.5),(3.5,4.5,0.5)'</>
</entry>
</row>
</tbody>