listtools.group_by_weights — Abjad v1.1.1 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Project Abjad »
- Abjad v1.1.1 documentation »
- Abjad API »

# listtools.group_by_weights

`abjad.tools.listtools.` `group_by_weights`(l, weights, fill='exact', cyclic=False, overhang=False)

  Partition `l` into list `result` of sublists according to `weights`.

  Behavior of fill:

  - When `fill = 'exact'`, `listtools.weight(result[i])` must equal `weights[i]` exactly.
  - When `fill = 'less'`, allow `listtools.weight(result[i])` to be just less than, or equal to, `weights[i]`.
  - When `fill = 'greater'`, allow `listtools.weight(result[i])` to be just greater than, or equal to, `weights[i]`.
  - Defaults to `'exact'`.

  Behavior of cyclic:

  - When `cyclic = False`, read weights only once.
  - When `cyclic = True`, read weights cyclically.
  - Defaults to `False`.

  Behavior of overhang:

  - When `overhang = False` and elements of `l` remain, do not append as final part.
  - When `overhang = True` and elements of `l` remain, do append as final part.
  - Defaults to `False`.

  Raise `PartitionError` when

  - When `fill = 'exact'` and `listtools.weight(result[i])` can not equal `weights[i]` exactly.
  - When `fill = 'less'` and `listtools.weight(result[i])` exceeds `weights[i]`.

  Examples:

      abjad> l = [3, 3, 3, 3, 4, 4, 4, 4, 5, 5]

      abjad> t = listtools.group_by_weights(l, [3, 9], fill = 'exact', cyclic = False, overhang = False)
      [[3], [3, 3, 3]]

      abjad> listtools.group_by_weights(l, [3, 9], fill = 'exact', cyclic = False, overhang = True)
      [[3], [3, 3, 3], [4, 4, 4, 4, 5, 5]]

      abjad> t = listtools.group_by_weights(l, [3, 9], fill = 'exact', cyclic = True, overhang = False)
      PartitionError

      abjad> listtools.group_by_weights(l, [3, 9], fill = 'exact', cyclic = True, overhang = True)
      PartitionError

      abjad> listtools.group_by_weights(l, [3, 9], fill = 'less', cyclic = False, overhang = False)
      t == [[3], [3, 3, 3]]

      abjad> listtools.group_by_weights(l, [3, 9], fill = 'less', cyclic = False, overhang = True)
      [[3], [3, 3, 3], [4, 4, 4, 4, 5, 5]]

      abjad> listtools.group_by_weights(l, [3, 9], fill = 'less', cyclic = True, overhang = False)
      PartitionError

      abjad> t = listtools.group_by_weights(l, [3, 9], fill = 'less', cyclic = True, overhang = True)
      PartitionError

      abjad> listtools.group_by_weights(l, [3, 9], fill = 'greater', cyclic = False, overhang = False)
      [[3], [3, 3, 3]]

      abjad> listtools.group_by_weights(l, [3, 9], fill = 'greater', cyclic = False, overhang = True)
      [[3], [3, 3, 3], [4, 4, 4, 4, 5, 5]]

      abjad> listtools.group_by_weights(l, [3, 9], fill = 'greater', cyclic = True, overhang = False)
      [[3], [3, 3, 3], [4], [4, 4, 4], [5]]

      abjad> listtools.group_by_weights(l, [3, 9], fill = 'greater', cyclic = True, overhang = True)
      [[3], [3, 3, 3], [4], [4, 4, 4], [5], [5]]

### Navigation

- index
- modules |
- next |
- previous |
- Project Abjad »
- Abjad v1.1.1 documentation »
- Abjad API »