annotate liboctave/util/lo-utils.h @ 31606:dfa5d9c3ae72

maint: merge stable to default
author Rik <rik@octave.org>
date Thu, 01 Dec 2022 14:28:07 -0800
parents 9a0ce9eea1b7 e88a07dec498
children 23664317f0d3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
1 ////////////////////////////////////////////////////////////////////////
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
2 //
30564
796f54d4ddbf update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 29954
diff changeset
3 // Copyright (C) 1996-2022 The Octave Project Developers
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
4 //
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
5 // See the file COPYRIGHT.md in the top-level directory of this
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
6 // distribution or <https://octave.org/copyright/>.
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
7 //
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
8 // This file is part of Octave.
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
9 //
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
10 // Octave is free software: you can redistribute it and/or modify it
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
11 // under the terms of the GNU General Public License as published by
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
12 // the Free Software Foundation, either version 3 of the License, or
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
13 // (at your option) any later version.
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
14 //
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
15 // Octave is distributed in the hope that it will be useful, but
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
16 // WITHOUT ANY WARRANTY; without even the implied warranty of
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
18 // GNU General Public License for more details.
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
19 //
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
20 // You should have received a copy of the GNU General Public License
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
21 // along with Octave; see the file COPYING. If not, see
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
22 // <https://www.gnu.org/licenses/>.
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
23 //
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
24 ////////////////////////////////////////////////////////////////////////
1967
4cb6aaa0f2c7 [project @ 1996-02-17 02:54:24 by jwe]
jwe
parents:
diff changeset
25
20791
f7084eae3318 maint: Use Octave coding conventions for #if statements.
Rik <rik@octave.org>
parents: 19697
diff changeset
26 #if ! defined (octave_lo_utils_h)
17822
ebb3ef964372 maint: Use common #define syntax "octave_filename_h" in h_files.
Rik <rik@octave.org>
parents: 17744
diff changeset
27 #define octave_lo_utils_h 1
1967
4cb6aaa0f2c7 [project @ 1996-02-17 02:54:24 by jwe]
jwe
parents:
diff changeset
28
21244
1473547f50f5 include octave-config.h in public header files
John W. Eaton <jwe@octave.org>
parents: 21139
diff changeset
29 #include "octave-config.h"
1473547f50f5 include octave-config.h in public header files
John W. Eaton <jwe@octave.org>
parents: 21139
diff changeset
30
2926
66ef74ee5d9f [project @ 1997-05-05 03:20:52 by jwe]
jwe
parents: 2847
diff changeset
31 #include <cstdio>
66ef74ee5d9f [project @ 1997-05-05 03:20:52 by jwe]
jwe
parents: 2847
diff changeset
32
25438
cb1606f78f6b prefer <istream>, <ostream>, or <iosfwd> to <iostream> where possible
John W. Eaton <jwe@octave.org>
parents: 25054
diff changeset
33 #include <iosfwd>
2926
66ef74ee5d9f [project @ 1997-05-05 03:20:52 by jwe]
jwe
parents: 2847
diff changeset
34 #include <string>
66ef74ee5d9f [project @ 1997-05-05 03:20:52 by jwe]
jwe
parents: 2847
diff changeset
35
4130
7d9bda865012 [project @ 2002-10-28 21:05:30 by jwe]
jwe
parents: 3970
diff changeset
36 #include "oct-cmplx.h"
23443
3f1bf237908b maint: Eliminate <cfloat.h> header from liboctave files.
Rik <rik@octave.org>
parents: 23220
diff changeset
37 #include "quit.h"
4130
7d9bda865012 [project @ 2002-10-28 21:05:30 by jwe]
jwe
parents: 3970
diff changeset
38
31605
e88a07dec498 maint: Use macros to begin/end C++ namespaces.
Rik <rik@octave.org>
parents: 30595
diff changeset
39 OCTAVE_BEGIN_NAMESPACE(octave)
e88a07dec498 maint: Use macros to begin/end C++ namespaces.
Rik <rik@octave.org>
parents: 30595
diff changeset
40
29937
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
41 // Generic any/all test functionality with arbitrary predicate.
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
42
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
43 template <typename F, typename T, bool zero>
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
44 bool
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
45 any_all_test (F fcn, const T *m, octave_idx_type len)
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
46 {
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
47 octave_idx_type i;
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
48
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
49 for (i = 0; i < len - 3; i += 4)
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
50 {
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
51 octave_quit ();
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
52
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
53 if (fcn (m[i]) != zero
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
54 || fcn (m[i+1]) != zero
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
55 || fcn (m[i+2]) != zero
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
56 || fcn (m[i+3]) != zero)
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
57 return ! zero;
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
58 }
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
59
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
60 octave_quit ();
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
61
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
62 for (; i < len; i++)
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
63 if (fcn (m[i]) != zero)
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
64 return ! zero;
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
65
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
66 return zero;
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
67 }
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
68
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
69 extern OCTAVE_API bool xis_int_or_inf_or_nan (double x);
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
70
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
71 template <typename T>
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
72 bool is_one_or_zero (const T& x)
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
73 {
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
74 return x == T (0) || x == T (1);
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
75 }
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
76
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
77 template <typename T>
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
78 bool is_zero (const T& x)
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
79 {
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
80 return x == T (0);
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
81 }
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
82
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
83 extern OCTAVE_API bool too_large_for_float (double x);
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
84
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
85 extern OCTAVE_API bool too_large_for_float (const Complex& x);
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
86
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
87 extern OCTAVE_API bool is_int_or_inf_or_nan (float x);
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
88 extern OCTAVE_API bool too_large_for_float (float x);
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
89
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
90 extern OCTAVE_API char * strsave (const char *);
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
91
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
92 extern OCTAVE_API std::string fgets (std::FILE *);
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
93 extern OCTAVE_API std::string fgetl (std::FILE *);
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
94
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
95 extern OCTAVE_API std::string fgets (std::FILE *, bool& eof);
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
96 extern OCTAVE_API std::string fgetl (std::FILE *, bool& eof);
da7210e30f3e move some utility functions inside octave namespace
John W. Eaton <jwe@octave.org>
parents: 29445
diff changeset
97
29230
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
98 template <typename T> OCTAVE_API T read_value (std::istream& is);
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
99
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
100 template <> OCTAVE_API double read_value (std::istream& is);
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
101 template <> OCTAVE_API Complex read_value (std::istream& is);
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
102 template <> OCTAVE_API float read_value (std::istream& is);
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
103 template <> OCTAVE_API FloatComplex read_value (std::istream& is);
28628
83172e1c77f2 refactor octave_read_* and octave_write_* functions
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
104
29230
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
105 template <typename T> OCTAVE_API void write_value (std::ostream& os, const T& value);
28628
83172e1c77f2 refactor octave_read_* and octave_write_* functions
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
106
29230
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
107 template <> OCTAVE_API void write_value (std::ostream& os, const double& value);
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
108 template <> OCTAVE_API void write_value (std::ostream& os, const Complex& value);
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
109 template <> OCTAVE_API void write_value (std::ostream& os, const float& value);
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
110 template <> OCTAVE_API void write_value (std::ostream& os, const FloatComplex& value);
28849
8b0675c2cfe0 Add functions to check for integer overflow on multiplication (bug #59094).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28643
diff changeset
111
31605
e88a07dec498 maint: Use macros to begin/end C++ namespaces.
Rik <rik@octave.org>
parents: 30595
diff changeset
112 OCTAVE_BEGIN_NAMESPACE(math)
e88a07dec498 maint: Use macros to begin/end C++ namespaces.
Rik <rik@octave.org>
parents: 30595
diff changeset
113
29445
b5f3ae7610cf Use gnulib macros that account for the output type in integer overflow checks.
Markus Mützel <markus.muetzel@gmx.de>
parents: 29359
diff changeset
114 extern OCTAVE_API bool int_multiply_overflow (int a, int b, int *r);
29230
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
115
29445
b5f3ae7610cf Use gnulib macros that account for the output type in integer overflow checks.
Markus Mützel <markus.muetzel@gmx.de>
parents: 29359
diff changeset
116 extern OCTAVE_API bool
b5f3ae7610cf Use gnulib macros that account for the output type in integer overflow checks.
Markus Mützel <markus.muetzel@gmx.de>
parents: 29359
diff changeset
117 int_multiply_overflow (long int a, long int b, long int *r);
29230
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
118
28849
8b0675c2cfe0 Add functions to check for integer overflow on multiplication (bug #59094).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28643
diff changeset
119 #if defined (OCTAVE_HAVE_LONG_LONG_INT)
29230
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
120 extern OCTAVE_API bool
29445
b5f3ae7610cf Use gnulib macros that account for the output type in integer overflow checks.
Markus Mützel <markus.muetzel@gmx.de>
parents: 29359
diff changeset
121 int_multiply_overflow (long long int a, long long int b, long long int *r);
28849
8b0675c2cfe0 Add functions to check for integer overflow on multiplication (bug #59094).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28643
diff changeset
122 #endif
29230
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
123
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
124 extern OCTAVE_API bool
29445
b5f3ae7610cf Use gnulib macros that account for the output type in integer overflow checks.
Markus Mützel <markus.muetzel@gmx.de>
parents: 29359
diff changeset
125 int_multiply_overflow (unsigned int a, unsigned int b, unsigned int *r);
29230
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
126
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
127 extern OCTAVE_API bool
29445
b5f3ae7610cf Use gnulib macros that account for the output type in integer overflow checks.
Markus Mützel <markus.muetzel@gmx.de>
parents: 29359
diff changeset
128 int_multiply_overflow (unsigned long int a, unsigned long int b,
b5f3ae7610cf Use gnulib macros that account for the output type in integer overflow checks.
Markus Mützel <markus.muetzel@gmx.de>
parents: 29359
diff changeset
129 unsigned long int *r);
29230
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
130
28849
8b0675c2cfe0 Add functions to check for integer overflow on multiplication (bug #59094).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28643
diff changeset
131 #if defined (OCTAVE_HAVE_UNSIGNED_LONG_LONG_INT)
29230
6b3faa844395 Set API tags in files in liboctave/util (patch #8919).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28849
diff changeset
132 extern OCTAVE_API bool
29445
b5f3ae7610cf Use gnulib macros that account for the output type in integer overflow checks.
Markus Mützel <markus.muetzel@gmx.de>
parents: 29359
diff changeset
133 int_multiply_overflow (unsigned long long int a, unsigned long long int b,
b5f3ae7610cf Use gnulib macros that account for the output type in integer overflow checks.
Markus Mützel <markus.muetzel@gmx.de>
parents: 29359
diff changeset
134 unsigned long long int *r);
28849
8b0675c2cfe0 Add functions to check for integer overflow on multiplication (bug #59094).
Markus Mützel <markus.muetzel@gmx.de>
parents: 28643
diff changeset
135 #endif
31605
e88a07dec498 maint: Use macros to begin/end C++ namespaces.
Rik <rik@octave.org>
parents: 30595
diff changeset
136
e88a07dec498 maint: Use macros to begin/end C++ namespaces.
Rik <rik@octave.org>
parents: 30595
diff changeset
137 OCTAVE_END_NAMESPACE(math)
e88a07dec498 maint: Use macros to begin/end C++ namespaces.
Rik <rik@octave.org>
parents: 30595
diff changeset
138 OCTAVE_END_NAMESPACE(octave)
9469
c6edba80dfae sanity checks for loading sparse matrices
John W. Eaton <jwe@octave.org>
parents: 8950
diff changeset
139
29954
4c88a452519c rename OCTAVE_USE_DEPRECATED_FUNCTIONS macro and attempt to make it work
John W. Eaton <jwe@octave.org>
parents: 29937
diff changeset
140 #endif