Fix spaceship operator bugs, document, add tests

Remove some erroneously added brackets_increment() calls.

Reject <=> in preprocessor expressions with a clear error message (it
seems it isn't supported here - clang and gcc don't at least).

The type returned by `<=>` is not `bool`.  We pretend it's
`int` for now, which should work for how it's likely to be used
in constant expressions.

Fixes #1622

Examples/test-suite/common.mk

@@ -649,6 +649,7 @@ CPP17_TEST_BROKEN = \
 
 # C++20 test cases.
 CPP20_TEST_CASES += \
+	cpp20_spaceship_operator \
 
 # Broken C++20 test cases.
 CPP20_TEST_BROKEN = \

Examples/test-suite/cpp20_spaceship_operator.i

@@ -0,0 +1,28 @@
+%module cpp20_spaceship_operator
+
+%rename(spaceship) operator<=>;
+
+%inline %{
+#include <compare>
+
+int v = (-1 <=> 1 > 0) ? 7 : 42;
+
+// We use !(a >= b) here due to limited support for (a < b) in SWIG's parser.
+#define ALIEN !(0 <=> 1 >= 0)
+
+const int SPACE = 3 <=> 3 == 0;
+
+struct A {
+  int v;
+
+  explicit A(int v_) : v(v_) { }
+};
+
+int operator<=>(const A& a, const A& b) {
+  return a.v - b.v;
+}
+
+int f(int v = (-1 <=> 1 > 0) ? 7 : 42) { return v; }
+%}
+
+%constant int COMET = (4 <=> 2 > 0);

Examples/test-suite/errors/pp_expressions_bad.i

@@ -66,3 +66,7 @@
 /* Unary + was a no-op and so this didn't give an error in SWIG < 4.1.0. */
 #if "1" == +"1"
 #endif
+
+/* Spaceship operator doesn't seem to be allowed in preprocessor expressions. */
+#if (4 <=> 2) < 0
+#endif

Examples/test-suite/errors/pp_expressions_bad.stderr

@@ -31,3 +31,5 @@ pp_expressions_bad.i:64: Warning 202: Could not evaluate expression '"1" == ~"1"
 pp_expressions_bad.i:64: Warning 202: Syntax error: attempt to apply unary operator to string
 pp_expressions_bad.i:67: Warning 202: Could not evaluate expression '"1" == +"1"'
 pp_expressions_bad.i:67: Warning 202: Syntax error: attempt to apply unary operator to string
+pp_expressions_bad.i:71: Warning 202: Could not evaluate expression '(4 <=> 2) < 0'
+pp_expressions_bad.i:71: Warning 202: Spaceship operator (<=>) not allowed in preprocessor expression

Examples/test-suite/php/cpp20_spaceship_operator_runme.php

@@ -0,0 +1,23 @@
+<?php
+
+require "tests.php";
+
+check::functions(array('f', 'spaceship'));
+check::classes(array('cpp20_spaceship_operator','A'));
+check::globals(array('v', 'SPACE'));
+
+//check::equal(ALIEN, true);
+check::equal(SPACE_get(), 1);
+check::equal(COMET, 1);
+check::equal(v_get(), 42);
+
+$x = new A(1);
+$y = new A(2);
+
+check::equal(spaceship($x, $y) < 0, true);
+check::equal(spaceship($x, $x), 0);
+check::equal(spaceship($y, $x) > 0, true);
+
+check::equal(f(), 42);
+
+check::done();