refactor: rename class Rand to RandOf; removal of RandDig and RandHex

Closes #31

Breaking Changes

Author: rafamizes

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Dart Package Versioning](https://dart.dev/tools/pub
 
 ## [Unreleased]
 
+### Added
+
+- classes RandText, RandTextSrc, and RandTextLen — [29](https://github.com/dartoos-dev/dartoos/issues/29).
+
+### Changed
+
+- rename class Rand to RandOf — **Breaking Change**.
+
+### Removed
+
+- RandDig and RandHex classes — **Breaking Change**s.
+
 ## [0.3.1] - 2021-12-15
 
 ### Added

example/crypto/hash/hmac_sha256_benchmark.dart

@@ -20,7 +20,7 @@ void main() {
   const len = 25000000;
   const alphabet =
       'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
-  final data = BytesOf.text(Rand(len, alphabet)).value;
+  final data = BytesOf.text(RandOf(alphabet, len)).value;
   final key = BytesOf.utf8('Dartoos vs Crypto').value;
   print('\nLength of the data to be hashed: ${data.lengthInBytes} bytes.');
 

example/crypto/hash/sha256_benchmark.dart

@@ -21,7 +21,7 @@ void main() {
   const len = 25000000;
   const alphabet =
       'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
-  final data = BytesOf.text(Rand(len, alphabet)).value;
+  final data = BytesOf.text(RandOf(alphabet, len)).value;
   print('\nLength of the data to be hashed: ${data.lengthInBytes} bytes.');
 
   print('\n--- Hashing elapsed times ---');

example/crypto/hash/sha512_benchmark.dart

@@ -21,7 +21,7 @@ void main() {
   const len = 25000000;
   const alphabet =
       'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
-  final data = BytesOf.text(Rand(len, alphabet)).value;
+  final data = BytesOf.text(RandOf(alphabet, len)).value;
   print('\nLength of the data to be hashed: ${data.lengthInBytes} bytes.');
 
   print('\n--- SHA-512 — Elapsed times for hasing ---');

example/encoding/base64_benchmark.dart

@@ -26,7 +26,7 @@ void main() {
   const len = 50000000;
   const alphabet =
       'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
-  final bytes = dartoos.BytesOf.text(dartoos.Rand(len, alphabet)).value;
+  final bytes = dartoos.BytesOf.text(dartoos.RandOf(alphabet, len)).value;
   print('\nLength of the data to be encoded: ${bytes.length} bytes.');
 
   print('\n--- Encoding elapsed times ---');

example/rand/rand_benchmark.dart

@@ -2,7 +2,7 @@
 
 import 'dart:math';
 
-import 'package:dartoos/src/rand/rand.dart';
+import 'package:dartoos/rand.dart';
 
 /// Dartoos random text generator vs. Dart's built-in generator.
 ///
@@ -37,15 +37,14 @@ void main() {
 
   print('Start...');
   final watch = Stopwatch()..start();
-  final dartText = randText(len, src, index);
+  final dartText = randText(src, len, index);
   final elapsedDartTime = watch.elapsedMilliseconds;
   print('\nDart elapsed time....: $elapsedDartTime milliseconds');
   watch.stop();
   watch.reset();
 
   watch.start();
-  final rand = Rand(len, src, index);
-  final dartoosText = rand();
+  final dartoosText = RandOf(src, len, index).value;
   final elapsedDartoosTime = watch.elapsedMilliseconds;
   print('Dartoos elapsed time.: $elapsedDartoosTime milliseconds');
   watch.stop();
@@ -58,7 +57,7 @@ void main() {
 }
 
 /// Common approach to generate random Strings in Dart.
-String randText(int len, String chars, Random index) {
+String randText(String chars, int len, Random index) {
   final buffer = StringBuffer();
   for (var i = 0; i < len; ++i) {
     buffer.write(chars[index.nextInt(chars.length)]);

lib/rand.dart

@@ -1,7 +1,5 @@
 /// Set of classes that generate random data — Randomizers.
 library rand;
 
-export 'src/rand/rand.dart';
-export 'src/rand/rand_dig.dart';
-export 'src/rand/rand_hex.dart';
+export 'src/rand/rand_of.dart';
 export 'src/rand/rand_text.dart';

lib/src/rand/rand_dig.dart

@@ -7,33 +7,45 @@ import '../text/text.dart';
 /// eligible characters.
 ///
 /// For a cryptographically secure random number, see [Rand.secure].
-class Rand with Text {
+class RandOf with Text {
   /// Texts of length [len] with randomly selected characters from [src].
   ///
   /// [len] >= 0; src must not be empty.
   ///
-  /// For a cryptographically secure random number generator, see [Rand.secure].
-  Rand(int len, String src, [Random? index])
+  /// For a cryptographically secure random number generator, see [R.secure].
+  RandOf(String src, int len, [Random? index])
       : assert(len >= 0, 'Error: negative length.'),
         assert(src.isNotEmpty, 'Error: empty source of eligible characters.'),
         _len = len,
         _src = src,
         _index = index ?? Random();
 
-  /// Cryptographically secure texts of length [len] with randomly selected
+  /// Fixed-length texts with randomly selected digits [0–9].
+  ///
+  /// This is the ideal class for generating verification codes.
+  ///
+  /// ```dart
+  ///  final fourDigitCode = RandOf.dig(4).value;
+  /// ```
+  RandOf.dig(int len, [Random? index]) : this('0123456789', len, index);
+
+  /// Fixed-length strings with randomly selected hex digits [0–9a–f].
+  RandOf.hex(int len, [Random? index]) : this('0123456789abcdef', len, index);
+
+  /// Cryptographically secure strings of length [len] with randomly selected
   /// characters from [src].
   ///
   /// [len] >= 0; src must not be empty.
   ///
   /// It uses an instance of [Random.secure] as the index randomizer.
-  Rand.secure(int len, String src) : this(len, src, Random.secure());
+  RandOf.secure(String src, int len) : this(src, len, Random.secure());
 
-  final int _len;
   final String _src;
+  final int _len;
   final Random _index;
 
-  /// Generates fixed-length texts with randomly selected characters from the
-  /// source of eligible characters.
+  /// Returns a fixed-length [String] with randomly selected characters from the
+  /// predefined source of elegible characters.
   @override
   String call() {
     final Uint16List codes = Uint16List(_len);