https://github.com/bluefireteam/ordered_set
A simple implementation for an ordered set
https://github.com/bluefireteam/ordered_set
collections dart flame flutter hacktoberfest set
Last synced: 5 months ago
JSON representation
A simple implementation for an ordered set
- Host: GitHub
- URL: https://github.com/bluefireteam/ordered_set
- Owner: bluefireteam
- License: mit
- Created: 2018-05-26T15:13:46.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2025-05-21T15:50:12.000Z (10 months ago)
- Last Synced: 2025-09-23T12:41:30.308Z (6 months ago)
- Topics: collections, dart, flame, flutter, hacktoberfest, set
- Language: Dart
- Homepage:
- Size: 136 KB
- Stars: 24
- Watchers: 3
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# ordered_set
[](https://pub.dev/packages/ordered_set)
[](https://github.com/bluefireteam/ordered_set/actions/workflows/cicd.yml)
[](https://coveralls.io/github/bluefireteam/ordered_set?branch=main)
A simple implementation for an Ordered Set for Dart.
It accepts either a comparator function that compares items for their priority or a mapper function
that maps items to their priority.
Unlike Dart's [SplayTreeSet](https://api.dart.dev/dart-collection/SplayTreeSet-class.html) or
[SplayTreeMap](https://api.dart.dev/dart-collection/SplayTreeMap-class.html) classes, it allows for
several different elements with the same "priority" to be added.
It also implements [Iterable](https://api.dart.dev/dart-core/Iterable-class.html), allowing you to
iterate the contents (in order) in O(n) (no additional overhead).
## Usage
A simple usage example:
```dart
import 'package:ordered_set/ordered_set.dart';
main() {
final items = OrderedSet.simple();
items.add(2);
items.add(1);
print(items.toList()); // [1, 2]
}
```
But it can accept multiple items with the same priority:
```dart
import 'package:ordered_set/ordered_set.dart';
main() {
final items = OrderedSet.mapping((p) => p.name);
items.add(Person('Alice', 'Engineering'));
items.add(Person('Bob', 'Accounting'));
items.add(Person('Alice', 'Marketing'));
print(items.toList()); // [Alice, Alice, Bob]
}
```
## Comparing
In order to assist the creation of `Comparator`s, the `Comparing` class can be used:
```dart
// sort by name length
final people = OrderedSet.comparing(Comparing.on((p) => p.name.length));
// sort by name desc
final people = OrderedSet.comparing(Comparing.reverse(Comparing.on((p) => p.name)));
// sort by role and then by name
final people = OrderedSet.comparing(Comparing.join([(p) => p.role, (p) => p.name]));
```
Note that you could instead just create a `MappingOrderedSet` instead:
```dart
final people = OrderedSet.mapping((p) => p.name.length);
// ...
```
## Mapping vs Comparing
There are two main implementations of the `OrderedSet` interface:
* `ComparingOrderedSet`: the simplest implementation, takes in a `Comparator` and does not cache
priorities. It uses Dart's `SplayTreeSet` as a backing implementation.
* `MappingOrderedSet`: a slightly more advanced implementation that takes in a mapper function
(maps elements to their priorities) and caches them. It uses Dart's `SplayTreeMap` as a backing
implementation.
In order to create an `OrderedSet`, however, you can just use the static methods on the interface
itself:
* `OrderedSet.comparing([comparator])`: creates a `ComparingOrderedSet` with the given
`Comparator`.
* `OrderedSet.mapping([mapper])`: creates a `MappingOrderedSet` with the given mapper
function.
* `OrderedSet.comparable()`: if `E extends Comparable`, this is a simpler way of creating
a `MappingOrderedSet` with identity mapping.
* `OrderedSet.simple()`: if `E extends Comparable`, this is an even simpler way of creating
a `MappingOrderedSet` with identity mapping.
## Querying
You can [register] a set of queries, i.e., predefined sub-types, whose results, i.e., subsets of
this set, are then cached. Since the queries have to be type checks, and types are runtime
constants, this can be vastly optimized.
You can then filter by type by using the [query] method (or using [whereType]; which is overridden).
Note that you can change [strictMode] to allow for querying for unregistered types; if you do so,
the registration cost is payed on the first query.
## Contributing
All contributions are very welcome! Please feel free to create Issues, help us with PR's or comment
your suggestions, feature requests, bugs, et cetera. Give us a star if you liked it!