extra/sequences/extras/extras-docs.factor

   1 USING: arrays help.markup help.syntax kernel math multiline
   2 quotations sequences ;
   3 IN: sequences.extras
   4
   5 HELP: ?supremum
   6 { $values
   7     { "seq/f" { $maybe sequence } }
   8     { "elt/f" { $maybe object } }
   9 }
  10 { $description "Outputs the greatest element of " { $snippet "seq" } ", ignoring any " { $link POSTPONE: f } " elements in it. If " { $snippet "seq" } " is empty or " { $link POSTPONE: f } ", returns " { $link POSTPONE: f } "." }
  11 { $examples
  12     { $example "USING: prettyprint sequences.extras ;"
  13     "{ 1 f 3 2 } ?supremum ."
  14     "3" }
  15 } ;
  16
  17 HELP: ?infimum
  18 { $values
  19     { "seq/f" { $maybe sequence } }
  20     { "elt/f" { $maybe object } }
  21 }
  22 { $description "Outputs the least element of " { $snippet "seq" } ", ignoring any " { $link POSTPONE: f } " elements in it. If " { $snippet "seq" } " is empty or " { $link POSTPONE: f } ", returns " { $link POSTPONE: f } "." }
  23 { $examples
  24     { $example "USING: prettyprint sequences.extras ;"
  25     "{ 1 f 3 2 } ?infimum ."
  26     "1" }
  27 } ;
  28
  29 { ?supremum ?infimum } related-words
  30
  31 HELP: 2count
  32 { $values
  33     { "seq1" sequence }
  34     { "seq2" sequence }
  35     { "quot" { $quotation ( ... elt1 elt2 -- ... ? ) } }
  36     { "n" integer } }
  37 { $description "Efficiently counts how many pairwise elements of " { $snippet "seq1" } " and " { $snippet "seq2" } " that the predicate quotation matches." }
  38 { $examples
  39     { $example "USING: kernel prettyprint sequences.extras ;" "{ 1 2 3 } { 3 2 1 } [ = ] 2count ." "1" } }
  40 { $see-also count } ;
  41
  42 HELP: 2each-index
  43 { $values
  44     { "seq1" sequence }
  45     { "seq2" sequence }
  46     { "quot" { $quotation ( ... elt1 elt2 index -- ... ) } } }
  47 { $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." }
  48 { $see-also 2each each-index } ;
  49
  50 HELP: 2map!
  51 { $values
  52     { "seq1" sequence }
  53     { "seq2" sequence }
  54     { "quot" { $quotation ( ... elt1 elt2 -- ... newelt ) } } }
  55 { $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" } "." }
  56 { $see-also 2map map! } ;
  57
  58 HELP: 2map-index
  59 { $values
  60     { "seq1" sequence }
  61     { "seq2" sequence }
  62     { "quot" { $quotation ( ... elt1 elt2 index -- ... newelt ) } }
  63     { "newseq" sequence } }
  64 { $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." }
  65 { $see-also 2map map-index } ;
  66
  67 HELP: count*
  68 { $values
  69     { "seq" sequence }
  70     { "quot" { $quotation ( ... elt -- ... ? ) } }
  71     { "%" rational } }
  72 { $description "Outputs the fraction of elements in the sequence for which the predicate quotation matches." }
  73 { $examples { $example "USING: math math.ranges prettyprint sequences.extras ;" "100 [1,b] [ even? ] count* ." "1/2" } } ;
  74
  75 HELP: collapse
  76 { $values
  77     { "seq" sequence }
  78     { "quot" { $quotation ( ... elt -- ... ? ) } }
  79     { "elt" object }
  80     { "seq'" sequence } }
  81 { $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" } "." }
  82 { $see-also compact }
  83 { $examples
  84     "Collapse multiple spaces in a string down to a single space"
  85     { $example "USING: kernel prettyprint sequences.extras ;" "\"   Hello,    crazy    world   \" [ CHAR: \\s = ] \" \" collapse ." "\" Hello, crazy world \"" } } ;
  86
  87 HELP: compact
  88 { $values
  89     { "seq" sequence }
  90     { "quot" { $quotation ( ... elt -- ... ? ) } }
  91     { "elt" object }
  92     { "seq'" sequence } }
  93 { $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." }
  94 { $see-also collapse }
  95 { $examples
  96     "Collapse multiple spaces in a string down to a single space"
  97     { $example "USING: kernel prettyprint sequences.extras ;" "\"   Hello,    crazy    world   \" [ CHAR: \\s = ] \" \" compact ." "\"Hello, crazy world\"" } } ;
  98
  99 HELP: <evens>
 100 { $values { "seq" sequence } { "evens" evens } }
 101 { $description "Create a virtual sequence whose elements consist of the even-indexed elements from the original sequence." }
 102 { $notes "Because sequences are zero-indexed, this collection includes the first, third, fifth, etc. elements of the actual sequence which can be counterintuitive." }
 103 { $see-also <odds> } ;
 104
 105 HELP: find-all
 106 { $values
 107     { "seq" sequence }
 108     { "quot" { $quotation ( ... elt -- ... ? ) } }
 109     { "elts" "the indices of the matching elements" } }
 110 { $description "Similar to " { $link find } ", but finds all of the indices and elements that match the provided quotation, not just the first." }
 111 { $notes "The result is provided as an array of arrays, whose first value is the index and whose second value is the element." } ;
 112
 113 HELP: first=
 114 { $values
 115     { "seq" sequence }
 116     { "elt" object }
 117     { "?" boolean } }
 118 { $description "Checks whether the first element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
 119
 120 HELP: first?
 121 { $values
 122     { "seq" sequence }
 123     { "quot" { $quotation ( ... elt -- ... ? ) } }
 124     { "?" boolean } }
 125 { $description "Tests whether the first element of " { $snippet "seq" } " satisfies the provided predicate." } ;
 126
 127 HELP: fourth=
 128 { $values
 129     { "seq" sequence }
 130     { "elt" object }
 131     { "?" boolean } }
 132 { $description "Checks whether the fourth element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
 133
 134 HELP: fourth?
 135 { $values
 136     { "seq" sequence }
 137     { "quot" { $quotation ( ... elt -- ... ? ) } }
 138     { "?" boolean } }
 139 { $description "Tests whether the fourth element of " { $snippet "seq" } " satisfies the provided predicate." } ;
 140
 141 HELP: <odds>
 142 { $values { "seq" sequence } { "odds" odds } }
 143 { $description "Create a virtual sequence whose elements consist of the odd-indexed elements from the original sequence." }
 144 { $notes "Because sequences are zero-indexed, this collection includes the second, fourth, sixth, etc. elements of the actual sequence which can be counterintuitive." }
 145 { $see-also <evens> } ;
 146
 147 HELP: >resizable
 148 { $values { "seq" sequence } { "accum" sequence } }
 149 { $description "Converts a sequence into the nearest resizable equivalent, preserving its contents." } ;
 150
 151 HELP: second=
 152 { $values
 153     { "seq" sequence }
 154     { "elt" object }
 155     { "?" boolean } }
 156 { $description "Checks whether the second element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
 157
 158 HELP: second?
 159 { $values
 160     { "seq" sequence }
 161     { "quot" { $quotation ( ... elt -- ... ? ) } }
 162     { "?" boolean } }
 163 { $description "Tests whether the second element of " { $snippet "seq" } " satisfies the provided predicate." } ;
 164
 165 HELP: subseq*
 166 { $values
 167      { "from" integer } { "to" integer } { "seq" sequence } { "subseq" sequence } }
 168 { $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." }
 169 { $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" } "." }
 170 { $examples
 171     "Using a negative relative index:"
 172     { $example "USING: prettyprint sequences.extras ; 2 -1 \"abcdefg\" subseq* ."
 173                "\"cdef\""
 174     }
 175     "Using optional indices:"
 176     { $example "USING: prettyprint sequences.extras ; f -4 \"abcdefg\" subseq* ."
 177                "\"abc\""
 178     }
 179     "Using larger-than-necessary indices:"
 180     { $example "USING: prettyprint sequences.extras ; 0 10 \"abcdefg\" subseq* ."
 181                "\"abcdefg\""
 182     }
 183     "Trimming from either end of the sequence."
 184     { $example "USING: prettyprint sequences.extras ; 1 -1 \"abcdefg\" subseq* ."
 185                "\"bcdef\""
 186     }
 187 } ;
 188
 189 HELP: third=
 190 { $values
 191     { "seq" sequence }
 192     { "elt" object }
 193     { "?" boolean } }
 194 { $description "Checks whether the third element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
 195
 196 HELP: third?
 197 { $values
 198     { "seq" sequence }
 199     { "quot" { $quotation ( ... elt -- ... ? ) } }
 200     { "?" boolean } }
 201 { $description "Tests whether the third element of " { $snippet "seq" } " satisfies the provided predicate." } ;
 202
 203 HELP: unsurround
 204 { $values
 205     { "newseq" sequence }
 206     { "seq2" sequence }
 207     { "seq3" sequence }
 208     { "seq1" sequence } }
 209 { $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" } "." }
 210 { $see-also surround } ;
 211
 212 HELP: start-all
 213 { $values
 214      { "subseq" sequence } { "seq" sequence } { "indices" sequence } }
 215 { $description "Outputs the starting indices of the non-overlapping occurrences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
 216 { $examples
 217     { $example "USING: prettyprint sequences.extras ; \"ABA\" \"ABABA\" start-all ."
 218                "{ 0 }"
 219     }
 220     { $example "USING: prettyprint sequences.extras ; \"ABA\" \"ABAABA\" start-all ."
 221       "{ 0 3 }"
 222     }
 223  } ;
 224
 225 HELP: start-all*
 226 { $values
 227     { "subseq" sequence } { "seq" sequence } { "indices" sequence } }
 228 { $description "Outputs the starting indices of the possibly overlapping occurrences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
 229 { $examples
 230     { $example "USING: prettyprint sequences.extras ; \"ABA\" \"ABABA\" start-all* ."
 231                "{ 0 2 }"
 232     } } ;
 233
 234 HELP: arg-max
 235 { $values { "seq" sequence } { "n" integer } }
 236 { $description "Outputs the sequence with the largest item." } ;
 237
 238 HELP: arg-min
 239 { $values { "seq" sequence } { "n" integer } }
 240 { $description "Outputs the sequence with the smallest item." } ;
 241
 242 { arg-max arg-min } related-words
 243
 244 HELP: count-subseq
 245 { $values
 246     { "subseq" sequence } { "seq" sequence } { "n" integer } }
 247 { $description "Outputs the number of non-overlapping occurrences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
 248 { $examples
 249     { $example "USING: prettyprint sequences.extras ; \"ABA\" \"ABABA\" count-subseq ."
 250                "1"
 251     } } ;
 252
 253
 254 HELP: count-subseq*
 255 { $values
 256     { "subseq" sequence } { "seq" sequence } { "n" integer } }
 257 { $description "Outputs the number of possibly overlapping occurrences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
 258 { $examples
 259     { $example "USING: prettyprint sequences.extras ; \"ABA\" \"ABABA\" count-subseq* ."
 260                "2"
 261     } } ;
 262
 263 { start-all start-all* count-subseq count-subseq* } related-words
 264
 265 HELP: loop>array
 266 { $values
 267     { "quot" quotation }
 268     { "array" array }
 269 }
 270 { $description "Call the " { $snippet "quot" } ", which should output an object or " { $snippet "f" } ", and collect the objects in " { $snippet "array" } " until " { $snippet "quot" } " outputs " { $snippet "f" } "." }
 271 { $examples
 272     "Example:"
 273     { $example "USING: sequences.extras prettyprint io.encodings.binary"
 274     "io.streams.byte-array io ;"
 275         "B{ 10 20 30 } binary ["
 276         "   [ read1 ] loop>array"
 277         "] with-byte-reader ."
 278         "{ 10 20 30 }"
 279     }
 280 } ;
 281
 282 HELP: loop>array*
 283 { $values
 284     { "quot" quotation }
 285     { "array" array }
 286 }
 287 { $description "Call the " { $snippet "quot" } ", which should output an object and a " { $snippet "bool" } ", and collect the objects in " { $snippet "array" } " until " { $snippet "quot" } " outputs " { $snippet "f" } ". Do collect the last object." }
 288 { $examples
 289     "Example:"
 290     { $example "USING: sequences.extras prettyprint io.encodings.binary"
 291                "random random.mersenne-twister kernel math ;"
 292     "123 <mersenne-twister> ["
 293     "   ["
 294     "      10 random dup 5 >"
 295     "   ] loop>array* ."
 296     "] with-random"
 297     "{ 6 7 2 }"
 298     }
 299 } ;
 300
 301 HELP: loop>array**
 302 { $values
 303     { "quot" quotation }
 304     { "array" array }
 305 }
 306 { $description "Call the " { $snippet "quot" } ", which should output an object and a " { $snippet "bool" } ", and collect the objects in " { $snippet "array" } " until " { $snippet "quot" } " outputs " { $snippet "f" } ". Do not collect the last object." }
 307 { $examples
 308     "Example:"
 309     { $example "USING: sequences.extras prettyprint io.encodings.binary"
 310                "random random.mersenne-twister kernel math ;"
 311     "123 <mersenne-twister> ["
 312     "   ["
 313     "      10 random dup 5 >"
 314     "   ] loop>array** ."
 315     "] with-random"
 316     "{ 6 7 }"
 317     }
 318 } ;
 319
 320
 321 HELP: loop>sequence
 322 { $values
 323     { "quot" quotation } { "exemplar" object }
 324     { "seq" sequence }
 325 }
 326 { $description "Call " { $snippet "quot" } ", which should output an object or " { $snippet "f" } ", and collect the objects in " { $snippet "seq" } " of type " { $snippet "exemplar" } " until " { $snippet "quot" } " outputs " { $snippet "f" } "." }
 327 { $examples
 328     "Example:"
 329     { $example "USING: sequences.extras prettyprint io.encodings.binary"
 330                "random random.mersenne-twister kernel math ;"
 331     "! Get random numbers until one of them is greater than 5"
 332     "! but also output the last number"
 333     "123 <mersenne-twister> ["
 334     "   ["
 335     "      10 random dup 5 >"
 336     "   ] loop>array*"
 337     "] with-random ."
 338     "{ 6 7 2 }"
 339     }
 340 } ;
 341
 342 HELP: loop>sequence*
 343 { $values
 344     { "quot" quotation } { "exemplar" object }
 345     { "seq" sequence }
 346 }
 347 { $description "Call " { $snippet "quot" } ", which should output an object and a " { $snippet "bool" } ", and collect the objects in " { $snippet "seq" } " of type " { $snippet "exemplar" } " until " { $snippet "quot" } " outputs " { $snippet "f" } ". Do collect the last object." }
 348 { $examples
 349     "Example:"
 350     { $example "USING: sequences.extras prettyprint io.encodings.binary"
 351                "random random.mersenne-twister kernel math ;"
 352     "! Get random numbers until one of them is greater than 5"
 353     "! but also output the last number"
 354     "123 <mersenne-twister> ["
 355     "   ["
 356     "      10 random dup 5 >"
 357     "   ] V{ } loop>sequence*"
 358     "] with-random ."
 359     "V{ 6 7 2 }"
 360     }
 361 } ;
 362
 363 HELP: loop>sequence**
 364 { $values
 365     { "quot" quotation } { "exemplar" object }
 366     { "seq" sequence }
 367 }
 368 { $description "Call " { $snippet "quot" } ", which should output an object and a " { $snippet "bool" } ", and collect the objects in " { $snippet "seq" } " of type " { $snippet "exemplar" } " until " { $snippet "quot" } " outputs " { $snippet "f" } ". Do not collect the last object." }
 369 { $examples
 370     "Example:"
 371     { $example "USING: sequences.extras prettyprint io.encodings.binary"
 372                "random random.mersenne-twister kernel math ;"
 373     "! Get random numbers until one of them is greater than 5"
 374     "! but also output the last number"
 375     "123 <mersenne-twister> ["
 376     "   ["
 377     "      10 random dup 5 >"
 378     "   ] V{ } loop>sequence**"
 379     "] with-random ."
 380     "V{ 6 7 }"
 381     }
 382 } ;
 383
 384 {
 385     loop>array loop>array* loop>array**
 386     loop>sequence loop>sequence* loop>sequence**
 387     zero-loop>array zero-loop>sequence
 388 } related-words
 389
 390 HELP: zero-loop>array
 391 { $values
 392     { "quot" quotation }
 393     { "seq" sequence }
 394 }
 395 { $description "Call " { $snippet "quot" } ", which takes an integer starting from zero and incrementing on every loop, and should output an object, and collect the objects in " { $snippet "array" } " until " { $snippet "quot" } " outputs " { $snippet "f" } "." }
 396 { $examples
 397     "Example:"
 398     { $example "USING: sequences.extras prettyprint math.text.english math kernel ;"
 399         "[ dup 5 < [ number>text ] [ drop f ] if ] zero-loop>array ."
 400         [[ { "zero" "one" "two" "three" "four" }]]
 401     }
 402 } ;
 403
 404 HELP: zero-loop>sequence
 405 { $values
 406     { "quot" quotation } { "exemplar" object }
 407     { "seq" sequence }
 408 }
 409 { $description "Call the " { $snippet "quot" } ", which takes an integer starting from zero and incrementing on every loop, and should output an object or " { $snippet "f" } ", and collect the objects in " { $snippet "array" } " until " { $snippet "quot" } " outputs " { $snippet "f" } "." }
 410 { $examples
 411     "Example:"
 412     { $example "USING: sequences.extras prettyprint math.text.english math kernel ;"
 413         "[ dup 5 < [ number>text ] [ drop f ] if ] V{ } zero-loop>sequence ."
 414         [[ V{ "zero" "one" "two" "three" "four" }]]
 415     }
 416 } ;