Sugar - Standard Library Extension

Sugar Codecov Pub Dev Documentation

Sugar is an extension to Dart's standard library.

It provides the following (and much more!):

  • Date-time and timezone API inspired by java.time.
  • Monads such as Result<S,F> & Maybe<T>.
  • Syntax sugar for aggregating & manipulating collections.
  • Types for representing and working with ranges & intervals.

It consolidates several micro-packages that provide bits and pieces of date-time & timezone utilities into a single package.

Why Sugar's date-time API over other packages?

  • Sugar is able to detect the platform's timezone, ZonedDateTime.now(). Other packages such as timezone or even Dart's standard library don't. DateTime.timeZoneName returns an ambiguous abbreviation that can refer to multiple timezones. We provide a TZ database timezone identifier such as Asia/Singapore. See List of timezone abbreviations.

  • Sugar is less hassle to set up. You don't need to fiddle with assets or asynchronously initialize the package. Simply create a ZonedDateTime.

  • Sugar has (in theory) zero initialization cost & a better memory footprint. Other packages often parse the timezone information from binary files at runtime. We rely on code generation to eliminate IO completely. Other packages often load the entire TZ database into memory. We rely on lazy initialization to load only timezones you use, reducing memory footprint.

  • Sugar handles DST transitions similar to other packages such as Java, Python & C#. Other packages such as timezone don't. This can be an issue when interacting between a back-end written in one of those languages and a front-end written in Dart.

  • Sugar offers more than just ZonedDateTime. It offers classes such as LocalTime & Period, and utilities such as retrieving the ordinal week of the year.

Getting Started

Run the following command:

dart pub add sugar

Alternatively, add Sugar as a dependency in your pubspec:

dependencies:
  sugar: ^ 3.0.0

Import the library:

import 'package:sugar/sugar.dart';

Check out the documentation to get started.

Libraries

Sugar

sugar Sugar
Bundles and exports all other libraries.

Core

core Core
General purpose utilities for every Dart program.
core_range Core
Utilities for representing and manipulating a range of values in a domain.
core_runtime Core
Platform agnostic utilities for retrieving information about the current platform.
math Core
Utilities for performing numeric operations.

Collection

collection Collection
Non-aggregating utilities for working with collections.
collection_aggregate Collection
Utilities for aggregating and sorting collections.

Time

time Time
The main API for dates, times and timezones.
time_interop Time
A supplementary API to sugar.time for working with in-built and 3rd party date-times.
time_zone Time
Support for timezones and their rules.