Jiffy

By default, locales have a defined start of the week (e.g., en_US uses StartOfWeek.sunday). You can override this globally using Jiffy.setLocale with the startOfWeek parameter, which accepts values from the StartOFWeek enum (e.g., StartOFWeek.monday, StartOFWeek.saturday).

await Jiffy.setLocale(
    locale: 'en_US',
    startOfWeek: StartOFWeek.saturday,
);

You can modify Jiffy instances using .add() and .subtract() with various time units (days, hours, minutes, months, etc.). You can also snap a date to the start or end of a specific time unit using .startOf(Unit) and .endOf(Unit) most common units are Unit.yearandUnit.month`.

// Adding and subtracting
var jiffy = Jiffy.now().add(days: 1);
var complex = Jiffy.now()
  .add(hours: 3, days: 1)
  .subtract(minutes: 30, months: 1);

// Setting boundaries
Jiffy.parse('1997/09/23').startOf(Unit.year);
Jiffy.parse('1997/09/23').endOf(Unit.month);

Jiffy allows you to express the difference between two dates in human-readable relative terms (e.g., "5 years ago" or "in 5 years").

• Use .from(otherJiffy) or .fromNow() to calculate time elapsed from a point in the past.
• Use .to(otherJiffy) or .toNow() to calculate time remaining until a point in the future.

// From a specific date
Jiffy.parse('1997/09/23').from(Jiffy.parse('2002/10/26')); // 5 years ago

// From now
Jiffy.parse('1997/09/23').fromNow(); // 25 years ago

// To a specific date
Jiffy.parse('1997/09/23').to(Jiffy.parse('2002/10/26')); // in 5 years

// To now
Jiffy.parse('1997/09/23').toNow(); // in 25 years

Jiffy supports all locales provided by the intl package. Note: Jiffy.setLocale always returns a Future and must be awaited.

Basic Locale Setting

To change the global locale for Jiffy:

await Jiffy.setLocale('fr');

Advanced Locale Configuration

You can provide a custom configuration object to override default behaviors for a locale, such as the start of the week, ordinal suffixes, and relative date-time formatting.

await Jiffy.setLocale(
  locale: 'en_US',
  startOfWeek: StartOFWeek.monday,
  ordinals: Ordinals(first: "st", second: "nd", third: "rd", nth: "th"),
  relativeDateTime: EnRelativeDateTime()
);

Use comparison methods to check the relationship between two Jiffy instances:

• .isBefore(other): Returns true if the instance is before the provided date.
• .isAfter(other): Returns true if the instance is after the provided date.
• .isSame(other): Returns true if the instances represent the same time.
• .isBetween(start, end): Returns true if the instance falls within the range of the two provided dates.

Jiffy.parse('1997/9/23').isBefore(Jiffy.parse('1997/9/24')); // true
Jiffy.parse('1997/9/23').isAfter(Jiffy.parse('1997/9/20')); // true
Jiffy.parse('1997/9/23').isSame(Jiffy.parse('1997/9/23')); // true
Jiffy.parse('1997/9/23').isBetween(Jiffy.parse('1997/9/20'), Jiffy.parse('1997/9/24')); // true

Jiffy provides multiple ways to format dates into human-readable strings. You can use the .format() method with a custom pattern or use convenient pre-set getter properties (like .yMMMMd) for common formats.

Parsing can be done from strings, lists, or maps. When parsing a string with a non-standard format, provide the pattern to the parse method.

// Custom patterns
Jiffy.parse('2021/01/19').format(pattern: 'MMMM do yyyy, h:mm:ss a'); 
Jiffy.now().format(pattern: 'EEEE'); 

// Pre-set formats (getters)
Jiffy.parseFromList([2020, 10, 19]).yMMMMd; 

// Parsing from a Map using Unit enum
Jiffy.parseFromMap({
  Unit.year: 2020,
  Unit.month: 10,
  Unit.day: 19,
  Unit.hour: 19
}).dMMMMEEEEyjm;

// Parsing with a specific pattern
Jiffy.parse('19, Jan 2021', pattern: 'dd, MMM yyyy').yMMMMd;

Ordinals are suffixes like 'st', 'nd', 'rd', and 'th' used in date formatting (e.g., '1st'). If a locale's default ordinals are not suitable or supported, you can provide a custom Ordinals object when calling Jiffy.setLocale.

await Jiffy.setLocale(
    locale: 'en_US',
    ordinals: Ordinals(first: "st", second: "nd", third: "rd", nth: "th"),
);

Jiffy supports localization for date formatting. You can check the current locale using .localeCode and change the global locale for all subsequent Jiffy operations using the asynchronous await Jiffy.setLocale(localeCode) method. Supported locale codes include en_US, fr_ca, ja, and zh_cn.

// Get current locale
String code = Jiffy.now().localeCode; 

// Set a new locale
await Jiffy.setLocale('fr_ca');
Jiffy.now().yMMMMEEEEdjm; // dimanche 26 février 2023 12 h 03

await Jiffy.setLocale('ja');
Jiffy.now().yMMMMEEEEdjm; // 2023年2月26日日曜日 12:02

Relative date-time expresses time differences in human-readable formats (e.g., '14 years ago'). To customize this behavior, you can create a class that extends the RelativeDateTime abstract class or extends an existing implementation like EnRelativeDateTime.

Extending RelativeDateTime (Full Customization)

Implement all required methods like prefixAgo, suffixAgo, minutes, hours, etc.

Extending EnRelativeDateTime (Partial Customization)

Override only the specific methods you wish to change.

class CustomRelativeDateTime extends EnRelativeDateTime {
  @override
  String suffixAgo() => 'ago, i think';
  @override
  String aDay(int hours) => 'like a day';
}

await Jiffy.setLocale(
    locale: 'en_US',
    relativeDateTime: CustomRelativeDateTime(),
);

In Jiffy, a Locale object encapsulates all internationalization rules for a specific language and region. When implementing or extending locale support, a Locale must define four key components:

1. code: A unique string identifier (e.g., "en_US", "fr_CA").
2. startOfWeek: A StartOfWeek enum value indicating which day the week begins for that locale.
3. ordinals: An Ordinals object containing the suffixes used for ordinal numbers (e.g., "st", "nd", "rd", "th").
4. relativeDateTime: A RelativeDateTime instance that defines the rules for formatting relative time strings (e.g., "3 hours ago" or "in 2 days").

Use Jiffy.setLocale to set the global locale for Jiffy instances. This affects date formatting, relative time strings, and the start of the week. You can also customize startOfWeek, ordinals, and relativeDateTime settings during setup.

Supported locales can be retrieved using Jiffy.getSupportedLocales().

await Jiffy.setLocale('en_US');
await Jiffy.setLocale('en_US', startOfWeek: StartOfWeek.monday);

final supportLocales = Jiffy.getSupportedLocales();
print(supportLocales); // ['en_us', 'en', 'fr', ...]