vaikene.ee Git - evaf/blob - src/libs/Common/util.h

   1 /**
   2  * @file Common/util.h
   3  * @brief Global utility functions for eVaf
   4  * @author Enar Vaikene
   5  *
   6  * Copyright (c) 2011-2019 Enar Vaikene
   7  *
   8  * This file is part of the eVaf C++ cross-platform application development framework.
   9  *
  10  * This file can be used under the terms of the GNU General Public License
  11  * version 3.0 as published by the Free Software Foundation and appearing in
  12  * the file LICENSE included in the packaging of this file. Please review the
  13  * the following information to ensure the GNU General Public License version
  14  * 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
  15  *
  16  * Alternatively, this file may be used in accordance with the Commercial License
  17  * Agreement provided with the Software.
  18  */
  19
  20 #ifndef __COMMON_UTIL_H
  21 #  define __COMMON_UTIL_H
  22
  23 #include "libcommon.h"
  24
  25 #include <QString>
  26 #include <QVariant>
  27
  28 namespace eVaf {
  29 namespace Common {
  30
  31 /**
  32  * Tests if the string means 'true'
  33  * @param str The string
  34  * @return True if the string is 'yes', 'true', 'on' or '1'.
  35  *
  36  * This function tests if the string means 'true'. Use this function when the default value
  37  * should be 'false'.
  38  */
  39 inline bool isTrue(QString const & str)
  40 {
  41     return str == "1" || str.toLower() == "yes" || str.toLower() == "true" || str.toLower() == "on";
  42 }
  43
  44 /**
  45  * Tests if the string means 'false'
  46  * @param str The string
  47  * @return True if the string is 'no', 'false', 'off' or '0'.
  48  *
  49  * This function tests if the string means 'false'. Use this function when the default value
  50  * should be 'true'.
  51  */
  52 inline bool isFalse(QString const & str)
  53 {
  54     return str == "0" || str.toLower() == "no" || str.toLower() == "false" || str.toLower() == "off";
  55 }
  56
  57 /**
  58  * Converts strings to variant values
  59  * @param value The string
  60  * @param defaultValue The default value
  61  * @return value converted from the string or the default if failed
  62  *
  63  * This function converts strings to variant values. The type of the expected value is determined
  64  * from the default value. If the string fails to convert to the expected type, returns the
  65  * default value.
  66  *
  67  * If the default value is of one of the following types, then the following conversion rules are applied:
  68  * @li QVariant::UInt - if the string begins with "0x", base 16 is used; if the string begins with "0",
  69  * base 8 is used; otherwise base 10 is used;
  70  * @li QVariant::Int - base 10 is used;
  71  * @li QVariant::Double - the decimal point is expecte to be '.' regardless which locale is used;
  72  * @li QVariant::Bool - tries to use isTrue() and isFalse() methods; otherwise performs a conversion to QVariant::uint;
  73  * @li QVariant::Char - if the string begins with "\0x", expects it to be a UTF-16 code in hex; if the
  74  * string begins with "\0", expects it to be a UTF-16 code in oct; if the string begins with "&", expects it to
  75  * be a numeric character reference ("&#nnnn;" or "&#xhhhh;") or a predefined character entity reference;
  76  * otherwise uses the first character in the string;
  77  */
  78
  79 COMMON_EXPORT QVariant toVariant(QString const & value, QVariant const & defaultValue);
  80
  81 /**
  82  * Converts unicode strings to escaped 7-bit character arrays.
  83  * @param str Unicode string
  84  * @return Escaped 7-bit character array
  85  *
  86  * This function converts a unicode (or any) string to the escaped 7-bit character array. Characters that cannot
  87  * be output directly as a printable 7-bit character are output as numeric character references. The result can be
  88  * directly inserted into XML or HTML documents and later converted back with the eVaf::Common::strFromEscapedCharArray()
  89  * function.
  90  *
  91  * For example, "Groß" becomes "Gro&#xdf;".
  92  */
  93 COMMON_EXPORT QByteArray strToEscapedCharArray(QString const & str);
  94
  95 /**
  96  * Converts escaped 7-bit character arrays to unicode string.
  97  * @param str Escaped 7-bit character array
  98  * @return Unicode string
  99  *
 100  * This function converts an escaped 7-bit character array to the unicode string. Numeric character references and
 101  * character entity references are expanded to actual unicode characters.
 102  */
 103 COMMON_EXPORT QString strFromEscapedCharArray(QByteArray const & str);
 104
 105 /**
 106  * Converts binary arrays to escaped 7-bit character arrays
 107  * @param src Binary array
 108  * @return Escaped 7-bit character array
 109  *
 110  * This function converts a binary array to the escaped 7-bit character array. Bytes that cannot be output
 111  * directly as printable 7-bit characters are output as numeric character references. The result can be directly
 112  * inserted into XML or HTML documents and later converted back with the eVaf::Common::binFromEscapedCharArray()
 113  * function.
 114  *
 115  * For example, "Hello\r\n" becomes "Hello&#xd;&#xa;".
 116  */
 117 COMMON_EXPORT QByteArray binToEscapedCharArray(QByteArray const & src);
 118
 119 /**
 120  * Converts escaped 7-bit character arrays to binary arrays
 121  * @param str Escaped 7-bit character array
 122  * @return Binary array
 123  *
 124  * This function converts an escaped 7-bit character array to the binary array. Numeric character references and
 125  * character entoty references are expanded to characters and binary bytes.
 126  */
 127 COMMON_EXPORT QByteArray binFromEscapedCharArray(QByteArray const & str);
 128
 129 } // namespace eVaf::Common
 130 } // namespace eVaf
 131
 132 #endif // util.h