Module generic_size 

Generic Size Value Object

This module provides a generic, type-safe size value object system for the adaptive pipeline system. It uses phantom types to enforce compile-time size category safety while providing shared arithmetic operations and unit conversions.

Overview

The generic size system provides:

• Type Safety: Compile-time enforcement of size categories
• Unit Conversions: Automatic conversions between size units
• Arithmetic Operations: Safe arithmetic operations on sizes
• Zero-Cost Abstractions: Phantom types with no runtime overhead
• Validation: Category-specific size validation and constraints

Architecture

The size system follows Domain-Driven Design principles:

• Value Object: Immutable value object with equality semantics
• Type Safety: Phantom types prevent category mixing at compile time
• Rich Domain Model: Encapsulates size-related business logic
• Validation: Comprehensive validation of size values and constraints

Key Features

Type-Safe Size Categories

• File Sizes: Sizes for files and file operations
• Memory Sizes: Sizes for memory allocation and usage
• Network Sizes: Sizes for network bandwidth and data transfer
• Storage Sizes: Sizes for storage capacity and usage
• Custom Categories: Support for custom size categories

Unit Conversions

• Automatic Conversion: Automatic conversion between units
• Multiple Units: Support for bytes, KB, MB, GB, TB, PB
• Binary/Decimal: Support for both binary (1024) and decimal (1000) units
• Precision Handling: Proper handling of precision during conversions

Arithmetic Operations

• Addition: Add sizes of the same category
• Subtraction: Subtract sizes with underflow protection
• Multiplication: Multiply sizes by scalars
• Division: Divide sizes with division by zero protection

Usage Examples

Basic Size Creation

Unit Conversions

Arithmetic Operations

Type Safety Demonstration

Custom Size Categories

Size Validation and Constraints

Size Categories

Built-in Categories

• FileSizeCategory: For file sizes and file operations

  • Validation: Standard file size validation
  • Use case: File processing and storage

• MemorySizeCategory: For memory allocation and usage

  • Validation: Memory-specific constraints
  • Use case: Memory management and allocation

• NetworkSizeCategory: For network bandwidth and data transfer

  • Validation: Network-specific constraints
  • Use case: Network operations and bandwidth management

• StorageSizeCategory: For storage capacity and usage

  • Validation: Storage-specific constraints
  • Use case: Storage planning and management

Custom Categories

Create custom size categories by implementing the SizeCategory trait:

• Category Name: Unique identifier for the category
• Validation Logic: Custom validation rules
• Size Limits: Category-specific size limits

Unit Systems

Binary Units (Base 1024)

• Byte: 1 byte
• KiB: 1,024 bytes
• MiB: 1,048,576 bytes
• GiB: 1,073,741,824 bytes
• TiB: 1,099,511,627,776 bytes

Decimal Units (Base 1000)

• Byte: 1 byte
• KB: 1,000 bytes
• MB: 1,000,000 bytes
• GB: 1,000,000,000 bytes
• TB: 1,000,000,000,000 bytes

Arithmetic Operations

Supported Operations

• Addition: size1 + size2
• Subtraction: size1 - size2 (with underflow protection)
• Multiplication: size * scalar
• Division: size / scalar (with division by zero protection)

Safety Features

• Overflow Protection: Detect and handle arithmetic overflow
• Underflow Protection: Prevent negative sizes
• Division by Zero: Prevent division by zero
• Type Safety: Ensure operations are on same category

Validation Rules

General Validation

• Non-negative: Sizes must be non-negative
• Finite: Sizes must be finite values
• Range Limits: Sizes must be within valid ranges

Category-Specific Validation

• File Sizes: Validate against file system limits
• Memory Sizes: Validate against available memory
• Network Sizes: Validate against bandwidth limits
• Custom Categories: Apply custom validation rules

Error Handling

Size Errors

• Invalid Size: Size value is invalid
• Overflow: Arithmetic operation caused overflow
• Underflow: Arithmetic operation caused underflow
• Division by Zero: Division by zero attempted

Validation Errors

• Constraint Violation: Size violates category constraints
• Range Error: Size is outside valid range
• Type Error: Invalid size type or category

Performance Considerations

Memory Usage

• Compact Storage: Efficient storage of size values
• Zero-Cost Types: Phantom types have no runtime cost
• Efficient Arithmetic: Optimized arithmetic operations

Conversion Performance

• Fast Conversions: Efficient unit conversions
• Minimal Allocations: Avoid unnecessary allocations
• Cached Results: Cache expensive conversion results

Integration

The generic size system integrates with:

• File System: File size management and validation
• Memory Management: Memory allocation and tracking
• Network Operations: Bandwidth and transfer size management
• Storage Systems: Storage capacity planning and monitoring

Thread Safety

The generic size system is thread-safe:

• Immutable: Sizes are immutable after creation
• Safe Sharing: Safe to share between threads
• Concurrent Operations: Safe concurrent arithmetic operations

Future Enhancements

Planned enhancements include:

• More Unit Types: Support for additional unit types
• Precision Control: Better precision control for conversions
• Performance Optimization: Further performance optimizations
• Enhanced Validation: More sophisticated validation rules

Structs

FileSizeMarker

Marker type for file sizes

GenericSize

Generic size value object with type-safe size categories

MemorySizeMarker

Marker type for memory sizes

NetworkSizeMarker

Marker type for network transfer sizes

StorageSizeMarker

Marker type for storage capacity sizes

Traits

SizeCategory

Size category trait for type-specific behavior

Type Aliases

FileSize

Type aliases for common size types

MemorySize

NetworkSize

StorageSize