extra/sequences/extras/extras-docs.factor

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