extra/sequences/extras/extras-docs.factor

   1 USING: help.markup help.syntax kernel math sequences ;
   2 IN: sequences.extras
   3
   4 HELP: 2count
   5 { $values
   6     { "seq1" sequence }
   7     { "seq2" sequence }
   8     { "quot" { $quotation ( ... elt1 elt2 -- ... ? ) } }
   9     { "n" integer } }
  10 { $description "Efficiently counts how many pairwise elements of " { $snippet "seq1" } " and " { $snippet "seq2" } " that the predicate quotation matches." }
  11 { $examples
  12     { $example "USING: kernel prettyprint sequences.extras ;" "{ 1 2 3 } { 3 2 1 } [ = ] 2count ." "1" } }
  13 { $see-also count } ;
  14
  15 HELP: 2each-index
  16 { $values
  17     { "seq1" sequence }
  18     { "seq2" sequence }
  19     { "quot" { $quotation ( ... elt1 elt2 index -- ... ) } } }
  20 { $description "Applies " { $snippet "quot" } " to each pair of elements from " { $snippet "seq1" } " and " { $snippet "seq2" } ", providing the index of the elements at the top of the stack." }
  21 { $see-also 2each each-index } ;
  22
  23 HELP: 2map!
  24 { $values
  25     { "seq1" sequence }
  26     { "seq2" sequence }
  27     { "quot" { $quotation ( ... elt1 elt2 -- ... newelt ) } } }
  28 { $description "Applies the quotation to each pair of elements from " { $snippet "seq1" } " and " { $snippet "seq2" } ", yielding a new element, and storing it back into " { $snippet "seq1" } ".  Returns " { $snippet "seq1" } "." }
  29 { $see-also 2map map! } ;
  30
  31 HELP: 2map-index
  32 { $values
  33     { "seq1" sequence }
  34     { "seq2" sequence }
  35     { "quot" { $quotation ( ... elt1 elt2 index -- ... newelt ) } }
  36     { "newseq" sequence } }
  37 { $description "Calls the quotation with each pair of elements of the two sequences and their index on the stack, with the index on the top of the stack.  Collects the outputs of the quotation and outputs them into a new sequence of the same type as the first sequence." }
  38 { $see-also 2map map-index } ;
  39
  40 HELP: count*
  41 { $values
  42     { "seq" sequence }
  43     { "quot" { $quotation ( ... elt -- ... ? ) } }
  44     { "%" rational } }
  45 { $description "Outputs the fraction of elements in the sequence for which the predicate quotation matches." }
  46 { $examples { $example "USING: math math.ranges prettyprint sequences.extras ;" "100 [1,b] [ even? ] count* ." "1/2" } } ;
  47
  48 HELP: collapse
  49 { $values
  50     { "seq" sequence }
  51     { "quot" { $quotation ( ... elt -- ... ? ) } }
  52     { "elt" object }
  53     { "seq'" sequence } }
  54 { $description "Generate a new sequence where all runs of elements for which the predicate returns true are replaced by a single instance of " { $snippet "elt" } "." }
  55 { $see-also compact }
  56 { $examples
  57     "Collapse multiple spaces in a string down to a single space"
  58     { $example "USING: kernel prettyprint sequences.extras ;" "\"   Hello,    crazy    world   \" [ CHAR: \\s = ] \" \" collapse ." "\" Hello, crazy world \"" } } ;
  59
  60 HELP: compact
  61 { $values
  62     { "seq" sequence }
  63     { "quot" { $quotation ( ... elt -- ... ? ) } }
  64     { "elt" object }
  65     { "seq'" sequence } }
  66 { $description "Generate a new sequence where all runs of elements for which the predicate returns true are replaced by a single instance of " { $snippet "elt" } ".  Runs at the beginning or end of the sequence for which the predicate returns true are removed." }
  67 { $see-also collapse }
  68 { $examples
  69     "Collapse multiple spaces in a string down to a single space"
  70     { $example "USING: kernel prettyprint sequences.extras ;" "\"   Hello,    crazy    world   \" [ CHAR: \\s = ] \" \" compact ." "\"Hello, crazy world\"" } } ;
  71
  72 HELP: combos
  73 { $values
  74     { "list1" sequence }
  75     { "list2" sequence }
  76     { "result" sequence } }
  77 { $description "Returns all combinations of the first sequence with the second sequence.  The result is not uniquified: if the sequences contain duplicate elements, then the same pair may appear multiple times in the result sequence." } ;
  78
  79 HELP: <evens>
  80 { $values { "seq" sequence } { "evens" evens } }
  81 { $description "Create a virtual sequence whose elements consist of the even-indexed elements from the original sequence." }
  82 { $notes "Because sequences are zero-indexed, this collection includes the first, third, fifth, etc. elements of the actual sequence which can be counterintuitive." }
  83 { $see-also <odds> } ;
  84
  85 HELP: find-all
  86 { $values
  87     { "seq" sequence }
  88     { "quot" { $quotation ( elt -- ? ) } }
  89     { "elts" "the indices of the matching elements" } }
  90 { $description "Similar to " { $link find } ", but finds all of the indices and elements that match the provided quotation, not just the first." }
  91 { $notes "The result is provided as an array of arrays, whose first value is the index and whose second value is teh element." } ;
  92
  93 HELP: first=
  94 { $values
  95     { "seq" sequence }
  96     { "elt" object }
  97     { "?" boolean } }
  98 { $description "Checks whether the first element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
  99
 100 HELP: first?
 101 { $values
 102     { "seq" sequence }
 103     { "quot" { $quotation ( ... elt -- ... ? ) } }
 104     { "?" boolean } }
 105 { $description "Tests whether the first element of " { $snippet "seq" } " satisfies the provided predicate." } ;
 106
 107 HELP: fourth=
 108 { $values
 109     { "seq" sequence }
 110     { "elt" object }
 111     { "?" boolean } }
 112 { $description "Checks whether the fourth element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
 113
 114 HELP: fourth?
 115 { $values
 116     { "seq" sequence }
 117     { "quot" { $quotation ( ... elt -- ... ? ) } }
 118     { "?" boolean } }
 119 { $description "Tests whether the fourth element of " { $snippet "seq" } " satisfies the provided predicate." } ;
 120
 121 HELP: <odds>
 122 { $values { "seq" sequence } { "odds" odds } }
 123 { $description "Create a virtual sequence whose elements consist of the odd-indexed elements from the original sequence." }
 124 { $notes "Because sequences are zero-indexed, this collection includes the second, fourth, sixth, etc. elements of the actual sequence which can be counterintuitive." }
 125 { $see-also <evens> } ;
 126
 127 HELP: >resizable
 128 { $values { "seq" sequence } { "accum" sequence } }
 129 { $description "Converts a sequence into the nearest resizable equivalent, preserving its contents." } ;
 130
 131 HELP: second=
 132 { $values
 133     { "seq" sequence }
 134     { "elt" object }
 135     { "?" boolean } }
 136 { $description "Checks whether the second element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
 137
 138 HELP: second?
 139 { $values
 140     { "seq" sequence }
 141     { "quot" { $quotation ( ... elt -- ... ? ) } }
 142     { "?" boolean } }
 143 { $description "Tests whether the second element of " { $snippet "seq" } " satisfies the provided predicate." } ;
 144
 145 HELP: subseq*
 146 { $values
 147      { "from" integer } { "to" integer } { "seq" sequence } { "subseq" sequence } }
 148 { $description "Outputs a new sequence using positions relative to one or both ends of the sequence. Positive values describes offsets relative to the start of the sequence, negative values relative to the end. Values of " { $link f } " for " { $snippet "from" } " indicate the beginning of the sequence, while an " { $link f } " for " { $snippet "to" } " indicates the end of the sequence." }
 149 { $notes "Both " { $snippet "from" } " and " { $snippet "to" } " can be safely set to values outside the length of the sequence. Also, " { $snippet "from" } " can safely reference a smaller or greater index position than " { $snippet "to" } "." }
 150 { $examples
 151     "Using a negative relative index:"
 152     { $example "USING: prettyprint sequences.extras ; 2 -1 \"abcdefg\" subseq* ."
 153                "\"cdef\""
 154     }
 155     "Using optional indices:"
 156     { $example "USING: prettyprint sequences.extras ; f -4 \"abcdefg\" subseq* ."
 157                "\"abc\""
 158     }
 159     "Using larger-than-necessary indices:"
 160     { $example "USING: prettyprint sequences.extras ; 0 10 \"abcdefg\" subseq* ."
 161                "\"abcdefg\""
 162     }
 163     "Trimming from either end of the sequence."
 164     { $example "USING: prettyprint sequences.extras ; 1 -1 \"abcdefg\" subseq* ."
 165                "\"bcdef\""
 166     }
 167 } ;
 168
 169 HELP: third=
 170 { $values
 171     { "seq" sequence }
 172     { "elt" object }
 173     { "?" boolean } }
 174 { $description "Checks whether the third element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
 175
 176 HELP: third?
 177 { $values
 178     { "seq" sequence }
 179     { "quot" { $quotation ( ... elt -- ... ? ) } }
 180     { "?" boolean } }
 181 { $description "Tests whether the third element of " { $snippet "seq" } " satisfies the provided predicate." } ;
 182
 183 HELP: unsurround
 184 { $values
 185     { "newseq" sequence }
 186     { "seq2" sequence }
 187     { "seq3" sequence }
 188     { "seq1" sequence } }
 189 { $description "Reverses the result of a " { $link surround } " call, stripping off the prefix " { $snippet "seq2" } " and suffix " { $snippet "seq3" } " to restore the original sequence " { $snippet "seq" } "." }
 190 { $see-also surround } ;
 191
 192 HELP: start-all
 193 { $values
 194      { "subseq" sequence } { "seq" sequence } { "indices" sequence } }
 195 { $description "Outputs the starting indices of the non-overlapping occurences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
 196 { $examples
 197     { $example "USING: prettyprint sequences.extras ; \"ABA\" \"ABABA\" start-all ."
 198                "{ 0 }"
 199     }
 200     { $example "USING: prettyprint sequences.extras ; \"ABA\" \"ABAABA\" start-all ."
 201       "{ 0 3 }"
 202     }
 203  } ;
 204
 205 HELP: start-all*
 206 { $values
 207     { "subseq" sequence } { "seq" sequence } { "indices" sequence } }
 208 { $description "Outputs the starting indices of the possibly overlapping occurences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
 209 { $examples
 210     { $example "USING: prettyprint sequences.extras ; \"ABA\" \"ABABA\" start-all* ."
 211                "{ 0 2 }"
 212     } } ;
 213
 214 HELP: count-subseq
 215 { $values
 216     { "subseq" sequence } { "seq" sequence } { "n" integer } }
 217 { $description "Outputs the number of non-overlapping occurences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
 218 { $examples
 219     { $example "USING: prettyprint sequences.extras ; \"ABA\" \"ABABA\" count-subseq ."
 220                "1"
 221     } } ;
 222
 223
 224 HELP: count-subseq*
 225 { $values
 226     { "subseq" sequence } { "seq" sequence } { "n" integer } }
 227 { $description "Outputs the number of possibly overlapping occurences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
 228 { $examples
 229     { $example "USING: prettyprint sequences.extras ; \"ABA\" \"ABABA\" count-subseq* ."
 230                "2"
 231     } } ;
 232
 233 { start-all start-all* count-subseq count-subseq* } related-words