Added the randomly_subsample() functions.

--HG--
extra : convert_revision : svn%3Afdd8eb12-d10e-0410-9acb-85c331704f74/trunk%403596

dlib/statistics/random_subset_selector.h

@@ -8,6 +8,7 @@
 #include <vector>
 #include "../algs.h"
 #include "../memory_manager.h"
+#include "../string.h"
 
 namespace dlib
 {
@@ -227,6 +228,47 @@ namespace dlib
         random_subset_selector<T,rand_type>& b
     ) { a.swap(b); }
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T,
+        typename alloc
+        >
+    random_subset_selector<T> randomly_subsample (
+        const std::vector<T,alloc>& samples,
+        unsigned long num
+    )
+    {
+        random_subset_selector<T> subset;
+        subset.set_max_size(num);
+        for (unsigned long i = 0; i < samples.size(); ++i)
+            subset.add(samples[i]);
+        return subset;
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T,
+        typename alloc,
+        typename U
+        >
+    random_subset_selector<T> randomly_subsample (
+        const std::vector<T,alloc>& samples,
+        unsigned long num,
+        const U& random_seed
+    )
+    {
+        random_subset_selector<T> subset;
+        subset.set_seed(cast_to_string(random_seed));
+        subset.set_max_size(num);
+        for (unsigned long i = 0; i < samples.size(); ++i)
+            subset.add(samples[i]);
+        return subset;
+    }
+
+// ----------------------------------------------------------------------------------------
+
 }
 
 #endif // DLIB_RANDOM_SUBSeT_SELECTOR_H_

dlib/statistics/random_subset_selector_abstract.h

@@ -6,6 +6,7 @@
 #include <vector>
 #include "../rand/rand_kernel_abstract.h"
 #include "../memory_manager.h"
+#include "../string.h"
 
 namespace dlib
 {
@@ -237,6 +238,53 @@ namespace dlib
         provides global swap support
     !*/
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T,
+        typename alloc
+        >
+    random_subset_selector<T> randomly_subsample (
+        const std::vector<T,alloc>& samples,
+        unsigned long num
+    );
+    /*!
+        ensures
+            - returns a random subset R such that:
+                - R contains a random subset of the given samples
+                - R.size() == min(num, samples.size())
+                - R.max_size() == num
+            - The random number generator used by this function will always be
+              initialized in the same way.  I.e. this function will always pick
+              the same random subsample if called multiple times.
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T,
+        typename alloc,
+        typename U
+        >
+    random_subset_selector<T> randomly_subsample (
+        const std::vector<T,alloc>& samples,
+        unsigned long num,
+        const U& random_seed
+    );
+    /*!
+        requires
+            - random_seed must be convertible to a string by dlib::cast_to_string()
+        ensures
+            - returns a random subset R such that:
+                - R contains a random subset of the given samples
+                - R.size() == min(num, samples.size())
+                - R.max_size() == num
+            - The given random_seed will be used to initialize the random number
+              generator used by this function.
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
 }
 
 #endif // DLIB_RANDOM_SUBSeT_SELECTOR_ABSTRACT_H_