Implement Sample

Author: deanpapas

lib/sample.dart

@@ -0,0 +1,4 @@
+library turf_sample;
+
+export 'package:geotypes/geotypes.dart';
+export 'src/sample.dart';

lib/src/sample.dart

@@ -0,0 +1,33 @@
+import 'dart:math';
+import 'package:turf/turf.dart';
+
+/// Returns a new [FeatureCollection] containing [num] randomly-selected features
+/// from the input collection, **without replacement**.
+///
+/// Throws [ArgumentError] if:
+/// * [fc] is `null`
+/// * [num] is `null`, negative, or greater than `fc.features.length`
+FeatureCollection<T> sample<T extends GeometryObject>(
+  FeatureCollection<T> fc,
+  int num, {
+  Random? random,
+}) {
+  if (num < 0 || num > fc.features.length) {
+    throw ArgumentError(
+        'num must be between 0 and the number of features in the collection');
+  }
+
+  final rnd = random ?? Random();
+  final shuffled = List<Feature<T>>.from(fc.features);
+
+  // Partial Fisher-Yates: shuffle only the tail we need.
+  for (var i = shuffled.length - 1; i >= shuffled.length - num; i--) {
+    final j = rnd.nextInt(i + 1);
+    final temp = shuffled[i];
+    shuffled[i] = shuffled[j];
+    shuffled[j] = temp;
+  }
+
+  final selected = shuffled.sublist(shuffled.length - num);
+  return FeatureCollection<T>(features: selected);
+}

lib/turf.dart

@@ -37,6 +37,7 @@ export 'polygon_to_line.dart';
 export 'polygonize.dart';
 export 'points_within_polygon.dart';
 export 'polyline.dart';
+export 'sample.dart';
 export 'square.dart';
 export 'transform.dart';
 export 'truncate.dart';

test/components/sample_test.dart

@@ -0,0 +1,34 @@
+import 'dart:math';
+import 'package:test/test.dart';
+import 'package:turf/turf.dart';
+
+void main() {
+  test('sample picks the requested number of features', () {
+    final points = FeatureCollection<Point>(features: [
+      Feature<Point>(
+          geometry: Point(coordinates: Position(1, 2)),
+          properties: {'team': 'Red Sox'}),
+      Feature<Point>(
+          geometry: Point(coordinates: Position(2, 1)),
+          properties: {'team': 'Yankees'}),
+      Feature<Point>(
+          geometry: Point(coordinates: Position(3, 1)),
+          properties: {'team': 'Nationals'}),
+      Feature<Point>(
+          geometry: Point(coordinates: Position(2, 2)),
+          properties: {'team': 'Yankees'}),
+      Feature<Point>(
+          geometry: Point(coordinates: Position(2, 3)),
+          properties: {'team': 'Red Sox'}),
+      Feature<Point>(
+          geometry: Point(coordinates: Position(4, 2)),
+          properties: {'team': 'Yankees'}),
+    ]);
+
+    // Pass a seeded RNG so the test is reproducible.
+    final results = sample<Point>(points, 4, random: Random(42));
+
+    expect(results.features.length, equals(4),
+        reason: 'should sample exactly 4 features');
+  });
+}