package orsetto

A generic type to indicate whether an event sequence is A) ready to produce another step or B) finished with all production.

Use repeat v to make a sequence that always produces v. (finite, concurrently persistent, exception safe)

Use compose f i to make a sequence that encloses the composing function f and the initial cursor i. On each step of the sequence, the current cursor is applied to f and if Some (i, _ as v) is returned the step is P (v, compose f i), otherwise if None is returned, then the step is Z.

Accordingly, if applying f never returns None then the resulting sequence is an infinite sequence, and otherwise if f is guaranteed eventually to return None then the resulting sequence is a finite sequence. If neither is guaranteed by f, then the resulting sequence is a contextually limited sequence.

The result is a concurrently persistent sequence only if s is immutable and f is pure, i.e. it has no side effects.

The result is exception safe if f never raises an exception.

Use zipcompose f i to make a sequence as with compose, but zipped at each step with the current cursor value.

Use range a b to make a sequence that produces on each successive step the integers starting at a and ending at b, thereafter produces no further values. If b < a then Invalid_argument is raised immediately. (finite, concurrently persistent, exception safe)

Use of_option s to make a sequence equivalent to match p with None -> nil | Some v -> one v. (finite, concurrently persistent, exception safe)

Use of_list s to make a sequence that produces each value in s beginning at the head. At each successive step only the remaining elements of the list are enclosed in the sequence. (finite, concurrently persistent, exception safe)

Use of_subbytes b pos len to make a sequence that produces each of the len bytes in b starting at position pos, one by one on each successive step. Immediately raises Invalid_argument if b does not contain at least len bytes starting at position pos. A reference to b is retained until the final step of the sequence. (finite, exception safe)

Use of_bytes b to make a sequence that produces each of the bytes in b one by one on each successive step. A reference to b is retained until the final step of the sequence. (finite, exception safe)

Use of_substring s pos len to make a sequence that operates like of_subbytes does but using input of type string instead of bytes. (finite, concurrently persistent, exception safe)

Use of_string s to make a sequence that operates like of_bytes does but using input of type string instead of bytes. (finite, concurrently persistent, exception safe)

Use of_subarray a pos len to make a sequence that produces each of the len values in a starting at position pos, one by one on each successive step. Immediately raises Invalid_argument if a not contain at least len values starting at position pos. A reference to a is retained until the final step of the sequence. (finite, exception safe)

Use of_array a to make a sequence that produces each of the values in a one by one on each successive step. A reference to a is retained until the final step of the sequence. (finite, exception safe)

Use of_channel inc to make a contextually limited sequence that produces each byte by reading them on successive steps from the input channel inc, and by catching the End_of_file exception that signals no further bytes can be produced. A reference to inc is retained until the final step of the sequence.

If reading from inc is guaranteed eventually to raise End_of_file then the result is a finite sequence. The result is not confluently persistent because reading from a channel is a side effect. The result is also not exception safe because reading an I/O channel can raise the Sys_error exception.

Use of_buffered_channel n inc is an efficient shortcut implementation of of_channel inc |> buffermap n. See buffermap below.

Use cons v s to compose a sequence that produces v followed by the sequence s. (Compare to

ist.cons

in the standard library.)

Use exnsafe s to make an exception safe transformer that progressively tries to consume a value v from s and produces Ok v, unless an exception x is caught, in which case produces Error x before terminating.

Use peek s to make a transformer that progressively consumes from s an additional value ahead of the one it produces, which is annotated with Rdy if it can produce further values and Fin if no further values can be produced.

The result is finite, infinite or contextually limited according to whether s is finite, infinite or contextually limited.

Use optlift s to make an infinite transformer that progressively tries to consume a value v from s at each step, and produces Some v if possible. Otherwise, discards s and produces None every time thereafter.

Use optdown s to make a contextually limited transformer that progressively produces each value v while Some v is produced by s. Upon the first None produced by s, the result terminates.

Use limit n s to make a finite transformer that produces only the first n values consumed from s.

Use concat s1 s2 to make a transformer that first produces all the values consumed from s1, then all the values consumed from s2.

If both s1 and s2 are finite, then the result is finite. If either s1 or s2 is infinite, then the result is infinite. If s1 is infinite, then s2 will never be evaluated, yet its enclosing state will remain live until the resulting sequence is discarded.

Use buffermap n s to make a transformer that conceptually encloses a buffer b of size n, adding characters consumed from s to produce a persistent sequence of strings of size n. (The last string in the resulting sequence is of non-zero length less than or equal to n.)

Use zip s1 s2 to make a transformer that produces pairs of values (a, b) by first consuming a from s1, then consuming b from s2. If either s1 or s2 terminates, the remaining values of the unterminated sequence are discarded.

If either s1 or s2 is finite, then the result is finite, else if both s1 and s2 are infinite, then the result is infinite. Otherwise, neither s1 nor s2 is finite, and one or both of s1 and s2 are contextually limited, therefore the result is contextually limited.

Use persist s to make a confluently persistent transformer that produces values lazily consumed from a volatile sequence s.

Use gate g s to make a transformer that precedes each consumption of s by calling g#syn and follows each consumption by calling g#fin.

Use join s to make a sequence that produces its values by consuming them in turn from each sequence produced by s.

If s and all of the sequences it produces are finite, then the result is finite. If either p or any of the sequences it produces are infinite, then the result is infinite. Otherwise, the result is contextually limited.

Use unzip s as an abbreviation of map fst s, map snd s. Consuming each resulting stream entails consuming s independently. If s is not a confluently persistent stream, then only one of the results may safely be consumed. If s is not a concurrently persistent stream, then both results may only be consumed in the same thread of execution.

Use run s to consume and ignore all the values from s. Neverreturns if s never termiantes.

Use empty s to attempt to consume and discard a value. Returns false if successful, otherwise returns true.

Use tryopt s to obtain Some v if a value is produced by s and otherwise None.

Use head s to obtain the first value produced by s. Raises Not_found if no value is produced.

Use tail s to discard the first value produced by s returning the sequence of remaining values. Raises Not_found if no value is produced. The result has the same limitation and persistence properties as s does.

Use length s to consume and ignore all the values from s and return the number of values produced. Never returns if s never terminates.

Use canshift n s to consume and ignore the next n values from s. Returns false if s has fewer than n values. Otherwise returns true. Raises Invalid_argument if n < 0.

Use shift n s to make a sequence that starts after consuming the next n values from s. Raises Invalid_argument if n < 0. The result has the same limitation and persistence properties as s does.

Use predicate f s to consume values v from s while f v is true. Returns false on the first step that f v is false. Otherwise, if s is finite, then returns true. Never returns if s does not terminate, and applying f never returns false.

Use memf f v s to consume values v' from s until the first step is encountered from which eq v v' returns true. Returns false if the sequence is exhausted before f returns true, otherwise returns true.

Use mem v s as an abbreviation for memf Pervasives.(=) v s.

Use find f s to consume values v from s until the first step is encountered for which f v returns true, returning v. Raises Not_found if s is exhausted before f returns true.

Use search f s to consume values v from s until the first step is encountered for which f v returns false. Returns None if f returns false for every step in the sequence. Otherwise, returns Some (v, s') where s' is the sequence of the remaining steps. Never returns if s does not terminate, and applying f never returns true. When the result is Some (_, s'), the sequence s' has the same limitation and persistence properties as s does.

Use searchmap f s to consume values v from s until the first step is encountered for which f v returns Some v. Returns None if f returns None for every step in the sequence. Otherwise, returns Some (v, s') where s' is the sequence of the remaining steps. Never returns if s does not terminate, and applying f always returns None. When the result is Some (_, s'), the sequence p' has the same limitation and persistence properties as s does.

Use eqf f s1 s2 with an equality comparison function f to compare sequences s1 and s2.

Returns true if both s1 and s2 terminate at the same step. Returns false if either s1 or s2 terminates before the other.

Returns false on the first step where v1 consumed from s1 and v2 is consumed from s2, and the result r of applying f v1 v2 isfalse.

Never returns if neither s1 nor s2 terminate and f v1 v2 always returns true.

Use cmpf f s1 s2 with a total ordering function f to compare the sequences s1 and s2.

Returns 0 if both s1 and s2 terminate at the same step. Returns -1 if s1 terminates before s2 does. Returns 1 if s2 terminates before s1 does.

On the first step where v1 consumed from s1 and v2 is consumed from s2, and the result r of applying f v1 v2 is not zero, returns r.

Never returns if neither s1 nor s2 terminate and f v1 v2 always returns 0.

Use equal s1 s2 as an abbreviation for eqf Pervasives.equal s1 s2.

Use compare s1 s2 as an abbreviation for cmpf Pervasives.compare s1 s2.

Use phyeq s1 s2 as an abbreviation for eqf (==) s1 s2.

Use reverse s to produce a list of the all values, in reverse order, of that consumed from the finite sequence s. Never returns and exhausts all memory if s never terminates.

Use to_list s as an abbreviation for reverse p |> List.rev.

Use to_array n s to make an array comprising the first n values in the sequence s. Raises Failure if s terminates before all n elements are consumed.

Use to_buffer b s to consume all the characters in the finite sequence s and add them in sequence to the buffer b. Note well: if s is not finite, then to_buffer may exhaust all available memory.

Use to_channel outc s to consume all the bytes from the sequence s and write them to the standard output channel outc. Note well: if s is not finite and outc is a communication channel that never closes, then to_channel may never terminate.

Use to_string n s to make a string comprising all the bytes in the finite sequence s. Raises Failure if s terminates before all n elements are consumed.

Use to_bytes s to produce a mutable byte array containing all the characters produced by the finite sequence s. Raises Failure if s terminates before all n elements are consumed.

Use to_subarray a pos len s to consume values from s and copy them into the mutable slice of the array a from position pos with length len, raising Invalid_argument if the position and length do not specify a valid slice. Raises Failure if the sequence does not provide enough values to fill the slice specified.

Use to_subbytes b pos len s to consume characters from s and copy them into the mutable slice of the bytes b from position pos with length len, raising Invalid_argument if the position and length do not specify a valid slice. Raises Failure if the sequence does not provide enough values to fill the slice specified.

Use string_pipe f s to apply f to the sequence of characters in s and consume the result to produce a new string.

Use bytes_pipe f s to apply f to the sequence of characters in s and consume the result to produce a new bytes array.

Use array_pipe f a to apply f to the sequence of values in a and consume the result to produce a new array.