*vital/Data/LazyList.txt*	lazy list including file io.

Maintainer: ujihisa <ujihisa at gmail com>

==============================================================================
CONTENTS			*Vital.Data.LazyList-contents*

INTRODUCTION			|Vital.Data.LazyList-introduction|
  USAGE				|Vital.Data.LazyList-usage|
INTERFACE			|Vital.Data.LazyList-interface|
  FUNCTIONS			  |Vital.Data.LazyList-functions|
INTERNAL			|Vital.Data.LazyList-internal|
  DATA STRUCTURE		  |Vital.Data.LazyList-datastructure|

==============================================================================
INTRODUCTION			*Vital.Data.LazyList-introduction*

*Vital.Data.LazyList* is TODO

==============================================================================
USAGE				*Vital.Data.LazyList-usage*
>
	let s:L = vital#{plugin-name}#new().import('Data.LazyList')
	let xs = s:L.file_readlines('/tmp/a.txt')
	let xs = s:L.map(xs, 'split(v:val, ":")')
	let xs = s:L.filter(xs, 'v:val[1] < 3')
	echo s:L.take(3, xs)
<

==============================================================================
INTERFACE			*Vital.Data.LazyList-interface*

------------------------------------------------------------------------------
FUNCTIONS			*Vital.Data.LazyList-functions*

from_list({list})		*Vital.Data.LazyList.from_list()*
	Constructs lazy list based on given |List| {list}.

iterate({init}, {f})		*Vital.Data.LazyList.iterate()*
	Constructs lazy list based on given initial value {init} and a
	function {f} to make new item of lazy list based on previous value,
	described in |String|.
>
	:echo L.take(3, L.iterate(0, 'v:val + 1'))
	[0, 1, 2]
	:echo L.take(3, L.filter(L.iterate(0, 'v:val + 1'), 'v:val % 2 == 0'))
	[0, 2, 4]
<

file_readlines({fname})		*Vital.Data.LazyList.file_readlines()*
	Constructs lazy list based on given filename |String| {fname}.
	This function requires |vimproc|.

	For example, the following line of code will read first 4 lines from
	the given file "/tmp/a.txt".
>
	L.take(4, L.file_readlines('/tmp/a.txt'))
<

take({n}, {xs})			*Vital.Data.LazyList.take()*
	De-constructs from lazy list {xs} to |List|, but the length will be at
	most {n}.
	See other functions such as |Vital.Data.LazyList.iterate()| for sample
	use case.

	You may get confused by the order of arguments, but it's on purpose.

zip({xs}, {ys})			*Vital.Data.LazyList.zip()*
	Constructs a new lazy list based on given 2 lazy lists {xs} and {ys}.
>
	:let xs = L.from_list([3, 1, 4])
	:let ys = L.from_list(['a', 'b', 'c'])
	:echo L.take(3, L.zip(L.map(xs, 'v:val + 1'), ys))
	[[4, 'a'], [2, 'b'], [5, 'c']]
<
filter({xs}, {string})			*Vital.Data.LazyList.filter()*

map({xs}, {string})			*Vital.Data.LazyList.map()*


==============================================================================
INTERNAL			*Vital.Data.LazyList-internal*

------------------------------------------------------------------------------
DATA STRUCTURE			*Vital.Data.LazyList-datastructure*

	This section is only for deep understanding of lazy list
	implementation just for  debugging / developing this library itself.
	Any application code should not depend on its internal data structure
	since vital developers may make changes without explicitly telling.

>
	:echo L.from_list([3, 1, 4])
	[[], {'list': [3, 1, 4], 'run': function('<SNR>385__f_from_list')}]
<
	A lazy list is a tuple (a 2-item |List|).  The left side is registered
	functions to apply when you take items from the lazy list. Each item
	is a string which has "v:val" that returns an empty list or a list
	which only has 1 item if you |eval()| it. The right side is a
	|Dictionary| which either at least has "run" key where the value is a
	|Funcref| or an empty dict {} which means the end of the lazy list.
	This is for generating an item and upcoming uncalculated next items.

==============================================================================
vim:tw=78:fo=tcq2mM:ts=8:ft=help:norl
