ConvertConfig class

Global and scoped configuration bundle for all convert_object APIs.

ConvertConfig controls parsing behavior for numbers, dates, booleans, URIs, and custom types. A single global instance is active by default, but you can customize behavior in several ways:

• configure - Replace the global configuration entirely.
• update - Modify the global configuration incrementally.
• runScoped - Apply temporary overrides for a call tree (zone-scoped).

Example: Global Configuration

// Set locale globally
ConvertConfig.configure(ConvertConfig(locale: 'de_DE'));

// Update specific options
ConvertConfig.update((c) => c.copyWith(
  dates: c.dates.copyWith(autoDetectFormat: true),
));

Example: Scoped Configuration

ConvertConfig.runScoped(
  ConvertConfig.overrides(locale: 'fr_FR'),
  () {
    // All conversions in this block use French locale
    final date = Convert.toDateTime('15/03/2024', autoDetectFormat: true);
  },
);

See also:

• NumberOptions for numeric parsing configuration.
• DateOptions for date/time parsing configuration.
• BoolOptions for boolean parsing configuration.
• UriOptions for URI parsing and coercion.
• TypeRegistry for custom type parsers.

Annotations

• @immutable

Constructors

ConvertConfig({String? locale, NumberOptions numbers = const NumberOptions(), DateOptions dates = const DateOptions(), BoolOptions bools = const BoolOptions(), UriOptions uri = const UriOptions(), TypeRegistry registry = const TypeRegistry.empty(), ExceptionHook? onException})

Creates a new configuration bundle.

const

ConvertConfig.overrides({String? locale, bool clearLocale = false, NumberOptions? numbers, DateOptions? dates, BoolOptions? bools, UriOptions? uri, TypeRegistry? registry, ExceptionHook? onException, bool clearOnException = false})

Creates a config intended for scoped overrides.

factory

Properties

bools → BoolOptions

Configuration for boolean parsing.

final

dates → DateOptions

Configuration for date and time parsing and formatting.

final

hashCode → int

The hash code for this object.

no setter, inherited

locale → String?

The default locale identifier (e.g., 'en_US') used for parsing operations when no specific locale is provided in numbers or dates.

final

numbers → NumberOptions

Configuration for parsing and formatting numeric values.

final

onException → ExceptionHook?

An optional hook that is invoked whenever a ConversionException is thrown.

final

registry → TypeRegistry

A registry of custom parsers for handling additional types in Convert.toType.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

uri → UriOptions

Configuration for URI parsing.

final

Methods

copyWith({String? locale, NumberOptions? numbers, DateOptions? dates, BoolOptions? bools, UriOptions? uri, TypeRegistry? registry, ExceptionHook? onException}) → ConvertConfig

Returns a copy of this config with the provided fields replaced.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Properties

effective → ConvertConfig

The configuration that is currently in effect (global or zone-overridden).

no setter

Static Methods

configure(ConvertConfig config) → ConvertConfig

Replaces the global configuration and returns the previous instance.

runScoped<T>(ConvertConfig overrides, T body()) → T

Runs body with overrides merged on top of the effective config.

update(ConvertConfig updater(ConvertConfig current)) → void

Updates the global configuration by applying updater to the current instance.