1 // SPDX-License-Identifier: Apache-2.0
2 //
3 // Copyright 2008-2016 Conrad Sanderson (http://conradsanderson.id.au)
4 // Copyright 2008-2016 National ICT Australia (NICTA)
5 //
6 // Licensed under the Apache License, Version 2.0 (the "License");
7 // you may not use this file except in compliance with the License.
8 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
10 //
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
16 // ------------------------------------------------------------------------
17 
18 
19 //! \addtogroup SpMat
20 //! @{
21 
22 
23 //! Sparse matrix class, with data stored in compressed sparse column (CSC) format
24 template<typename eT>
25 class SpMat : public SpBase< eT, SpMat<eT> >
26   {
27   public:
28 
29   typedef eT                                elem_type;  //!< the type of elements stored in the matrix
30   typedef typename get_pod_type<eT>::result  pod_type;  //!< if eT is std::complex<T>, pod_type is T; otherwise pod_type is eT
31 
32   static constexpr bool is_row  = false;
33   static constexpr bool is_col  = false;
34   static constexpr bool is_xvec = false;
35 
36   const uword n_rows;    //!< number of rows             (read-only)
37   const uword n_cols;    //!< number of columns          (read-only)
38   const uword n_elem;    //!< number of elements         (read-only)
39   const uword n_nonzero; //!< number of nonzero elements (read-only)
40   const uword vec_state; //!< 0: matrix; 1: column vector; 2: row vector
41 
42 
43   // The memory used to store the values of the matrix.
44   // In accordance with the CSC format, this stores only the actual values.
45   // The correct locations of the values are assembled from the row indices and column pointers.
46   //
47   // The length of this array is (n_nonzero + 1).
48   // The final value values[n_nonzero] must be zero to ensure integrity of iterators.
49   // Use mem_resize(new_n_nonzero) to resize this array.
50   //
51   // WARNING: the 'values' array is only valid after sync() is called;
52   // WARNING: there is a separate cache for fast element insertion
53 
54   arma_aligned const eT* const values;
55 
56 
57   // The row indices of each value.  row_indices[i] is the row of values[i].
58   //
59   // The length of this array is (n_nonzero + 1).
60   // The final value row_indices[n_nonzero] must be zero to ensure integrity of iterators.
61   // Use mem_resize(new_n_nonzero) to resize this array.
62   //
63   // WARNING: the 'row_indices' array is only valid after sync() is called;
64   // WARNING: there is a separate cache for fast element insertion
65 
66   arma_aligned const uword* const row_indices;
67 
68 
69   // The column pointers.  This stores the index of the first item in column i.
70   // That is, values[col_ptrs[i]] is the first value in column i,
71   // and it is in the row indicated by row_indices[col_ptrs[i]].
72   //
73   // The length of this array is (n_cols + 2).
74   // The element col_ptrs[n_cols] must be equal to n_nonzero.
75   // The element col_ptrs[n_cols + 1] must be an invalid very large value to ensure integrity of iterators.
76   //
77   // The col_ptrs array is set by the init() function
78   // (which is called by constructors, set_size() and other functions that change the matrix size).
79   //
80   // WARNING: the 'col_ptrs' array is only valid after sync() is called;
81   // WARNING: there is a separate cache for fast element insertion
82 
83   arma_aligned const uword* const col_ptrs;
84 
85   inline  SpMat();
86   inline ~SpMat();
87 
88   inline explicit SpMat(const uword in_rows, const uword in_cols);
89   inline explicit SpMat(const SizeMat& s);
90 
91   inline            SpMat(const char*        text);
92   inline SpMat& operator=(const char*        text);
93   inline            SpMat(const std::string& text);
94   inline SpMat& operator=(const std::string& text);
95   inline            SpMat(const SpMat<eT>&   x);
96 
97   inline            SpMat(SpMat&& m);
98   inline SpMat& operator=(SpMat&& m);
99 
100   inline explicit    SpMat(const MapMat<eT>& x);
101   inline SpMat& operator= (const MapMat<eT>& x);
102 
103   template<typename T1, typename T2, typename T3>
104   inline SpMat(const Base<uword,T1>& rowind, const Base<uword,T2>& colptr, const Base<eT,T3>& values, const uword n_rows, const uword n_cols);
105 
106   template<typename T1, typename T2>
107   inline SpMat(const Base<uword,T1>& locations, const Base<eT,T2>& values, const bool sort_locations = true);
108 
109   template<typename T1, typename T2>
110   inline SpMat(const Base<uword,T1>& locations, const Base<eT,T2>& values, const uword n_rows, const uword n_cols, const bool sort_locations = true, const bool check_for_zeros = true);
111 
112   template<typename T1, typename T2>
113   inline SpMat(const bool add_values, const Base<uword,T1>& locations, const Base<eT,T2>& values, const uword n_rows, const uword n_cols, const bool sort_locations = true, const bool check_for_zeros = true);
114 
115   inline SpMat& operator= (const eT val); //! sets size to 1x1
116   inline SpMat& operator*=(const eT val);
117   inline SpMat& operator/=(const eT val);
118   // operator+=(val) and operator-=(val) are not defined as they don't make sense for sparse matrices
119 
120   inline SpMat& operator= (const SpMat& m);
121   inline SpMat& operator+=(const SpMat& m);
122   inline SpMat& operator-=(const SpMat& m);
123   inline SpMat& operator*=(const SpMat& m);
124   inline SpMat& operator%=(const SpMat& m);
125   inline SpMat& operator/=(const SpMat& m);
126 
127   template<typename T1> inline explicit    SpMat(const Base<eT, T1>& m);
128   template<typename T1> inline SpMat& operator= (const Base<eT, T1>& m);
129   template<typename T1> inline SpMat& operator+=(const Base<eT, T1>& m);
130   template<typename T1> inline SpMat& operator-=(const Base<eT, T1>& m);
131   template<typename T1> inline SpMat& operator*=(const Base<eT, T1>& m);
132   template<typename T1> inline SpMat& operator/=(const Base<eT, T1>& m);
133   template<typename T1> inline SpMat& operator%=(const Base<eT, T1>& m);
134 
135   template<typename T1> inline explicit    SpMat(const Op<T1, op_diagmat>& expr);
136   template<typename T1> inline SpMat& operator= (const Op<T1, op_diagmat>& expr);
137   template<typename T1> inline SpMat& operator+=(const Op<T1, op_diagmat>& expr);
138   template<typename T1> inline SpMat& operator-=(const Op<T1, op_diagmat>& expr);
139   template<typename T1> inline SpMat& operator*=(const Op<T1, op_diagmat>& expr);
140   template<typename T1> inline SpMat& operator/=(const Op<T1, op_diagmat>& expr);
141   template<typename T1> inline SpMat& operator%=(const Op<T1, op_diagmat>& expr);
142 
143   //! explicit specification of sparse +/- scalar
144   template<typename T1, typename op_type> inline explicit SpMat(const SpToDOp<T1, op_type>& expr);
145 
146   //! construction of complex matrix out of two non-complex matrices
147   template<typename T1, typename T2>
148   inline explicit SpMat(const SpBase<pod_type, T1>& A, const SpBase<pod_type, T2>& B);
149 
150   inline             SpMat(const SpSubview<eT>& X);
151   inline SpMat& operator= (const SpSubview<eT>& X);
152   inline SpMat& operator+=(const SpSubview<eT>& X);
153   inline SpMat& operator-=(const SpSubview<eT>& X);
154   inline SpMat& operator*=(const SpSubview<eT>& X);
155   inline SpMat& operator%=(const SpSubview<eT>& X);
156   inline SpMat& operator/=(const SpSubview<eT>& X);
157 
158   template<typename T1> inline             SpMat(const SpSubview_col_list<eT,T1>& X);
159   template<typename T1> inline SpMat& operator= (const SpSubview_col_list<eT,T1>& X);
160   template<typename T1> inline SpMat& operator+=(const SpSubview_col_list<eT,T1>& X);
161   template<typename T1> inline SpMat& operator-=(const SpSubview_col_list<eT,T1>& X);
162   template<typename T1> inline SpMat& operator*=(const SpSubview_col_list<eT,T1>& X);
163   template<typename T1> inline SpMat& operator%=(const SpSubview_col_list<eT,T1>& X);
164   template<typename T1> inline SpMat& operator/=(const SpSubview_col_list<eT,T1>& X);
165 
166   inline             SpMat(const spdiagview<eT>& X);
167   inline SpMat& operator= (const spdiagview<eT>& X);
168   inline SpMat& operator+=(const spdiagview<eT>& X);
169   inline SpMat& operator-=(const spdiagview<eT>& X);
170   inline SpMat& operator*=(const spdiagview<eT>& X);
171   inline SpMat& operator%=(const spdiagview<eT>& X);
172   inline SpMat& operator/=(const spdiagview<eT>& X);
173 
174   // delayed unary ops
175   template<typename T1, typename spop_type> inline             SpMat(const SpOp<T1, spop_type>& X);
176   template<typename T1, typename spop_type> inline SpMat& operator= (const SpOp<T1, spop_type>& X);
177   template<typename T1, typename spop_type> inline SpMat& operator+=(const SpOp<T1, spop_type>& X);
178   template<typename T1, typename spop_type> inline SpMat& operator-=(const SpOp<T1, spop_type>& X);
179   template<typename T1, typename spop_type> inline SpMat& operator*=(const SpOp<T1, spop_type>& X);
180   template<typename T1, typename spop_type> inline SpMat& operator%=(const SpOp<T1, spop_type>& X);
181   template<typename T1, typename spop_type> inline SpMat& operator/=(const SpOp<T1, spop_type>& X);
182 
183   // delayed binary ops
184   template<typename T1, typename T2, typename spglue_type> inline             SpMat(const SpGlue<T1, T2, spglue_type>& X);
185   template<typename T1, typename T2, typename spglue_type> inline SpMat& operator= (const SpGlue<T1, T2, spglue_type>& X);
186   template<typename T1, typename T2, typename spglue_type> inline SpMat& operator+=(const SpGlue<T1, T2, spglue_type>& X);
187   template<typename T1, typename T2, typename spglue_type> inline SpMat& operator-=(const SpGlue<T1, T2, spglue_type>& X);
188   template<typename T1, typename T2, typename spglue_type> inline SpMat& operator*=(const SpGlue<T1, T2, spglue_type>& X);
189   template<typename T1, typename T2, typename spglue_type> inline SpMat& operator%=(const SpGlue<T1, T2, spglue_type>& X);
190   template<typename T1, typename T2, typename spglue_type> inline SpMat& operator/=(const SpGlue<T1, T2, spglue_type>& X);
191 
192   // delayed mixed-type unary ops
193   template<typename T1, typename spop_type> inline             SpMat(const mtSpOp<eT, T1, spop_type>& X);
194   template<typename T1, typename spop_type> inline SpMat& operator= (const mtSpOp<eT, T1, spop_type>& X);
195   template<typename T1, typename spop_type> inline SpMat& operator+=(const mtSpOp<eT, T1, spop_type>& X);
196   template<typename T1, typename spop_type> inline SpMat& operator-=(const mtSpOp<eT, T1, spop_type>& X);
197   template<typename T1, typename spop_type> inline SpMat& operator*=(const mtSpOp<eT, T1, spop_type>& X);
198   template<typename T1, typename spop_type> inline SpMat& operator%=(const mtSpOp<eT, T1, spop_type>& X);
199   template<typename T1, typename spop_type> inline SpMat& operator/=(const mtSpOp<eT, T1, spop_type>& X);
200 
201   // delayed mixed-type binary ops
202   template<typename T1, typename T2, typename spglue_type> inline             SpMat(const mtSpGlue<eT, T1, T2, spglue_type>& X);
203   template<typename T1, typename T2, typename spglue_type> inline SpMat& operator= (const mtSpGlue<eT, T1, T2, spglue_type>& X);
204   template<typename T1, typename T2, typename spglue_type> inline SpMat& operator+=(const mtSpGlue<eT, T1, T2, spglue_type>& X);
205   template<typename T1, typename T2, typename spglue_type> inline SpMat& operator-=(const mtSpGlue<eT, T1, T2, spglue_type>& X);
206   template<typename T1, typename T2, typename spglue_type> inline SpMat& operator*=(const mtSpGlue<eT, T1, T2, spglue_type>& X);
207   template<typename T1, typename T2, typename spglue_type> inline SpMat& operator%=(const mtSpGlue<eT, T1, T2, spglue_type>& X);
208   template<typename T1, typename T2, typename spglue_type> inline SpMat& operator/=(const mtSpGlue<eT, T1, T2, spglue_type>& X);
209 
210 
211   arma_inline       SpSubview_row<eT> row(const uword row_num);
212   arma_inline const SpSubview_row<eT> row(const uword row_num) const;
213 
214   inline            SpSubview_row<eT> operator()(const uword row_num, const span& col_span);
215   inline      const SpSubview_row<eT> operator()(const uword row_num, const span& col_span) const;
216 
217   arma_inline       SpSubview_col<eT> col(const uword col_num);
218   arma_inline const SpSubview_col<eT> col(const uword col_num) const;
219 
220   inline            SpSubview_col<eT> operator()(const span& row_span, const uword col_num);
221   inline      const SpSubview_col<eT> operator()(const span& row_span, const uword col_num) const;
222 
223   arma_inline       SpSubview<eT> rows(const uword in_row1, const uword in_row2);
224   arma_inline const SpSubview<eT> rows(const uword in_row1, const uword in_row2) const;
225 
226   arma_inline       SpSubview<eT> cols(const uword in_col1, const uword in_col2);
227   arma_inline const SpSubview<eT> cols(const uword in_col1, const uword in_col2) const;
228 
229   arma_inline       SpSubview<eT> submat(const uword in_row1, const uword in_col1, const uword in_row2, const uword in_col2);
230   arma_inline const SpSubview<eT> submat(const uword in_row1, const uword in_col1, const uword in_row2, const uword in_col2) const;
231 
232   arma_inline       SpSubview<eT> submat(const uword in_row1, const uword in_col1, const SizeMat& s);
233   arma_inline const SpSubview<eT> submat(const uword in_row1, const uword in_col1, const SizeMat& s) const;
234 
235   inline            SpSubview<eT> submat    (const span& row_span, const span& col_span);
236   inline      const SpSubview<eT> submat    (const span& row_span, const span& col_span) const;
237 
238   inline            SpSubview<eT> operator()(const span& row_span, const span& col_span);
239   inline      const SpSubview<eT> operator()(const span& row_span, const span& col_span) const;
240 
241   arma_inline       SpSubview<eT> operator()(const uword in_row1, const uword in_col1, const SizeMat& s);
242   arma_inline const SpSubview<eT> operator()(const uword in_row1, const uword in_col1, const SizeMat& s) const;
243 
244 
245   inline       SpSubview<eT> head_rows(const uword N);
246   inline const SpSubview<eT> head_rows(const uword N) const;
247 
248   inline       SpSubview<eT> tail_rows(const uword N);
249   inline const SpSubview<eT> tail_rows(const uword N) const;
250 
251   inline       SpSubview<eT> head_cols(const uword N);
252   inline const SpSubview<eT> head_cols(const uword N) const;
253 
254   inline       SpSubview<eT> tail_cols(const uword N);
255   inline const SpSubview<eT> tail_cols(const uword N) const;
256 
257 
258   template<typename T1> arma_inline       SpSubview_col_list<eT,T1> cols(const Base<uword,T1>& ci);
259   template<typename T1> arma_inline const SpSubview_col_list<eT,T1> cols(const Base<uword,T1>& ci) const;
260 
261 
262   inline       spdiagview<eT> diag(const sword in_id = 0);
263   inline const spdiagview<eT> diag(const sword in_id = 0) const;
264 
265 
266   inline void swap_rows(const uword in_row1, const uword in_row2);
267   inline void swap_cols(const uword in_col1, const uword in_col2);
268 
269   inline void shed_row(const uword row_num);
270   inline void shed_col(const uword col_num);
271 
272   inline void shed_rows(const uword in_row1, const uword in_row2);
273   inline void shed_cols(const uword in_col1, const uword in_col2);
274 
275 
276   // access the i-th element; if there is nothing at element i, 0 is returned
277   arma_inline arma_warn_unused SpMat_MapMat_val<eT> operator[] (const uword i);
278   arma_inline arma_warn_unused eT                   operator[] (const uword i) const;
279   arma_inline arma_warn_unused SpMat_MapMat_val<eT> at         (const uword i);
280   arma_inline arma_warn_unused eT                   at         (const uword i) const;
281   arma_inline arma_warn_unused SpMat_MapMat_val<eT> operator() (const uword i);
282   arma_inline arma_warn_unused eT                   operator() (const uword i) const;
283 
284   // access the element at the given row and column; if there is nothing at that position, 0 is returned
285   arma_inline arma_warn_unused SpMat_MapMat_val<eT> at         (const uword in_row, const uword in_col);
286   arma_inline arma_warn_unused eT                   at         (const uword in_row, const uword in_col) const;
287   arma_inline arma_warn_unused SpMat_MapMat_val<eT> operator() (const uword in_row, const uword in_col);
288   arma_inline arma_warn_unused eT                   operator() (const uword in_row, const uword in_col) const;
289 
290 
291   arma_inline arma_warn_unused bool is_empty()  const;
292   arma_inline arma_warn_unused bool is_vec()    const;
293   arma_inline arma_warn_unused bool is_rowvec() const;
294   arma_inline arma_warn_unused bool is_colvec() const;
295   arma_inline arma_warn_unused bool is_square() const;
296        inline arma_warn_unused bool is_finite() const;
297 
298   inline arma_warn_unused bool is_symmetric() const;
299   inline arma_warn_unused bool is_symmetric(const typename get_pod_type<eT>::result tol) const;
300 
301   inline arma_warn_unused bool is_hermitian() const;
302   inline arma_warn_unused bool is_hermitian(const typename get_pod_type<eT>::result tol) const;
303 
304   inline arma_warn_unused bool has_inf() const;
305   inline arma_warn_unused bool has_nan() const;
306 
307   arma_inline arma_warn_unused bool in_range(const uword i) const;
308   arma_inline arma_warn_unused bool in_range(const span& x) const;
309 
310   arma_inline arma_warn_unused bool in_range(const uword   in_row, const uword   in_col) const;
311   arma_inline arma_warn_unused bool in_range(const span& row_span, const uword   in_col) const;
312   arma_inline arma_warn_unused bool in_range(const uword   in_row, const span& col_span) const;
313   arma_inline arma_warn_unused bool in_range(const span& row_span, const span& col_span) const;
314 
315   arma_inline arma_warn_unused bool in_range(const uword in_row, const uword in_col, const SizeMat& s) const;
316 
317 
318   template<typename eT2> inline void copy_size(const SpMat<eT2>& m);
319   template<typename eT2> inline void copy_size(const   Mat<eT2>& m);
320 
321   inline void set_size(const uword in_elem);
322   inline void set_size(const uword in_rows, const uword in_cols);
323   inline void set_size(const SizeMat& s);
324 
325   inline void   resize(const uword in_rows, const uword in_cols);
326   inline void   resize(const SizeMat& s);
327 
328   inline void  reshape(const uword in_rows, const uword in_cols);
329   inline void  reshape(const SizeMat& s);
330 
331   inline void  reshape_helper_generic(const uword in_rows, const uword in_cols);  //! internal use only
332   inline void  reshape_helper_intovec();                                          //! internal use only
333 
334   template<typename functor> inline const SpMat&  for_each(functor F);
335   template<typename functor> inline const SpMat&  for_each(functor F) const;
336 
337   template<typename functor> inline const SpMat& transform(functor F);
338 
339   inline const SpMat& replace(const eT old_val, const eT new_val);
340 
341   inline const SpMat& clean(const pod_type threshold);
342 
343   inline const SpMat& clamp(const eT min_val, const eT max_val);
344 
345   inline const SpMat& zeros();
346   inline const SpMat& zeros(const uword in_elem);
347   inline const SpMat& zeros(const uword in_rows, const uword in_cols);
348   inline const SpMat& zeros(const SizeMat& s);
349 
350   inline const SpMat& eye();
351   inline const SpMat& eye(const uword in_rows, const uword in_cols);
352   inline const SpMat& eye(const SizeMat& s);
353 
354   inline const SpMat& speye();
355   inline const SpMat& speye(const uword in_rows, const uword in_cols);
356   inline const SpMat& speye(const SizeMat& s);
357 
358   inline const SpMat& sprandu(const uword in_rows, const uword in_cols, const double density);
359   inline const SpMat& sprandu(const SizeMat& s,                         const double density);
360 
361   inline const SpMat& sprandn(const uword in_rows, const uword in_cols, const double density);
362   inline const SpMat& sprandn(const SizeMat& s,                         const double density);
363 
364   inline void reset();
365   inline void reset_cache();
366 
367   //! don't use this unless you're writing internal Armadillo code
368   inline void reserve(const uword in_rows, const uword in_cols, const uword new_n_nonzero);
369 
370   //! don't use this unless you're writing internal Armadillo code
371   inline SpMat(const arma_reserve_indicator&, const uword in_rows, const uword in_cols, const uword new_n_nonzero);
372 
373   //! don't use this unless you're writing internal Armadillo code
374   template<typename eT2>
375   inline SpMat(const arma_layout_indicator&, const SpMat<eT2>& x);
376 
377   template<typename T1> inline void set_real(const SpBase<pod_type,T1>& X);
378   template<typename T1> inline void set_imag(const SpBase<pod_type,T1>& X);
379 
380 
381   // saving and loading
382   // TODO: implement auto_detect for sparse matrices
383 
384   inline arma_cold bool save(const std::string   name, const file_type type = arma_binary) const;
385   inline arma_cold bool save(const csv_name&     spec, const file_type type =   csv_ascii) const;
386   inline arma_cold bool save(      std::ostream& os,   const file_type type = arma_binary) const;
387 
388   inline arma_cold bool load(const std::string   name, const file_type type = arma_binary);
389   inline arma_cold bool load(const csv_name&     spec, const file_type type =   csv_ascii);
390   inline arma_cold bool load(      std::istream& is,   const file_type type = arma_binary);
391 
392   inline arma_cold bool quiet_save(const std::string   name, const file_type type = arma_binary) const;
393   inline arma_cold bool quiet_save(const csv_name&     spec, const file_type type =   csv_ascii) const;
394   inline arma_cold bool quiet_save(      std::ostream& os,   const file_type type = arma_binary) const;
395 
396   inline arma_cold bool quiet_load(const std::string   name, const file_type type = arma_binary);
397   inline arma_cold bool quiet_load(const csv_name&     spec, const file_type type =   csv_ascii);
398   inline arma_cold bool quiet_load(      std::istream& is,   const file_type type = arma_binary);
399 
400 
401 
402   // necessary forward declarations
403   class iterator_base;
404   class iterator;
405   class const_iterator;
406   class row_iterator;
407   class const_row_iterator;
408 
409   // iterator_base provides basic operators but not how to compare or how to iterate
410   class iterator_base
411     {
412     public:
413 
414     inline iterator_base();
415     inline iterator_base(const SpMat& in_M);
416     inline iterator_base(const SpMat& in_M, const uword col, const uword pos);
417 
418     arma_inline eT operator*() const;
419 
420     // don't hold location internally; call "dummy" methods to get that information
row() const421     arma_inline uword row() const { return M->row_indices[internal_pos]; }
col() const422     arma_inline uword col() const { return internal_col;                 }
pos() const423     arma_inline uword pos() const { return internal_pos;                 }
424 
425     arma_aligned const SpMat* M;
426     arma_aligned       uword  internal_col;
427     arma_aligned       uword  internal_pos;
428 
429     typedef std::bidirectional_iterator_tag iterator_category;
430     typedef eT                              value_type;
431     typedef std::ptrdiff_t                  difference_type;  // TODO: not certain on this one
432     typedef const eT*                       pointer;
433     typedef const eT&                       reference;
434     };
435 
436   class const_iterator : public iterator_base
437     {
438     public:
439 
440     inline const_iterator();
441     inline const_iterator(const SpMat& in_M, uword initial_pos = 0); // assumes initial_pos is valid
442     //! once initialised, will be at the first nonzero value after the given position (using forward columnwise traversal)
443     inline const_iterator(const SpMat& in_M, uword in_row, uword in_col);
444     //! if you know the exact position of the iterator;  in_row is a dummy argument
445     inline const_iterator(const SpMat& in_M, uword in_row, uword in_col, uword in_pos);
446     inline const_iterator(const const_iterator& other);
447 
448     inline arma_hot         const_iterator& operator++();
449     inline arma_warn_unused const_iterator  operator++(int);
450 
451     inline arma_hot         const_iterator& operator--();
452     inline arma_warn_unused const_iterator  operator--(int);
453 
454     inline arma_hot bool operator==(const const_iterator& rhs) const;
455     inline arma_hot bool operator!=(const const_iterator& rhs) const;
456 
457     inline arma_hot bool operator==(const typename SpSubview<eT>::const_iterator& rhs) const;
458     inline arma_hot bool operator!=(const typename SpSubview<eT>::const_iterator& rhs) const;
459 
460     inline arma_hot bool operator==(const const_row_iterator& rhs) const;
461     inline arma_hot bool operator!=(const const_row_iterator& rhs) const;
462 
463     inline arma_hot bool operator==(const typename SpSubview<eT>::const_row_iterator& rhs) const;
464     inline arma_hot bool operator!=(const typename SpSubview<eT>::const_row_iterator& rhs) const;
465     };
466 
467   /**
468    * So that we can iterate over nonzero values, we need an iterator implementation.
469    * This can't be as simple as for Mat, which is just a pointer to an eT.
470    * If a value is set to 0 using this iterator, the iterator is no longer valid!
471    */
472   class iterator : public const_iterator
473     {
474     public:
475 
iterator()476     inline iterator() : const_iterator() { }
iterator(SpMat & in_M,uword initial_pos=0)477     inline iterator(SpMat& in_M, uword initial_pos = 0) : const_iterator(in_M, initial_pos) { }
iterator(SpMat & in_M,uword in_row,uword in_col)478     inline iterator(SpMat& in_M, uword in_row, uword in_col) : const_iterator(in_M, in_row, in_col) { }
iterator(SpMat & in_M,uword in_row,uword in_col,uword in_pos)479     inline iterator(SpMat& in_M, uword in_row, uword in_col, uword in_pos) : const_iterator(in_M, in_row, in_col, in_pos) { }
iterator(const iterator & other)480     inline iterator(const iterator& other) : const_iterator(other) { }
481 
482     inline arma_hot SpValProxy< SpMat<eT> > operator*();
483 
484     // overloads needed for return type correctness
485     inline arma_hot         iterator& operator++();
486     inline arma_warn_unused iterator  operator++(int);
487 
488     inline arma_hot         iterator& operator--();
489     inline arma_warn_unused iterator  operator--(int);
490 
491     // this has a different value_type than iterator_base
492     typedef       SpValProxy< SpMat<eT> >   value_type;
493     typedef const SpValProxy< SpMat<eT> >*  pointer;
494     typedef const SpValProxy< SpMat<eT> >&  reference;
495     };
496 
497   class const_row_iterator : public iterator_base
498     {
499     public:
500 
501     inline const_row_iterator();
502     inline const_row_iterator(const SpMat& in_M, uword initial_pos = 0);
503     //! once initialised, will be at the first nonzero value after the given position (using forward row-wise traversal)
504     inline const_row_iterator(const SpMat& in_M, uword in_row, uword in_col);
505     inline const_row_iterator(const const_row_iterator& other);
506 
507     inline arma_hot         const_row_iterator& operator++();
508     inline arma_warn_unused const_row_iterator  operator++(int);
509 
510     inline arma_hot         const_row_iterator& operator--();
511     inline arma_warn_unused const_row_iterator  operator--(int);
512 
513     uword internal_row; // hold row internally
514     uword actual_pos; // this holds the true position we are at in the matrix, as column-major indexing
515 
operator *() const516     arma_inline eT operator*() const { return iterator_base::M->values[actual_pos]; }
517 
row() const518     arma_inline uword row() const { return internal_row; }
519 
520     inline arma_hot bool operator==(const const_iterator& rhs) const;
521     inline arma_hot bool operator!=(const const_iterator& rhs) const;
522 
523     inline arma_hot bool operator==(const typename SpSubview<eT>::const_iterator& rhs) const;
524     inline arma_hot bool operator!=(const typename SpSubview<eT>::const_iterator& rhs) const;
525 
526     inline arma_hot bool operator==(const const_row_iterator& rhs) const;
527     inline arma_hot bool operator!=(const const_row_iterator& rhs) const;
528 
529     inline arma_hot bool operator==(const typename SpSubview<eT>::const_row_iterator& rhs) const;
530     inline arma_hot bool operator!=(const typename SpSubview<eT>::const_row_iterator& rhs) const;
531     };
532 
533   class row_iterator : public const_row_iterator
534     {
535     public:
536 
row_iterator()537     inline row_iterator() : const_row_iterator() {}
row_iterator(SpMat & in_M,uword initial_pos=0)538     inline row_iterator(SpMat& in_M, uword initial_pos = 0) : const_row_iterator(in_M, initial_pos) { }
539     //! once initialised, will be at the first nonzero value after the given position (using forward row-wise traversal)
row_iterator(SpMat & in_M,uword in_row,uword in_col)540     inline row_iterator(SpMat& in_M, uword in_row, uword in_col) : const_row_iterator(in_M, in_row, in_col) { }
row_iterator(const row_iterator & other)541     inline row_iterator(const row_iterator& other) : const_row_iterator(other) { }
542 
543     inline arma_hot SpValProxy< SpMat<eT> > operator*();
544 
545     // overloads required for return type correctness
546     inline arma_hot         row_iterator& operator++();
547     inline arma_warn_unused row_iterator  operator++(int);
548 
549     inline arma_hot         row_iterator& operator--();
550     inline arma_warn_unused row_iterator  operator--(int);
551 
552     // this has a different value_type than iterator_base
553     typedef       SpValProxy< SpMat<eT> >  value_type;
554     typedef const SpValProxy< SpMat<eT> >* pointer;
555     typedef const SpValProxy< SpMat<eT> >& reference;
556     };
557 
558 
559   typedef       iterator       col_iterator;
560   typedef const_iterator const_col_iterator;
561 
562   typedef       iterator       row_col_iterator;
563   typedef const_iterator const_row_col_iterator;
564 
565 
566   inline       iterator     begin();
567   inline const_iterator     begin() const;
568   inline const_iterator    cbegin() const;
569 
570   inline       iterator     end();
571   inline const_iterator     end() const;
572   inline const_iterator    cend() const;
573 
574   inline       col_iterator begin_col(const uword col_num);
575   inline const_col_iterator begin_col(const uword col_num) const;
576 
577   inline       col_iterator begin_col_no_sync(const uword col_num);
578   inline const_col_iterator begin_col_no_sync(const uword col_num) const;
579 
580   inline       col_iterator end_col(const uword col_num);
581   inline const_col_iterator end_col(const uword col_num) const;
582 
583   inline       col_iterator end_col_no_sync(const uword col_num);
584   inline const_col_iterator end_col_no_sync(const uword col_num) const;
585 
586   inline       row_iterator begin_row(const uword row_num = 0);
587   inline const_row_iterator begin_row(const uword row_num = 0) const;
588 
589   inline       row_iterator end_row();
590   inline const_row_iterator end_row() const;
591 
592   inline       row_iterator end_row(const uword row_num);
593   inline const_row_iterator end_row(const uword row_num) const;
594 
595   inline       row_col_iterator begin_row_col();
596   inline const_row_col_iterator begin_row_col() const;
597 
598   inline       row_col_iterator end_row_col();
599   inline const_row_col_iterator end_row_col() const;
600 
601 
602   inline void  clear();
603   inline bool  empty() const;
604   inline uword size()  const;
605 
606   arma_inline arma_warn_unused SpMat_MapMat_val<eT> front();
607   arma_inline arma_warn_unused eT                   front() const;
608 
609   arma_inline arma_warn_unused SpMat_MapMat_val<eT> back();
610   arma_inline arma_warn_unused eT                   back() const;
611 
612   // Resize memory.
613   // If the new size is larger, the column pointers and new memory still need to be correctly set.
614   // If the new size is smaller, the first new_n_nonzero elements will be copied.
615   // n_nonzero is updated.
616   inline void mem_resize(const uword new_n_nonzero);
617 
618   //! synchronise CSC from cache
619   inline void sync() const;
620 
621   //! don't use this unless you're writing internal Armadillo code
622   inline void remove_zeros();
623 
624   //! don't use this unless you're writing internal Armadillo code
625   inline void steal_mem(SpMat& X);
626 
627   //! don't use this unless you're writing internal Armadillo code
628   inline void steal_mem_simple(SpMat& X);
629 
630   //! don't use this unless you're writing internal Armadillo code
631   template<              typename T1, typename Functor> inline void init_xform   (const SpBase<eT, T1>& x, const Functor& func);
632   template<typename eT2, typename T1, typename Functor> inline void init_xform_mt(const SpBase<eT2,T1>& x, const Functor& func);
633 
634   //! don't use this unless you're writing internal Armadillo code
635   arma_inline bool is_alias(const SpMat<eT>& X) const;
636 
637 
638   protected:
639 
640   inline void                init(uword in_rows, uword in_cols, const uword new_n_nonzero = 0);
641   inline void arma_cold init_cold(uword in_rows, uword in_cols, const uword new_n_nonzero = 0);
642 
643   inline void init(const std::string& text);
644   inline void init(const  SpMat<eT>& x);
645   inline void init(const MapMat<eT>& x);
646 
647   inline void init_simple(const SpMat<eT>& x);
648 
649   inline void init_batch_std(const Mat<uword>& locations, const Mat<eT>& values, const bool sort_locations);
650   inline void init_batch_add(const Mat<uword>& locations, const Mat<eT>& values, const bool sort_locations);
651 
652   inline SpMat(const arma_vec_indicator&, const uword in_vec_state);
653   inline SpMat(const arma_vec_indicator&, const uword in_n_rows, const uword in_n_cols, const uword in_vec_state);
654 
655 
656   private:
657 
658   inline arma_hot arma_warn_unused const eT* find_value_csc(const uword in_row, const uword in_col) const;
659 
660   inline arma_hot arma_warn_unused eT get_value(const uword i                         ) const;
661   inline arma_hot arma_warn_unused eT get_value(const uword in_row, const uword in_col) const;
662 
663   inline arma_hot arma_warn_unused eT get_value_csc(const uword i                         ) const;
664   inline arma_hot arma_warn_unused eT get_value_csc(const uword in_row, const uword in_col) const;
665 
666   inline arma_hot arma_warn_unused bool try_set_value_csc(const uword in_row, const uword in_col, const eT in_val);
667   inline arma_hot arma_warn_unused bool try_add_value_csc(const uword in_row, const uword in_col, const eT in_val);
668   inline arma_hot arma_warn_unused bool try_sub_value_csc(const uword in_row, const uword in_col, const eT in_val);
669   inline arma_hot arma_warn_unused bool try_mul_value_csc(const uword in_row, const uword in_col, const eT in_val);
670   inline arma_hot arma_warn_unused bool try_div_value_csc(const uword in_row, const uword in_col, const eT in_val);
671 
672   inline arma_warn_unused eT&  insert_element(const uword in_row, const uword in_col, const eT in_val = eT(0));
673   inline                  void delete_element(const uword in_row, const uword in_col);
674 
675 
676   // cache related
677 
678   arma_aligned mutable MapMat<eT> cache;
679   arma_aligned mutable state_type sync_state;
680   // 0: cache needs to be updated from CSC (ie.   CSC has more recent data)
681   // 1: CSC needs to be updated from cache (ie. cache has more recent data)
682   // 2: no update required                 (ie. CSC and cache contain the same data)
683 
684   #if (!defined(ARMA_DONT_USE_STD_MUTEX))
685   arma_aligned mutable std::mutex cache_mutex;
686   #endif
687 
688   arma_inline void invalidate_cache() const;
689   arma_inline void invalidate_csc()   const;
690 
691   inline void sync_cache()        const;
692   inline void sync_cache_simple() const;
693   inline void sync_csc()          const;
694   inline void sync_csc_simple()   const;
695 
696 
697   friend class SpValProxy< SpMat<eT> >;  // allow SpValProxy to call insert_element() and delete_element()
698   friend class SpSubview<eT>;
699   friend class SpRow<eT>;
700   friend class SpCol<eT>;
701   friend class SpMat_MapMat_val<eT>;
702   friend class SpSubview_MapMat_val<eT>;
703   friend class spdiagview<eT>;
704 
705   template<typename xT1, typename xT2> friend class SpSubview_col_list;
706 
707   public:
708 
709   #ifdef ARMA_EXTRA_SPMAT_PROTO
710     #include ARMA_INCFILE_WRAP(ARMA_EXTRA_SPMAT_PROTO)
711   #endif
712   };
713 
714 
715 
716 class SpMat_aux
717   {
718   public:
719 
720   template<typename eT, typename T1> inline static void set_real(SpMat<eT>&                out, const SpBase<eT,T1>& X);
721   template<typename T,  typename T1> inline static void set_real(SpMat< std::complex<T> >& out, const SpBase< T,T1>& X);
722 
723   template<typename eT, typename T1> inline static void set_imag(SpMat<eT>&                out, const SpBase<eT,T1>& X);
724   template<typename T,  typename T1> inline static void set_imag(SpMat< std::complex<T> >& out, const SpBase< T,T1>& X);
725   };
726 
727 
728 
729 #define ARMA_HAS_SPMAT
730 
731 
732 
733 //! @}
734