242 lines
6.8 KiB
Markdown
242 lines
6.8 KiB
Markdown
# 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`:
|
|
```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
|
|
```berry
|
|
# 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
|
|
```berry
|
|
# 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
|
|
```berry
|
|
# 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:
|
|
```berry
|
|
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
|
|
```berry
|
|
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
|
|
```berry
|
|
.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
|
|
```berry
|
|
# 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
|
|
```bash
|
|
# Run the original test suite
|
|
berry tests/int64.be
|
|
```
|
|
|
|
### Security Tests
|
|
```bash
|
|
# 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:
|
|
|
|
1. **Security First**: All changes must maintain security properties
|
|
2. **Test Coverage**: Add tests for new functionality
|
|
3. **Documentation**: Update documentation for API changes
|
|
4. **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:
|
|
1. Do not create public issues for security vulnerabilities
|
|
2. Contact the maintainers directly
|
|
3. Provide detailed reproduction steps
|
|
4. 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 validated `strtoll()`
|
|
- ✅ **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
|