11<!--
2- $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_operator.sgml,v 1.11 1999/07/22 15:09:08 thomas Exp $
2+ $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_operator.sgml,v 1.12 2000/03/18 18:03:12 tgl Exp $
33Postgres documentation
44-->
55
@@ -60,25 +60,25 @@ CREATE OPERATOR <replaceable>name</replaceable> ( PROCEDURE = <replaceable class
6060 <term><replaceable class="parameter">type1</replaceable></term>
6161 <listitem>
6262 <para>
63- The typefor the left-handside of the operator, if any. This option would be
64- omitted for aright -unary operator.
63+ The typeof the left-handargument of the operator, if any.
64+ This option would be omitted for aleft -unary operator.
6565 </para>
6666 </listitem>
6767 </varlistentry>
6868 <varlistentry>
6969 <term><replaceable class="parameter">type2</replaceable></term>
7070 <listitem>
7171 <para>
72- The typefor the right-handside of the operator, if any. This option would be
73- omitted for aleft -unary operator.
72+ The typeof the right-handargument of the operator, if any.
73+ This option would be omitted for aright -unary operator.
7474 </para>
7575 </listitem>
7676 </varlistentry>
7777 <varlistentry>
7878 <term><replaceable class="parameter">com_op</replaceable></term>
7979 <listitem>
8080 <para>
81- The commutatorfor this operator.
81+ The commutatorof this operator.
8282 </para>
8383 </listitem>
8484 </varlistentry>
@@ -110,23 +110,25 @@ CREATE OPERATOR <replaceable>name</replaceable> ( PROCEDURE = <replaceable class
110110 <term>HASHES</term>
111111 <listitem>
112112 <para>
113- Indicates this operator can support a hash-join algorithm .
113+ join .
114114 </para>
115115 </listitem>
116116 </varlistentry>
117117 <varlistentry>
118118 <term><replaceable class="parameter">left_sort_op</replaceable></term>
119119 <listitem>
120120 <para>
121- Operator that sorts the left-hand data type of this operator.
121+ If this operator can support a merge join, the
122+ operator that sorts the left-hand data type of this operator.
122123 </para>
123124 </listitem>
124125 </varlistentry>
125126 <varlistentry>
126127 <term><replaceable class="parameter">right_sort_op</replaceable></term>
127128 <listitem>
128129 <para>
129- Operator that sorts the right-hand data type of this operator.
130+ If this operator can support a merge join, the
131+ operator that sorts the right-hand data type of this operator.
130132 </para>
131133 </listitem>
132134 </varlistentry>
@@ -172,22 +174,56 @@ CREATE
172174 </para>
173175 <para>
174176 The operator <replaceable class="parameter">name</replaceable>
175- is a sequence of up tothirty two (32) characters in any combination
176- from the following:
177+ is a sequence of up toNAMEDATALEN-1 (31 by default) characters
178+ from the following list :
177179 <literallayout>
178- + - * / < > = ~ ! @ # % ^ & | ` ? $ :
180+ + - * / < > = ~ ! @ # % ^ & | ` ? $ :
179181 </literallayout>
182+
183+ There are a few restrictions on your choice of name:
184+ <itemizedlist>
185+ <listitem>
186+ <para>
187+ "$" and ":" cannot be defined as single-character operators,
188+ although they can be part of a multi-character operator name.
189+ </para>
190+ </listitem>
191+ <listitem>
192+ <para>
193+ "--" and "/*" cannot appear anywhere in an operator name,
194+ since they will be taken as the start of a comment.
195+ </para>
196+ </listitem>
197+ <listitem>
198+ <para>
199+ A multi-character operator name cannot end in "+" or "-",
200+ unless the name also contains at least one of these characters:
201+ <literallayout>
202+ ~ ! @ # % ^ & | ` ? $ :
203+ </literallayout>
204+ For example, <literal>@-</literal> is an allowed operator name,
205+ but <literal>*-</literal> is not.
206+ This restriction allows <productname>Postgres</productname> to
207+ parse SQL-compliant queries without requiring spaces between tokens.
208+ </para>
209+ </listitem>
210+ </itemizedlist>
211+
180212 <note>
181213 <para>
182- No alphabetic characters are allowed in an operator name.
183- This enables <productname>Postgres</productname> to parse SQL input
184- into tokens without requiring spaces between each token.
214+ When working with non-SQL-standard operator names, you will usually
215+ need to separate adjacent operators with spaces to avoid ambiguity.
216+ For example, if you have defined a left-unary operator named "@",
217+ you cannot write <literal>X*@Y</literal>; you must write
218+ <literal>X* @Y</literal> to ensure that
219+ <productname>Postgres</productname> reads it as two operator names
220+ not one.
185221 </para>
186222 </note>
187223 </para>
188224 <para>
189- The operator "!=" is mapped to "<>" on input, sothey are
190- therefore equivalent.
225+ The operator "!=" is mapped to "<>" on input, sothese two names
226+ are always equivalent.
191227 </para>
192228 <para>
193229 At least one of LEFTARG and RIGHTARG must be defined. For
@@ -196,11 +232,11 @@ CREATE
196232 unary operators only RIGHTARG should be defined.
197233 </para>
198234 <para>
199- Also, the
235+ The
200236 <replaceable class="parameter">func_name</replaceable> procedure must have
201237 been previously defined using <command>CREATE FUNCTION</command> and must
202238 be defined to accept the correct number of arguments
203- (either one or two).
239+ (either one or two) of the indicated types .
204240 </para>
205241 <para>
206242 The commutator operator should be identified if one exists,
@@ -247,8 +283,6 @@ MYBOXES.description !== "0,0,1,1"::box
247283 does not yet have a commutator itself, then the commutator's
248284 entry is updated to have the newly created operator as its
249285 commutator. This applies to the negator, as well.
250- </para>
251- <para>
252286 This is to allow the definition of two operators that are
253287 the commutators or the negators of each other. The first
254288 operator should be defined without a commutator or negator
@@ -258,7 +292,7 @@ MYBOXES.description !== "0,0,1,1"::box
258292 it also works to just have both operators refer to each other.)
259293 </para>
260294 <para>
261- Thenext three specifications are present to support the
295+ TheHASHES, SORT1, and SORT2 options are present to support the
262296 query optimizer in performing joins.
263297 <productname>Postgres</productname> can always
264298 evaluate a join (i.e., processing a clause with two tuple
@@ -294,9 +328,8 @@ MYBOXES.description !== "0,0,1,1"::box
294328 be worth the complexity involved.
295329 </para>
296330 <para>
297- The last two pieces of the specification are present so
298- the query optimizer can estimate result sizes. If a
299- clause of the form:
331+ The RESTRICT and JOIN options assist the query optimizer in estimating
332+ result sizes. If a clause of the form:
300333 <programlisting>
301334MYBOXES.description <<< "0,0,1,1"::box
302335 </programlisting>
@@ -310,15 +343,15 @@ MYBOXES.description <<< "0,0,1,1"::box
310343 data types and returns a floating point number. The
311344 query optimizer simply calls this function, passing the
312345 parameter "0,0,1,1" and multiplies the result by the relation
313- size to get thedesired expected number of instances.
346+ size to get the expected number of instances.
314347 </para>
315348 <para>
316349 Similarly, when the operands of the operator both contain
317350 instance variables, the query optimizer must estimate the
318351 size of the resulting join. The function join_proc will
319352 return another floating point number which will be multiplied
320353 by the cardinalities of the two classes involved to
321- compute thedesired expected result size.
354+ compute the expected result size.
322355 </para>
323356 <para>
324357 The difference between the function