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