Add skip

Author: mgenware

README.md

@@ -19,14 +19,29 @@ abstract class RandomAccessSource {
   Future<int> readByte();
 
   /// Reads an array of bytes from the source.
-  Future<Uint8List> read(int length);
+  Future<Uint8List> read(int count);
 
   /// Gets the current position in the source.
   Future<int> position();
 
   /// Sets the current position in the source.
   Future<void> seek(int position);
 
+  /// Reads all the remaining bytes from the source.
+  Future<Uint8List> readToEnd();
+
+  /// Skips a number of bytes in the source.
+  /// Returns the number of bytes actually skipped.
+  Future<int> skip(int count);
+
+  /// Reads a specific number of bytes, ensuring that the exact number is read.
+  /// Throws an exception if the number of bytes read is not equal to [length].
+  Future<Uint8List> mustRead(int length);
+
+  /// Skips a specific number of bytes, ensuring that the exact number is skipped.
+  /// Throws an exception if the number of bytes skipped is not equal to [length].
+  Future<void> mustSkip(int length);
+
   /// Closes the source.
   Future<void> close();
 }

lib/src/bytes_ra_source.dart

@@ -22,8 +22,8 @@ class BytesRASource extends RandomAccessSource {
   }
 
   @override
-  Future<Uint8List> read(int length) async {
-    return _syncSource.read(length);
+  Future<Uint8List> read(int count) async {
+    return _syncSource.read(count);
   }
 
   @override

lib/src/file_ra_source.dart

@@ -24,8 +24,8 @@ class FileRASource extends RandomAccessSource {
   }
 
   @override
-  Future<Uint8List> read(int length) async {
-    return _file.read(length);
+  Future<Uint8List> read(int count) async {
+    return _file.read(count);
   }
 
   @override

lib/src/random_access_source.dart

@@ -9,7 +9,7 @@ abstract class RandomAccessSource {
   Future<int> readByte();
 
   /// Reads an array of bytes from the source.
-  Future<Uint8List> read(int length);
+  Future<Uint8List> read(int count);
 
   /// Gets the current position in the source.
   Future<int> position();
@@ -20,8 +20,20 @@ abstract class RandomAccessSource {
   /// Reads all the remaining bytes from the source.
   Future<Uint8List> readToEnd();
 
-  /// Closes the source.
-  Future<void> close();
+  /// Skips a number of bytes in the source.
+  /// Returns the number of bytes actually skipped.
+  Future<int> skip(int count) async {
+    final currentPosition = await position();
+    final fileLength = await length();
+
+    // Calculate the target position clamped within the file boundaries
+    final targetPosition = (currentPosition + count).clamp(0, fileLength);
+    await seek(targetPosition);
+
+    // Calculate the actual bytes skipped
+    final actualSkipped = targetPosition - currentPosition;
+    return actualSkipped;
+  }
 
   /// Reads a specific number of bytes, ensuring that the exact number is read.
   /// Throws an exception if the number of bytes read is not equal to [length].
@@ -32,4 +44,16 @@ abstract class RandomAccessSource {
     }
     return bytes;
   }
+
+  /// Skips a specific number of bytes, ensuring that the exact number is skipped.
+  /// Throws an exception if the number of bytes skipped is not equal to [length].
+  Future<void> mustSkip(int length) async {
+    final count = await skip(length);
+    if (count != length) {
+      throw Exception('Failed to skip $length bytes, skipped $count bytes');
+    }
+  }
+
+  /// Closes the source.
+  Future<void> close();
 }

test/bytes_test.dart

@@ -75,4 +75,28 @@ void main() {
     expect(await src.position(), 5);
     await src.close();
   });
+
+  test('Skip (less than available)', () async {
+    final src = await _bytesSource();
+    expect(await src.skip(2), 2);
+    expect(await src.position(), 2);
+    expect(await src.readByte(), 3);
+    await src.close();
+  });
+
+  test('Skip (more than available)', () async {
+    final src = await _bytesSource();
+    expect(await src.skip(10), 5);
+    expect(await src.position(), 5);
+    expect(await src.readByte(), -1);
+    await src.close();
+  });
+
+  test('Skip (exactly available)', () async {
+    final src = await _bytesSource();
+    expect(await src.skip(5), 5);
+    expect(await src.position(), 5);
+    expect(await src.readByte(), -1);
+    await src.close();
+  });
 }

test/bytes_view_test.dart

@@ -76,4 +76,28 @@ void main() {
     expect(await src.position(), 5);
     await src.close();
   });
+
+  test('Skip (less than available)', () async {
+    final src = await _bytesSource();
+    expect(await src.skip(2), 2);
+    expect(await src.position(), 2);
+    expect(await src.readByte(), 3);
+    await src.close();
+  });
+
+  test('Skip (more than available)', () async {
+    final src = await _bytesSource();
+    expect(await src.skip(10), 5);
+    expect(await src.position(), 5);
+    expect(await src.readByte(), -1);
+    await src.close();
+  });
+
+  test('Skip (exactly available)', () async {
+    final src = await _bytesSource();
+    expect(await src.skip(5), 5);
+    expect(await src.position(), 5);
+    expect(await src.readByte(), -1);
+    await src.close();
+  });
 }

test/raf_test.dart

@@ -84,4 +84,28 @@ void main() {
     expect(await src.position(), 5);
     await src.close();
   });
+
+  test('Skip (less than available)', () async {
+    final src = await _rafSource();
+    expect(await src.skip(2), 2);
+    expect(await src.position(), 2);
+    expect(await src.readByte(), 3);
+    await src.close();
+  });
+
+  test('Skip (more than available)', () async {
+    final src = await _rafSource();
+    expect(await src.skip(10), 5);
+    expect(await src.position(), 5);
+    expect(await src.readByte(), -1);
+    await src.close();
+  });
+
+  test('Skip (exactly available)', () async {
+    final src = await _rafSource();
+    expect(await src.skip(5), 5);
+    expect(await src.position(), 5);
+    expect(await src.readByte(), -1);
+    await src.close();
+  });
 }