Berry Int64 Library
A secure 64-bit integer implementation for Berry language on 32-bit architectures, specifically designed for embedded systems like ESP32.
Overview
This library provides comprehensive 64-bit integer support for Berry applications running on 32-bit platforms where native 64-bit integer operations are not available or efficient. It integrates seamlessly with Berry's type system and memory management.
Features
Core Functionality
- Complete 64-bit arithmetic: Addition, subtraction, multiplication, division, modulo
- Bitwise operations: Left/right shifts with defined behavior
- Comparison operations: All standard comparison operators
- Type conversions: From/to strings, integers, floats, bytes
- Memory efficient: Optimized for embedded systems
Security Features ✅
- Secure string parsing: Validates all string-to-integer conversions
- Overflow detection: Detects and reports arithmetic overflow
- Memory safety: Proper cleanup in all error paths
- Defined behavior: Eliminates undefined behavior in shift operations
- Input validation: Comprehensive validation of all inputs
Installation
PlatformIO
Add to your platformio.ini
:
lib_deps =
https://github.com/your-repo/berry_int64
Manual Installation
Copy the src/
directory contents to your Berry library path.
Usage
Basic Operations
# Create int64 values
var a = int64(42)
var b = int64("1234567890123456789")
var c = int64.fromu32(0xFFFFFFFF, 0x12345678)
# Arithmetic operations
var sum = a + b
var product = a * b
var quotient = b / a
# Comparisons
if a > b
print("a is greater")
end
# Type conversions
print(a.tostring())
print(a.toint()) # Convert to int32 (if in range)
print(a.tobool()) # Convert to boolean
Advanced Features
# Bitwise operations
var shifted = a << 10
var masked = b >> 5
# Byte operations
var bytes_data = a.tobytes()
var from_bytes = int64.frombytes(bytes_data)
# Range checking
if a.isint()
var safe_int = a.toint()
end
# Factory methods
var from_float = int64.fromfloat(3.14159)
var from_string = int64.fromstring("999999999999")
Error Handling
# The library provides comprehensive error handling
try
var invalid = int64("not_a_number")
except "value_error"
print("Invalid string format")
end
try
var overflow = int64.fromu32(0xFFFFFFFF, 0x7FFFFFFF) + int64(1)
except "overflow_error"
print("Arithmetic overflow detected")
end
try
var div_error = int64(10) / int64(0)
except "divzero_error"
print("Division by zero")
end
Security
This library has been thoroughly analyzed and hardened for security:
✅ Security Features
- Input Validation: All string inputs are validated using secure parsing
- Overflow Detection: Arithmetic operations detect and report overflow
- Memory Safety: No memory leaks, proper cleanup in all error paths
- Defined Behavior: Shift operations use wrapping to eliminate undefined behavior
- Error Reporting: Clear, specific error messages for debugging
🛡️ Security Testing
Run the security test suite:
load("security_tests.be")
The test suite validates:
- String parsing security (malformed inputs, overflow)
- Arithmetic overflow detection
- Shift operation defined behavior
- Division by zero protection
- Memory allocation robustness
- Buffer operation safety
API Reference
Constructors
int64() # Create int64 with value 0
int64(value) # Create from int, real, string, bool, or int64
int64.fromu32(low, high) # Create from two 32-bit values
int64.fromfloat(f) # Create from float
int64.fromstring(s) # Create from string (with validation)
int64.frombytes(bytes, idx) # Create from byte buffer
Instance Methods
.tostring() # Convert to string representation
.toint() # Convert to int32 (if in range)
.tobool() # Convert to boolean (non-zero = true)
.tobytes() # Convert to byte representation
.isint() # Check if value fits in int32
.low32() # Get low 32 bits as int32
.high32() # Get high 32 bits as int32
Operators
# Arithmetic
+, -, *, /, % # Standard arithmetic operators
-* (unary minus) # Negation
# Comparison
==, !=, <, <=, >, >= # All comparison operators
# Bitwise
<<, >> # Left and right shift (with wrapping)
Performance
Optimized for embedded systems:
- Memory efficient: ~24-32 bytes per int64 instance
- CPU optimized: Minimal overhead for arithmetic operations
- GC friendly: Integrates with Berry's garbage collector
- Cache efficient: Compact data structures
Compatibility
- Berry Version: Compatible with Berry mapping system
- Platforms: ESP32, ESP8266, and other 32-bit embedded platforms
- Frameworks: Arduino, ESP-IDF
- Memory: Minimum 4KB RAM recommended
Error Types
The library defines specific error types for different failure modes:
"value_error"
: Invalid input values (malformed strings, out of range)"overflow_error"
: Arithmetic overflow in operations"divzero_error"
: Division or modulo by zero"memory_error"
: Memory allocation failures
Testing
Basic Tests
# Run the original test suite
berry tests/int64.be
Security Tests
# Run security validation tests
berry tests/security_tests.be
Integration Tests
Test with your application to ensure proper integration with Berry's type system and garbage collector.
Contributing
When contributing to this library:
- Security First: All changes must maintain security properties
- Test Coverage: Add tests for new functionality
- Documentation: Update documentation for API changes
- Compatibility: Maintain backward compatibility where possible
License
MIT License - see LICENSE file for details.
Security Disclosure
If you discover security vulnerabilities, please report them responsibly:
- Do not create public issues for security vulnerabilities
- Contact the maintainers directly
- Provide detailed reproduction steps
- Allow time for fixes before public disclosure
Changelog
Version 1.1 (Security Hardened)
- ✅ SECURITY: Fixed memory leaks in error paths
- ✅ SECURITY: Replaced unsafe
atoll()
with validatedstrtoll()
- ✅ SECURITY: Added arithmetic overflow detection
- ✅ SECURITY: Eliminated undefined behavior in shift operations
- ✅ SECURITY: Added comprehensive input validation
- ✅ TESTING: Added security test suite
- ✅ DOCS: Added security documentation
Version 1.0 (Original)
- Basic 64-bit integer functionality
- Integration with Berry type system
- Comprehensive test suite