diff --git a/src/FSharp.Control.TaskSeq/TaskSeq.fs b/src/FSharp.Control.TaskSeq/TaskSeq.fs index 78f156e9..6519dd95 100644 --- a/src/FSharp.Control.TaskSeq/TaskSeq.fs +++ b/src/FSharp.Control.TaskSeq/TaskSeq.fs @@ -21,7 +21,7 @@ module TaskSeq = } } - let singleton (source: 'T) = Internal.singleton source + let singleton (value: 'T) = Internal.singleton value let isEmpty source = Internal.isEmpty source diff --git a/src/FSharp.Control.TaskSeq/TaskSeq.fsi b/src/FSharp.Control.TaskSeq/TaskSeq.fsi index ddae68c2..8752cb1c 100644 --- a/src/FSharp.Control.TaskSeq/TaskSeq.fsi +++ b/src/FSharp.Control.TaskSeq/TaskSeq.fsi @@ -12,37 +12,58 @@ module TaskSeq = /// /// Creates a sequence from that generates a single element and then ends. /// - val singleton: source: 'T -> taskSeq<'T> + /// + /// The input item to use as the single item of the task sequence. + val singleton: value: 'T -> taskSeq<'T> /// /// Returns if the task sequence contains no elements, otherwise. /// + /// + /// The input task sequence. + /// Thrown when the input task sequence is null. val isEmpty: source: taskSeq<'T> -> Task /// /// Returns the length of the sequence. This operation requires the whole sequence to be evaluated and /// should not be used on potentially infinite sequences, see for an alternative. /// + /// + /// The input task sequence. + /// Thrown when the input task sequence is null. val length: source: taskSeq<'T> -> Task /// /// Returns the length of the sequence, or , whichever comes first. This operation requires the task sequence - /// to be evaluated in full, or until items have been processed. Use this method instead of - /// if you want to prevent too many items to be evaluated, or if the sequence is potentially infinite. + /// to be evaluated ether in full, or until items have been processed. Use this method instead of + /// if you need to limit the number of items evaluated, or if the sequence is potentially infinite. /// + /// + /// Limit at which to stop evaluating source items for finding the length. + /// The input task sequence. + /// Thrown when the input task sequence is null. val lengthOrMax: max: int -> source: taskSeq<'T> -> Task /// /// Returns the length of the sequence of all items for which the returns true. /// This operation requires the whole sequence to be evaluated and should not be used on potentially infinite sequences. + /// If is asynchronous, consider using . /// + /// + /// A function to test whether an item in the input sequence should be included in the count. + /// The input task sequence. + /// Thrown when the input task sequence is null. val lengthBy: predicate: ('T -> bool) -> source: taskSeq<'T> -> Task /// /// Returns the length of the sequence of all items for which the returns true. /// This operation requires the whole sequence to be evaluated and should not be used on potentially infinite sequences. - /// If does not need to be asynchronous, consider using . + /// If is synchronous, consider using . /// + /// + /// A function to test whether an item in the input sequence should be included in the count. + /// The input task sequence. + /// Thrown when the input task sequence is null. val lengthByAsync: predicate: ('T -> #Task) -> source: taskSeq<'T> -> Task /// @@ -55,7 +76,7 @@ module TaskSeq = /// /// Generates a new task sequence which, when iterated, will return successive elements by calling the given function - /// with the current index, up to the given count. Each element is saved after its initialization for successive access to + /// with the curren zero-basedt index, up to the given count. Each element is saved after its initialization for successive access to /// , which will not re-evaluate the . However, /// re-iterating the returned task sequence will re-evaluate the initialization function. The returned sequence may /// be passed between threads safely. However, individual IEnumerator values generated from the returned sequence should @@ -70,7 +91,7 @@ module TaskSeq = /// /// Generates a new task sequence which, when iterated, will return successive elements by calling the given function - /// with the current index, up to the given count. Each element is saved after its initialization for successive access to + /// with the current zero-based index, up to the given count. Each element is saved after its initialization for successive access to /// , which will not re-evaluate the . However, /// re-iterating the returned task sequence will re-evaluate the initialization function. The returned sequence may /// be passed between threads safely. However, individual IEnumerator values generated from the returned sequence should @@ -85,7 +106,7 @@ module TaskSeq = /// /// Generates a new task sequence which, when iterated, will return successive elements by calling the given function - /// with the current index, ad infinitum, or until is reached. + /// with the current zero-based index, ad infinitum, or until is reached. /// Each element is saved after its initialization for successive access to /// , which will not re-evaluate the . However, /// re-iterating the returned task sequence will re-evaluate the initialization function. The returned sequence may @@ -99,7 +120,7 @@ module TaskSeq = /// /// Generates a new task sequence which, when iterated, will return successive elements by calling the given function - /// with the current index, ad infinitum, or until is reached. + /// with the current zero-based index, ad infinitum, or until is reached. /// Each element is saved after its initialization for successive access to /// , which will not re-evaluate the . However, /// re-iterating the returned task sequence will re-evaluate the initialization function. The returned sequence may @@ -116,9 +137,9 @@ module TaskSeq = /// new flattened, single task sequence. Each task sequence is awaited item by item, before the next is iterated. /// /// - /// The input enumeration-of-enumerations. + /// The input task-sequence-of-task-sequences. /// The resulting task sequence. - /// Thrown when the input sequence is null. + /// Thrown when the input task sequence of task sequences is null. val concat: sources: taskSeq<#taskSeq<'T>> -> taskSeq<'T> /// @@ -129,7 +150,7 @@ module TaskSeq = /// The first input task sequence. /// The second input task sequence. /// The resulting task sequence. - /// Thrown when either of the input sequences is null. + /// Thrown when either of the input task sequences is null. val append: source1: taskSeq<'T> -> source2: taskSeq<'T> -> taskSeq<'T> /// @@ -154,414 +175,814 @@ module TaskSeq = /// Thrown when either of the input sequences is null. val prependSeq: source1: seq<'T> -> source2: taskSeq<'T> -> taskSeq<'T> - /// Returns taskSeq as an array. This function is blocking until the sequence is exhausted and will properly dispose of the resources. + /// + /// Builds an F# from the input task sequence in . + /// This function is blocking until the sequence is exhausted and will then properly dispose of the resources. + /// + /// + /// The input task sequence. + /// The resulting list. + /// Thrown when the input sequence is null. val toList: source: taskSeq<'T> -> 'T list - /// Returns taskSeq as an array. This function is blocking until the sequence is exhausted and will properly dispose of the resources. + /// + /// Builds an from the input task sequence in . + /// This function is blocking until the sequence is exhausted and will then properly dispose of the resources. + /// + /// + /// The input task sequence. + /// The resulting array. + /// Thrown when the input sequence is null. val toArray: source: taskSeq<'T> -> 'T[] /// - /// Returns the task sequence as an F# , that is, an - /// . This function is blocking at each , but otherwise - /// acts as a normal delay-executed sequence. - /// It will then dispose of the resources. + /// Views the task sequence in as an F# , that is, an + /// . This function is blocking at each or call + /// to in the resulting sequence. + /// Resources are disposed when the sequence is disposed, or the sequence is exhausted. /// /// /// The input task sequence. /// The resulting task sequence. + /// Thrown when the input sequence is null. val toSeq: source: taskSeq<'T> -> seq<'T> - /// Unwraps the taskSeq as a Task>. This function is non-blocking. + /// + /// Builds an asynchronously from the input task sequence. + /// This function is non-blocking while it builds the array. + /// + /// + /// The input task sequence. + /// The resulting array. + /// Thrown when the input sequence is null. val toArrayAsync: source: taskSeq<'T> -> Task<'T[]> - /// Unwraps the taskSeq as a Task>. This function is non-blocking. + /// + /// Builds an F# asynchronously from the input task sequence. + /// This function is non-blocking while it builds the list. + /// + /// + /// The input task sequence. + /// The resulting list. + /// Thrown when the input sequence is null. val toListAsync: source: taskSeq<'T> -> Task<'T list> - /// Unwraps the taskSeq as a Task>. This function is non-blocking. + /// + /// Gathers items into a ResizeArray (see ) asynchronously from the input task sequence. + /// This function is non-blocking while it builds the resizable array. + /// + /// + /// The input task sequence. + /// The resulting resizable array. + /// Thrown when the input sequence is null. val toResizeArrayAsync: source: taskSeq<'T> -> Task> - /// Unwraps the taskSeq as a Task>. This function is non-blocking. + /// + /// Builds an asynchronously from the input task sequence. + /// This function is non-blocking while it builds the IList. + /// + /// + /// The input task sequence. + /// The resulting IList interface. + /// Thrown when the input sequence is null. val toIListAsync: source: taskSeq<'T> -> Task> - /// Create a taskSeq of an array. + /// + /// Views the given as a task sequence, that is, as an . + /// + /// + /// The input array. + /// The resulting task sequence. + /// Thrown when the input array is null. val ofArray: source: 'T[] -> taskSeq<'T> - /// Create a taskSeq of a list. + /// + /// Views the given as a task sequence, that is, as an . + /// + /// + /// The input list. + /// The resulting task sequence. val ofList: source: 'T list -> taskSeq<'T> - /// Create a taskSeq of a seq. + /// + /// Views the given as a task sequence, that is, as an . + /// + /// + /// The input sequence. + /// The resulting task sequence. + /// Thrown when the input sequence is null. val ofSeq: source: seq<'T> -> taskSeq<'T> - /// Create a taskSeq of a ResizeArray, aka List. + /// + /// Views the given resizable array as a task sequence, that is, as an . + /// + /// + /// The input resize array. + /// The resulting task sequence. + /// Thrown when the input resize array is null. val ofResizeArray: source: ResizeArray<'T> -> taskSeq<'T> - /// Create a taskSeq of a sequence of tasks, that may already have hot-started. + /// + /// Views the given of s as a task sequence, that is, as an + /// . A sequence of tasks is not the same as a task sequence. + /// Each task in a sequence of tasks can be run individually and potentially out of order, or with + /// overlapping side effects, while a task sequence forces awaiting between the items in the sequence, + /// preventing such overlap to happen. + /// + /// + /// The input sequence-of-tasks. + /// The resulting task sequence. + /// Thrown when the input sequence is null. val ofTaskSeq: source: seq<#Task<'T>> -> taskSeq<'T> - /// Create a taskSeq of a list of tasks, that may already have hot-started. + /// + /// Views the given of s as a task sequence, that is, as an + /// . A list of tasks will typically already be hot-started, + /// as a result, each task can already run and potentially out of order, or with + /// overlapping side effects, while a task sequence forces awaiting between the items in the sequence, + /// preventing such overlap to happen. Converting a list of tasks into a task sequence is no guarantee + /// that overlapping side effects are prevented. Safe for side-effect free tasks. + /// + /// + /// The input list-of-tasks. + /// The resulting task sequence. val ofTaskList: source: #Task<'T> list -> taskSeq<'T> - /// Create a taskSeq of an array of tasks, that may already have hot-started. + /// + /// Views the given of s as a task sequence, that is, as an + /// . An array of tasks will typically already be hot-started, + /// as a result, each task can already run and potentially out of order, or with + /// overlapping side effects, while a task sequence forces awaiting between the items in the sequence, + /// preventing such overlap to happen. Converting an array of tasks into a task sequence is no guarantee + /// that overlapping side effects are prevented. Safe for side-effect free tasks. + /// + /// + /// The input array-of-tasks. + /// The resulting task sequence. + /// Thrown when the input array is null. val ofTaskArray: source: #Task<'T> array -> taskSeq<'T> - /// Create a taskSeq of a seq of async. + /// + /// Views the given of s as a task sequence, that is, as an + /// . A sequence of asyncs is not the same as a task sequence. + /// Each async computation in a sequence of asyncs can be run individually or in parallel, potentially + /// with overlapping side effects, while a task sequence forces awaiting between the items in the sequence, + /// preventing such overlap to happen. + /// + /// + /// The input sequence-of-asyncs. + /// The resulting task sequence. + /// Thrown when the input sequence is null. val ofAsyncSeq: source: seq> -> taskSeq<'T> - /// Create a taskSeq of a list of async. + /// + /// Views the given of s as a task sequence, that is, as an + /// . A list of asyncs is not the same as a task sequence. + /// Each async computation in a list of asyncs can be run individually or in parallel, potentially + /// with overlapping side effects, while a task sequence forces awaiting between the items in the sequence, + /// preventing such overlap to happen. + /// + /// + /// The input list-of-asyncs. + /// The resulting task sequence. val ofAsyncList: source: Async<'T> list -> taskSeq<'T> - /// Create a taskSeq of an array of async. + /// + /// Views the given of s as a task sequence, that is, as an + /// . An array of asyncs is not the same as a task sequence. + /// Each async computation in an array of asyncs can be run individually or in parallel, potentially + /// with overlapping side effects, while a task sequence forces awaiting between the items in the sequence, + /// preventing such overlap to happen. + /// + /// + /// The input array-of-asyncs. + /// The resulting task sequence. + /// Thrown when the input sequence is null. val ofAsyncArray: source: Async<'T> array -> taskSeq<'T> /// - /// Boxes as type each item in the sequence asynchyronously. + /// Views each item in the input task sequence as , boxing value types. /// + /// + /// The input task sequence. + /// The resulting task sequence. + /// Thrown when the input task sequence is null. val box: source: taskSeq<'T> -> taskSeq /// - /// Unboxes to the target type each item in the sequence asynchyronously. + /// Unboxes to the target type each item in the input task sequence. /// The target type must be a or a built-in value type. /// + /// + /// The input task sequence. + /// The resulting task sequence. + /// Thrown when the input task sequence is null. /// Thrown when the function is unable to cast an item to the target type. val unbox<'U when 'U: struct> : source: taskSeq -> taskSeq<'U> /// - /// Casts each item in the untyped sequence asynchyronously. If your types are boxed struct types + /// Casts each item in the untyped input task sequence. If the input sequence contains value types /// it is recommended to use instead. /// + /// + /// The input task sequence. + /// The resulting task sequence. + /// Thrown when the input task sequence is null. /// Thrown when the function is unable to cast an item to the target type. - val cast: source: taskSeq -> taskSeq<'T> + val cast: source: taskSeq -> taskSeq<'U> - /// Iterates over the taskSeq applying the action function to each item. This function is non-blocking - /// exhausts the sequence as soon as the task is evaluated. + /// + /// Iterates over the input task sequence, applying the function to each item. + /// This function is non-blocking, but will exhaust the full input sequence as soon as the task is evaluated. + /// + /// + /// A function to apply to each element of the task sequence. + /// The input task sequence. + /// A . + /// Thrown when the input sequence is null. val iter: action: ('T -> unit) -> source: taskSeq<'T> -> Task - /// Iterates over the taskSeq applying the action function to each item. This function is non-blocking, - /// exhausts the sequence as soon as the task is evaluated. + /// + /// Iterates over the input task sequence, applying the function to each item, + /// supplying the zero-based index as extra parameter for the function. + /// This function is non-blocking, but will exhaust the full input sequence as soon as the task is evaluated. + /// + /// + /// A function to apply to each element of the task sequence that can also access the current index. + /// The input task sequence. + /// A . + /// Thrown when the input task sequence is null. val iteri: action: (int -> 'T -> unit) -> source: taskSeq<'T> -> Task - /// Iterates over the taskSeq applying the async action to each item. This function is non-blocking - /// exhausts the sequence as soon as the task is evaluated. + /// + /// Iterates over the input task sequence, applying the asynchronous function to each item. + /// This function is non-blocking, but will exhaust the full input sequence as soon as the task is evaluated. + /// + /// + /// An asynchronous function to apply to each element of the task sequence. + /// The input task sequence. + /// A . + /// Thrown when the input task sequence is null. val iterAsync: action: ('T -> #Task) -> source: taskSeq<'T> -> Task - /// Iterates over the taskSeq, applying the async action to each item. This function is non-blocking, - /// exhausts the sequence as soon as the task is evaluated. + /// + /// Iterates over the input task sequence, applying the asynchronous function to each item, + /// supplying the zero-based index as extra parameter for the function. + /// This function is non-blocking, but will exhaust the full input sequence as soon as the task is evaluated. + /// + /// + /// An asynchronous function to apply to each element of the task sequence that can also access the current index. + /// The input task sequence. + /// A . + /// Thrown when the input sequence is null. val iteriAsync: action: (int -> 'T -> #Task) -> source: taskSeq<'T> -> Task - /// Maps over the taskSeq, applying the mapper function to each item. This function is non-blocking. - val map: mapper: ('T -> 'U) -> source: taskSeq<'T> -> taskSeq<'U> - /// /// Builds a new task sequence whose elements are the corresponding elements of the input task /// sequence paired with the integer index (from 0) of each element. /// Does not evaluate the input sequence until requested. /// + /// /// The input task sequence. /// The resulting task sequence of tuples. - /// Thrown when the input sequence is null. + /// Thrown when the input task sequence is null. val indexed: source: taskSeq<'T> -> taskSeq - /// Maps over the taskSeq with an index, applying the mapper function to each item. This function is non-blocking. + /// + /// Builds a new task sequence whose elements are the results of applying the + /// function to each of the elements of the input task sequence in . + /// The given function will be applied as elements are pulled using the + /// method on async enumerators retrieved from the input task sequence. + /// Does not evaluate the input sequence until requested. + /// + /// + /// A function to transform items from the input task sequence. + /// The input task sequence. + /// The resulting task sequence. + /// Thrown when the input task sequence is null. + val map: mapper: ('T -> 'U) -> source: taskSeq<'T> -> taskSeq<'U> + + /// + /// Builds a new task sequence whose elements are the results of applying the + /// function to each of the elements of the input task sequence in , passing + /// an extra zero-based index argument to the function. + /// The given function will be applied as elements are pulled using the + /// method on async enumerators retrieved from the input task sequence. + /// Does not evaluate the input sequence until requested. + /// + /// + /// A function to transform items from the input task sequence that also access the current index. + /// The input task sequence. + /// The resulting task sequence. + /// Thrown when the input task sequence is null. val mapi: mapper: (int -> 'T -> 'U) -> source: taskSeq<'T> -> taskSeq<'U> - /// Maps over the taskSeq, applying the async mapper function to each item. This function is non-blocking. + /// + /// Builds a new task sequence whose elements are the results of applying the asynchronous + /// function to each of the elements of the input task sequence in . + /// The given function will be applied as elements are pulled using the + /// method on async enumerators retrieved from the input task sequence. + /// Does not evaluate the input sequence until requested. + /// + /// + /// An asynchronous function to transform items from the input task sequence. + /// The input task sequence. + /// The resulting task sequence. + /// Thrown when the input task sequence is null. val mapAsync: mapper: ('T -> #Task<'U>) -> source: taskSeq<'T> -> taskSeq<'U> - /// Maps over the taskSeq with an index, applying the async mapper function to each item. This function is non-blocking. + /// + /// Builds a new task sequence whose elements are the results of applying the asynchronous + /// function to each of the elements of the input task sequence in , passing + /// an extra zero-based index argument to the function. + /// The given function will be applied as elements are pulled using the + /// method on async enumerators retrieved from the input task sequence. + /// Does not evaluate the input sequence until requested. + /// + /// + /// An asynchronous function to transform items from the input task sequence that also access the current index. + /// The input task sequence. + /// The resulting task sequence. + /// Thrown when the input task sequence is null. val mapiAsync: mapper: (int -> 'T -> #Task<'U>) -> source: taskSeq<'T> -> taskSeq<'U> - /// Applies the given function to the items in the taskSeq and concatenates all the results in order. + /// + /// Builds a new task sequence whose elements are the results of applying the + /// function to each of the elements of the input task sequence in , and concatenating the + /// returned task sequences. + /// The given function will be applied as elements are pulled using the + /// method on async enumerators retrieved from the input task sequence. + /// Does not evaluate the input sequence until requested. + /// + /// + /// A function to transform items from the input task sequence into a task sequence. + /// The input task sequence. + /// The resulting concatenation of all returned task sequences. + /// Thrown when the input task sequence is null. val collect: binder: ('T -> #taskSeq<'U>) -> source: taskSeq<'T> -> taskSeq<'U> - /// Applies the given function to the items in the taskSeq and concatenates all the results in order. + /// + /// Builds a new task sequence whose elements are the results of applying the + /// function to each of the elements of the input task sequence in , and concatenating the + /// returned regular F# sequences. + /// The given function will be applied as elements are pulled using the + /// method on async enumerators retrieved from the input task sequence. + /// Does not evaluate the input sequence until requested. + /// + /// + /// A function to transform items from the input task sequence into a regular sequence. + /// The input task sequence. + /// The resulting concatenation of all returned task sequences. + /// Thrown when the input task sequence is null. val collectSeq: binder: ('T -> #seq<'U>) -> source: taskSeq<'T> -> taskSeq<'U> - /// Applies the given async function to the items in the taskSeq and concatenates all the results in order. + /// + /// Builds a new task sequence whose elements are the results of applying the asynchronous + /// function to each of the elements of the input task sequence in , and concatenating the + /// returned task sequences. + /// The given function will be applied as elements are pulled using the + /// method on async enumerators retrieved from the input task sequence. + /// Does not evaluate the input sequence until requested. + /// + /// + /// An asynchronous function to transform items from the input task sequence into a task sequence. + /// The input task sequence. + /// The resulting concatenation of all returned task sequences. + /// Thrown when the input task sequence is null. val collectAsync: binder: ('T -> #Task<'TSeqU>) -> source: taskSeq<'T> -> taskSeq<'U> when 'TSeqU :> taskSeq<'U> - /// Applies the given async function to the items in the taskSeq and concatenates all the results in order. + /// + /// Builds a new task sequence whose elements are the results of applying the asynchronous + /// function to each of the elements of the input task sequence in , and concatenating the + /// returned regular F# sequences. + /// The given function will be applied as elements are pulled using the + /// method on async enumerators retrieved from the input task sequence. + /// Does not evaluate the input sequence until requested. + /// + /// + /// An asynchronous function to transform items from the input task sequence into a regular sequence. + /// The input task sequence. + /// The resulting concatenation of all returned task sequences. + /// Thrown when the input task sequence is null. val collectSeqAsync: binder: ('T -> #Task<'SeqU>) -> source: taskSeq<'T> -> taskSeq<'U> when 'SeqU :> seq<'U> /// - /// Returns the first element of the task sequence from , or if the sequence is empty. + /// Returns the first element of the input task sequence given by , + /// or if the sequence is empty. /// + /// + /// The input task sequence. + /// The first element of the task sequence, or . + /// Thrown when the input task sequence is null. val tryHead: source: taskSeq<'T> -> Task<'T option> /// - /// Returns the first elementof the task sequence from + /// Returns the first element of the input task sequence given by . /// - /// Thrown when the sequence is empty. + /// + /// The input task sequence. + /// The first element of the task sequence. + /// Thrown when the input task sequence is null. + /// Thrown when the task sequence is empty. val head: source: taskSeq<'T> -> Task<'T> /// - /// Returns the whole task sequence from , minus its first element, or if the sequence is empty. + /// Returns the whole input task sequence given by , minus its first element, + /// or if the sequence is empty. /// + /// + /// The input task sequence. + /// The input task sequence minus the first element, or . + /// Thrown when the input task sequence is null. val tryTail: source: taskSeq<'T> -> Task option> /// /// Returns the whole task sequence from , minus its first element. /// - /// Thrown when the sequence is empty. + /// + /// The input task sequence. + /// The input task sequence minus the first element. + /// Thrown when the input task sequence is null. + /// Thrown when the task sequence is empty. val tail: source: taskSeq<'T> -> Task> /// - /// Returns the last element of the task sequence from , or if the sequence is empty. + /// Returns the last element of the input task sequence given by , + /// or if the sequence is empty. /// + /// + /// The input task sequence. + /// The last element of the task sequence, or None. + /// Thrown when the input task sequence is null. val tryLast: source: taskSeq<'T> -> Task<'T option> /// - /// Returns the last element of the . + /// Returns the last element of the input task sequence given by . /// - /// Thrown when the sequence is empty. + /// + /// The input task sequence. + /// The last element of the task sequence. + /// Thrown when the input task sequence is null. + /// Thrown when the task sequence is empty. val last: source: taskSeq<'T> -> Task<'T> /// - /// Returns the nth element of the , or if the sequence - /// does not contain enough elements, or if is negative. - /// Parameter is zero-based, that is, the value 0 returns the first element. + /// Returns the nth element of the input task sequence given by , + /// or if the sequence does not contain enough elements. + /// The index is zero-based, that is, using index 0 returns the first element. /// + /// + /// The input task sequence. + /// The nth element of the task sequence, or None if it doesn't exist. + /// Thrown when the input task sequence is null. val tryItem: index: int -> source: taskSeq<'T> -> Task<'T option> /// - /// Returns the nth element of the , or raises an exception if the sequence - /// does not contain enough elements, or if is negative. + /// Returns the nth element of the input task sequence given by , + /// or raises an exception if the sequence does not contain enough elements. + /// The index is zero-based, that is, using index 0 returns the first element. /// - /// Thrown when the sequence has insufficient length or - /// is negative. + /// + /// The input task sequence. + /// The nth element of the task sequence. + /// Thrown when the input task sequence is null. + /// Thrown when the sequence has insufficient length or is negative. val item: index: int -> source: taskSeq<'T> -> Task<'T> /// /// Returns the only element of the task sequence, or if the sequence is empty of /// contains more than one element. /// + /// + /// The input task sequence. + /// The only element of the singleton task sequence, or . + /// Thrown when the input task sequence is null. val tryExactlyOne: source: taskSeq<'T> -> Task<'T option> /// /// Returns the only element of the task sequence. /// - /// Thrown when the input sequence does not contain precisely one element. + /// + /// The input task sequence. + /// The only element of the singleton task sequence, or . + /// Thrown when the input task sequence is null. + /// Thrown when the input task sequence does not contain precisely one element. val exactlyOne: source: taskSeq<'T> -> Task<'T> /// /// Applies the given function to each element of the task sequence. Returns - /// a sequence comprised of the results "x" for each element where - /// the function returns Some(x). + /// a sequence comprised of the results where the function returns . /// If is asynchronous, consider using . /// + /// + /// A function to transform items of type into options of type . + /// The input task sequence. + /// The resulting task sequence. + /// Thrown when the input task sequence is null. val choose: chooser: ('T -> 'U option) -> source: taskSeq<'T> -> taskSeq<'U> /// - /// Applies the given asynchronous function to each element of the task sequence. Returns - /// a sequence comprised of the results "x" for each element where - /// the function returns . - /// If does not need to be asynchronous, consider using . + /// Applies the given asynchronous function to each element of the task sequence. + /// Returns a sequence comprised of the results where the function returns a result + /// of . + /// If is synchronous, consider using . /// + /// + /// An asynchronous function to transform items of type into options of type . + /// The input task sequence. + /// The resulting task sequence. + /// Thrown when the input task sequence is null. val chooseAsync: chooser: ('T -> #Task<'U option>) -> source: taskSeq<'T> -> taskSeq<'U> /// - /// Returns a new collection containing only the elements of the collection - /// for which the given function returns . + /// Returns a new task sequence containing only the elements of the collection + /// for which the given function returns . /// If is asynchronous, consider using . /// + /// + /// A function to test whether an item in the input sequence should be included in the output or not. + /// The input task sequence. + /// The resulting task sequence. + /// Thrown when the input task sequence is null. val filter: predicate: ('T -> bool) -> source: taskSeq<'T> -> taskSeq<'T> /// - /// Yields items from the source while the function returns . - /// The first result concludes consumption of the source. + /// Returns a new task sequence containing only the elements of the input sequence + /// for which the given function returns . + /// If is synchronous, consider using . + /// + /// + /// An asynchronous function to test whether an item in the input sequence should be included in the output or not. + /// The input task sequence. + /// The resulting task sequence. + /// Thrown when the input task sequence is null. + val filterAsync: predicate: ('T -> #Task) -> source: taskSeq<'T> -> taskSeq<'T> + + /// + /// Returns a task sequence that, when iterated, yields elements of the underlying sequence while the + /// given function returns , and then returns no further elements. + /// The first element where the predicate returns is not included in the resulting sequence + /// (see also ). /// If is asynchronous, consider using . /// + /// + /// A function that evaluates to false when no more items should be returned. + /// The input task sequence. + /// The resulting task sequence. + /// Thrown when the input task sequence is null. val takeWhile: predicate: ('T -> bool) -> source: taskSeq<'T> -> taskSeq<'T> /// - /// Yields items from the source while the asynchronous function returns . - /// The first result concludes consumption of the source. - /// If does not need to be asynchronous, consider using . + /// Returns a sequence that, when iterated, yields elements of the underlying sequence while the + /// given asynchronous function returns , and then returns no further elements. + /// The first element where the predicate returns is not included in the resulting sequence + /// (see also ). + /// If is synchronous, consider using . /// + /// + /// An asynchronous function that evaluates to false when no more items should be returned. + /// The input task sequence. + /// The resulting task sequence. + /// Thrown when the input task sequence is null. val takeWhileAsync: predicate: ('T -> #Task) -> source: taskSeq<'T> -> taskSeq<'T> /// - /// Yields items from the source while the function returns . - /// The first result concludes consumption of the source, but is included in the result. + /// Returns a sequence that, when iterated, yields elements of the underlying sequence until the given + /// function returns , returns that element + /// and then returns no further elements (see also ). This function returns + /// at least one element of a non-empty sequence, or the empty task sequence if the input is empty. /// If is asynchronous, consider using . - /// If the final item is not desired, consider using . /// + /// + /// A function that evaluates to false when no more items should be returned. + /// The input task sequence. + /// The resulting task sequence. + /// Thrown when the input task sequence is null. val takeWhileInclusive: predicate: ('T -> bool) -> source: taskSeq<'T> -> taskSeq<'T> /// - /// Yields items from the source while the asynchronous function returns . - /// The first result concludes consumption of the source, but is included in the result. - /// If does not need to be asynchronous, consider using . - /// If the final item is not desired, consider using . + /// Returns a sequence that, when iterated, yields elements of the underlying sequence until the given + /// asynchronous function returns , returns that element + /// and then returns no further elements (see also ). This function returns + /// at least one element of a non-empty sequence, or the empty task sequence if the input is empty. + /// If is synchronous, consider using . /// + /// + /// An asynchronous function that evaluates to false when no more items should be returned. + /// The input task sequence. + /// The resulting task sequence. + /// Thrown when the input task sequence is null. val takeWhileInclusiveAsync: predicate: ('T -> #Task) -> source: taskSeq<'T> -> taskSeq<'T> /// - /// Returns a new collection containing only the elements of the collection - /// for which the given asynchronous function returns . - /// If does not need to be asynchronous, consider using . - /// - val filterAsync: predicate: ('T -> #Task) -> source: taskSeq<'T> -> taskSeq<'T> - - /// - /// Applies the given function to successive elements of the task sequence - /// in , returning the first result where the function returns . + /// Applies the given function to successive elements, returning the first result where + /// the function returns . /// If is asynchronous, consider using . /// + /// A function to transform items of type into options of type . + /// The input task sequence. + /// The chosen element or . + /// Thrown when the input task sequence is null. val tryPick: chooser: ('T -> 'U option) -> source: taskSeq<'T> -> Task<'U option> /// - /// Applies the given asynchronous function to successive elements of the task sequence - /// in , returning the first result where the function returns . - /// If does not need to be asynchronous, consider using . + /// Applies the given asynchronous function to successive elements, returning the first result where + /// the function returns . + /// If is synchronous, consider using . /// + /// An asynchronous function to transform items of type into options of type . + /// The input task sequence. + /// The chosen element or . + /// Thrown when the input task sequence is null. val tryPickAsync: chooser: ('T -> #Task<'U option>) -> source: taskSeq<'T> -> Task<'U option> /// - /// Returns the first element of the task sequence in for which the given function - /// returns . Returns if no such element exists. + /// Returns the first element for which the given function returns + /// . Returns if no such element exists. /// If is asynchronous, consider using . /// + /// + /// A function that evaluates to a when given an item in the sequence. + /// The input task sequence. + /// The found element or . + /// Thrown when the input task sequence is null. val tryFind: predicate: ('T -> bool) -> source: taskSeq<'T> -> Task<'T option> /// - /// Returns the first element of the task sequence in for which the given asynchronous function - /// returns . Returns if no such element exists. - /// If does not need to be asynchronous, consider using . + /// Returns the first element for which the given asynchronous function returns + /// . Returns if no such element exists. + /// If is synchronous, consider using . /// + /// + /// An asynchronous function that evaluates to a when given an item in the sequence. + /// The input task sequence. + /// The found element or . + /// Thrown when the input task sequence is null. val tryFindAsync: predicate: ('T -> #Task) -> source: taskSeq<'T> -> Task<'T option> /// - /// Returns the index, starting from zero, of the task sequence in for which the given function - /// returns . Returns if no such element exists. + /// Returns the index, starting from zero, for which the given function returns + /// . Returns if no such element exists. /// If is asynchronous, consider using . /// + /// + /// A function that evaluates to a when given an item in the sequence. + /// The input task sequence. + /// The found element or . + /// Thrown when the input task sequence is null. val tryFindIndex: predicate: ('T -> bool) -> source: taskSeq<'T> -> Task /// - /// Returns the index, starting from zero, of the task sequence in for which the given asynchronous function - /// returns . Returns if no such element exists. - /// If does not need to be asynchronous, consider using . + /// Returns the index, starting from zero, for which the given asynchronous function returns + /// . Returns if no such element exists. + /// If is synchronous, consider using . /// + /// + /// An asynchronous function that evaluates to a when given an item in the sequence. + /// The input task sequence. + /// The found element or . + /// Thrown when the input task sequence is null. val tryFindIndexAsync: predicate: ('T -> #Task) -> source: taskSeq<'T> -> Task /// - /// Applies the given function to successive elements of the task sequence - /// in , returning the first result where the function returns . + /// Applies the given function to successive elements, returning the first result where + /// the function returns . Throws an exception if none is found. /// If is asynchronous, consider using . - /// Thrown when every item of the sequence - /// evaluates to when the given function is applied. /// + /// + /// A function to transform items of type into options of type . + /// The input sequence. + /// The selected element. + /// Thrown when the input task sequence is null. + /// Thrown when every item of the sequence evaluates to when the given function is applied. val pick: chooser: ('T -> 'U option) -> source: taskSeq<'T> -> Task<'U> /// - /// Applies the given asynchronous function to successive elements of the task sequence - /// in , returning the first result where the function returns . - /// If does not need to be asynchronous, consider using . - /// Thrown when every item of the sequence - /// evaluates to when the given function is applied. + /// Applies the given asynchronous function to successive elements, returning the first result where + /// the function returns . Throws an exception if none is found. + /// If is synchronous, consider using . /// + /// + /// An asynchronous function to transform items of type into options of type . + /// The input sequence. + /// The selected element. + /// Thrown when the input task sequence is null. + /// Thrown when every item of the sequence evaluates to when the given function is applied. val pickAsync: chooser: ('T -> #Task<'U option>) -> source: taskSeq<'T> -> Task<'U> /// - /// Returns the first element of the task sequence in for which the given function - /// returns . + /// Returns the first element for which the given function returns . + /// Throws an exception if none is found. /// If is asynchronous, consider using . /// - /// Thrown if no element returns when - /// evaluated by the function. + /// + /// A function that evaluates to a when given an item in the sequence. + /// The input task sequence. + /// The first element for which the predicate returns . + /// Thrown when the input task sequence is null. + /// Thrown if no element returns when evaluated by the function. val find: predicate: ('T -> bool) -> source: taskSeq<'T> -> Task<'T> /// - /// Returns the first element of the task sequence in for which the given - /// asynchronous function returns . - /// If does not need to be asynchronous, consider using . + /// Returns the first element for which the given asynchronous function returns . + /// Throws an exception if none is found. + /// If is synchronous, consider using . /// - /// Thrown if no element returns when - /// evaluated by the function. + /// + /// An asynchronous function that evaluates to a when given an item in the sequence. + /// The input task sequence. + /// The first element for which the predicate returns . + /// Thrown when the input task sequence is null. + /// Thrown if no element returns when evaluated by the function. val findAsync: predicate: ('T -> #Task) -> source: taskSeq<'T> -> Task<'T> /// - /// Returns the index, starting from zero, of the first element of the task sequence in for which - /// the given function returns . + /// Returns the index, starting from zero, of the first element for which the given function + /// returns . /// If is asynchronous, consider using . /// - /// Thrown if no element returns when - /// evaluated by the function. + /// + /// A function that evaluates to a when given an item in the sequence. + /// The input task sequence. + /// The index for which the predicate returns . + /// Thrown when the input task sequence is null. + /// Thrown if no element returns when evaluated by the function. val findIndex: predicate: ('T -> bool) -> source: taskSeq<'T> -> Task /// - /// Returns the index, starting from zero, of the task sequence in for which the given - /// asynchronous function returns . - /// If does not need to be asynchronous, consider using . + /// Returns the index, starting from zero, of the first element for which the given function + /// returns . + /// If is synchronous, consider using . /// /// - /// Thrown if no element returns when - /// evaluated by the function. + /// An asynchronous function that evaluates to a when given an item in the sequence. + /// The input task sequence. + /// The index for which the predicate returns . + /// Thrown when the input task sequence is null. + /// Thrown if no element returns when evaluated by the function. val findIndexAsync: predicate: ('T -> #Task) -> source: taskSeq<'T> -> Task /// /// Tests if the sequence contains the specified element. Returns /// if contains the specified element; - /// otherwise. + /// otherwise. The input task sequence is only evaluated until the first element that matches the value. /// /// /// The value to locate in the input sequence. - /// The input sequence. - /// True if the input sequence contains the specified element; false otherwise. - /// Thrown when the input sequence is null. + /// The input task sequence. + /// if the input sequence contains the specified element; otherwise. + /// Thrown when the input task sequence is null. val contains<'T when 'T: equality> : value: 'T -> source: taskSeq<'T> -> Task /// - /// Tests if any element of the task sequence in satisfies - /// the given . - /// The function is applied to the elements of the input sequence. If any application - /// returns then the overall result is and no further elements are evaluated and tested. + /// Tests if any element of the task sequence in satisfies the given . The function + /// is applied to the elements of the input task sequence. If any application returns then the overall result + /// is and no further elements are evaluated and tested. /// Otherwise, is returned. /// /// /// A function to test each item of the input sequence. - /// The input sequence. /// - /// True if any result from the predicate is true; false otherwise. /// - /// Thrown when the input sequence is null. + /// The input task sequence. + /// if any result from the predicate is true; otherwise. + /// Thrown when the input task sequence is null. val exists: predicate: ('T -> bool) -> source: taskSeq<'T> -> Task /// - /// Tests if any element of the task sequence in satisfies - /// the given async . - /// The function is applied to the elements of the input sequence. If any application - /// returns then the overall result is and no further elements are evaluated and tested. + /// Tests if any element of the task sequence in satisfies the given asynchronous . + /// The function is applied to the elements of the input task sequence. If any application returns then the overall result + /// is and no further elements are evaluated and tested. /// Otherwise, is returned. /// /// /// A function to test each item of the input sequence. - /// The input sequence. /// - /// True if any result from the predicate is true; false otherwise. /// - /// Thrown when the input sequence is null. + /// The input task sequence. + /// if any result from the predicate is true; otherwise. + /// Thrown when the input task sequence is null. val existsAsync: predicate: ('T -> #Task) -> source: taskSeq<'T> -> Task /// /// Returns a new task sequence with the distinct elements of the second task sequence which do not appear in the - /// , using generic hash and equality comparisons to compare values. + /// sequence, using generic hash and equality comparisons to compare values. /// /// /// /// Note that this function returns a task sequence that digests the whole of the first input task sequence as soon as - /// the result sequence first gets awaited or iterated. As a result this function should not be used with + /// the resulting task sequence first gets awaited or iterated. As a result this function should not be used with /// large or infinite sequences in the first parameter. The function makes no assumption on the ordering of the first input /// sequence. /// /// /// A task sequence whose elements that also occur in the second sequence will cause those elements to be removed from the returned sequence. - /// A sequence whose elements that are not also in first will be returned. + /// The input task sequence whose elements that are not also in the first will be returned. /// A sequence that contains the set difference of the elements of two sequences. /// - /// Thrown when either of the two input sequences is null. + /// Thrown when either of the two input task sequences is null. val except<'T when 'T: equality> : itemsToExclude: taskSeq<'T> -> source: taskSeq<'T> -> taskSeq<'T> /// /// Returns a new task sequence with the distinct elements of the second task sequence which do not appear in the - /// , using generic hash and equality comparisons to compare values. + /// sequence, using generic hash and equality comparisons to compare values. /// /// /// @@ -572,29 +993,46 @@ module TaskSeq = /// /// /// A task sequence whose elements that also occur in the second sequence will cause those elements to be removed from the returned sequence. - /// A sequence whose elements that are not also in first will be returned. + /// The input task sequence whose elements that are not also in first will be returned. /// A sequence that contains the set difference of the elements of two sequences. /// - /// Thrown when either of the two input sequences is null. + /// Thrown when either of the two input task sequences is null. val exceptOfSeq<'T when 'T: equality> : itemsToExclude: seq<'T> -> source: taskSeq<'T> -> taskSeq<'T> /// - /// Zips two task sequences, returning a taskSeq of the tuples of each sequence, in order. May raise ArgumentException - /// if the sequences are or unequal length. + /// Combines the two task sequences into a new task sequence of pairs. The two sequences need not have equal lengths: + /// when one sequence is exhausted any remaining elements in the other sequence are ignored. /// - /// The sequences have different lengths. + /// + /// The first input task sequence. + /// The second input task sequence. + /// Thrown when either of the two input task sequences is null. val zip: source1: taskSeq<'T> -> source2: taskSeq<'U> -> taskSeq<'T * 'U> /// - /// Applies the function to each element in the task sequence, - /// threading an accumulator argument of type through the computation. + /// Applies the function to each element in the task sequence, threading an accumulator + /// argument of type through the computation. If the input function is and the elements are + /// then computes . /// If the accumulator function is asynchronous, consider using . /// + /// + /// A function that updates the state with each element from the sequence. + /// The initial state. + /// The input sequence. + /// The state object after the folding function is applied to each element of the sequence. + /// Thrown when the input task sequence is null. val fold: folder: ('State -> 'T -> 'State) -> state: 'State -> source: taskSeq<'T> -> Task<'State> /// - /// Applies the asynchronous function to each element in the task sequence, - /// threading an accumulator argument of type through the computation. - /// If the accumulator function does not need to be asynchronous, consider using . + /// Applies the asynchronous function to each element in the task sequence, threading an accumulator + /// argument of type through the computation. If the input function is and the elements are + /// then computes . + /// If the accumulator function is synchronous, consider using . /// + /// + /// A function that updates the state with each element from the sequence. + /// The initial state. + /// The input sequence. + /// The state object after the folding function is applied to each element of the sequence. + /// Thrown when the input task sequence is null. val foldAsync: folder: ('State -> 'T -> #Task<'State>) -> state: 'State -> source: taskSeq<'T> -> Task<'State> diff --git a/src/FSharp.Control.TaskSeq/TaskSeqInternal.fs b/src/FSharp.Control.TaskSeq/TaskSeqInternal.fs index a194c836..97712620 100644 --- a/src/FSharp.Control.TaskSeq/TaskSeqInternal.fs +++ b/src/FSharp.Control.TaskSeq/TaskSeqInternal.fs @@ -76,7 +76,7 @@ module internal TaskSeqInternal = return not step } - let singleton (source: 'T) = + let singleton (value: 'T) = { new IAsyncEnumerable<'T> with member _.GetAsyncEnumerator(_) = let mutable status = BeforeAll @@ -94,7 +94,7 @@ module internal TaskSeqInternal = member _.Current: 'T = match status with - | WithCurrent -> source + | WithCurrent -> value | _ -> Unchecked.defaultof<'T> member _.DisposeAsync() = ValueTask.CompletedTask