extra/lists/lists-docs.factor

   1 ! Copyright (C) 2006 Chris Double.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: kernel help.markup help.syntax ;
   4
   5 IN: lists
   6
   7 { car cons cdr nil nil? list? uncons } related-words
   8
   9 HELP: cons
  10 { $values { "car" "the head of the lazy list" } { "cdr" "the tail of the lazy list" } { "cons" "a cons object" } }
  11 { $description "Constructs a cons cell." } ;
  12
  13 HELP: car
  14 { $values { "cons" "a cons object" } { "car" "the first item in the list" } }
  15 { $description "Returns the first item in the list." } ;
  16
  17 HELP: cdr
  18 { $values { "cons" "a cons object" } { "cdr" "a cons object" } }
  19 { $description "Returns the tail of the list." } ;
  20
  21 HELP: nil
  22 { $values { "symbol" "The empty cons (+nil+)" } }
  23 { $description "Returns a symbol representing the empty list" } ;
  24
  25 HELP: nil?
  26 { $values { "object" object } { "?" "a boolean" } }
  27 { $description "Return true if the cons object is the nil cons." } ;
  28
  29 HELP: list? ( object -- ? )
  30 { $values { "object" "an object" } { "?" "a boolean" } }
  31 { $description "Returns true if the object conforms to the list protocol." } ;
  32
  33 { 1list 2list 3list } related-words
  34
  35 HELP: 1list
  36 { $values { "obj" "an object" } { "cons" "a cons object" } }
  37 { $description "Create a list with 1 element." } ;
  38
  39 HELP: 2list
  40 { $values { "a" "an object" } { "b" "an object" } { "cons" "a cons object" } }
  41 { $description "Create a list with 2 elements." } ;
  42
  43 HELP: 3list
  44 { $values { "a" "an object" } { "b" "an object" } { "c" "an object" } { "cons" "a cons object" } }
  45 { $description "Create a list with 3 elements." } ;
  46
  47 HELP: lnth
  48 { $values { "n" "an integer index" } { "list" "a cons object" } { "elt" "the element at the nth index" } }
  49 { $description "Outputs the nth element of the list." }
  50 { $see-also llength cons car cdr } ;
  51
  52 HELP: llength
  53 { $values { "list" "a cons object" } { "n" "a non-negative integer" } }
  54 { $description "Outputs the length of the list. This should not be called on an infinite list." }
  55 { $see-also lnth cons car cdr } ;
  56
  57 HELP: uncons
  58 { $values { "cons" "a cons object" }  { "cdr" "the tail of the list" } { "car" "the head of the list" } }
  59 { $description "Put the head and tail of the list on the stack." } ;
  60
  61 { leach foldl lmap>array } related-words
  62
  63 HELP: leach
  64 { $values { "list" "a cons object" } { "quot" { $quotation "( obj -- )" } } }
  65 { $description "Call the quotation for each item in the list." } ;
  66
  67 HELP: foldl
  68 { $values { "list" "a cons object" } { "identity" "an object" } { "quot" { $quotation "( prev elt -- next )" } } { "result" "the final result" } }
  69 { $description "Combines successive elements of the list (in a left-assocative order) using a binary operation and outputs the final result." } ;
  70
  71 HELP: foldr
  72 { $values { "list" "a cons object" } { "identity" "an object" } { "quot" { $quotation "( prev elt -- next )" } } { "result" "the final result" } }
  73 { $description "Combines successive elements of the list (in a right-assocative order) using a binary operation, and outputs the final result." } ;
  74
  75 HELP: lmap
  76 { $values { "list" "a cons object" } { "quot" { $quotation "( old -- new )" } } { "result" "the final result" } }
  77 { $description "Applies the quotation to each element of the list in order, collecting the new elements into a new list." } ;
  78
  79 HELP: lreverse
  80 { $values { "list" "a cons object" } { "newlist" "a new cons object" } }
  81 { $description "Reverses the input list, outputing a new, reversed list" } ;
  82
  83 HELP: list>seq
  84 { $values { "list" "a cons object" } { "array" "an array object" } }
  85 { $description "Turns the given cons object into an array, maintaing order." } ;
  86
  87 HELP: seq>list
  88 { $values { "seq" "a sequence" } { "list" "a cons object" } }
  89 { $description "Turns the given array into a cons object, maintaing order." } ;
  90
  91 HELP: cons>seq
  92 { $values { "cons" "a cons object" } { "array" "an array object" } }
  93 { $description "Recursively turns the given cons object into an array, maintaing order and also converting nested lists." } ;
  94
  95 HELP: seq>cons
  96 { $values { "seq" "a sequence object" } { "cons" "a cons object" } }
  97 { $description "Recursively turns the given sequence into a cons object, maintaing order and also converting nested lists." } ;
  98
  99 HELP: traverse
 100 { $values { "list"  "a cons object" } { "pred" { $quotation "( list/elt -- ? )" } }
 101           { "quot" { $quotation "( list/elt -- result)" } }  { "result" "a new cons object" } }
 102 { $description "Recursively traverses the list object, replacing any elements (which can themselves be sublists) that pred"
 103     " returns true for with the result of applying quot to." } ;
 104