sugar 4.0.0
sugar: ^4.0.0 copied to clipboard
Forus Labs' standard library extension. Utilities for date-times, timezones, collections, monads & more.
Sugar - Standard Library Extension #
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>
. - 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()
synchronously. Other packages such astimezone
don't.flutter_native_timezone
detects the timezone asynchronously whileDateTime.timeZoneName
returns an ambiguous abbreviation that can refer to multiple timezones. Sugar provide a TZDB timezone identifier such asAsia/Singapore
. See List of timezone abbreviations. -
Sugar is less hassle to set up. You don't need to fiddle with assets. Simply create a
ZonedDateTime
. -
Sugar has (in theory) lower initialization cost. Other packages often parse the timezone information from binary files at runtime. We rely on code generation to eliminate IO during initialization completely.
-
Sugar has a better memory footprint. Other packages often load the entire TZ database into memory. We rely on lazy initialization to load only timezones actually used.
-
Sugar offers more than just
ZonedDateTime
. It aims to be a one-stop for your date-time needs. It offers classes such asLocalTime
&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.1.0
Import the library:
import 'package:sugar/sugar.dart';
Check out the documentation to get started.
Updating timezones #
This section is for maintainers. It describes how to update the embedded IANA database. It assumes that you are on macOS/Linux. The current version of the IANA database is 2025a.
$ chmod +x tool/refresh.sh
$ tool/refresh.sh