From 5e63c170f80ae33a80fa6392dccf22811ac1d7a3 Mon Sep 17 00:00:00 2001 From: "J. B. Lopez" Date: Sun, 11 May 2025 09:57:36 -0700 Subject: [PATCH 1/2] Add ext/operator documentation --- appendices/extensions.xml | 2 + language/operators.xml | 5 + reference/operator/book.xml | 33 +++ reference/operator/overloading.xml | 339 +++++++++++++++++++++++++++++ reference/operator/setup.xml | 21 ++ 5 files changed, 400 insertions(+) create mode 100644 reference/operator/book.xml create mode 100644 reference/operator/overloading.xml create mode 100644 reference/operator/setup.xml diff --git a/appendices/extensions.xml b/appendices/extensions.xml index 3434c95e8c14..0a208a442582 100644 --- a/appendices/extensions.xml +++ b/appendices/extensions.xml @@ -94,6 +94,7 @@ + @@ -348,6 +349,7 @@ + diff --git a/language/operators.xml b/language/operators.xml index 0716c8dd6351..5e2476a52b50 100644 --- a/language/operators.xml +++ b/language/operators.xml @@ -29,6 +29,11 @@ exactly how expressions containing several different operators are evaluated. + + There is a PECL extension that allows for overloading of some operators for + objects. For more information, see the Operator + Overloading for Objects section. + &language.operators.precedence; &language.operators.arithmetic; diff --git a/reference/operator/book.xml b/reference/operator/book.xml new file mode 100644 index 000000000000..c75abdf4d9fb --- /dev/null +++ b/reference/operator/book.xml @@ -0,0 +1,33 @@ + + + + + Operator Overloading for Objects + Operator Overloading + + + + &reftitle.intro; + + This extension allows you to define and implement operator overloading for objects. + It is possible to define how an object reacts when an operator is used on it. + + + One example of this is creating a collection type object that has the addition + operator overloaded to allow adding elements to the collection or adding two + collections together. + + + Another example is creating an enhanced string class that has the multiplication + operator overloaded to allow repeating the string a certain number of times. + + +
+ &reftitle.seealso; + +
+ + + &reference.operator.setup; + &reference.operator.overloading; + diff --git a/reference/operator/overloading.xml b/reference/operator/overloading.xml new file mode 100644 index 000000000000..12110da401a1 --- /dev/null +++ b/reference/operator/overloading.xml @@ -0,0 +1,339 @@ + + + + + Operator Overloading Magic Methods + + The operator overloading extension allows you to define how an object reacts to operators. This is done by implementing the following magic methods: + + + Arithmetic operators: + + $a::__add($b) + $a::__sub($b) + $a::__mul($b) + $a::__div($b) + $a::__mod($b) + $a::__pow($b) + + + + Assignment operators: + + $a::__assign($b) + $a::__assign_add($b) + $a::__assign_sub($b) + $a::__assign_mul($b) + $a::__assign_div($b) + $a::__assign_mod($b) + $a::__assign_pow($b) + $a::__assign_and($b) + $a::__assign_or($b) + $a::__assign_xor($b) + $a::__assign_sl($b) + $a::__assign_sr($b) + $a::__assign_concat($b) + + + + Bitwise operators: + + $a::__bw_and($b) + $a::__bw_or($b) + $a::__bw_xor($b) + $a::__bw_not() + $a::__bw_sl($b) + $a::__bw_sr($b) + + + + Comparison operators: + + $a::__is_equal($b) + $a::__is_not_equal($b) + $a::__is_identical($b) + $a::__is_not_identical($b) + $a::__is_smaller($b) + $a::__is_smaller_or_equal($b) + $a::__is_greater($b) + $a::__is_greater_or_equal($b) + + + + Incrementing and decrementing operators: + + $a::__pre_inc() + $a::__post_inc() + $a::__pre_dec() + $a::__post_dec() + + + + String operators: + + $a::__concat($b) + + +
+ Operator Overloading Examples + + The following is the class that is used in the testing of the operator overloading extension. + It overloads all of the possible operators that can be overloaded for testing. + + + Complete class for operator overloading + +value; + } + + public function __set(string $name, mixed $value) + { + $this->value = $value; + } + + public function __construct(mixed $init = null) + { + $this->value = $init; + } + //endregion + + //region Arithmetic Operators + public function __add(mixed $val): int|float + { + return $this->value + $val; + } + + public function __div(mixed $val): int|float + { + return $this->value / $val; + } + + public function __mod(mixed $val): int + { + return $this->value % $val; + } + + public function __mul(mixed $val): int|float + { + return $this->value * $val; + } + + public function __pow(mixed $val): int|float + { + return $this->value ** $val; + } + + public function __sub(mixed $val): int|float + { + return $this->value - $val; + } + //endregion + + //region Assignment Operators + public function __assign(mixed $val): mixed + { + return $this->value = $val; + } + + public function __assign_add(mixed $val): mixed + { + return $this->value += $val; + } + + public function __assign_bw_and(mixed $val): mixed + { + return $this->value &= $val; + } + + public function __assign_bw_or(mixed $val): mixed + { + return $this->value |= $val; + } + + public function __assign_concat(mixed $val): string + { + return $this->value .= $val; + } + + public function __assign_div(mixed $val): mixed + { + return $this->value /= $val; + } + + public function __assign_mod(mixed $val): mixed + { + return $this->value %= $val; + } + + public function __assign_mul(mixed $val): mixed + { + return $this->value *= $val; + } + + public function __assign_pow(mixed $val): mixed + { + return $this->value **= $val; + } + + public function __assign_sl(mixed $val): mixed + { + return $this->value <<= $val; + } + + public function __assign_sr(mixed $val): mixed + { + return $this->value >>= $val; + } + + public function __assign_sub(mixed $val): mixed + { + return $this->value -= $val; + } + //endregion + + //region Bitwise Operators + public function __bw_and(mixed $val): int + { + return $this->value & $val; + } + + public function __bw_not(): int|string + { + return ~$this->value; + } + + public function __bw_or(mixed $val): int + { + return $this->value | $val; + } + + public function __bw_xor(mixed $val): int + { + return $this->value ^ $val; + } + + public function __sl(mixed $val): int + { + return $this->value << $val; + } + + public function __sr(mixed $val): int + { + return $this->value >> $val; + } + //endregion + + //region Comparison Operators + public function __is_equal(mixed $val): bool + { + return $this->value == $val; + } + + public function __is_greater(mixed $val): bool + { + return $this->value > $val; + } + + public function __is_greater_or_equal(mixed $val): bool + { + return $this->value >= $val; + } + + public function __is_identical(mixed $val): bool + { + return $this->value === $val; + } + + public function __is_not_equal(mixed $val): bool + { + return $this->value != $val; + } + + public function __is_not_identical(mixed $val): bool + { + return $this->value !== $val; + } + + public function __is_smaller(mixed $val): bool + { + return $this->value < $val; + } + + public function __is_smaller_or_equal(mixed $val): bool + { + return $this->value <= $val; + } + + public function __spaceship(mixed $val): int + { + return $this->value <=> $val; + } + //endregion + + //region Incrementing/Decrementing Operators + public function __post_dec(): mixed + { + return $this->value--; + } + + public function __post_inc(): mixed + { + return $this->value++; + } + + public function __pre_dec(): mixed + { + return --$this->value; + } + + public function __pre_inc(): mixed + { + return ++$this->value; + } + //endregion + + //region String Operators + public function __concat(mixed $val): string + { + return $this->value . $val; + } + //endregion + +} + +]]> + + + Using the above class, you can overload the operators as follows: + + + + + + The above code will output: + + + + + +
+ diff --git a/reference/operator/setup.xml b/reference/operator/setup.xml new file mode 100644 index 000000000000..1ea82ede421c --- /dev/null +++ b/reference/operator/setup.xml @@ -0,0 +1,21 @@ + + + + + &reftitle.setup; + +
+ &reftitle.install; + + &pecl.info; + &url.pecl.package;operator. + + + Windows users can download prebuilt release binaries from the PECL website. + + + operator releases are hosted by PECL and the source code by + github. + +
+ From 8aa098199f6d3a8c1e187e51ded057635cbc7b84 Mon Sep 17 00:00:00 2001 From: "J.B. Lopez" Date: Tue, 13 May 2025 09:49:45 -0700 Subject: [PATCH 2/2] Removed trailing whitespace --- reference/operator/book.xml | 2 -- reference/operator/setup.xml | 1 - 2 files changed, 3 deletions(-) diff --git a/reference/operator/book.xml b/reference/operator/book.xml index c75abdf4d9fb..c8ae29b9be6a 100644 --- a/reference/operator/book.xml +++ b/reference/operator/book.xml @@ -21,10 +21,8 @@ Another example is creating an enhanced string class that has the multiplication operator overloaded to allow repeating the string a certain number of times. -
&reftitle.seealso; -
diff --git a/reference/operator/setup.xml b/reference/operator/setup.xml index 1ea82ede421c..22fbff489cd4 100644 --- a/reference/operator/setup.xml +++ b/reference/operator/setup.xml @@ -3,7 +3,6 @@ &reftitle.setup; -
&reftitle.install;