database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-04-25 21:42:33 +03:00
Code

Minor hacking on contrib/cube documentation.

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