Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:118896
To: "internals@lists.php.net" <internals@lists.php.net>
Thread-Topic: Proposal: Expanded iterable helper functions and aliasing
 iterator_to_array in `iterable\` namespace
Thread-Index: AQHY6sww8NTpxZKOCkWLxQu8jgxWQg==
Date: Fri, 28 Oct 2022 13:45:06 +0000
Message-ID:
 <DM6PR14MB4155BEF0A6C924DB3812C97DF9329@DM6PR14MB4155.namprd14.prod.outlook.com>
Accept-Language: en-CA, en-US
Content-Language: en-CA
msip_labels:
x-tmn: [GydLOiKHhS2rGqKAKFTibHzXh5oflLdkZx38Oh6GFyz9XCRARVphrg==]
x-ms-publictraffictype: Email
x-ms-traffictypediagnostic: DM6PR14MB4155:EE_|SJ0PR14MB5492:EE_
x-ms-office365-filtering-correlation-id: fefe5213-12ff-4135-cccb-08dab8ea9fb8
x-microsoft-antispam: BCL:0;
x-microsoft-antispam-message-info:
 1P7wSfN1FNciMdBtQlsUWbhs3GngT0TESq1jATN3zFh/eYLiNaVu1LC9m6csBebglvRR7nuu5a37hYJyN4MUwSe/GBtjVUg4eHGkwvvM/Md+fyNn0+0J1t5VaIW7RJdUkmbFyClg+FxavlWv+VCpPqNLZRLWQu0gGiPAqJHpasKGdZzwHwUN9sGsl2PsAIZaQXm/mc8CliGm9moEATMz0xw/IhA3mVa2Sm07/u/8AszxkWo7C2x1O1047f43lewxnU7VHPFfHmvQ0rLwsIKaJBeXugKp0qjkPLdDkn4hJQI15ZevNjBBN+q+A3aKfZd2pOz7nkimYrRMyUq7uvarNq59IcRUQiOVQqbF07YY9zOm8FBuAp80g02fUXZbDeBSzN/KGalQLIeRB/6EVSilnc6xgjU09xiQKS5ZgEBw20kgI7Nfu9AACwvv/VsDiMeKxEo6z+eVZSrI1u25+zahtesVLdWkABMDMs7SsergVeYeUNfnGVlJ7FmpzHczhype/+VVB4MkISHT7eSUFQGyIUHgCA4TJFGJjPBtu4bMc2b4djmRiU+coQScFb4HDmrkxK65q67Olnk1y/hQOQyJJ9rzqbuUcKCvgC0aph8bNU/1VX/09/N5MjmyXFGFQV8mwQjvGnP0Ny/CpcVc78XJk0APHEDCouFF+pqDCqJLQ7E=
x-ms-exchange-antispam-messagedata-chunkcount: 1
x-ms-exchange-antispam-messagedata-0:
 =?iso-8859-1?Q?9nBCO/cf0GiohlEWGeYOG3k7m+1fbikkUc068521x4I82bQ8QsWcWpUT8G?=
 =?iso-8859-1?Q?9zoOufQhKMvMUBM7wTJLEFTSqqkg7SZ7ew1Ykn0DBJod+wxgRkPhPHVs+v?=
 =?iso-8859-1?Q?VoiM3G7m5UIdmpFmFxArotGBhDflF53dyqxq8+/+eK+pTGN4kBDKSIoOLx?=
 =?iso-8859-1?Q?re+vQv/6HHfx5p3Qx5x7CJuwFCCi/Re17sDvybRW/rWktDXEmmVVpmcdAW?=
 =?iso-8859-1?Q?RwdjL1814ShBZll5iapN4DcnWSVsghYziUng8Azc9OPugKNwdFRzUVmEez?=
 =?iso-8859-1?Q?tF3u4a2uM+6Y9wEt1RevyKVbx8yFnOVQMgGENEh9zYlpR8moBToZOzDHSq?=
 =?iso-8859-1?Q?PT7rLUZTQG8IpaScu2rBUNb7BwUn6KVAox47oJrZPnwb7o3uiDNFY1KJ6E?=
 =?iso-8859-1?Q?C2mKb06UzJgb5Af+FZ7X4iTIc8WeBnrQrUHMCs4LeHHQ6w9bayPnhUTU3S?=
 =?iso-8859-1?Q?Flmj0fJt6chTxi7QJvM7VbfstJJbaXHDH5onPV78iXyrxoJgMvR/qqZHlj?=
 =?iso-8859-1?Q?6DOXusg3JkCDN3uaRXEeBL5sSryl5uLdY+OEeqDIWPGLlZD7r29GoZoFP1?=
 =?iso-8859-1?Q?zZbI9/zBZjmdZ59ng34KyLtVnHmBy/5pdnolJQQEITWvT0v7aYM1BzXcIh?=
 =?iso-8859-1?Q?dTkqMHTHSKBi2mNtoyy4FR2rtel3P5WZGtESsvkTLKdBtONWvNcXLNuHOY?=
 =?iso-8859-1?Q?DD7P8xFL74aq/+6PGS92De+SDjBJ4UF7xR1M7GbaaePDDWN0UDQDoZd4fp?=
 =?iso-8859-1?Q?rs53Aitw1o3BsFfYoAGwnsr11rqAWSHUq+BxU/dwkBDqM32csH/zkojKPP?=
 =?iso-8859-1?Q?gFa1aKuzVaubvOIYhzwiuBsuHTgQoCwdm5eR9XzVimveXcUCd+KdSxuuMM?=
 =?iso-8859-1?Q?lwk3H/0XnAwM3BoPjHZKGSQVPm8JtIjNfwSXucWhaPwWkoTkB4AKceY5q6?=
 =?iso-8859-1?Q?jmsQBy5B3ZWHECCZDE9mMxKZMscTgFzbawVHoWCJ72H36yDLNx+DHmhPOV?=
 =?iso-8859-1?Q?OUO4mUzmXFT+rcjqCALMdi6wOieryjUj35Mcw/tkpDVQtDSQu3k0kc/Bso?=
 =?iso-8859-1?Q?6VCc9Syy40np4IDsJ6bxZqD7DYk1PiAIYQS6A1IFBkv1qPsPaQj6jI3Ajo?=
 =?iso-8859-1?Q?WOw8ZmglOuRzprPiACgr5mTVSAfq4eGgBTweYyuW0kpkh5PjzoQwz4iccH?=
 =?iso-8859-1?Q?dMPOvWeYBDnkttEC0+3x1Y+IsUCoA7Gms0mpYUE/fhCiYrEBKzg5439J/h?=
 =?iso-8859-1?Q?Jsr2eWZY3AlOUQvcDtnPMPg1GGppibwpWVCkATWE0JkCzICZn41Un59mrD?=
 =?iso-8859-1?Q?3zeKwYShjRTXBICdgJBNC/kWW6gMxEWjNJTCx/YZQvUU7/o=3D?=
Content-Type: text/plain; charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
X-OriginatorOrg: sct-15-20-4755-11-msonline-outlook-cd57b.templateTenant
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-AuthSource: DM6PR14MB4155.namprd14.prod.outlook.com
X-MS-Exchange-CrossTenant-RMS-PersistedConsumerOrg: 00000000-0000-0000-0000-000000000000
X-MS-Exchange-CrossTenant-Network-Message-Id: fefe5213-12ff-4135-cccb-08dab8ea9fb8
X-MS-Exchange-CrossTenant-originalarrivaltime: 28 Oct 2022 13:45:06.7580
 (UTC)
X-MS-Exchange-CrossTenant-fromentityheader: Hosted
X-MS-Exchange-CrossTenant-id: 84df9e7f-e9f6-40af-b435-aaaaaaaaaaaa
X-MS-Exchange-CrossTenant-rms-persistedconsumerorg: 00000000-0000-0000-0000-000000000000
X-MS-Exchange-Transport-CrossTenantHeadersStamped: SJ0PR14MB5492
Subject: Proposal: Expanded iterable helper functions and aliasing
 iterator_to_array in `iterable\` namespace
From: tysonandre775@hotmail.com (tyson andre)

Hi internals,=0A=
=0A=
https://wiki.php.net/rfc/iterator_xyz_accept_array recently passed in php 8=
.2,=0A=
fixing a common inconvenience of those functions throwing a TypeError for a=
rrays.=0A=
=0A=
However, from the `iterator_` name (https://www.php.net/manual/en/class.ite=
rator.php),=0A=
it's likely to become a source of confusion when writing or reviewing code =
decades from now,=0A=
when the name suggests it only accepts objects (Traversable Iterator/Iterat=
orAggregate).=0A=
=0A=
I'm planning on creating an RFC adding the following functions to the `iter=
able\` namespace as aliases of iterator_count/iterator_to_array.=0A=
Those accept iterables (https://www.php.net/manual/en/language.types.iterab=
le.php), i.e. both Traversable objects and arrays.=0A=
=0A=
Namespaces were chosen after feedback on my previous RFC,=0A=
and I believe `iterable\` follows the guidance from https://wiki.php.net/rf=
c/namespaces_in_bundled_extensions and=0A=
https://wiki.php.net/rfc/namespaces_in_bundled_extensions#core_standard_spl=
=0A=
=0A=
I plan to create an RFC with the following functionality in the iterable\ n=
amespace, and wanted to see what the preference on naming was, or if there =
was other feedback.=0A=
(Not having enough functionality and wanting a better idea of the overall =
=0A=
=0A=
- `iterable\count(...)` (alias of iterator_count)=0A=
- `iterable\to_array(Traversable $iterator, bool $preserve_keys =3D true): =
array` (alias of iterator_to_array, so that users can stop using a misleadi=
ng name)=0A=
=0A=
- `iterable\any(iterable $input, ?callable $callback =3D null): bool` - Det=
ermines whether any value of the iterable satisfies the predicate.=0A=
   and all() - Determines whether all values of the iterable satisfies the =
predicate.=0A=
=0A=
  This is a different namespace from https://wiki.php.net/rfc/any_all_on_it=
erable=0A=
- `iterable\none(iterable $input, ?callable $callback =3D null): bool`=0A=
=0A=
   returns the opposite of any()=0A=
- `iterable\find(iterable $iterable, callable $callback, mixed $default =3D=
 null): mixed`=0A=
=0A=
   Returns the first value for which $callback($value) is truthy. On failur=
e, returns default=0A=
- `iterable\fold(iterable $iterable, callable $callback, mixed $initial): m=
ixed`=0A=
=0A=
  `fold` and requiring an initial value seems like better practice. See htt=
ps://externals.io/message/112558#112834=0A=
  and https://stackoverflow.com/questions/25149359/difference-between-reduc=
e-and-fold=0A=
- `iterable\unique_values(iterable $iterable): array {}`=0A=
=0A=
  Returns true if this iterable includes a value identical to $value (`=3D=
=3D=3D`).=0A=
- `iterable\includes_value(iterable $iterable, mixed $value): bool {}`=0A=
   Returns a list of unique values of $iterable=0A=
=0A=
There's other functionality that I was less certain about proposing, such a=
s `iterable\keys(iterable $iterable): array`,=0A=
which would work similarly to array_keys but also work on Traversables (e.g=
. to be used with userland/internal collections, generators, etc.)=0A=
Or functions to get the iterable\first()/last() value in an iterable. Any t=
houghts on those?=0A=
=0A=
I also wanted to know if more verbose names such as find_value(), fold_valu=
es(), any_values(), all_values() were generally preferred before proposing =
this,=0A=
since I only had feedback from a small number of names. My assumption was s=
hort names were generally preferred when possible.=0A=
=0A=
See https://github.com/TysonAndre/pecl-teds/blob/main/teds.stub.php for doc=
umentation of the other functions mentioned here. The functionality can be =
tried out by installing https://pecl.php.net/package/teds=0A=
=0A=
Background=0A=
-----------=0A=
=0A=
In February 2021, I proposed expanded iterable functionality and brought it=
 to a vote,=0A=
https://wiki.php.net/rfc/any_all_on_iterable , where feedback was mainly ab=
out being too small in scope and the choice of naming.=0A=
=0A=
Later, after https://externals.io/message/112558#112780 , https://wiki.php.=
net/rfc/namespaces_in_bundled_extensions#proposal was created and brought t=
o a vote in April 2021 that passed,=0A=
offering useful recommendations on how to standardize namespaces in future =
proposals of new categories of functionality=0A=
(e.g. `iterable\any()` and `iterable\all()`)=0A=
=0A=
Any comments?=0A=
=0A=
Thanks,=0A=
Tyson=