name an array function

name an array function

[Daniel Llorens]

Hello,

version 2.2 of Guile will (I hope) include rank-polymorphic versions of array-ref, array-set! and array-for-each. What this means is that instead of requiring as many indices as the rank of the array, with these functions you can give fewer indices and get a subarray (a ‘prefix slice’). If you give all the indices, they behave just as the current versions.

My original intention was for these functions to replace array-ref and array-set!. That's how a number of array languages/libraries do it (numpy, to mention a popular one. You don't need to say A[i, :, :], you can just say A[i].). However, the maintainers spoke against this, so these functions need different names.

The names I chose are array-from, array-amend! and array-for-each-cell. These names are taken from the J docs (http://www.jsoftware.com/help/dictionary/d520.htm, http://www.jsoftware.com/help/dictionary/d530n.htm), because the behavior is based on J and I consider J to be ‘the source’ when it comes to these concepts.

civodul has proposed array-slice instead of array-from. However, array-from only returns a slice when the rank of the result would be positive. wingo has pointed out that it is unusual to have a function name ending in a preposition. 

What do *you* think should be the names of these functions?

Thanks,

	lloda

PS: The justification for these functions is given in the documentation, but in short: 1) other than the creation of the subarray descriptors, they don't cost any more than the rank-strict versions, 2) the only way to reproduce them in current Guile is with make-shared-array, which is very slow and cumbersome, 3) they recover a functionality that used to be part of Guile but was removed (‘enclosed arrays’). 

PPS: You can check out the functions at http://git.savannah.gnu.org/gitweb/?p=guile.git;a=shortlog;h=refs/heads/lloda-squash1. I rebase this branch on master periodically. The maintainers have reviewed it, but any extra reviews would of course be appreciated, especially of the doc.

Re: name an array function

[Stefan Israelsson Tampe]

array-sub maybe,

On Mon, Nov 21, 2016 at 11:32 AM, Daniel Llorens <daniel.llorens@bluewin.ch>
wrote:

>
> Hello,
>
> version 2.2 of Guile will (I hope) include rank-polymorphic versions of
> array-ref, array-set! and array-for-each. What this means is that instead
> of requiring as many indices as the rank of the array, with these functions
> you can give fewer indices and get a subarray (a ‘prefix slice’). If you
> give all the indices, they behave just as the current versions.
>
> My original intention was for these functions to replace array-ref and
> array-set!. That's how a number of array languages/libraries do it (numpy,
> to mention a popular one. You don't need to say A[i, :, :], you can just
> say A[i].). However, the maintainers spoke against this, so these functions
> need different names.
>
> The names I chose are array-from, array-amend! and array-for-each-cell.
> These names are taken from the J docs (http://www.jsoftware.com/
> help/dictionary/d520.htm, http://www.jsoftware.com/help/
> dictionary/d530n.htm), because the behavior is based on J and I consider
> J to be ‘the source’ when it comes to these concepts.
>
> civodul has proposed array-slice instead of array-from. However,
> array-from only returns a slice when the rank of the result would be
> positive. wingo has pointed out that it is unusual to have a function name
> ending in a preposition.
>
> What do *you* think should be the names of these functions?
>
> Thanks,
>
>         lloda
>
> PS: The justification for these functions is given in the documentation,
> but in short: 1) other than the creation of the subarray descriptors, they
> don't cost any more than the rank-strict versions, 2) the only way to
> reproduce them in current Guile is with make-shared-array, which is very
> slow and cumbersome, 3) they recover a functionality that used to be part
> of Guile but was removed (‘enclosed arrays’).
>
> PPS: You can check out the functions at http://git.savannah.gnu.org/
> gitweb/?p=guile.git;a=shortlog;h=refs/heads/lloda-squash1. I rebase this
> branch on master periodically. The maintainers have reviewed it, but any
> extra reviews would of course be appreciated, especially of the doc.
>
>
>

Re: name an array function

[tomas]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Mon, Nov 21, 2016 at 11:32:28AM +0100, Daniel Llorens wrote:
> 
> Hello,
> 
> version 2.2 of Guile will (I hope) include rank-polymorphic versions
> of array-ref, array-set! and array-for-each. What this means is that
> instead of requiring as many indices as the rank of the array, with
> these functions you can give fewer indices and get a subarray (a
> ‘prefix slice’). If you give all the indices, they behave just as
> the current versions.

Yay! (the really exciting part is in the PSen).

> My original intention was for these functions to replace array-ref
> and array-set!. That's how a number of array languages/libraries do
> it (numpy, to mention a popular one. You don't need to say A[i, :, :],
> you can just say A[i].). However, the maintainers spoke against this,
> so these functions need different names.

Understandable... but a pity, really.

[J...]

Uh, oh. That's NSFW material ;-) My head exploded (faint memories
of APL).

> civodul has proposed array-slice instead of array-from. However,
> array-from only returns a slice when the rank of the result would
> be positive. wingo has pointed out that it is unusual to have a
> function name ending in a preposition. 
> 
> What do *you* think should be the names of these functions?

I do like slice. But I'm perhaps off because I don't quite understand
your mumblings about "the rank of the result would be positive".
What do they return otherwise? Do they throw an exception?

thanks
- -- t
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iEYEARECAAYFAlgy7twACgkQBcgs9XrR2kZ/9wCbBS0lNcujS1Z9YHZt55TRe5fm
RlQAmwZ7mNBfIH28JCCocEO/FXkT1VH8
=9Mxq
-----END PGP SIGNATURE-----

Re: name an array function

[Daniel Llorens]

On 21 Nov 2016, at 13:55, <tomas@tuxteam.de> <tomas@tuxteam.de> wrote:

> > it (numpy, to mention a popular one. You don't need to say A[i, :, :],
> > you can just say A[i].). However, the maintainers spoke against this,
> > so these functions need different names.
> 
> Understandable... but a pity, really.

yeah...

> Uh, oh. That's NSFW material ;-) My head exploded (faint memories
> of APL).

check out ‘J for C programmers’, I think it has good explanations.

> I do like slice. But I'm perhaps off because I don't quite understand
> your mumblings about "the rank of the result would be positive".
> What do they return otherwise? Do they throw an exception?

They return the element itself. E.g.

(array-from #2((a b) (c d)) 0) => #1(a b)
(array-from #2((a b) (c d)) 0 0) => a

the rank of the second result would be zero (so #0(a)) if the result was always a ‘slice’. This is what I meant. There's a variant which always returns a ‘slice’:

(array-from* #2((a b) (c d)) 0) => #1(a b)
(array-from* #2((a b) (c d)) 0 0) => #0(a)

Re: name an array function

[tomas]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Mon, Nov 21, 2016 at 02:10:12PM +0100, Daniel Llorens wrote:
> 
> On 21 Nov 2016, at 13:55, <tomas@tuxteam.de> <tomas@tuxteam.de> wrote:
> 
> > > it (numpy, to mention a popular one. You don't need to say A[i, :, :],
> > > you can just say A[i].). However, the maintainers spoke against this,
> > > so these functions need different names.
> > 
> > Understandable... but a pity, really.
> 
> yeah...
> 
> > Uh, oh. That's NSFW material ;-) My head exploded (faint memories
> > of APL).
> 
> check out ‘J for C programmers’, I think it has good explanations.
> 
> > I do like slice. But I'm perhaps off because I don't quite understand
> > your mumblings about "the rank of the result would be positive".
> > What do they return otherwise? Do they throw an exception?
> 
> They return the element itself. E.g.
> 
> (array-from #2((a b) (c d)) 0) => #1(a b)
> (array-from #2((a b) (c d)) 0 0) => a
> 
> the rank of the second result would be zero (so #0(a)) if the result was always a ‘slice’. This is what I meant. There's a variant which always returns a ‘slice’:
> 
> (array-from* #2((a b) (c d)) 0) => #1(a b)
> (array-from* #2((a b) (c d)) 0 0) => #0(a)

OK, got it.

So should "slice" prevail, it'd make sense to "invert" the star
(array-slice corresponding to array-from* and vice-versa)?

Slice still feels way better to me, but I'll take them with any
name :-D

Had I to look it up by name without any idea of what to look
for, I'd never come up with array-from, whereas I'd have a faint
chance of coming up with array-slice; that said, the most
ergonomic choice would still be (an extension of) array-ref et
al. or some close relative.

thanks
- -- tomás
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iEYEARECAAYFAlgy9XUACgkQBcgs9XrR2kY9zQCeMkQZK2OPXtAlTMC56dW0HLDg
Y9sAnR0tKAJ8C6iQYwbKlLQh4fBBIB9A
=eb31
-----END PGP SIGNATURE-----

Re: name an array function

[Daniel Llorens]

On 21 Nov 2016, at 14:24, tomas@tuxteam.de wrote:

> So should "slice" prevail, it'd make sense to "invert" the star
> (array-slice corresponding to array-from* and vice-versa)?

I think it's more important to give the simpler names to the functions that are more commonly used. So I would keep the name array-slice* for the function that returns #0(a), in spite of logic.

Of course, that's one reason why I don't like array-slice too much!

> Had I to look it up by name without any idea of what to look
> for, I'd never come up with array-from, whereas I'd have a faint
> chance of coming up with array-slice; that said, the most
> ergonomic choice would still be (an extension of) array-ref et
> al. or some close relative.

Yeah, I do see your point.

Re: name an array function

[tomas]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Mon, Nov 21, 2016 at 02:42:58PM +0100, Daniel Llorens wrote:
> 
> On 21 Nov 2016, at 14:24, tomas@tuxteam.de wrote:
> 
> > So should "slice" prevail, it'd make sense to "invert" the star
> > (array-slice corresponding to array-from* and vice-versa)?
> 
> I think it's more important to give the simpler names to the
> functions that are more commonly used. So I would keep the
> name array-slice* for the function that returns #0(a), in
> spite of logic.

I (politely) disagree: the most "commonly" used function is
already array-ref, so you would seldomly use array-from/slice
for a scalar result (the rank-0 result will be more frequent,
because there's no substitute). But hey, as I said.

> Of course, that's one reason why I don't like array-slice too much!

Understood.

> > Had I to look it up by name without any idea of what to look
> > for, I'd never come up with array-from, whereas I'd have a faint
> > chance of coming up with array-slice; that said, the most
> > ergonomic choice would still be (an extension of) array-ref et
> > al. or some close relative.
> 
> Yeah, I do see your point.

Thanks
- -- tomás
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iEYEARECAAYFAlgy/PkACgkQBcgs9XrR2kakUQCfTVxPE7aXqyQkTYqQ6b7J1nyx
tMYAnRnSrx4airVvEs9gywUJ2MIY4jJJ
=lTwH
-----END PGP SIGNATURE-----

Re: name an array function

[Daniel Llorens]

On 21 Nov 2016, at 14:56, tomas@tuxteam.de wrote:

> I (politely) disagree: the most "commonly" used function is
> already array-ref, so you would seldomly use array-from/slice
> for a scalar result (the rank-0 result will be more frequent,
> because there's no substitute). But hey, as I said.

I don't use array-ref/set! anymore since array-from/amend! generalize them. I actually use a further generalization in a separate library :p

But I have a proposal below that makes this discussion moot, I hope.

| master (current)    | meaning                          | proposal             |
|---------------------+----------------------------------+----------------------|
| array-from*         | look up subarray, even #0(x)     | array-slice          |
| array-from          | look up cell, so x and not #0(x) | array-cell-ref       |
| array-amend!        | set cell                         | array-cell-set!      |
| array-for-each-cell | iterate over subarrays           | array-for-each-slice |

We define a k-cell to be a (prefix) k-subarray except that the 0-cells are x instead of #0(x). This is also consistent with the APL/J terminology (there are no rank 0 arrays in APL/J that are different from a simple element).

(array-for-each-cell) however must iterate over k-subarrays (not k-cells) so that they can be used as write targets. Then it makes sense to change this name to (array-for-each-slice), and all the names are consistent.

What do you think?

Regards

	lloda

Re: name an array function

[tomas]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Wed, Nov 23, 2016 at 05:07:30PM +0100, Daniel Llorens wrote:
> 
> On 21 Nov 2016, at 14:56, tomas@tuxteam.de wrote:
> 
> > I (politely) disagree: the most "commonly" used function is
> > already array-ref, so you would seldomly use array-from/slice
> > for a scalar result (the rank-0 result will be more frequent,
> > because there's no substitute). But hey, as I said.
> 
> I don't use array-ref/set! anymore since array-from/amend! generalize them. I actually use a further generalization in a separate library :p
> 
> But I have a proposal below that makes this discussion moot, I hope.
> 
> | master (current)    | meaning                          | proposal             |
> |---------------------+----------------------------------+----------------------|
> | array-from*         | look up subarray, even #0(x)     | array-slice          |
> | array-from          | look up cell, so x and not #0(x) | array-cell-ref       |
> | array-amend!        | set cell                         | array-cell-set!      |
> | array-for-each-cell | iterate over subarrays           | array-for-each-slice |
> 
> We define a k-cell to be a (prefix) k-subarray except that the 0-cells are x instead of #0(x). This is also consistent with the APL/J terminology (there are no rank 0 arrays in APL/J that are different from a simple element).
> 
> (array-for-each-cell) however must iterate over k-subarrays (not k-cells) so that they can be used as write targets. Then it makes sense to change this name to (array-for-each-slice), and all the names are consistent.
> 
> What do you think?

This looks awesome to me. Very readable!

thanks
- -- tomás
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iEUEARECAAYFAlg1/OEACgkQBcgs9XrR2ka1IwCdEpdCEQ+o8brVsFSWEXyR5bLY
EkkAmK0Q59yIYdnAOC3ciOW9++AsjsE=
=5dGO
-----END PGP SIGNATURE-----

Re: name an array function

[David Pirotte]

[-- Attachment #1: Type: text/plain, Size: 1269 bytes --]

Le Wed, 23 Nov 2016 17:07:30 +0100,
Daniel Llorens <daniel.llorens@bluewin.ch> a écrit :

> On 21 Nov 2016, at 14:56, tomas@tuxteam.de wrote:
> 
> > I (politely) disagree: the most "commonly" used function is
> > already array-ref, so you would seldomly use array-from/slice
> > for a scalar result (the rank-0 result will be more frequent,
> > because there's no substitute). But hey, as I said.  
> 
> I don't use array-ref/set! anymore since array-from/amend! generalize them. I
> actually use a further generalization in a separate library :p
> 
> But I have a proposal below that makes this discussion moot, I hope.
> 
> | master (current)    | meaning                          | proposal             |
> |---------------------+----------------------------------+----------------------|
> | array-from*         | look up subarray, even #0(x)     | array-slice          |
> | array-from          | look up cell, so x and not #0(x) | array-cell-ref       |
> | array-amend!        | set cell                         | array-cell-set!      |
> | array-for-each-cell | iterate over subarrays           | array-for-each-slice |

I'd use 

	array-slice-ref/set!
	array-slice-for-each

Unless I miss understood something :)

Cheers,
David

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: name an array function

[Daniel Llorens]

On 23 Nov 2016, at 21:48, David Pirotte <david@altosw.be> wrote:

> Le Wed, 23 Nov 2016 17:07:30 +0100,
> Daniel Llorens <daniel.llorens@bluewin.ch> a écrit :
> 
>> On 21 Nov 2016, at 14:56, tomas@tuxteam.de wrote:
>> 
>>> I (politely) disagree: the most "commonly" used function is
>>> already array-ref, so you would seldomly use array-from/slice
>>> for a scalar result (the rank-0 result will be more frequent,
>>> because there's no substitute). But hey, as I said.  
>> 
>> I don't use array-ref/set! anymore since array-from/amend! generalize them. I
>> actually use a further generalization in a separate library :p
>> 
>> But I have a proposal below that makes this discussion moot, I hope.
>> 
>> | master (current)    | meaning                          | proposal             |
>> |---------------------+----------------------------------+----------------------|
>> | array-from*         | look up subarray, even #0(x)     | array-slice          |
>> | array-from          | look up cell, so x and not #0(x) | array-cell-ref       |
>> | array-amend!        | set cell                         | array-cell-set!      |
>> | array-for-each-cell | iterate over subarrays           | array-for-each-slice |
> 
> I'd use 
> 
> 	array-slice-ref/set!
> 	array-slice-for-each
> 
> Unless I miss understood something :)
> 
> Cheers,
> David

The slice/cell distinction is to be able to use the array as a list of items regardless of whether the items have rank 0 or not.

array-slice doesn't need -ref or -set! variants because it always returns an array object, so you can do (array-copy! B (array-slice A ...)) or (array-copy! (array-slice A ...) B). On the other hand array-cell-ref may return a non-array object so the -set! variant is necessary.

array-for-each-cell -> array-slice-for-each is ok I think b/c it really does iterate over slices and not cells.

So what about this? if there's no comment in a week or so I'll take it as settled.

| master (current)    | meaning                          | proposal             |
|---------------------+----------------------------------+----------------------|
| array-from*         | look up subarray, even #0(x)     | array-slice          |
| array-from          | look up cell, so x and not #0(x) | array-cell-ref       |
| array-amend!        | set cell                         | array-cell-set!      |
| array-for-each-cell | iterate over subarrays           | array-slice-for-each |

Thanks

	Daniel

Re: name an array function

[tomas]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Thu, Dec 15, 2016 at 12:12:58PM +0100, Daniel Llorens wrote:
> 
> On 23 Nov 2016, at 21:48, David Pirotte <david@altosw.be> wrote:

[...]

> > I'd use 
> > 
> > 	array-slice-ref/set!
> > 	array-slice-for-each
> > 
> > Unless I miss understood something :)
> > 
> > Cheers,
> > David
> 
> The slice/cell distinction is to be able to use the array as a list of items regardless of whether the items have rank 0 or not.

[...]

Makes sense.

[...]

> So what about this? if there's no comment in a week or so I'll take it as settled.
> 
> | master (current)    | meaning                          | proposal             |
> |---------------------+----------------------------------+----------------------|
> | array-from*         | look up subarray, even #0(x)     | array-slice          |
> | array-from          | look up cell, so x and not #0(x) | array-cell-ref       |
> | array-amend!        | set cell                         | array-cell-set!      |
> | array-for-each-cell | iterate over subarrays           | array-slice-for-each |

My take: beautiful :)

Thanks for all the care you put into interface design!

regards
- -- tomás
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iEYEARECAAYFAlhSfsgACgkQBcgs9XrR2kYWJwCZAU8ZUKogI1zAP783eazROTgB
a6EAn1c/gs9oIaL3OBbfI3av1bZe1En8
=a5lG
-----END PGP SIGNATURE-----

Re: name an array function

[Panicz Maciej Godek]

2016-11-21 11:32 GMT+01:00 Daniel Llorens <daniel.llorens@bluewin.ch>:

>
> Hello,
>
> version 2.2 of Guile will (I hope) include rank-polymorphic versions of
> array-ref, array-set! and array-for-each. What this means is that instead
> of requiring as many indices as the rank of the array, with these functions
> you can give fewer indices and get a subarray (a ‘prefix slice’). If you
> give all the indices, they behave just as the current versions.
>
> [...]

>
> What do *you* think should be the names of these functions?
>

As far as accessors are concerned, I'm not sure whether they actaully need
names. Maybe it would be better to make them applicable, and produce
"procedures with setters"?

Re: name an array function

[Daniel Llorens]

On 21 Nov 2016, at 15:01, Panicz Maciej Godek <godek.maciek@gmail.com> wrote:

> As far as accessors are concerned, I'm not sure whether they actaully need names. Maybe it would be better to make them applicable, and produce "procedures with setters"?

I'd absolutely prefer (A i j) to (array-whatever A i j). Arrays *are* functions of indices.

But the mechanism for applicable objects isn't being used right now for any of the data structures with accessors. It isn't documented in the manual, either. I don't know how it works. Some patches are needed there, examples. Moreover if the type of arrays is changed (which I believe is needed to make arrays an applicable object), then we must retain compatibility with all the existing array procedures. I like the idea, but I don't think it's going to happen for 2.2.

Procedures with setters would remove the need for the modifying function (array-slice-copy! or whatever it ends up being called), but this isn't done now even for the pair array-ref / array-set!. However it is easier to implement.

My idea has always been to move the array descriptor (storage pointer, strides, etc), which is now an opaque C object, to Scheme. Then we could do lots of stuff without having to rebuild Guile, take advantage of compiler optimizations, etc. But even that isn't in the cards for 2.2. At least I don't think anyone is working on it.