extra/lists/lazy/lazy-docs.factor

   1 ! Copyright (C) 2006 Chris Double.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3
   4 USING: help.markup help.syntax sequences strings lists ;
   5 IN: lists.lazy
   6
   7 HELP: lazy-cons
   8 { $values { "car" "a quotation with stack effect ( -- X )" } { "cdr" "a quotation with stack effect ( -- cons )" } { "promise" "the resulting cons object" } }
   9 { $description "Constructs a cons object for a lazy list from two quotations. The " { $snippet "car" } " quotation should return the head of the list, and the " { $snippet "cons" } " quotation the tail when called. When " { $link cons } " or " { $link cdr } " are called on the lazy-cons object then the appropriate quotation is called." }
  10 { $see-also cons car cdr nil nil? } ;
  11
  12 { 1lazy-list 2lazy-list 3lazy-list } related-words
  13
  14 HELP: 1lazy-list
  15 { $values { "a" "a quotation with stack effect ( -- X )" } { "lazy-cons" "a lazy-cons object" } }
  16 { $description "Create a lazy list with 1 element. The element is the result of calling the quotation. The quotation is only called when the list element is requested." } ;
  17
  18 HELP: 2lazy-list
  19 { $values { "a" "a quotation with stack effect ( -- X )" } { "b" "a quotation with stack effect ( -- X )" } { "lazy-cons" "a lazy-cons object" } }
  20 { $description "Create a lazy list with 2 elements. The elements are the result of calling the quotations. The quotations are only called when the list elements are requested." } ;
  21
  22 HELP: 3lazy-list
  23 { $values { "a" "a quotation with stack effect ( -- X )" } { "b" "a quotation with stack effect ( -- X )" } { "c" "a quotation with stack effect ( -- X )" } { "lazy-cons" "a lazy-cons object" } }
  24 { $description "Create a lazy list with 3 elements. The elements are the result of calling the quotations. The quotations are only called when the list elements are requested." } ;
  25
  26 HELP: <memoized-cons>
  27 { $values { "cons" "a cons object" } { "memoized-cons" "the resulting memoized-cons object" } }
  28 { $description "Constructs a cons object that wraps an existing cons object. Requests for the car, cdr and nil? will be remembered after the first call, and the previous result returned on subsequent calls." }
  29 { $see-also cons car cdr nil nil? } ;
  30
  31 HELP: lnth
  32 { $values { "n" "an integer index" } { "list" "a cons object" } { "elt" "the element at the nth index" } }
  33 { $description "Outputs the nth element of the list." }
  34 { $see-also llength cons car cdr } ;
  35
  36 HELP: llength
  37 { $values { "list" "a cons object" } { "n" "a non-negative integer" } }
  38 { $description "Outputs the length of the list. This should not be called on an infinite list." }
  39 { $see-also lnth cons car cdr } ;
  40
  41 HELP: uncons
  42 { $values { "cons" "a cons object" } { "car" "the head of the list" } { "cdr" "the tail of the list" } }
  43 { $description "Put the head and tail of the list on the stack." } ;
  44
  45 { leach lreduce lmap lmap-with ltake lfilter lappend lfrom lfrom-by lconcat lcartesian-product lcartesian-product* lcomp lcomp* lmerge lreduce lwhile luntil } related-words
  46
  47 HELP: leach
  48 { $values { "list" "a cons object" } { "quot" "a quotation with stack effect ( obj -- )" } }
  49 { $description "Call the quotation for each item in the list." } ;
  50
  51 HELP: lreduce
  52 { $values { "list" "a cons object" } { "identity" "an object" } { "quot" "a quotation with stack effect ( prev elt -- next )" } { "result" "the final result" } }
  53 { $description "Combines successive elements of the list using a binary operation, and outputs the final result." } ;
  54
  55 HELP: lmap
  56 { $values { "list" "a cons object" } { "quot" "a quotation with stack effect ( obj -- X )" } { "result" "resulting cons object" } }
  57 { $description "Perform a similar functionality to that of the " { $link map } " word, but in a lazy manner. No evaluation of the list elements occurs initially but a " { $link <lazy-map> } " object is returned which conforms to the list protocol. Calling " { $link car } ", " { $link cdr } " or " { $link nil? } " on this will evaluate elements as required." } ;
  58
  59 HELP: lmap-with
  60 { $values { "value" "an object" } { "list" "a cons object" } { "quot" "a quotation with stack effect ( obj elt -- X )" } { "result" "resulting cons object" } }
  61 { $description "Variant of " { $link lmap } " which pushes a retained object on each invocation of the quotation." } ;
  62
  63 HELP: ltake
  64 { $values { "n" "a non negative integer" } { "list" "a cons object" } { "result" "resulting cons object" } }
  65 { $description "Outputs a lazy list containing the first n items in the list. This is done a lazy manner. No evaluation of the list elements occurs initially but a " { $link <lazy-take> } " object is returned which conforms to the list protocol. Calling " { $link car } ", " { $link cdr } " or " { $link nil? } " on this will evaluate elements as required." } ;
  66
  67 HELP: lfilter
  68 { $values { "list" "a cons object" } { "quot" "a quotation with stack effect ( -- X )" } { "result" "resulting cons object" } }
  69 { $description "Perform a similar functionality to that of the " { $link filter } " word, but in a lazy manner. No evaluation of the list elements occurs initially but a " { $link <lazy-filter> } " object is returned which conforms to the list protocol. Calling " { $link car } ", " { $link cdr } " or " { $link nil? } " on this will evaluate elements as required." } ;
  70
  71 HELP: lwhile
  72 { $values { "list" "a cons object" } { "quot" "a quotation with stack effect ( X -- bool )" } { "result" "resulting cons object" } }
  73 { $description "Outputs a lazy list containing the first items in the list as long as " { $snippet "quot" } " evaluates to t. No evaluation of the list elements occurs initially but a " { $link <lazy-while> } " object is returned with conforms to the list protocol. Calling " { $link car } ", " { $link cdr } " or " { $link nil? } " on this will evaluate elements as required." } ;
  74
  75 HELP: luntil
  76 { $values { "list" "a cons object" } { "quot" "a quotation with stack effect ( X -- bool )" } { "result" "resulting cons object" } }
  77 { $description "Outputs a lazy list containing the first items in the list until after " { $snippet "quot" } " evaluates to t. No evaluation of the list elements occurs initially but a " { $link <lazy-while> } " object is returned with conforms to the list protocol. Calling " { $link car } ", " { $link cdr } " or " { $link nil? } " on this will evaluate elements as required." } ;
  78
  79 HELP: list>vector
  80 { $values { "list" "a cons object" } { "vector" "the list converted to a vector" } }
  81 { $description "Convert a list to a vector. If the list is a lazy infinite list then this will enter an infinite loop." }
  82 { $see-also list>array } ;
  83
  84 HELP: list>array
  85 { $values { "list" "a cons object" } { "array" "the list converted to an array" } }
  86 { $description "Convert a list to an array. If the list is a lazy infinite list then this will enter an infinite loop." }
  87 { $see-also list>vector } ;
  88
  89 HELP: lappend
  90 { $values { "list1" "a cons object" } { "list2" "a cons object" } { "result" "a lazy list of list2 appended to list1" } }
  91 { $description "Perform a similar functionality to that of the " { $link append } " word, but in a lazy manner. No evaluation of the list elements occurs initially but a " { $link <lazy-append> } " object is returned which conforms to the list protocol. Calling " { $link car } ", " { $link cdr } " or " { $link nil? } " on this will evaluate elements as required. Successive calls to " { $link cdr } " will iterate through list1, followed by list2." } ;
  92
  93 HELP: lfrom-by
  94 { $values { "n" "an integer" } { "quot" "a quotation with stack effect ( -- int )" } { "list" "a lazy list of integers" } }
  95 { $description "Return an infinite lazy list of values starting from n, with each successive value being the result of applying quot to n." } ;
  96
  97 HELP: lfrom
  98 { $values { "n" "an integer" } { "list" "a lazy list of integers" } }
  99 { $description "Return an infinite lazy list of incrementing integers starting from n." } ;
 100
 101 HELP: seq>list
 102 { $values { "index" "an integer 0 or greater" } { "seq" "a sequence" } { "list" "a list" } }
 103 { $description "Convert the sequence into a list, starting from the 'index' offset into the sequence." }
 104 { $see-also >list } ;
 105
 106 HELP: >list
 107 { $values { "object" "an object" } { "list" "a list" } }
 108 { $description "Convert the object into a list. Existing lists are passed through intact, sequences are converted using " { $link seq>list } " and other objects cause an error to be thrown." }
 109 { $see-also seq>list } ;
 110
 111 HELP: lconcat
 112 { $values { "list" "a list of lists" } { "result" "a list" } }
 113 { $description "Concatenates a list of lists together into one list." } ;
 114
 115 HELP: lcartesian-product
 116 { $values { "list1" "a list" } { "list2" "a list" } { "result" "list of cartesian products" } }
 117 { $description "Given two lists, return a list containing the cartesian product of those lists." } ;
 118
 119 HELP: lcartesian-product*
 120 { $values { "lists" "a list of lists" } { "result" "list of cartesian products" } }
 121 { $description "Given a list of lists, return a list containing the cartesian product of those lists." } ;
 122
 123 HELP: lcomp
 124 { $values { "list" "a list of lists" } { "quot" "a quotation with stack effect ( seq -- X )" } { "result" "the resulting list" } }
 125 { $description "Get the cartesian product of the lists in " { $snippet "list" } " and call " { $snippet "quot" } " call with each element from the cartesian product on the stack, the result of which is returned in the final " { $snippet "list" } "." } ;
 126
 127 HELP: lcomp*
 128 { $values { "list" "a list of lists" } { "guards" "a sequence of quotations with stack effect ( seq -- bool )" } { "quot" "a quotation with stack effect ( seq -- X )" } { "list" "the resulting list" } { "result" "a list" } }
 129 { $description "Get the cartesian product of the lists in " { $snippet "list" } ", filter it by applying each guard quotation to it and call " { $snippet "quot" } " call with each element from the remaining cartesian product items on the stack, the result of which is returned in the final " { $snippet "list" } "." }
 130 { $examples
 131   { $code "{ 1 2 3 } >list { 4 5 6 } >list 2list { [ first odd? ] } [ first2 + ] lcomp*" }
 132 } ;
 133
 134 HELP: lmerge
 135 { $values { "list1" "a list" } { "list2" "a list" } { "result" "lazy list merging list1 and list2" } }
 136 { $description "Return the result of merging the two lists in a lazy manner." }
 137 { $examples
 138   { $example "USING: lazy-lists prettyprint ;" "{ 1 2 3 } >list { 4 5 6 } >list lmerge list>array ." "{ 1 4 2 5 3 6 }" }
 139 } ;
 140
 141 HELP: lcontents
 142 { $values { "stream" "a stream" } { "result" string } }
 143 { $description "Returns a lazy list of all characters in the file. " { $link car } " returns the next character in the file, " { $link cdr } " returns the remaining characters as a lazy list. " { $link nil? } " indicates end of file." }
 144 { $see-also llines } ;
 145
 146 HELP: llines
 147 { $values { "stream" "a stream" } { "result" "a list" } }
 148 { $description "Returns a lazy list of all lines in the file. " { $link car } " returns the next lines in the file, " { $link cdr } " returns the remaining lines as a lazy list. " { $link nil? } " indicates end of file." }
 149 { $see-also lcontents } ;
 150