quiver 0.25.0

Quiver

Quiver is a set of utility libraries for Dart that makes using many Dart libraries easier and more convenient, or adds additional functionality.

Build Status Coverage Status

Documentation

API Docs are available.

Installation

Add Quiver to your project's pubspec.yaml file and run pub get. We recommend the following version constraint:

dependencies:
  quiver: '>=0.25.0<0.26.0'

Main Libraries

quiver.async

Utilities for working with Futures, Streams and async computations.

collect collects the completion events of an Iterable of Futures into a Stream.

enumerate and concat represent Stream versions of the same-named quiver.iterables methods.

doWhileAsync, reduceAsync and forEachAsync perform async computations on the elements of on Iterables, waiting for the computation to complete before processing the next element.

StreamBuffer allows for the orderly reading of elements from a stream, such as a socket.

FutureGroup is collection of Futures that signals when all its child futures have completed. Allows adding new Futures as long as it hasn't completed yet. Useful when async tasks can spwn new async tasks and you need to wait for all of them to complete.

FutureStream turns a Future<Stream> into a Stream which emits the same events as the stream returned from the future.

StreamRouter splits a Stream into mulltiple streams based on a set of predicates.

CountdownTimer is a simple countdown timer that fires events in regular increments.

CreateTimer and CreateTimerPeriodic are typedefs that are useful for passing Timer factories to classes and functions, increasing the testability of code that depends on Timer.

Metronome is a self-correcting alternative to Timer.periodic. It provides a simple, tracking periodic stream of DateTime events with optional anchor time.

quiver.cache

Cache is a semi-persistent, asynchronously accessed, mapping of keys to values. Caches are similar to Maps, except that the cache implementation might store values in a remote system, so all operations are asynchronous, and caches might have eviction policies.

MapCache is a Cache implementation backed by a Map.

quiver.check

checkArgument throws ArgumentError if the specifed argument check expression is false.

checkListIndex throws RangeError if the specified index is out of bounds.

checkNotNull throws ArgumentError if the specified argument is null.

checkState throws StateError if the specifed state check expression is false.

quiver.collection

listsEqual, mapsEqual and setsEqual check collections for equality.

LruMap is a map that removes the least recently used item when a threshold length is exceeded.

Multimap is an associative collection that maps keys to collections of values.

BiMap is a bidirectional map and provides an inverse view, allowing lookup of key by value.

TreeSet is a balanced binary tree that offers a bidirectional iterator, the ability to iterate from an arbitrary anchor, and 'nearest' search.

quiver.core

Optional is a way to represent optional values without allowing null.

firstNonNull returns its first non-null argument.

hashObjects, hash2, hash3, and hash4 generate high-quality hashCodes for a list of objects, or 2, 3, or 4 arguments respectively.

quiver.io

visitDirectory is a recursive directory lister that conditionally recurses into sub-directories based on the result of a handler function.

quiver.iterables

concat, count, cycle, enumerate, merge, partition, range, and zip create, transform, or combine Iterables in different ways, similar to Python's itertools.

min, max, and extent retreive the minimum and maximum elements from an iterable.

GeneratingIterable is an easy way to create lazy iterables that produce elements by calling a function. A common use-case is to traverse properties in an object graph, like the parent relationship in a tree.

InfiniteIterable is a base class for Iterables that throws on operations that require a finite length.

quiver.mirrors

getTypeName returns the name of a Type instance.

implements and classImplements determine if an instance or ClassMirror, respectively, implement the interface represented by a Type instance. They implement the behavior of is for mirrors, except for generics.

getMemberMirror searches though a ClassMirror and its class hierarchy for a member. This makes up for the fact that ClassMirror.members doesn't contain members from interfaces or superclasses.

Method wraps an InstanceMirror and Symbol to create a callable that invokes a method on the instance. It in effect closurizes a method reflectively.

quiver.pattern

pattern.dart container utilities for work with Patterns and RegExps.

Glob implements glob patterns that are commonly used with filesystem paths.

matchesAny combines multiple Patterns into one, and allows for exclusions.

matchesFull returns true if a Pattern matches an entire String.

escapeRegex escapes special regex characters in a String so that it can be used as a literal match inside of a RegExp.

quiver.strings

isBlank checks if a string is null, empty or made of whitespace characters.

isEmpty checks if a string is null or empty.

equalsIgnoreCase checks if two strings are equal, ignoring case.

compareIgnoreCase compares two strings, ignoring case.

flip flips the order of characters in a string.

nullToEmpty turns null to empty string, and returns non-empty strings unchanged.

emptyToNull turns empty string to null, and returns non-empty strings unchanged.

repeat concatenates a string to itself a given number of times.

loop allows you to loop through characters in a string starting and ending at arbitrary indices. Out of bounds indices allow you to wrap around the string, supporting a number of use-cases, including:

  • Rotating: loop('lohel', -3, 2) => 'hello'
  • Repeating, like repeat, but with better character-level control, e.g.: loop('la ', 0, 8) => 'la la la' // no tailing space
  • Tailing: loop('/path/to/some/file.txt', -3) => 'txt'
  • Reversing: loop('top', 3, 0) => 'pot'

quiver.time

Clock provides points in time relative to the current point in time, for example: now, 2 days ago, 4 weeks from now, etc. For tesability, use Clock rather than other ways of accessing time, like new DateTime(), so that you can use a fake time function in your tests to control time.

Now is a typedef for functions that return the current time in microseconds, since Clock deals in DateTime which only have millisecond accuracy.

aMicrosecond, aMillisecond, aSecond, aMinute, anHour, aDay, and aWeek are unit duration constants to allow writing for example:

  • aDay vs. const Duration(days: 1)
  • aSecond * 30 vs. const Duration(seconds: 30)

Testing Libraries

The Quiver testing libraries are intended to be used in testing code, not production code. It currently consists of fake implementations of some Quiver interfaces.

quiver.testing.async

FakeAsync enables testing of units which depend upon timers and microtasks. It supports fake advancements of time and the microtask queue, which cause fake timers and microtasks to be processed. A Clock is provided from which to read the current fake time. Faking synchronous or blocking time advancement is also supported.

quiver.testing.equality

areEqualityGroups is a matcher that supports testing operator== and hashCode implementations.

quiver.testing.runtime

assertCheckedMode asserts the current runtime has checked mode enabled.

quiver.testing.time

FakeStopwatch is a Stopwatch that uses a provided now() function to get the current time.

0.25.0 - 2017-03-28

  • BREAKING CHANGE: minimum SDK constraint increased to 1.21.0. This allows use of async-await and generic function in Quiver.
  • BREAKING CHANGE: eliminated deprecated FakeTimer.
  • BREAKING CHANGE: StreamBuffer<T> now implements StreamConsumer<T> as opposed to StreamConsumer<T|List<T>>.
  • Deprecated: FutureGroup. Use the replacement in package:async which requires a close() call to trigger auto-completion when the count of pending tasks drops to 0.
  • Deprecated: repeat in the strings library. Use the * operator on the String class.
  • Deprecated: in the strings library, flip has been renamed reverse. flip is deprecated and will be removed in the next release.
  • Iterables: enumerate is now generic.
  • Collection: added indexOf.

0.24.0 - 2016-10-31

  • BREAKING CHANGE: eliminated deprecated nullToEmpty, emptyToNull.
  • Fix: Strong mode: As of Dart SDK 1.21.0, Set.difference takes a Set<Object> parameter.

0.23.0 - 2016-09-21

  • Strings: nullToEmpty, emptyToNull deprecated. Removal in 0.24.0.
  • BREAKING CHANGE: eliminated deprecated multimap toMap.
  • BREAKING CHANGE: eliminated deprecated pad*, trim* string functions.

0.22.0 - 2015-04-21

  • BREAKING CHANGE: streams and async libraries have been merged into one async library
  • BREAKING CHANGE: Pre-1.8.0 SDKs are no longer supported.
  • Quiver is now strong mode compliant
  • New: Optional now implements Iterable and its methods are generic (using temporary syntax)
  • New: isNotEmpty and isDigit in strings.dart
  • New: Multimap.fromIterable
  • Fix: Change TreeSearch from class to enum.
  • Fix: fake_async.dart timers are now active while executing the callback

0.21.4 - 2015-05-15

  • Add stats reporting for fake async tests. You can query the number of pending microtasks and timers via microtaskCount, periodicTimerCount, nonPeriodicTimerCount.

0.21.3+1 - 2015-05-11

  • Switch from unittest to test.

0.21.3 - 2015-03-03

  • Bugfix: fixed return type on some methods (e.g. where of Iterables returned by Multimap.

0.21.2 - 2015-03-03

  • Bugfix: fix drifting times in Metronome.
  • Add LruMap to quiver/collection.
  • Un-deprecate Glob; feedback was that package:glob was not a suitable replacement in many cases. Key reasons: dependency on dart:io and significantly poorer performance.

0.21.1 - 2015-02-05

  • Add optional start param to Glob.allMatches() to match superclass method signature.
  • Add optional start param to Pattern returned by matchesAny() to match superclass method signature.
  • Deprecate Glob. Use package:glob. Will be removed in 0.22.0.

0.21.0+3 - 2015-02-04

  • Travis CI integration support added.
  • Document that the deprecated functions padLeft, padRight, trimLeft, trimRight will be removed in 0.22.0.

0.21.0+2 - 2015-02-04

  • Fix hanging FakeAsync unit test.

0.21.0+1 - 2015-02-03

  • Replace equalsTester dependency on unittest with finer-grained dependency on matcher.
  • path is now a dev dependency.

0.21.0 - 2015-02-02

  • Multimap: toMap() is deprecated and replaced with asMap(). toMap() will be removed in v0.22.0.
  • Cleanup method signatures that were inconsistent with the core library.
  • Added areEqualityGroups matcher for testing operator== and hashCode.
  • CONTRIBUTING.md added.

0.20.0 - 2014-12-10

  • Multimap: better toString() on returned collections.
  • Multimap: Bugfix: support edits on empty value collections.
  • Multimap: Added missing return statment in fold.
  • Added isEmpty() in strings.
  • Added max SDK constraint <2.0.0
  • Minor updates to README.md.
  • CHANGELOG.md added

0.19.0+1 - 2014-11-12

  • Corrected version constraint suggestion in README.md.

1. Depend on it

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

dependencies:
  quiver: "^0.25.0"

2. Install it

You can install packages from the command line:

$ pub get

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

3. Import it

Now in your Dart code, you can use:

import 'package:quiver/async.dart';
import 'package:quiver/cache.dart';
import 'package:quiver/check.dart';
import 'package:quiver/collection.dart';
import 'package:quiver/core.dart';
import 'package:quiver/io.dart';
import 'package:quiver/iterables.dart';
import 'package:quiver/mirrors.dart';
import 'package:quiver/pattern.dart';
import 'package:quiver/strings.dart';
import 'package:quiver/time.dart';

About

A set of utility libraries for Dart

Author

Email justinfagnani@google.com Justin Fagnani
Email yjbanov@google.com Yegor Jbanov
Email cbracken@google.com Chris Bracken
Email alexandre.ardhuin@gmail.com Alexandre Ardhuin
Email davidmorgan@google.com David Morgan
Email codefu@google.com John McDole
Email matanl@google.com Matan Lurey
Email guenter@gzoechbauer.com Günter Zöchbauer
Email seaneagan1@gmail.com Sean Eagan
Email victor@suumit.com Victor Berchet
Email willyp@google.com Wil Pirino

Homepage

github.com/google/quiver-dart

Documentation

www.dartdocs.org/documentation/quiver/0.25.0/

Source code (hyperlinked)

www.crossdart.info/p/quiver/0.25.0/

Uploader

justinfagnani@google.com
cbracken@google.com
sethladd@google.com
jacobr@google.com
yjbanov@google.com

Published

Mar 28, 2017

Share