Made resizable_tensor objects not perform a reallocation if they are resized to

be smaller.  Instead, they now behave like std::vector in that they just change
their nominal size but keep the same memory, only reallocating if they are
resized to something larger than their underlying memory block.

This change makes some uses of dlib faster, in particular, running networks on
a large set of images of differing sizes will now run faster since there won't
be any GPU reallocations, which are notoriously slow.

dlib/dnn/tensor.h

@@ -322,7 +322,7 @@ namespace dlib
         resizable_tensor(const resizable_tensor& item) : _annotation(item.annotation()) 
         {
             copy_size(item);
-            memcpy(data_instance, item.data_instance);
+            memcpy(*this, item);
         }
         resizable_tensor(const tensor& item) : _annotation(item.annotation()) 
         {
@@ -348,6 +348,8 @@ namespace dlib
         {
             set_size(0,0,0,0);
             _annotation.clear();
+            // free underlying memory
+            data_instance.set_size(0);
         }
 
         void copy_size (
@@ -385,7 +387,8 @@ namespace dlib
             m_nr = nr_;
             m_nc = nc_;
             m_size = n_*k_*nr_*nc_;
-            data_instance.set_size(m_size);
+            if ((long)data_instance.size() < m_size)
+                data_instance.set_size(m_size);
 #ifdef DLIB_USE_CUDA
             cudnn_descriptor.set_size(m_n,m_k,m_nr,m_nc);
 #endif

dlib/dnn/tensor_abstract.h

@@ -446,6 +446,7 @@ namespace dlib
                 - #k() == 0
                 - #nr() == 0
                 - #nc() == 0
+                - #capacity() == 0
         !*/
 
         template <typename EXP>
@@ -462,6 +463,7 @@ namespace dlib
                 - #nc() == 1
                 - Assigns item to *this tensor by performing:
                   set_ptrm(host(), num_samples(), k()*nr()*nc()) = item;
+                - #capacity() == size()
         !*/
 
         explicit resizable_tensor(
@@ -479,6 +481,7 @@ namespace dlib
                 - #k() == k_
                 - #nr() == nr_
                 - #nc() == nc_
+                - #capacity() == size()
         !*/
 
         // This object is copyable and movable
@@ -487,6 +490,18 @@ namespace dlib
         resizable_tensor& operator= (const resizable_tensor&) = default;
         resizable_tensor& operator= (resizable_tensor&&) = default;
 
+        size_t capacity (
+        ) const;
+        /*!
+            ensures
+                - returns the total number of floats allocated.  This might be different
+                  from the size() since calls to set_size() that make a tensor smaller
+                  don't trigger reallocations.  They simply adjust the nominal dimensions
+                  while keeping the same allocated memory block.  This makes calls to
+                  set_size() very fast.  If you need to deallocate a tensor then use
+                  clear().
+        !*/
+
         void clear(
         );
         /*!
@@ -497,6 +512,7 @@ namespace dlib
                 - #nr() == 0
                 - #nc() == 0
                 - #annotation().is_empty() == true
+                - #capacity() == 0
         !*/
 
         void copy_size (
@@ -522,6 +538,8 @@ namespace dlib
                 - #k() == k_
                 - #nr() == nr_
                 - #nc() == nc_
+                - #capacity() == max(#size(), capacity())
+                  (i.e. capacity() never goes down when calling set_size().)
         !*/
 
         template <typename EXP>