add sptk_utils to doc

doc/utils/sptk.rst

@@ -0,0 +1,4 @@
+sptk
+====
+
+.. doxygenfile:: sptk_utils.cc

include/SPTK/utils/sptk_utils.h

@@ -45,6 +45,7 @@
 #ifndef SPTK_UTILS_SPTK_UTILS_H_
 #define SPTK_UTILS_SPTK_UTILS_H_
 
+#include <cstddef>   // std::size_t
 #include <iostream>  // std::istream, std::ostream
 #include <sstream>   // std::ostringstream
 #include <string>    // std::string
@@ -61,62 +62,228 @@
 
 namespace sptk {
 
+//! Version of SPTK.
 static const char* const kVersion("4.0");
+//! @f$\pi@f$
 static const double kPi(3.141592653589793);
+//! @f$2\pi@f$
 static const double kTwoPi(6.283185307179586);
-static const double kNeper(8.685889638065035);   // 1 Np = 20 / ln(10) dB
-static const double kOctave(1.442695040888963);  // 1 / ln(2)
+//! @f$20 / \ln(10)@f$
+static const double kNeper(8.685889638065035);
+//! @f$1 / \ln(2)@f$
+static const double kOctave(1.442695040888963);
+//! @f$\ln(2)@f$
 static const double kLogTwo(0.693147180559945);
+//! @f$\ln(0)@f$
 static const double kLogZero(-1.0e+10);
 
+/**
+ * @param[out] data_to_read Scalar.
+ * @param[out] input_stream Stream to be read.
+ * @return True on success, false on failure.
+ */
 template <typename T>
 bool ReadStream(T* data_to_read, std::istream* input_stream);
+
+/**
+ * @param[out] matrix_to_read Matrix.
+ * @param[out] input_stream Stream to be read.
+ * @return True on success, false on failure.
+ */
 bool ReadStream(sptk::Matrix* matrix_to_read, std::istream* input_stream);
+
+/**
+ * @param[out] matrix_to_read Symmetric matrix.
+ * @param[out] input_stream Stream to be read.
+ * @return True on success, false on failure.
+ */
 bool ReadStream(sptk::SymmetricMatrix* matrix_to_read,
                 std::istream* input_stream);
 
+/**
+ * @param[in] zero_padding If true and @f$L'>0@f$, pad @f$L-L'@f$ elements
+ *            with zeros and return true. If false, padding is not performed
+ *            and return false.
+ * @param[in] stream_skip Skip size.
+ * @param[in] read_point Insert index in vector.
+ * @param[in] read_size Target read size, @f$L@f$.
+ * @param[out] sequence_to_read Vector.
+ * @param[out] input_stream Stream to be read.
+ * @param[out] actual_read_size Actual read size, @f$L'@f$.
+ * @return True on success, false on failure.
+ */
 template <typename T>
 bool ReadStream(bool zero_padding, int stream_skip, int read_point,
                 int read_size, std::vector<T>* sequence_to_read,
                 std::istream* input_stream, int* actual_read_size);
 
+/**
+ * @param[in] data_to_write Scalar.
+ * @param[out] output_stream Stream to be write.
+ * @return True on success, false on failure.
+ */
 template <typename T>
 bool WriteStream(T data_to_write, std::ostream* output_stream);
+
+/**
+ * @param[in] matrix_to_write Matrix.
+ * @param[out] output_stream Stream to be write.
+ * @return True on success, false on failure.
+ */
 bool WriteStream(const sptk::Matrix& matrix_to_write,
                  std::ostream* output_stream);
+
+/**
+ * @param[in] matrix_to_write Symmetric matrix.
+ * @param[out] output_stream Stream to be write.
+ * @return True on success, false on failure.
+ */
 bool WriteStream(const sptk::SymmetricMatrix& matrix_to_write,
                  std::ostream* output_stream);
 
+/**
+ * @param[in] write_point Start index.
+ * @param[in] write_size Target write size.
+ * @param[in] sequence_to_write Vector.
+ * @param[out] output_stream Stream to be write.
+ * @param[out] actual_write_size Actual write size.
+ * @return True on success, false on failure.
+ */
 template <typename T>
 bool WriteStream(int write_point, int write_size,
                  const std::vector<T>& sequence_to_write,
                  std::ostream* output_stream, int* actual_write_size);
 
+/**
+ * @param[in] data Data.
+ * @param[in] print_format Print format.
+ * @param[in] buffer_size Buffer size.
+ * @param[out] buffer Formatted data.
+ * @return True on success, false on failure.
+ */
 template <typename T>
-bool SnPrintf(T data, const std::string& print_format, size_t buffer_size,
+bool SnPrintf(T data, const std::string& print_format, std::size_t buffer_size,
               char* buffer);
 
+/**
+ * @param[in] input Boolean.
+ * @return Converted string, "TRUE" or "FALSE".
+ */
 const char* ConvertBooleanToString(bool input);
+
+/**
+ * @param[in] input String.
+ * @param[out] output Converted integer value.
+ * @return True on success, false on failure.
+ */
 bool ConvertStringToInteger(const std::string& input, int* output);
+
+/**
+ * @param[in] input String.
+ * @param[out] output Converted float value.
+ * @return True on success, false on failure.
+ */
 bool ConvertStringToDouble(const std::string& input, double* output);
+
+/**
+ * @param[in] input String can be "pi", "db", "cent", "semitone", "octave",
+ *            "sqrtX", "lnX", "expX", and "X", where "X" is a number.
+ * @param[out] output Converted float value.
+ * @return True on success, false on failure.
+ */
 bool ConvertSpecialStringToDouble(const std::string& input, double* output);
 
+/**
+ * @param[in] num A number.
+ * @return True if given number is even, false otherwise.
+ */
 bool IsEven(int num);
+
+/**
+ * @param[in] num A number.
+ * @param[in] min Minimum value.
+ * @param[in] max Maximum value.
+ * @return True if given number is in [min, max], false otherwise.
+ */
 bool IsInRange(int num, int min, int max);
+
+/**
+ * @param[in] num A number.
+ * @param[in] min Minimum value.
+ * @param[in] max Maximum value.
+ * @return True if given number is in [min, max], false otherwise.
+ */
 bool IsInRange(double num, double min, double max);
+
+/**
+ * @param[in] num A number.
+ * @return True if given number is @f$2^n@f$, where @f$n@f$ is a non-negative
+ *         number, false otherwise.
+ */
 bool IsPowerOfTwo(int num);
+
+/**
+ * @param[in] alpha All-pass constant, @f$\alpha@f$.
+ * @return True if given alpha satisfy @f$|\alpha| < 1@f$, false otherwise.
+ */
 bool IsValidAlpha(double alpha);
+
+/**
+ * @param[in] gamma Gamma, @f$\gamma@f$.
+ * @return True if given gamma satisfy @f$|\gamma| \le 1@f$, false otherwise.
+ */
 bool IsValidGamma(double gamma);
 
-int NextPow(int num);
-int ExtractSign(double x);
+/**
+ * @param[in] num A number, @f$x@f$.
+ * @return The smallest @f$2^n@f$ greater than or equal to @f$x@f$, where
+ *         @f$n@f$ is a non-negative number.
+ */
+int NextPowTwo(int num);
+
+/**
+ * @param[in] num A number, @f$x@f$.
+ * @return @f$\mathrm{sgn}(x)@f$.
+ */
+int ExtractSign(double num);
 
-double FloorLog(double x);
-double FloorLog2(double x);
-double FloorLog10(double x);
+/**
+ * @param[in] num A number, @f$x@f$.
+ * @return @f$\max(\ln(x), -1 \times 10^{10})@f$.
+ */
+double FloorLog(double num);
+
+/**
+ * @param[in] num A number, @f$x@f$.
+ * @return @f$\max(\log_2(x), -1 \times 10^{10})@f$.
+ */
+double FloorLog2(double num);
+
+/**
+ * @param[in] num A number, @f$x@f$.
+ * @return @f$\max(\log_{10}(x), -1 \times 10^{10})@f$.
+ */
+double FloorLog10(double num);
+
+/**
+ * @param[in] log_x @f$\ln(x)@f$.
+ * @param[in] log_y @f$\ln(y)@f$.
+ * @return @f$\ln(x + y)@f$.
+ */
 double AddInLogSpace(double log_x, double log_y);
 
+/**
+ * @param[in] symbol A character represents data type.
+ * @param[out] stream Stream to be written readable data type.
+ */
 void PrintDataType(const std::string& symbol, std::ostream* stream);
+
+/**
+ * Print error message to standard error.
+ *
+ * @param[in] program_name Name of SPTK command.
+ * @param[in] message Error message.
+ */
 void PrintErrorMessage(const std::string& program_name,
                        const std::ostringstream& message);
 

src/utils/misc_utils.cc

@@ -194,7 +194,7 @@ bool MakePseudoQuadratureMirrorFilterBanks(
     const std::vector<double>& window(kaiser_window.Get());
 
     // Prepare FFT.
-    const int fft_size(sptk::NextPow(filter_size));
+    const int fft_size(sptk::NextPowTwo(filter_size));
     sptk::RealValuedFastFourierTransform fft(num_filter_order, fft_size);
     sptk::RealValuedFastFourierTransform::Buffer buffer_for_fft;
     if (!fft.IsValid()) {

src/utils/sptk_utils.cc

@@ -48,7 +48,6 @@
 #include <cctype>     // std::tolower
 #include <cerrno>     // errno, ERANGE
 #include <cmath>      // std::ceil, std::exp, std::log, std::sqrt, etc.
-#include <cstddef>    // std::size_t
 #include <cstdint>    // int8_t, int16_t, int32_t, int64_t, etc.
 #include <cstdio>     // std::snprintf
 #include <cstdlib>    // std::strtod, std::strtol
@@ -244,6 +243,7 @@ bool WriteStream(int write_point, int write_size,
   return !output_stream->fail();
 }
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 template <>
 bool WriteStream(int write_point, int write_size,
                  const std::vector<std::string>& sequence_to_write,
@@ -272,6 +272,7 @@ bool WriteStream(int write_point, int write_size,
 
   return !output_stream->fail();
 }
+#endif  // DOXYGEN_SHOULD_SKIP_THIS
 
 template <typename T>
 bool SnPrintf(T data, const std::string& print_format, std::size_t buffer_size,
@@ -285,6 +286,7 @@ bool SnPrintf(T data, const std::string& print_format, std::size_t buffer_size,
              : true;
 }
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 template <>
 bool SnPrintf(int24_t data, const std::string& print_format,
               std::size_t buffer_size, char* buffer) {
@@ -297,7 +299,9 @@ bool SnPrintf(int24_t data, const std::string& print_format,
              ? false
              : true;
 }
+#endif  // DOXYGEN_SHOULD_SKIP_THIS
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 template <>
 bool SnPrintf(uint24_t data, const std::string& print_format,
               std::size_t buffer_size, char* buffer) {
@@ -310,6 +314,7 @@ bool SnPrintf(uint24_t data, const std::string& print_format,
              ? false
              : true;
 }
+#endif  // DOXYGEN_SHOULD_SKIP_THIS
 
 const char* ConvertBooleanToString(bool input) {
   return input ? "TRUE" : "FALSE";
@@ -405,8 +410,6 @@ bool IsInRange(double num, double min, double max) {
   return (min <= num && num <= max);
 }
 
-// Check whether the given number is a power of two, 2^p where p is a
-// non-negative integer.
 bool IsPowerOfTwo(int num) {
   return !((num < 1) || (num & (num - 1)));
 }
@@ -419,7 +422,7 @@ bool IsValidGamma(double gamma) {
   return (std::fabs(gamma) <= 1.0);
 }
 
-int NextPow(int num) {
+int NextPowTwo(int num) {
   num--;
   num |= num >> 1;
   num |= num >> 2;
@@ -430,25 +433,24 @@ int NextPow(int num) {
   return num;
 }
 
-int ExtractSign(double x) {
-  if (0.0 < x) return 1;
-  if (x < 0.0) return -1;
+int ExtractSign(double num) {
+  if (0.0 < num) return 1;
+  if (num < 0.0) return -1;
   return 0;
 }
 
-double FloorLog(double x) {
-  return (x <= 0.0) ? kLogZero : std::log(x);
+double FloorLog(double num) {
+  return (num <= 0.0) ? kLogZero : std::log(num);
 }
 
-double FloorLog2(double x) {
-  return (x <= 0.0) ? kLogZero : std::log2(x);
+double FloorLog2(double num) {
+  return (num <= 0.0) ? kLogZero : std::log2(num);
 }
 
-double FloorLog10(double x) {
-  return (x <= 0.0) ? kLogZero : std::log10(x);
+double FloorLog10(double num) {
+  return (num <= 0.0) ? kLogZero : std::log10(num);
 }
 
-// Compute log(x + y) given log(x) and log(y).
 double AddInLogSpace(double log_x, double log_y) {
   if (log_x == log_y) return log_x + kLogTwo;
 
@@ -524,6 +526,7 @@ void PrintErrorMessage(const std::string& program_name,
 }
 
 // clang-format off
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 template bool ReadStream<bool>(bool*, std::istream*);
 template bool ReadStream<int8_t>(int8_t*, std::istream*);
 template bool ReadStream<int16_t>(int16_t*, std::istream*);
@@ -589,6 +592,7 @@ template bool SnPrintf(uint64_t, const std::string&, std::size_t, char*);
 template bool SnPrintf(float, const std::string&, std::size_t, char*);
 template bool SnPrintf(double, const std::string&, std::size_t, char*);
 template bool SnPrintf(long double, const std::string&, std::size_t, char*);
+#endif  // DOXYGEN_SHOULD_SKIP_THIS
 // clang-format on
 
 }  // namespace sptk