1 /*************************************************************************** 2 Utils.h - some commonly used utility functions 3 ------------------- 4 begin : Sun Mar 27 2011 5 copyright : (C) 2011 by Thomas Eschenbacher 6 email : Thomas.Eschenbacher@gmx.de 7 ***************************************************************************/ 8 9 /*************************************************************************** 10 * * 11 * This program is free software; you can redistribute it and/or modify * 12 * it under the terms of the GNU General Public License as published by * 13 * the Free Software Foundation; either version 2 of the License, or * 14 * (at your option) any later version. * 15 * * 16 ***************************************************************************/ 17 18 #ifndef KWAVE_UTILS_H 19 #define KWAVE_UTILS_H 20 21 #include "config.h" 22 23 #include <limits> 24 25 #include <QString> 26 #include <QtGlobal> 27 #include <QUrl> 28 29 #include "libkwave/Sample.h" // for sample_index_t 30 31 namespace Kwave 32 { 33 34 /** 35 * Gives the control to the next thread. This can be called from 36 * within the run() function. 37 */ 38 void Q_DECL_EXPORT yield(); 39 40 /** 41 * Converts a zoom factor into a string. The number of decimals 42 * is automatically adjusted in order to give a nice formated 43 * percent value. If the zoom factor gets too high for a reasonable 44 * display in percent, the factor is displayed as a numeric 45 * multiplier. 46 * examples: "0.1 %", "12.3 %", "468 %", "11x" 47 * @param percent the zoom factor to be formated, a value of "100.0" 48 * means "100%", "0.1" means "0.1%" and so on. 49 */ 50 QString Q_DECL_EXPORT zoom2string(double percent); 51 52 /** 53 * Converts a time in milliseconds into a string. Times below one 54 * millisecond are formated with an automatically adjusted number 55 * of decimals. Times below one second are formated like "9.9 ms". 56 * Times above one second and below one minute are rounded up 57 * to full seconds and shown as "12.3 s". From one full minute 58 * upwards time is shown as "12:34" (like most CD players do). 59 * @param ms time in milliseconds 60 * @param precision number of digits after the comma, for limiting 61 * the length. optional, default = 6 digits, 62 * must be >= 3 ! 63 * @return time formatted as user-readable string 64 */ 65 QString Q_DECL_EXPORT ms2string(double ms, int precision = 6); 66 67 /** 68 * Converts a number of samples (aka sample_index_t) into a string, 69 * according the current locale settings. 70 * @param samples number of sample 71 * @return number formatted with thousands separators 72 */ 73 QString Q_DECL_EXPORT samples2string(sample_index_t samples); 74 75 /** 76 * Converts a time in milliseconds into a string with hours, 77 * minutes, seconds and milliseconds. 78 * @param ms time in milliseconds 79 * @return time formatted as HH:MM:SS:mmmm 80 */ 81 QString Q_DECL_EXPORT ms2hms(double ms); 82 83 /** 84 * Tries to convert a string into a QDate 85 * @param s string to convert 86 * @return a ISO 8601 timestamp: "yyyy-MM-ddTHH:mm:ss" 87 * or shortened as date "yyyy-MM-dd" 88 */ 89 QString Q_DECL_EXPORT string2date(const QString &s); 90 91 /** 92 * Round up a numeric value 93 * @param x value to round up 94 * @param s unit size 95 * @return x rounded up to the next unit 96 */ round_up(T x,const T s)97 template<class T> T round_up(T x, const T s) 98 { 99 T modulo = (x % s); 100 if (modulo) x += (s - modulo); 101 return x; 102 } 103 104 /** 105 * Convert a numeric value into an unsigned int, with range / overflow 106 * protection 107 * @param x some numeric value, e.g. a sample_index_t or qint64 108 * @return some unsigned int [0 ... UINT_MAX] 109 */ toUint(T x)110 template <typename T> unsigned int toUint(T x) 111 { 112 const unsigned int max = std::numeric_limits<unsigned int>::max(); 113 Q_ASSERT(x >= 0); 114 Q_ASSERT(static_cast<quint64>(x) <= static_cast<quint64>(max)); 115 116 if (x <= 0) return 0; 117 if (static_cast<quint64>(x) > static_cast<quint64>(max)) return max; 118 119 return static_cast<unsigned int>(x); 120 } 121 122 /** 123 * Convert a numeric value into an int, with range / overflow 124 * protection 125 * @param x some numeric value, e.g. a sample_index_t or qint64 126 * @return some (signed) int [INT_MIN ... INT_MAX] 127 */ toInt(T x)128 template <typename T> int toInt(T x) 129 { 130 const int min = std::numeric_limits<int>::min(); 131 const int max = std::numeric_limits<int>::max(); 132 Q_ASSERT(static_cast<qint64>(x) >= static_cast<qint64>(min)); 133 Q_ASSERT(static_cast<qint64>(x) <= static_cast<qint64>(max)); 134 135 if (static_cast<qint64>(x) < static_cast<qint64>(min)) return min; 136 if (static_cast<qint64>(x) > static_cast<qint64>(max)) return max; 137 138 return static_cast<int>(x); 139 } 140 141 /** 142 * Wrapper around Kwave::URLfromUserInput that handles relative paths and 143 * prefers local file names 144 * @param path a file name, path, or other kind of string encoded URL 145 * @return a QUrl object 146 */ 147 QUrl URLfromUserInput(const QString &path) Q_DECL_EXPORT; 148 149 /** returns the URL scheme for encoding/decoding kwave:<*> URLs */ 150 QString urlScheme() Q_DECL_EXPORT; 151 152 /** 153 * Returns the limit of memory that can be used for undo/redo 154 * in units of whole megabytes 155 */ 156 quint64 undoLimit() Q_DECL_EXPORT; 157 158 } 159 160 #endif /* KWAVE_UTILS_H */ 161 162 //*************************************************************************** 163 //*************************************************************************** 164