Format Amount Service

A Flutter library for formatting amounts and IBAN numbers with a clean, efficient singleton design pattern.

Features

• Amount Formatting: Convert numeric strings to display format with thousands separators
• Currency Conversion: Handle halalah to riyals conversion (Saudi currency)
• IBAN Formatting: Format IBAN numbers with proper spacing for readability
• Singleton Pattern: Memory-efficient single instance design
• Null Safety: Full null safety support
• Comprehensive Documentation: Well-documented with usage examples

Installation

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

dependencies:
  format_amount_service: ^2.0.0

Then run:

flutter pub get

Quick Start

import 'package:format_amount_service/format_amount_service.dart';

// Get the singleton instance
final formatter = FormatAmountService.instance;

// Format an amount
final formatted = formatter.formatAmount('100000'); // Returns "1,000.00"

// Format IBAN
final iban = formatter.formatIBAN('SA0380000000608010167519');
// Returns "SA03 8000 0000 6080 1016 7519"

Usage

Getting the Service Instance

// Get the singleton instance
final formatter = FormatAmountService.instance;

Formatting Amounts

// Format amount from halalah to riyals with thousands separators
final formatted = formatter.formatAmount('100000'); // Returns "1,000.00"
final largeAmount = formatter.formatAmount('100000000'); // Returns "1,000,000.00"
final smallAmount = formatter.formatAmount('50'); // Returns "0.50"

Extracting Amounts

// Get current amount from formatted string
final amount = formatter.getCurrentAmount('1,000.00'); // Returns 1000.0
final largeAmount = formatter.getCurrentAmount('1,000,000.00'); // Returns 1000000.0

Formatting IBAN

// Format IBAN with proper spacing
final iban = formatter.formatIBAN('SA0380000000608010167519');
// Returns "SA03 8000 0000 6080 1016 7519"

API Reference

FormatAmountService.instance

Returns the singleton instance of the service.

formatAmount(String value)

Formats a numeric string to display format.

Parameters:

• value (String): The numeric string to format (e.g., "100000")

Returns:

• String: Formatted amount with thousands separators (e.g., "1,000.00")

getCurrentAmount(String text)

Extracts the numeric amount from a formatted string.

Parameters:

• text (String): The formatted string (e.g., "1,000.00")

Returns:

• double?: The amount as a double (e.g., 1000.0)

formatIBAN(String value)

Formats an IBAN string with proper spacing.

Parameters:

• value (String): The IBAN string to format

Returns:

• String: The formatted IBAN with proper spacing

Currency Conversion

The service automatically handles conversion between halalah (the smallest currency unit) and riyals:

• Input: Amount in halalah (e.g., "100000" = 1000.00 riyals)
• Output: Formatted amount in riyals with thousands separators
• Conversion: 1 riyal = 100 halalah

Design Pattern

This service implements the Singleton Design Pattern:

• Private Constructor: Prevents direct instantiation
• Static Instance: Single shared instance across the application
• Memory Efficient: Only one instance exists in memory
• Thread Safe: Safe for concurrent access

Performance

• Efficient: Singleton pattern ensures minimal memory usage
• Fast: Optimized string operations and parsing
• Scalable: Single instance shared across the entire application

Contributing

We welcome contributions! Please see our contributing guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any problems or have suggestions, please file an issue at our GitHub repository.