feat: Rand class

Closes #9

Author: rafamizes

CHANGELOG.md

@@ -1,5 +1,20 @@
 <!--todo: release initial version -->
 
-## 0.0.1
+# Changelog
 
-- Initial version.
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Dart Package Versioning](https://dart.dev/tools/pub/versioning).
+
+## [Unreleased]
+
+### Added
+
+- FutureWrap class: instead of returning a value, subclasses will
+  themselves be the value.
+- Text abstract class
+- Rand class for generating random string patterns —
+  [9](https://g]]]ithub.com/dartoos-dev/dartoos/issues/9).
+
+## [0.0.1]

example/dartoos_example.dart

@@ -1,7 +1 @@
-import 'package:dartoos/dartoos.dart';
-
-void main() {
-  final awesome = Awesome();
-// ignore: avoid_print
-  print('awesome: ${awesome.isAwesome}');
-}
+void main() {}

lib/dartoos.dart

@@ -3,7 +3,6 @@
 /// More dartdocs go here.
 library dartoos;
 
-export 'src/dartoos_base.dart';
 export 'src/future_wrap.dart';
-
+export 'text.dart';
 // @todo: #3 Export any libraries intended for clients of this package.

lib/src/dartoos_base.dart

@@ -0,0 +1,10 @@
+import 'future_wrap.dart';
+
+/// Represents a Future<String> value.
+abstract class Text extends FutureWrap<String> {
+  /// Constructs a Text from a Future<String>
+  Text(Future<String> text) : super(text);
+
+  /// Text from value.
+  Text.value(String value) : super.value(value);
+}

lib/src/text.dart

@@ -0,0 +1,31 @@
+import 'dart:math';
+
+import '../text.dart';
+
+/// Randomized text.
+class Rand extends Text {
+  /// Random text having [src] as the source of eligible characters, [len] as
+  /// the length, and [index] as the index randomizer.
+  Rand(int len, Future<String> src, [Random? index])
+      : super(
+          Future(() async {
+            final buffer = StringBuffer();
+            final randIndex = index ?? Random();
+            final chars = await src;
+            for (int count = 0; count < len; count++) {
+              buffer.write(chars[randIndex.nextInt(chars.length)]);
+            }
+            return buffer.toString();
+          }),
+        );
+
+  /// Random digits [0–9] of length [len].
+  Rand.dig(int len, [Random? index]) : this.str(len, '0123456789', index);
+
+  /// Random hex digits [0–9a-f] of length [len].
+  Rand.hex(int len, [Random? index]) : this.str(len, '0123456789abcdef', index);
+
+  /// Random string of length [len] from [src].
+  Rand.str(int len, String src, [Random? index])
+      : this(len, Future.value(src), index);
+}

lib/src/text/rand.dart

@@ -0,0 +1,5 @@
+/// Collection of text-related classes
+library text;
+
+export 'src/text.dart';
+export 'src/text/rand.dart';

lib/text.dart

@@ -1,16 +1,13 @@
-import 'package:dartoos/dartoos.dart';
 import 'package:test/test.dart';
 
 void main() {
   group('A group of tests', () {
-    final awesome = Awesome();
-
     setUp(() {
       // Additional setup goes here.
     });
 
     test('First Test', () {
-      expect(awesome.isAwesome, isTrue);
+      expect(true, true);
     });
   });
 }

test/dartoos_test.dart renamed to test/future_wrap_test.dart

@@ -0,0 +1,77 @@
+import 'dart:math';
+
+import 'package:dartoos/src/text/rand.dart';
+import 'package:test/test.dart';
+
+Future<void> main() async {
+  group('Rand.dig', () {
+    test('length', () async {
+      final four = await Rand.dig(4, Random.secure());
+      expect(four.length, 4);
+    });
+    test('digits only', () async {
+      final digits = await Rand.dig(10, SeqIndexRandom());
+      // Regexp '\D' means non-digit characters
+      // the generated value cannot contain any non-digit character
+      expect(digits.contains(RegExp(r'\D')), false);
+    });
+    test('decimal digits [0–9]', () async {
+      final decimalDigits = await Rand.dig(10, SeqIndexRandom());
+      expect(decimalDigits, '0123456789');
+    });
+  });
+  group('Rand.hex', () {
+    test('length', () async {
+      expect((await Rand.hex(1)).length, 1);
+      expect((await Rand.hex(5)).length, 5);
+    });
+    test('hex digits only', () async {
+      final hex = await Rand.hex(10, SeqIndexRandom());
+      // the generated value cannot contain any non-hex character
+      expect(hex.contains(RegExp('[^0-9a-f]')), false);
+    });
+    test('hexadecimal digits [0–9a–f]', () async {
+      final hexDigits = await Rand.hex(16, SeqIndexRandom());
+      expect(hexDigits, '0123456789abcdef');
+    });
+  });
+  group('Rand.str', () {
+    test('length', () async {
+      final one = await Rand.str(1, 'abc');
+      expect(one.length, 1);
+    });
+    test('custom characters source', () async {
+      final custom = await Rand.str(100, 'a', SeqIndexRandom());
+      expect(custom.length, 100);
+
+      /// Must not contain any character other than 'a'
+      expect(custom.contains(RegExp('[^a]')), false);
+    });
+  });
+}
+
+/// Sequentially generated integer values; quite the opposite of
+/// random!!!
+class SeqIndexRandom implements Random {
+  int _counter = 1;
+  int _currBound = 1;
+
+  @override
+  bool nextBool() => throw UnsupportedError('nextBool not implemented');
+  @override
+  double nextDouble() => throw UnsupportedError('nextDouble not implemented');
+
+  /// Generates sequential integers from 0 up to bound - 1.
+  /// If [bound] changes, the counter is reset so that the first
+  /// value for the new max is 0.
+  @override
+  int nextInt(int bound) {
+    if (_currBound != bound) {
+      _currBound = bound;
+      _counter = bound;
+    }
+    final value = _counter % _currBound;
+    ++_counter;
+    return value;
+  }
+}