I am getting ready to tag a new release of the Algorithms package, and there are a couple new additions that I'd like to discuss the naming for before they become part of a release.
First up is slidingWindows(ofCount:), which you can read about in the Sliding Windows guide. This method was originally called windows(ofCount:), and was changed to the current name based on a question about overlap with the Windows platform.
My questions here:
Does slidingWindows(ofCount:) make a good name for this operation?
Would windows(ofCount:) really cause confusion with the similarly-named platform?
If the windows are sliding, are there windows-plural, or is there just one window that slides along the collection?
Many thanks to ollieatkinson for contributing this method to the package!
In that same StackOverflow question "windows" are mentioned too, so it's appropriate.
As a Swift user, however, since we have the concept of SubSequences, I personally find it more suitable as a naming candidate. From the official documentation:
SubSequence
A sequence that represents a contiguous subrange of the collection’s elements.
I’m a big fan of subsequences(ofCount:). I like associating it with the SubSequence name, which helps to reinforce what the return values are.
One minor note is that the use of sub sequence as two words (SubSequence) and one word (subsequence) seems inconsistent, but it looks like it’s already used inconsistently in the standard library .
Another thing to consider with this API’s naming is how this may tie in to the naming of a potential future adjacentPairs algorithm.
Subsequences already have a use within Swift's collection protocols, so it's probably not a good idea to overload it, especially when this method doesn't actually produce subsequences.
windows(ofCount:) is fine in regards to any conflict with Windows the OS, it's just not very descriptive. slidingWindows is better because it tells me there's a sequence of windows. As for plurality, this produces many values, so it seems fine.
public subscript(index: Index) -> Base.SubSequence
There’s some similarity, but the difference is that adjacentPairs returns tuples where each subsequent pair overlaps with the previous pair—similar to slidingWindows(ofSize: 2)—whereas chunks(ofSize: 2) wouldn’t have overlapping subsequences.
Given [1, 2, 4, 8]:
adjacentPairs() would produce: [(1, 2), (2, 4), (4, 8)]
This can be useful for calculating deltas between elements like: adjacentPairs().map({ $1 - $0 }).
chunks(ofSize: 2) would produce: [[1, 2], [4, 8]]
But I don’t see a chunks(ofSize:) function defined as such, so that’s how I would imagine it would behave.
My point there was more directed at the return type of this function, which was named Windows in line with the method. The consideration was that, if it is meant as a facility potentially to be incorporated into the standard library, a standard library type named Windows would be potentially improvident in that regard.
But as to the method itself, I could go either way, but slidingWindows is very clear in a way that windows alone is not as to which windows are being returned; it is confusable with the concept of a view (viz. String.UTF8View), which in Swift definitively does not suggest which part of the parent collection is being viewed.
(On that note, we could consider slidingViews also...)
The "windows" terminology feels a bit too... cute to me, though perhaps this is a term of art that I'm simply not familiar with. Given that there's already API which refers to contiguous regions of the collection as "chunks", what about taking some inspiration from this thread and calling this method overlappingChunks(ofSize:)?
It should be either windows or slidingWindow; there are either multiple windows, or a single window that slides along the collection. There are not multiple sliding windows.
@Jumhyn Yes, "sliding window" is the usual DSP term of art for this. In math, the standard term would be "contiguous subsequence of length N" (in math, a "subsequence" is not necessarily contiguous).
Personally I would probably use the more-verbose contiguousSubsequences(ofCount:), but that may be a step too far.
I think slidingWindow(s), be it plural or singular, is not a good description of what is returned: we use the resulting windows directly, without making them move (slide). Hence, windows would be a better fit IMO.
However, I’m not sure this term would be clear to everybody. I don’t know how many people are familiar with this use of the word. As for myself, when I talk about a window in DSP, in my head it represents the lens through which we access a chunk of signal, not the actual part of the signal — here, without reading the documentation, I would expect this function to return a collection of ranges of indices (i.e. an extra level of indirection), rather than something that gives me direct access to the elements of the base collection (I don’t know if I’m being very clear here).
Why not just use slices(ofSize:)?
It would avoid introducing yet another term to refer to a part of a collection, and it would be consistent with what is said in the Naming section of the description of Chunked:
sliced : Not included in this package or the stdlib. Breaks a collection into potentially overlapping subsequences.
I guess it could be either slices(ofSize:) or sliced(bySize:) (but I tend to prefer the former).
But how do you communicate which slices of that size are returned, namely that it isn’t potentially overlapping, but definitely overlapping, and moreover that each one overlaps the previous in all but one element?
Well, you don’t… which is surely due to the fact that I had read the description of this function way too fast and had badly misunderstood what it actually does!
Sorry about that (and thanks for making me realize my mistake).
In that case, my previous comment was just useless noise, and now that I have finally understood the function correctly, I have to admit that I can’t find any name for it that seems better than slidingWindow(ofSize:).
Singular form, for the reason @scanon has explained above.
And with the label ofSize for the argument, because I find it weird to talk about the count of a window when actually referring to the count of the elements in the window. The size of a window just makes more sense to me (which, I admit, may very well be just because of being used to that term rather than because of logic).
.
