Skip to content

ListSeqArrayAdditions.md

Latest commit

 

History

History
176 lines (149 loc) · 12.6 KB

ListSeqArrayAdditions.md

File metadata and controls

176 lines (149 loc) · 12.6 KB

F# 4.0 Speclet: Regularizing and extending the List, Array and Seq modules

User Voice

There is an approved proposal to make the functions defined in the List, Array, and Seq modules in FSharp.Core.dll more regular and to add some new functions.

New functions added in this proposal: splitAt, contains, findBack, tryFindBack, findIndexBack, tryFindIndexBack, item, tryItem, indexed, mapFold, mapFoldBack, tryLast, tryHead.

Background

The F# 2.x and 3.x philosophy for these functions was somewhat irregular. The majority of functions (e.g. map, filter, groupBy, averageBy) were defined for Seq, but some were not present on List and Array (e.g. groupBy). This leads to awkward code where Seq-producing functions are used even when List is an input. Seq.groupBy is a particular example.

Also, some functions were not defined on Seq, even though they exist in List or Array.

The proposal below is to complete the matrix for List, Array and Seq w.r.t. functional collection functions.

Review and Completion

This work is only completed when all rows have a status of ":)". The library updates will only be done when all PRs are ready (or features are dropped).

Status column

  • :) - reviewed and ready to be pulled
  • :/ - reviewed but changes needed
  • (empty) - no PR or not reviewed

If an item is marked "low-pri" it doesn't need to be completed in order for the library update to happen.

Regular functional functions

Function Comment List Array Seq PR Status
append o o o --- n/a
average o o o --- n/a
averageBy o o o --- n/a
contains new ADD ADD ADD PR committed
choose o o o --- n/a
chunkBySize ADD ADD ADD PR committed
collect o o o --- n/a
compareWith ADD ADD o PR committed
concat o o o --- n/a
countBy ADD ADD o PR committed
distinct ADD ADD o PR committed
distinctBy ADD ADD o PR committed
splitInto ADD ADD ADD PR committed
empty o o o --- n/a
exactlyOne ADD ADD o PR committed
except ADD ADD ADD PR committed
exists o o o --- n/a
exists2 o o o --- n/a
filter o o o --- n/a
find o o o --- n/a
findBack new ADD ADD ADD PR committed
findIndex o o o --- n/a
findIndexBack new ADD ADD ADD PR committed
fold o o o --- n/a
fold2 o o ADD PR committed
foldBack o o ADD PR committed
foldBack2 o o ADD PR committed
forall o o o --- n/a
forall2 o o o --- n/a
groupBy o o ADD PR committed
head o ADD o PR committed
indexed new, signature indexed: C<T> -> C<int*T> ADD ADD ADD PR committed
init o o o --- n/a
isEmpty o o o --- n/a
item New, see note. Signature int -> C<'T> -> 'T ADD ADD ADD PR committed
iter o o o --- n/a
iter2 o o o --- n/a
iteri o o o --- n/a
iteri2 o o ADD PR committed
last ADD ADD o PR committed
length o o o --- n/a
map o o o --- n/a
map2 o o o --- n/a
map3 o ADD ADD PR committed
mapi o o o --- n/a
mapi2 o o ADD PR committed
mapFold New, map + fold, with signature mapFold : ('State -> 'T -> 'U * 'State) -> 'State -> C<'T> -> C<'U> * 'State e.g. see here ADD ADD ADD PR committed
mapFoldBack New, map + fold, with signature mapFoldBack : ('T -> 'State -> 'U * 'State) -> C<'T> -> 'State -> C<'U> * 'State ADD ADD ADD PR committed
max o o o --- n/a
maxBy o o o --- n/a
min o o o --- n/a
minBy o o o --- n/a
nth see note long-term deprecate, see note o long-term deprecate, see note --- n/a
pairwise ADD ADD o PR committed
permute o o ADD PR committed
pick o o o --- n/a
reduce o o o --- n/a
reduceBack o o ADD PR committed
replicate o ADD ADD PR committed
rev o o ADD PR committed
scan o o o --- n/a
scanBack o o ADD PR committed
singleton ADD ADD o PR committed
skip ADD ADD o PR committed
skipWhile ADD ADD o PR committed
sort o o o --- n/a
sortBy o o o --- n/a
sortWith o o ADD PR committed
sortDescending ADD ADD ADD PR committed
sortByDescending ADD ADD ADD PR committed
sum o o o --- n/a
sumBy o o o --- n/a
tail o ADD ADD PR committed
take ADD ADD o PR committed
takeWhile ADD ADD o PR committed
truncate ADD ADD o PR committed
tryFind o o o --- n/a
tryFindBack new ADD ADD ADD PR committed
tryFindIndex o o o --- n/a
tryFindIndexBack new ADD ADD ADD PR committed
tryHead new ADD ADD ADD PR committed
tryItem new ADD ADD ADD PR committed
tryLast new ADD ADD ADD PR committed
tryPick o o o --- n/a
unfold ADD ADD o PR committed
where syn. filter ADD ADD o PR committed
windowed ADD ADD o PR committed
zip o o o --- n/a
zip3 o o o --- n/a

Note: In F# 3.0 Seq.where was defined as a synonym for Seq.filter, mainly due to the use of "where" in query expressions. Given it already exists as a synonym (= decision made) it seems sensible to just complete the matrix and define List.where and Array.where as well.

Note: In F# 3.x, nth is defined with inconsistent signatures for Array and List. The proposal above replaces nth by item and would eventually deprecate nth (with a message to say 'please use Seq.item'. It also adds a corresponding tryItem. Both item and tryItem would take the integer index as the first parameter.

Regular functional operators producing two or more output collections

These operators are not defined for Seq.* for performance reasons because using them would require iterating the input sequence twice.

Note it is arguable that if these are not defined, then Seq.tail, Seq.skip and Seq.skipWhile should also not be defined, since they implicitly skip inputs and can be a performance trap, especially when used recursively.

Function Comment List Array Seq PR Status
partition o o n/a --- n/a
splitAt new, taking index ADD ADD n/a PR committed
unzip o o n/a --- n/a
unzip3 o o n/a --- n/a

Mutation-related operators

Function Comment List Array Seq PR Status
blit n/a o n/a --- n/a
copy n/a o n/a --- n/a
create n/a o n/a --- n/a
fill n/a o n/a --- n/a
get n/a o n/a --- n/a
set n/a o n/a --- n/a
sortInPlace n/a o n/a --- n/a
sortInPlaceBy n/a o n/a --- n/a
sortInPlaceWith n/a o n/a --- n/a
sub n/a o n/a --- n/a
zeroCreate n/a o n/a --- n/a

Conversion operators

Function Comment List Array Seq PR Status
ofList n/a o o --- n/a
ofArray o n/a o --- n/a
ofSeq o o n/a --- n/a
toList n/a o o --- n/a
toArray o n/a o --- n/a
toSeq o o n/a --- n/a

On-demand or IEnumerable computation operators

Function Comment List Array Seq PR Status
cache n/a n/a o --- n/a
cast n/a n/a o --- n/a
delay n/a n/a o --- n/a
initInfinite n/a n/a o --- n/a
readonly n/a n/a o --- n/a