code / tomo

   1 List.binary_search:
   2   short: binary search
   3   description: >
   4     Performs a binary search on a sorted list.
   5   return:
   6     type: 'Int'
   7     description: >
   8       Assuming the input list is sorted according to the given comparison function,
   9       return the index where the given item would be inserted to maintain the sorted
  10       order. That is, if the item is found, return its index, otherwise return the
  11       place where it would be found if it were inserted and the list were sorted.
  12   args:
  13     list:
  14       type: '[T]'
  15       description: >
  16         The sorted list to search.
  17     by:
  18       type: 'func(x,y:&T->Int32)'
  19       default: 'T.compare'
  20       description: >
  21         The comparison function used to determine order. If not specified, the
  22         default comparison function for the item type will be used.
  23   example: |
  24     assert [1, 3, 5, 7, 9].binary_search(5) == 3
  25     assert [1, 3, 5, 7, 9].binary_search(-999) == 1
  26     assert [1, 3, 5, 7, 9].binary_search(999) == 6
  27 
  28 List.by:
  29   short: slice by a step value
  30   description: >
  31     Creates a new list with elements spaced by the specified step value.
  32   return:
  33     type: '[T]'
  34     description: >
  35       A new list with every `step`-th element from the original list.
  36   args:
  37     list:
  38       type: '[T]'
  39       description: >
  40         The original list.
  41     step:
  42       type: 'Int'
  43       description: >
  44         The step value for selecting elements.
  45   example: |
  46     assert [1, 2, 3, 4, 5, 6].by(2) == [1, 3, 5]
  47 
  48 List.clear:
  49   short: clear a list
  50   description: >
  51     Clears all elements from the list.
  52   return:
  53     type: 'Void'
  54     description: >
  55       Nothing.
  56   args:
  57     list:
  58       type: '@[T]'
  59       description: >
  60         The mutable reference to the list to be cleared.
  61   example: |
  62     list := &[10, 20]
  63     list.clear()
  64     assert list[] == []
  65 
  66 List.counts:
  67   short: count occurrences
  68   description: >
  69     Counts the occurrences of each element in the list.
  70   return:
  71     type: '{T=Int}'
  72     description: >
  73       A table mapping each element to its count.
  74   args:
  75     list:
  76       type: '[T]'
  77       description: >
  78         The list to count elements in.
  79   example: |
  80     assert [10, 20, 30, 30, 30].counts() == {10:1, 20:1, 30:3}
  81 
  82 List.find:
  83   short: find an element's index
  84   description: >
  85     Finds the index of the first occurrence of an element (if any).
  86   return:
  87     type: 'Int?'
  88     description: >
  89       The index of the first occurrence or `none` if not found.
  90   args:
  91     list:
  92       type: '[T]'
  93       description: >
  94         The list to search through.
  95     target:
  96       type: 'T'
  97       description: >
  98         The item to search for.
  99   example: |
 100     assert [10, 20, 30, 40, 50].find(20) == 2
 101     assert [10, 20, 30, 40, 50].find(9999) == none
 102 
 103 List.from:
 104   short: slice an array from a start index
 105   description: >
 106     Returns a slice of the list starting from a specified index.
 107   return:
 108     type: '[T]'
 109     description: >
 110       A new list starting from the specified index.
 111   args:
 112     list:
 113       type: '[T]'
 114       description: >
 115         The original list.
 116     first:
 117       type: 'Int'
 118       description: >
 119         The index to start from.
 120   example: |
 121     assert [10, 20, 30, 40, 50].from(3) == [30, 40, 50]
 122 
 123 List.has:
 124   short: check for member
 125   description: >
 126     Checks if the list has an element.
 127   return:
 128     type: 'Bool'
 129     description: >
 130       `yes` if the list has the element, `no` otherwise.
 131   args:
 132     list:
 133       type: '[T]'
 134       description: >
 135         The list to check.
 136     target:
 137       type: 'T'
 138       description: >
 139         The element to check for.
 140   example: |
 141     assert [10, 20, 30].has(20) == yes
 142 
 143 List.heap_pop:
 144   short: heap pop
 145   description: >
 146     Removes and returns the top element of a heap or `none` if the list is empty.
 147     By default, this is the *minimum* value in the heap.
 148   return:
 149     type: 'T?'
 150     description: >
 151       The removed top element of the heap or `none` if the list is empty.
 152   args:
 153     list:
 154       type: '@[T]'
 155       description: >
 156         The mutable reference to the heap.
 157     by:
 158       type: 'func(x,y:&T->Int32)'
 159       default: 'T.compare'
 160       description: >
 161         The comparison function used to determine order. If not specified, the
 162         default comparison function for the item type will be used.
 163   example: |
 164     my_heap := &[30, 10, 20]
 165     my_heap.heapify()
 166     assert my_heap.heap_pop() == 10
 167 
 168 List.heap_push:
 169   short: heap push
 170   description: >
 171     Adds an element to the heap and maintains the heap property. By default, this
 172     is a *minimum* heap.
 173   return:
 174     type: 'Void'
 175     description: >
 176       Nothing.
 177   args:
 178     list:
 179       type: '@[T]'
 180       description: >
 181         The mutable reference to the heap.
 182     item:
 183       type: 'T'
 184       description: >
 185         The item to be added.
 186     by:
 187       default: 'T.compare'
 188       description: >
 189         The comparison function used to determine order. If not specified, the
 190         default comparison function for the item type will be used.
 191   example: |
 192     my_heap : &[Int]
 193     my_heap.heap_push(10)
 194     assert my_heap.heap_pop() == 10
 195 
 196 List.heapify:
 197   short: convert a list into a heap
 198   description: >
 199     Converts a list into a heap.
 200   return:
 201     type: 'Void'
 202     description: >
 203       Nothing.
 204   args:
 205     list:
 206       type: '@[T]'
 207       description: >
 208         The mutable reference to the list to be heapified.
 209     by:
 210       type: 'func(x,y:&T->Int32)'
 211       default: 'T.compare'
 212       description: >
 213         The comparison function used to determine order. If not specified, the
 214         default comparison function for the item type will be used.
 215   example: |
 216     my_heap := &[30, 10, 20]
 217     my_heap.heapify()
 218 
 219 List.insert:
 220   short: add an item to a list
 221   description: >
 222     Inserts an element at a specified position in the list.
 223   return:
 224     type: 'Void'
 225     description: >
 226       Nothing.
 227   args:
 228     list:
 229       type: '@[T]'
 230       description: >
 231         The mutable reference to the list.
 232     item:
 233       type: 'T'
 234       description: >
 235         The item to be inserted.
 236     at:
 237       type: 'Int'
 238       default: '0'
 239       description: >
 240         The index at which to insert the item.
 241   note: >
 242     Since indices are 1-indexed and negative indices mean "starting from the
 243     back", an index of `0` means "after the last item".
 244   example: |
 245     list := &[10, 20]
 246     list.insert(30)
 247     assert list == [10, 20, 30]
 248 
 249     list.insert(999, at=2)
 250     assert list == [10, 999, 20, 30]
 251 
 252 List.insert_all:
 253   short: add multiple items to a list
 254   description: >
 255     Inserts a list of items at a specified position in the list.
 256   return:
 257     type: 'Void'
 258     description: >
 259       Nothing.
 260   args:
 261     list:
 262       type: '@[T]'
 263       description: >
 264         The mutable reference to the list.
 265     items:
 266       type: '[T]'
 267       description: >
 268         The items to be inserted.
 269     at:
 270       type: 'Int'
 271       default: '0'
 272       description: >
 273         The index at which to insert the item.
 274   note: >
 275     Since indices are 1-indexed and negative indices mean "starting from the
 276     back", an index of `0` means "after the last item".
 277   example: |
 278     list := &[10, 20]
 279     list.insert_all([30, 40])
 280     assert list == [10, 20, 30, 40]
 281 
 282     list.insert_all([99, 100], at=2)
 283     assert list == [10, 99, 100, 20, 30, 40]
 284 
 285 List.pop:
 286   short: pop an item from a list
 287   description: >
 288     Removes and returns an item from the list. If the given index is present in
 289     the list, the item at that index will be removed and the list will become one
 290     element shorter.
 291   return:
 292     type: 'T?'
 293     description: >
 294       `none` if the list is empty or the given index does not exist in the list,
 295       otherwise the item at the given index.
 296   args:
 297     list:
 298       type: '&[T]'
 299       description: >
 300         The list to remove an item from.
 301     index:
 302       type: 'Int'
 303       default: '-1'
 304       description: >
 305         The index from which to remove the item.
 306   note: >
 307     Since negative indices are counted from the back, the default behavior is
 308     to pop the last value.
 309   example: |
 310     list := &[10, 20, 30, 40]
 311 
 312     assert list.pop() == 40
 313     assert list[] == [10, 20, 30]
 314 
 315     assert list.pop(index=2) == 20
 316     assert list[] == [10, 30]
 317 
 318 List.random:
 319   short: pick a random element
 320   description: >
 321     Selects a random element from the list.
 322   return:
 323     type: 'T?'
 324     description: >
 325       A random element from the list or `none` if the list is empty.
 326   args:
 327     list:
 328       type: '[T]'
 329       description: >
 330         The list from which to select a random element.
 331     random:
 332       type: 'func(min,max:Int64->Int64)?'
 333       default: 'none'
 334       description: >
 335         If provided, this function will be used to get a random index in the list. Returned
 336         values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number
 337         generation)
 338   example: |
 339     nums := [10, 20, 30]
 340     pick := nums.random()!
 341     assert nums.has(pick)
 342     empty : [Int]
 343     assert empty.random() == none
 344 
 345 List.remove_at:
 346   short: remove an item by index
 347   description: >
 348     Removes elements from the list starting at a specified index.
 349   return:
 350     type: 'Void'
 351     description: >
 352       Nothing.
 353   args:
 354     list:
 355       type: '@[T]'
 356       description: >
 357         The mutable reference to the list.
 358     at:
 359       type: 'Int'
 360       default: '-1'
 361       description: >
 362         The index at which to start removing elements.
 363     count:
 364       type: 'Int'
 365       default: '1'
 366       description: >
 367         The number of elements to remove.
 368   note: >
 369     Since negative indices are counted from the back, the default behavior is
 370     to remove the last item.
 371   example: |
 372     list := &[10, 20, 30, 40, 50]
 373     list.remove_at(2)
 374     assert list == [10, 30, 40, 50]
 375 
 376     list.remove_at(2, count=2)
 377     assert list == [10, 50]
 378 
 379 List.remove_item:
 380   short: remove an item by value
 381   description: >
 382     Removes all occurrences of a specified item from the list.
 383   return:
 384     type: 'Void'
 385     description: >
 386       Nothing.
 387   args:
 388     list:
 389       type: '@[T]'
 390       description: >
 391         The mutable reference to the list.
 392     item:
 393       type: 'T'
 394       description: >
 395         The item to be removed.
 396     max_count:
 397       type: 'Int'
 398       default: '-1'
 399       description: >
 400         The maximum number of occurrences to remove.
 401   note: >
 402     A negative `max_count` means "remove all occurrences".
 403   example: |
 404     list := &[10, 20, 10, 20, 30]
 405     list.remove_item(10)
 406     assert list == [20, 20, 30]
 407 
 408     list.remove_item(20, max_count=1)
 409     assert list == [20, 30]
 410 
 411 List.reversed:
 412   short: get a reversed list
 413   description: >
 414     Returns a reversed slice of the list.
 415   return:
 416     type: '[T]'
 417     description: >
 418       A slice of the list with elements in reverse order.
 419   args:
 420     list:
 421       type: '[T]'
 422       description: >
 423         The list to be reversed.
 424   example: |
 425     assert [10, 20, 30].reversed() == [30, 20, 10]
 426 
 427 List.sample:
 428   short: weighted random choices
 429   description: >
 430     Selects a sample of elements from the list, optionally with weighted
 431     probabilities.
 432   return:
 433     type: '[T]'
 434     description: >
 435       A list of sampled elements from the list.
 436   errors: >
 437     Errors will be raised if any of the following conditions occurs:
 438     - The given list has no elements and `count >= 1`
 439     - `count < 0` (negative count)
 440     - The number of weights provided doesn't match the length of the list. 
 441     - Any weight in the weights list is negative, infinite, or `NaN`
 442     - The sum of the given weights is zero (zero probability for every element).
 443   args:
 444     list:
 445       type: '[T]'
 446       description: >
 447         The list to sample from.
 448     count:
 449       type: 'Int'
 450       description: >
 451         The number of elements to sample.
 452     weights:
 453       type: '[Num]?'
 454       default: 'none'
 455       description: >
 456         The probability weights for each element in the list. These
 457         values do not need to add up to any particular number, they are relative
 458         weights. If no weights are given, elements will be sampled with uniform
 459         probability.
 460     random:
 461       type: 'func(->Num)?'
 462       default: 'none'
 463       description: >
 464         If provided, this function will be used to get random values for
 465         sampling the list. The provided function should return random numbers
 466         between `0.0` (inclusive) and `1.0` (exclusive). (Used for deterministic
 467         pseudorandom number generation)
 468   example: |
 469     _ := [10, 20, 30].sample(2, weights=[90%, 5%, 5%]) # E.g. [10, 10]
 470 
 471 List.shuffle:
 472   short: shuffle a list in place
 473   description: >
 474     Shuffles the elements of the list in place.
 475   return:
 476     type: 'Void'
 477     description: >
 478       Nothing.
 479   args:
 480     list:
 481       type: '@[T]'
 482       description: >
 483         The mutable reference to the list to be shuffled.
 484     random:
 485       type: 'func(min,max:Int64->Int64)?'
 486       default: 'none'
 487       description: >
 488         If provided, this function will be used to get a random index in the list. Returned
 489         values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number
 490         generation)
 491   example: |
 492     nums := &[10, 20, 30, 40]
 493     nums.shuffle()
 494     # E.g. [20, 40, 10, 30]
 495 
 496 List.shuffled:
 497   short: return a shuffled list
 498   description: >
 499     Creates a new list with elements shuffled.
 500   return:
 501     type: '[T]'
 502     description: >
 503       A new list with shuffled elements.
 504   args:
 505     list:
 506       type: '[T]'
 507       description: >
 508         The list to be shuffled.
 509     random:
 510       type: 'func(min,max:Int64->Int64)?'
 511       default: 'none'
 512       description: >
 513         If provided, this function will be used to get a random index in the list. Returned
 514         values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number
 515         generation)
 516   example: |
 517     nums := [10, 20, 30, 40]
 518     _ := nums.shuffled()
 519     # E.g. [20, 40, 10, 30]
 520 
 521 List.slice:
 522   short: get a slice of a list
 523   description: >
 524     Returns a slice of the list spanning the given indices (inclusive).
 525   return:
 526     type: '[T]'
 527     description: >
 528       A new list spanning the given indices. Note: negative indices are counted from
 529       the back of the list, so `-1` refers to the last element, `-2` the
 530       second-to-last, and so on.
 531   args:
 532     list:
 533       type: '[T]'
 534       description: >
 535         The original list.
 536     from:
 537       type: 'Int'
 538       description: >
 539         The first index to include.
 540     to:
 541       type: 'Int'
 542       description: >
 543         The last index to include.
 544   example: |
 545     assert [10, 20, 30, 40, 50].slice(2, 4) == [20, 30, 40]
 546     assert [10, 20, 30, 40, 50].slice(-3, -2) == [30, 40]
 547 
 548 List.sort:
 549   short: sort a list
 550   description: >
 551     Sorts the elements of the list in place in ascending order (small to large).
 552   return:
 553     type: 'Void'
 554     description: >
 555       Nothing.
 556   args:
 557     list:
 558       type: '@[T]'
 559       description: >
 560         The mutable reference to the list to be sorted.
 561     by:
 562       default: 'T.compare'
 563       description: >
 564         The comparison function used to determine order. If not specified, the
 565         default comparison function for the item type will be used.
 566   example: |
 567     list := &[40, 10, -30, 20]
 568     list.sort()
 569     assert list == [-30, 10, 20, 40]
 570 
 571     list.sort(func(a,b:&Int) a.abs() <> b.abs())
 572     assert list == [10, 20, -30, 40]
 573 
 574 List.sorted:
 575   short: sorted copy of a list
 576   description: >
 577     Creates a new list with elements sorted.
 578   return:
 579     type: '[T]'
 580     description: >
 581       A new list with sorted elements.
 582   args:
 583     list:
 584       type: '[T]'
 585       description: >
 586         The list to be sorted.
 587     by:
 588       default: 'T.compare'
 589       description: >
 590         The comparison function used to determine order. If not specified, the
 591         default comparison function for the item type will be used.
 592   example: |
 593     assert [40, 10, -30, 20].sorted() == [-30, 10, 20, 40]
 594     assert [40, 10, -30, 20].sorted(
 595        func(a,b:&Int) a.abs() <> b.abs()
 596     ) == [10, 20, -30, 40]
 597 
 598 List.to:
 599   short: slice a list to an end index
 600   description: >
 601     Returns a slice of the list from the start of the original list up to a specified index (inclusive).
 602   return:
 603     type: '[T]'
 604     description: >
 605       A new list containing elements from the start up to the specified index.
 606   args:
 607     list:
 608       type: '[T]'
 609       description: >
 610         The original list.
 611     last:
 612       type: 'Int'
 613       description: >
 614         The index up to which elements should be included.
 615   example: |
 616     assert [10, 20, 30, 40, 50].to(3) == [10, 20, 30]
 617     assert [10, 20, 30, 40, 50].to(-2) == [10, 20, 30, 40]
 618 
 619 List.unique:
 620   short: get the unique items in a list
 621   description: >
 622     Returns a set of the unique elements of the list.
 623   return:
 624     type: '{T}'
 625     description: >
 626       A set of the unique elements from the list.
 627   args:
 628     list:
 629       type: '[T]'
 630       description: >
 631         The list to process.
 632   example: |
 633     assert [10, 20, 10, 10, 30].unique() == {10, 20, 30}
 634 
 635 List.where:
 636   short: find an index where a predicate matches
 637   description: >
 638     Find the index of the first item that matches a predicate function (if any).
 639   return:
 640     type: 'Int'
 641     description: >
 642       Returns the index of the first item where the predicate is true or `none` if no
 643       item matches.
 644   args:
 645     list:
 646       type: '[T]'
 647       description: >
 648         The list to search through.
 649     predicate:
 650       type: 'func(item:&T -> Bool)'
 651       description: >
 652         A function that returns `yes` if the item's index should be returned or
 653         `no` if it should not.
 654   example: |
 655     assert ["BC", "ABC", "CD"].where(func(t:&Text) t.starts_with("A")) == 2
 656     assert ["BC", "ABC", "CD"].where(func(t:&Text) t.starts_with("X")) == none