Human Readable Formats

A comprehensive pure Dart package to format raw data into human-readable text. From basic numbers and dates to advanced scientific notation, geographic coordinates, network data, and complex data structures - this package provides 60+ specialized formatting functions. Platform-independent with no Flutter dependencies.

Brought to you by SDKWala

This project is an open-source initiative by SDKWala, a company dedicated to creating high-quality, developer-friendly SDKs and open-source projects.

• Website: www.sdkwala.com
• GitHub: https://github.com/sdkwala

Features

📊 Core Data Formatting

• Numbers: Format numbers with localization, ordinals, compact notation (e.g., "1.2K", "3rd", "1,234.56")
• File Sizes: Format bytes with SI/IEC standards (e.g., "1.5 MB", "2.3 GiB")
• Durations: Format time spans in multiple styles (e.g., "2h 30m", "2 hours and 30 minutes")
• Dates & Times: Friendly date formatting (e.g., "Today at 3:45 PM", "2 days ago")
• Percentages & Ratios: Format numbers as percentages or ratios (e.g., "75%", "3 out of 4")
• Currencies: Format monetary values with proper symbols and localization

🌐 Network & Technical

• Network Data: Bandwidth, latency, data rates, IP addresses, MAC addresses, URLs
• Protocols: HTTP status codes, network protocols, DNS records, SSL certificates
• Performance: Speed tests, packet loss, signal strength, WiFi channels

🗺️ Geographic & Mapping

• Coordinates: Decimal degrees, DMS, UTM, What3Words formatting
• Distances & Areas: Smart unit conversion (km/mi, m²/ft², etc.)
• Elevations: Height formatting with appropriate units
• Navigation: Bearings, magnetic declination, GPS accuracy
• Locations: Addresses, bounding boxes, timezones, regions

🔬 Scientific & Technical

• Scientific Notation: Unicode exponents and engineering notation
• Physical Units: Energy, power, voltage, current, resistance, capacitance
• Chemistry: Chemical formulas with proper subscripts (H₂O, C₆H₁₂O₆)
• Physics: Wavelengths, frequencies, temperatures, pressures
• Mathematics: Mathematical expressions with superscripts and subscripts

📋 Data Structures

• Structured Data: JSON, XML, CSV with proper formatting and alignment
• Tables: ASCII/Unicode tables with borders and indexing
• Trees & Hierarchies: Visual tree structures and hierarchical data
• Lists & Matrices: Formatted lists (bullet/numbered) and 2D arrays

🌍 Localization & Configuration

• Multi-language: Built-in English and Spanish support
• Global Configuration: Set defaults for locale, decimal places, and standards
• Fluent API: Chainable builder pattern for complex formatting

Installation

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

dependencies:
  human_readable_formats: ^0.1.0  # Check for the latest version

Then, run dart pub get.

Quick Start

import 'package:human_readable_formats/human_readable_formats.dart';

void main() {
  // Format file sizes
  print(humanizeFileSize(1572864)); // "1.5 MiB"
  
  // Format durations
  print(humanizeDuration(const Duration(hours: 2, minutes: 30))); // "2h 30m"
  
  // Format friendly dates
  final now = DateTime.now();
  print(humanizeFriendlyDate(now)); // "Today"
  
  // Format percentages
  print(humanizePercentage(0.75)); // "75%"
  
  // Format ratios
  print(humanizeRatio(3, 4)); // "3 out of 4"
}

Comprehensive Usage

Core Data Formatting

Numbers & File Sizes

import 'package:human_readable_formats/human_readable_formats.dart';

// Numbers
print(humanizeNumber(1234567)); // "1,234,567"
print(humanizeCompactNumber(1234567)); // "1.2M"
print(humanizeOrdinal(3)); // "3rd"

// File Sizes
print(humanizeFileSize(1536)); // "1.5 KB"
print(humanizeFileSize(1073741824)); // "1.0 GB"
print(humanizeFileSize(1073741824, standard: FileSizeStandard.iec)); // "1.0 GiB"

Durations & Dates

// Durations
print(humanizeDuration(Duration(hours: 2, minutes: 30))); // "2h 30m"
print(humanizeDuration(Duration(hours: 2, minutes: 30), style: DurationStyle.long)); // "2 hours and 30 minutes"

// Friendly Dates
print(humanizeFriendlyDate(DateTime.now())); // "Today at 3:45 PM"
print(humanizeFriendlyDate(DateTime.now().subtract(Duration(hours: 2)), style: FriendlyDateStyle.relative)); // "2 hours ago"

Percentages & Currencies

// Percentages & Ratios
print(humanizePercentage(0.75)); // "75%"
print(humanizeRatio(3, 4)); // "3 out of 4"

// Currencies
print(humanizeCurrency(1234.56, 'USD')); // "$1,234.56"
print(humanizeCurrency(1234.56, 'EUR')); // "€1,234.56"

Network & Technical Formatting

// Network Data
print(humanizeBandwidth(1048576)); // "1.0 Mbps"
print(humanizeLatency(45)); // "45 ms"
print(humanizeDataRate(1073741824)); // "1.0 GB/s"

// IP Addresses & URLs
print(humanizeIPAddress('192.168.1.1')); // "192.168.1.1 (Private)"
print(humanizeMACAddress('00:1B:44:11:3A:B7')); // "00:1B:44:11:3A:B7 (Dell Inc.)"
print(humanizeURL('https://api.example.com/v1/users?page=1')); // "api.example.com/v1/users"

// Network Performance
print(humanizeSpeedTest(downloadSpeed: 50000000, uploadSpeed: 10000000, ping: 25)); 
// "Download: 50.0 Mbps, Upload: 10.0 Mbps, Ping: 25 ms"

print(humanizeSignalStrength(-65)); // "Good (-65 dBm)"
print(humanizeWiFiChannel(6)); // "Channel 6 (2.437 GHz)"

Geographic & Mapping

// Coordinates
print(humanizeCoordinates(40.7128, -74.0060)); // "40.7128°N, 74.0060°W"
print(humanizeCoordinatesDMS(40.7128, -74.0060)); // "40°42'46\"N, 74°0'22\"W"

// Distances & Areas
print(humanizeDistance(1500)); // "1.5 km"
print(humanizeDistance(500, unit: DistanceUnit.feet)); // "1,640 ft"
print(humanizeArea(1000000)); // "1.0 km²"

// Navigation & Location
print(humanizeBearing(45.5)); // "45.5° NE"
print(humanizeElevation(1500)); // "1,500 m"
print(humanizeTimezone('America/New_York')); // "Eastern Time (UTC-5)"

Scientific & Technical

// Scientific Notation
print(humanizeScientificNotation(1234.5)); // "1.235 × 10³"
print(humanizeEngineeringNotation(1234500)); // "1.235 × 10⁶"

// Chemistry & Physics
print(humanizeChemicalFormula('H2O')); // "H₂O"
print(humanizeChemicalFormula('C6H12O6')); // "C₆H₁₂O₆"
print(humanizeMathExpression('x^2 + y^2 = z^2')); // "x² + y² = z²"

// Physical Units
print(humanizeEnergy(1000)); // "1.0 kJ"
print(humanizePower(1500)); // "1.5 kW"
print(humanizeTemperature(273.15)); // "273.1 K"
print(humanizePressure(101325)); // "101.33 kPa"
print(humanizeWavelength(550e-9)); // "550 nm"

Data Structures

// JSON & XML
Map<String, dynamic> data = {'name': 'John', 'age': 30, 'city': 'NYC'};
print(humanizeJSON(data));
// {
//   "name": "John",
//   "age": 30,
//   "city": "NYC"
// }

// Tables
List<List<String>> tableData = [
  ['Name', 'Age', 'City'],
  ['John', '30', 'NYC'],
  ['Jane', '25', 'LA']
];
print(humanizeTable(tableData));
// ┌──────┬─────┬─────┐
// │ Name │ Age │ City│
// ├──────┼─────┼─────┤
// │ John │ 30  │ NYC │
// │ Jane │ 25  │ LA  │
// └──────┴─────┴─────┘

// Trees & Hierarchies
Map<String, dynamic> tree = {
  'root': {
    'child1': {},
    'child2': {'grandchild': {}}
  }
};
print(humanizeTree(tree));
// └── root
//     ├── child1
//     └── child2
//         └── grandchild

// Lists & Matrices
print(humanizeListStructure(['item1', 'item2', 'item3'], style: ListStyle.bullet));
// • item1
// • item2
// • item3

List<List<int>> matrix = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
print(humanizeMatrix(matrix));
// [1, 2, 3]
// [4, 5, 6]
// [7, 8, 9]

Global Configuration

Set default values that apply throughout your app:

void main() {
  // Set global defaults
  HumanReadableConfig.instance
    ..locale = 'es'  // Default to Spanish
    ..decimalPlaces = 2
    ..fileSizeStandard = FileSizeStandard.si;
    
  // Now all formatting functions will use these defaults
  print(humanizeFileSize(1000)); // "1.00 KB" (SI units)
  print(humanizePercentage(0.5)); // "50.00%"
}

Migration Guide

From v0.0.x to v0.1.0

The package has been significantly updated with new features and improvements. Here are the key changes:

1. New Features:

   • Added file size formatting with support for SI and IEC standards
   • Added duration formatting with short and long styles
   • Added friendly date formatting
   • Added percentage and ratio formatting
   • Added localization support (English and Spanish)
   • Added global configuration
   • Added fluent builder API

2. Breaking Changes:

   • Removed Flutter widget dependencies (now pure Dart)
   • Moved to using FileSizeStandard enum instead of boolean flags
   • Changed default decimal places behavior to be more intuitive

3. Migration Steps:

   • Update your imports if you were using Flutter-specific widgets
   • If you were using custom formatting, update to use the new builder API
   • Test your app thoroughly as the behavior of some formatters may have changed slightly

API Reference

Core Data Functions

Numbers

• humanizeNumber(num value, {String? locale}) - Format numbers with localization
• humanizeCompactNumber(num value, {int? decimalPlaces, String? locale}) - Compact notation (1.2K, 3.4M)
• humanizeOrdinal(int number, {String? locale}) - Ordinal numbers (1st, 2nd, 3rd)

File Sizes

• humanizeFileSize(int bytes, {int? decimalPlaces, FileSizeStandard? standard, String? locale})
• FileSizeFormatter class with fluent API

Durations & Dates

• humanizeDuration(Duration duration, {DurationStyle? style, int? maxUnits, String? locale})
• humanizeFriendlyDate(DateTime date, {FriendlyDateStyle? style, TimeFormat? timeFormat, String? locale})
• DurationFormatter and FriendlyDateFormatter classes with fluent APIs

Percentages & Currencies

• humanizePercentage(double value, {int? decimalPlaces, String? symbol, String? locale})
• humanizeRatio(int numerator, int denominator, {RatioStyle? style, String? locale})
• humanizeCurrency(double amount, String currencyCode, {int? decimalPlaces, String? locale})

Network & Technical Functions

Network Data

• humanizeBandwidth(int bitsPerSecond, {int? decimalPlaces}) - Format bandwidth
• humanizeLatency(int milliseconds) - Format network latency
• humanizeDataRate(int bytesPerSecond, {int? decimalPlaces}) - Format data transfer rates
• humanizePacketLoss(double percentage) - Format packet loss percentage

Network Addresses

• humanizeIPAddress(String ipAddress) - Format IP addresses with type detection
• humanizeMACAddress(String macAddress) - Format MAC addresses with vendor lookup
• humanizeURL(String url, {bool showProtocol = false}) - Clean URL formatting

Network Performance

• humanizeSpeedTest({required int downloadSpeed, required int uploadSpeed, required int ping})
• humanizeSignalStrength(int dbm) - WiFi/cellular signal strength
• humanizeWiFiChannel(int channel) - WiFi channel with frequency

Geographic Functions

Coordinates

• humanizeCoordinates(double latitude, double longitude, {int? precision})
• humanizeCoordinatesDMS(double latitude, double longitude) - Degrees, Minutes, Seconds
• humanizeUTMCoordinates(double easting, double northing, int zone, String band)
• humanizeWhat3Words(String words) - What3Words address formatting

Distances & Areas

• humanizeDistance(double meters, {DistanceUnit? unit, int? decimalPlaces})
• humanizeArea(double squareMeters, {AreaUnit? unit, int? decimalPlaces})
• humanizeElevation(double meters, {ElevationUnit? unit})

Navigation & Location

• humanizeBearing(double degrees) - Compass bearing with direction
• humanizeGPSAccuracy(double meters) - GPS accuracy description
• humanizeTimezone(String timezone) - Timezone with UTC offset
• humanizeAddress(Map<String, String> components) - Structured address formatting

Scientific Functions

Scientific Notation

• humanizeScientificNotation(double value, {int? precision}) - Unicode scientific notation
• humanizeEngineeringNotation(double value, {int? precision}) - Engineering notation
• humanizePhysicalConstant(String constant) - Physical constants with proper formatting

Chemistry & Physics

• humanizeChemicalFormula(String formula) - Chemical formulas with subscripts
• humanizeMathExpression(String expression) - Math expressions with super/subscripts
• humanizeWavelength(double meters) - Wavelength with appropriate units
• humanizeFrequency(double hertz) - Frequency with appropriate units

Physical Units

• humanizeEnergy(double joules, {EnergyUnit? unit}) - Energy formatting
• humanizePower(double watts, {PowerUnit? unit}) - Power formatting
• humanizeVoltage(double volts) - Voltage formatting
• humanizeCurrent(double amperes) - Current formatting
• humanizeResistance(double ohms) - Resistance formatting
• humanizeCapacitance(double farads) - Capacitance formatting
• humanizeTemperature(double kelvin, {TemperatureUnit? unit}) - Temperature formatting
• humanizePressure(double pascals, {PressureUnit? unit}) - Pressure formatting

Data Structure Functions

Structured Data

• humanizeJSON(dynamic data, {int? indent, bool sortKeys = false}) - Pretty JSON formatting
• humanizeXML(String xml, {int? indent}) - Pretty XML formatting
• humanizeCSV(List<List<String>> data, {String delimiter = ','}) - CSV formatting

Tables & Lists

• humanizeTable(List<List<String>> data, {TableStyle? style, bool showIndex = false})
• humanizeListStructure(List<dynamic> list, {ListStyle? style, bool allowNesting = true})
• humanizeKeyValuePairs(Map<String, dynamic> data, {String separator = ': '})

Trees & Hierarchies

• humanizeTree(Map<String, dynamic> tree, {TreeStyle? style}) - Visual tree structures
• humanizeHierarchy(Map<String, dynamic> hierarchy, {int maxDepth = 5})
• humanizeMatrix(List<List<dynamic>> matrix, {MatrixStyle? style})

Enums & Configuration

Standards & Units

• FileSizeStandard: si, iec
• DistanceUnit: meters, kilometers, feet, miles, nauticalMiles
• AreaUnit: squareMeters, squareKilometers, squareFeet, acres
• TemperatureUnit: kelvin, celsius, fahrenheit
• PressureUnit: pascals, kilopascals, atmospheres, bars

Styles & Formats

• DurationStyle: short, long, compact
• FriendlyDateStyle: friendly, relative
• ListStyle: bullet, numbered, dash
• TableStyle: ascii, unicode, minimal
• TreeStyle: unicode, ascii

Builder API

Use the HumanFormatter class for a fluent API:

final formatted = HumanFormatter()
  ..locale('es')
  ..decimalPlaces(2)
  .humanizeFileSize(1572864);

Localization

The package includes built-in support for English (default) and Spanish. To add support for additional languages, you can implement the HumanReadableLocalizations interface.

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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