contrast 0.1.1

  • README.md
  • Example
  • Installing
  • Versions
  • 3

contrast

Build Status

Utilities for comparing (and contrasting) dart values:

  • Comparator combinators (by/compound/reverse/lexicographic/nullsFirst/nullsLast)
  • Comparison operator mixin (Quantity)(<, <=, ==, >, >=)
  • Find extrema of Comparables and Iterables (min/max/minOf/maxOf)
  • Test and obtain clamped comparables (clamp/between)
  • Test and obtain sorted iterables (sorted/isOrdered/isStrictlyOrdered)

#Example


import 'package:contrast/contrast.dart';
import 'dart:math' as math;

main() {
  
  // Easily define comparison operators (see Point class below).
  assert(Point.ZERO < Point.UNIT);
  assert(Point.UNIT >= Point.ZERO);
  assert(Point.ZERO == new Point(0, 0));

  // Find extrema of arbitrary comparables.
  // (dart:math's min/max only work with numbers)
  assert(min(Point.ZERO, Point.UNIT) == Point.ZERO);
  assert(max(Point.ZERO, Point.UNIT) == Point.UNIT);
  assert(clamp(new Point(1, 2), Point.ZERO, Point.UNIT) == Point.UNIT);
  assert(between(new Point(0.5, 0.5), Point.ZERO, Point.UNIT));
  
  // Find extrema of iterables.
  var points = [Point.UNIT, new Point(1, 2), Point.ZERO, new Point(0, 1)];
  assert(minOf(points) == Point.ZERO);
  assert(maxOf(points) == new Point(1, 2));
  
  // Sort into a new List easily ( vs. iterable.toList()..sort() ).
  var sortedPoints = sorted(points);
  
  // Check ordering of iterables.
  assert(isOrdered(sortedPoints));
  assert(isStrictlyOrdered(sortedPoints));

  // Define comparators using combinator helpers...
  
  // By key function
  var byMagnitude = by((point) => point.magnitude);
  assert(max(Point.ZERO, new Point(-1, -1), 
      compare: byMagnitude) == new Point(-1, -1));
  
  // Compound
  assert(max(Point.ZERO, new Point(-1, -1), 
      compare: compound([byMagnitude, Comparable.compare])) == new Point(-1, -1));
  
  // Reversed
  assert(max(Point.ZERO, Point.UNIT, compare: reverse()) == Point.ZERO);

  // Lexicographic
  assert(min([Point.ZERO, Point.UNIT], [Point.ZERO, new Point(2, 2)], 
      compare: lexicographic()).last == Point.UNIT);
  
  // Null safe
  var maybePoints = [Point.UNIT, null, Point.ZERO, null];
  assert(sorted(maybePoints, compare: nullsFirst()).first == null);
  assert(sorted(maybePoints, compare: nullsLast()).last == null);
}

// Mixin `Comparable`-based comparison operators with `Quantity`.
class Point extends Object with Quantity<Point> {
  
  static Point ZERO = new Point(0, 0);
  static Point UNIT = new Point(1, 1);
  
  final num x, y;
  
  num get magnitude => math.sqrt(x*x + y*y);
  
  Point(this.x, this.y);
  
  // Use comparator combinators`compound` and `by`.
  static final _comparator = compound([by((p) => p.x), by((p) => p.y)]);
  
  int compareTo(Point other) => _comparator(this, other);
  
  toString() => '($x, $y)';
}

example/example.dart

import 'package:contrast/contrast.dart';
import 'dart:math' as math;

main() {
  
  // Easily define comparison operators (see Point class below).
  assert(Point.ZERO < Point.UNIT);
  assert(Point.UNIT >= Point.ZERO);
  assert(Point.ZERO == new Point(0, 0));

  // Find extrema of arbitrary comparables.
  // (dart:math's min/max only work with numbers)
  assert(min(Point.ZERO, Point.UNIT) == Point.ZERO);
  assert(max(Point.ZERO, Point.UNIT) == Point.UNIT);
  assert(clamp(new Point(1, 2), Point.ZERO, Point.UNIT) == Point.UNIT);
  assert(between(new Point(0.5, 0.5), Point.ZERO, Point.UNIT));
  
  // Find extrema of iterables.
  var points = [Point.UNIT, new Point(1, 2), Point.ZERO, new Point(0, 1)];
  assert(minOf(points) == Point.ZERO);
  assert(maxOf(points) == new Point(1, 2));
  
  // Sort into a new List easily ( vs. iterable.toList()..sort() ).
  var sortedPoints = sorted(points);
  
  // Check ordering of iterables.
  assert(isOrdered(sortedPoints));
  assert(isStrictlyOrdered(sortedPoints));

  // Define comparators using combinator helpers...
  
  // By key function
  var byMagnitude = by((point) => point.magnitude);
  assert(max(Point.ZERO, new Point(-1, -1), 
      compare: byMagnitude) == new Point(-1, -1));
  
  // Compound
  assert(max(Point.ZERO, new Point(-1, -1), 
      compare: compound([byMagnitude, Comparable.compare])) == new Point(-1, -1));
  
  // Reversed
  assert(max(Point.ZERO, Point.UNIT, compare: reverse()) == Point.ZERO);

  // Lexicographic
  assert(min([Point.ZERO, Point.UNIT], [Point.ZERO, new Point(2, 2)], 
      compare: lexicographic()).last == Point.UNIT);
  
  // Null safe
  var maybePoints = [Point.UNIT, null, Point.ZERO, null];
  assert(sorted(maybePoints, compare: nullsFirst()).first == null);
  assert(sorted(maybePoints, compare: nullsLast()).last == null);
}

// Mixin `Comparable`-based comparison operators with `Quantity`.
class Point extends Object with Quantity<Point> {
  
  static Point ZERO = new Point(0, 0);
  static Point UNIT = new Point(1, 1);
  
  final num x, y;
  
  num get magnitude => math.sqrt(x*x + y*y);
  
  Point(this.x, this.y);
  
  // Use comparator combinators`compound` and `by`.
  static final _comparator = compound([by((p) => p.x), by((p) => p.y)]);
  
  int compareTo(Point other) => _comparator(this, other);
  
  toString() => '($x, $y)';
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  contrast: "^0.1.1"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or flutter packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


      import 'package:contrast/contrast.dart';
  
Version Uploaded Documentation Archive
0.1.1 Sep 23, 2014 Go to the documentation of contrast 0.1.1 Download contrast 0.1.1 archive
0.1.0 Sep 19, 2014 Go to the documentation of contrast 0.1.0 Download contrast 0.1.0 archive

Analysis

We analyzed this package on Jun 19, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0-dev.63.0
  • pana: 0.11.3

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
4 / 100
Health:
Code health derived from static analysis. [more]
3 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
0 / 100
Overall score:
Weighted score of the above. [more]
3
Learn more about scoring.

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:contrast/contrast.dart.

Suggestions

  • Maintain CHANGELOG.md.

    Changelog entries help clients to follow the progress in your code.

  • Package is too old.

    The package was released more than two years ago.

  • Fix analysis and formatting issues.

    Analysis or formatting checks reported 15 errors 7 hints.

    Strong-mode analysis of lib/src/comparators.dart failed with the following error:

    line: 14 col: 27
    The method tear-off 'compare' has type '(Comparable<dynamic>, Comparable<dynamic>) → int' that isn't of expected type '(dynamic, dynamic) → int'. This means its parameter or return type does not match what is expected.

    Strong-mode analysis of lib/src/extrema.dart failed with the following error:

    line: 8 col: 41
    The method tear-off 'compare' has type '(Comparable<dynamic>, Comparable<dynamic>) → int' that isn't of expected type '(dynamic, dynamic) → int'. This means its parameter or return type does not match what is expected.

    Similar analysis of the following files failed:

    • lib/src/ordered.dart (error)
    • lib/src/quantity.dart (error)
    • lib/src/sorted.dart (error)
    • lib/contrast.dart (hint)
  • The description is too short.

    Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

Dependencies

Package Constraint Resolved Available
Dev dependencies
quiver >=0.18.2 <0.20.0
unittest >=0.11.0+2 <0.12.0