Strings, containers, I/O

1. Strings, containers, I/O Maciej Dębiński 2010-09-200.9

2. Strings, containers, I/O Module Overview This module covers a wide range of APIs useful to application developers - container classes, string handling, timers, files and streams, among others. Course Duration 3~4 hours. Target Audience Anyone. Prerequisites Basic knowledge of C++ programming. Basic knowledge of Qt’s painting mechanism. Training method Class room or self study. MODULE CONTENT 1. Qt container classes 2. String classes and localization in Qt 3. QUrl 4. Regular expressions in Qt 5. Basic input validation in Qt 6. Timers 7. Brief overview of printing in Qt 8. Access to files & directories in Qt 9. Binary and text-oriented streams in Qt 2

3. Containers in Qt

4. Characteristics of Qt containers • The Qt library provides a set of general purpose template-based container classes: • QList, QVector, QMap, … • Qt containers have been designed to be lighter, safer, and easier to use than the STL containers. • According to the documentation, Qt containers have been optimized for speed, low memory footprint(脚印) and minimal code expansion. • All container classes by use the concept of implicit sharing to minimize copying overhead. • All methods of Qt container classes are reentrant（折返）.

5. Sequential containers • Qt provides the following sequential containers: • QList - an array-based general-purpose list • QLinkedList - a linked-list implementation of the list • QVector - array of values occupying contiguous（连续的）memory • QStack - a LIFO convenience subclass of QVector • QQueue - a FIFO convenience subclass of QList • QList internally stores pointers to objects passed to it in a contiguous array with pre-allocation of a few elements in the beginning and end to speed up insertion. • QVector stores the objects inserted into it themselves in a contiguous region of memory.

6. Associative containers • Qt provides the following associative containers: • QMap - an associative array which maps keys to values • QHash - a hash-table-based dictionary • QSet - a representation of a mathematical set • QMultiMap - a convenience subclass of QMap, which can hold multiple values associated with each key • QMultiHash - a convenience subclass of QHash, which can hold multiple values associated with each key • QMap stores values in Key order. • QMap is implemented as a skip-list-based dictionary.

7. Type requirements • Objects must fulfill certain requirements in order to be able to be stored in Qt containers (and STL as well, for that matter). • They must be an assignable data type, i.e. it must provide • a default constructor, • a copy constructor, • an assignment operator.（operator=） • Keys in QMap and QMultiMap must provide operator<() (so that QMap can determine the order of keys) • Keys in QHash, QMultiHash and QSet must provide operator==() and global qHash(Key) function.

8. Type requirements • QObject and all QObject subclasses (including QWidget) do not fullfill the first requirement. Rather than storing the objects directly, store pointers instead. • QVector<QWidget> vec; // WRONG • QVector<QWidget*> vec; // OK • Some functions in the containers have additional requirements towards the inserted elements, e.g.: • operator==() needs to be provided by the value type, if QMap or QHash’s == or != operators are used. • operator==() needs to be provided by the value type, if indexOf() or lastIndexOf() method of QList or QVector are used. • operator>>() and operator<<() need to be provided for both key type and value type, if respective container’s << or >> operator is used.

9. Adding elements to containers • In case of sequential containers(顺序容器), the easiest way to add new elements is to use the << operator. QList<QString> list; list << ”Apple" << ”Orange" << ”Kiwi” << ”Banana”; QVector<double> numbers; numbers << 0.0 << 0.5 << 1.0; • The following methods are also available: • void append ( const T & value ); • void prepend ( const T & value ); • void insert ( int i, const T & value )；); // not available in QLinkedList • iterator insert ( iterator before, const T & value ); • void push_back ( const T & value ); • void push_front ( const T & value );

10. Adding elements to containers • In associative containers(关联容器), key-value pairs are stored, so << operator is not available. Instead, [] operator is used. QMap<int, QString> map; map[1] = "one"; map[2] = “two”; map[3] = "three"; QHash<QString, double> hash; hash[“Bob”] = 13.5; hash[“John”] = 15.0; hash[“Bob”] = 10.5; • The following methods are also available: • iterator insert ( const Key & key, const T & value ); • iterator insertMulti ( const Key & key, const T & value ); QMap<int, int> map; map.insert(10, 1); // map contains pair 10 - 1 map.insert(10, 5); // map contains pair 10 - 5 exists, but not 10 - 1 map.insertMulti(10, 6); // map contains both pairs 10 - 5 and 10 - 6

11. Access to items in containers • Elements stored in sequential containers can be accessed in a number of ways: • First or last element • By index • Using Java-style iterators • Using STL-style iterators • Elements stored in associative containers are accessed: • By key • By value • Using Java-style iterators • Using STL-style iterators

12. Random access Access by index is not available in QLinkedList • The following methods for accessing previously stored values are available in sequential containers: • const T & at ( int i ) const; • T value ( int i ) const; • T & operator[] ( int i ); • T takeAt ( int i ); • T & front (); • T & back (); • T & first (); • T & last (); • T takeFirst (); • T takeLast ();

13. Access by key/value • Access to key-value pairs in associative containers is somewhat more concise than in sequential containers: • const T value ( const Key & key ) const; • const Key key ( const T & value ) const; • T & operator[] ( const Key & key ); • QList<T> values () const; • QList<Key> keys () const; • Methods value() and key() return a default-constructed value if the looked-up parameter was not found in the container. • Operator [] inserts a new pair <key - default-constructed value> if there was no value assigned to the key yet. Then it returns a reference to that default-constructed value.

14. Iterators in Qt Java-style STL-style • Qt provides two types of iterators: • STL-style iterators • Java-style iterators • The differences between these two types are summarized below: • Different class names (QListIterator<T> vs. QList<T>::const_iterator) • Different APIs • STL-style iterators point directly to individual elements of the container, while Java-style iterators point between the elements.

15. Java-style iterators • The following Java-style iterators are available in Qt: • Read-only: QListIterator, QLinkedListIterator, QVectorIterator, QSetIterator, QMapIterator, QHashIterator • Read-write: QMutableListIterator, QMutableLinkedListIterator, QMutable-VectorIterator, QMutableSetIterator, QMutableMapIterator, QMutableHash-Iterator • Whenever possible, use the read-only versions as they are more efficient. • With read-write iterators, there is also risk of causing a detachment（分离）of implicitly shared data (i.e. making data’s deep copy), which is an unnecessary overhead.

16. Java-style iterators • The read-write iterators implement in addition: • void insert ( const T & value ); • void remove (); • void setValue ( const T & value ) const; • T & value (); • Also, obviously, next() and previous() families of methods return non-const references to stored elements. • Use key() and value() methods with iterators of associative containers. • The read-only iterators’ API: • bool findNext( const T & value ); • bool findPrevious( const T & value ); • bool hasNext() const; • bool hasPrevious() const; • const T & next(); • const T & previous(); • const T & peekNext() const; • const T & peekPrevious() const; • void toBack(); • void toFront();

17. Java-style iterators QMap<QString, QString> map; map.insert("Guatemala City", "Guatemala"); map.insert("Mexico City", "Mexico"); map.insert("Moscow", "Russia"); QMutableMapIterator<QString,QString> i(map); while (i.hasNext()) { if (i.next().key().endsWith("City")) i.remove(); } QMap<int, QWidget *> map; QHash<int, QWidget *> hash; QMapIterator<int, QWidget *> i(map); while (i.hasNext()) { i.next(); hash.insert(i.key(), i.value()); } QList<QString> names; names << “Bob" << “John" << “Patrick" << “Sue"; QListIterator<QString> i(names); while ( i.hasNext() ) qDebug() << i.next(); QListIterator<QString> i(names); i.toBack(); while (i.hasPrevious()) qDebug() << i.previous(); QMutableListIterator<QString> i(names); while ( i.hasNext() ) { if ( i.next() % 2 != 0 ) i.remove(); }

18. STL-style iterators • The following STL-style iterators are available in Qt: • Read-write • QList<T>::iterator • QLinkedList<T>::iterator • QVector<T>::iterator • QSet<T>::iterator • QMap<T>::iterator • QHash<T>::iterator • The following STL-style iterators are available in Qt: • Read-only • QList<T>::const_iterator • QLinkedList<T>::const_iterator • QVector<T>::const_iterator • QSet<T>::const_iterator • QMap<T>::const_iterator • QHash<T>::const_iterator • With STL-style iterators, ++ is used to move iterator forward, -- to move it backward, and * (dereference operator) is used for retrieving the value of the element.

19. STL-style iterators • Qt containers provide the following functions used in conjunction with STL-style iterators: • iterator begin (); • const_iterator constBegin () const; • iterator end (); • const_iterator constEnd () const; • iterator insert ( iterator before, const T & value ); QList<QString>::const_iterator i; for (i = list.constBegin(); i != list.constEnd(); ++i) qDebug() << *i;

20. Foreach keyword • To make iterating over the contents of containers easier, Qt provides a new keyword ‘foreach’. Under the hood（引擎盖）, ‘foreach’ is a macro. • The syntax is as follows: • foreach (variable, container) statement • Unless the data type contains a comma, variable can be declared inside of the parenthesis itself. • Qt automatically takes acopy of the container when it enters a foreach loop. However, since all Qt containers use implicit sharing, the copy is very quick and does not involve copying all stored elements. • Original container will remain unchanged, even if you modify the container as you are iterating.

21. Foreach keyword - examples QLinkedList<QString> list; list << “one” << “two” << “three” << QString() << “four”; foreach (const QString& str, list) { if (str.isEmpty()) break; qDebug() << str; } QString str; foreach (str, list) { qDebug() << str; } QMap<QString, int> map; map.insert(“one”, 1); foreach (const QString &str, map.keys()) { qDebug() << str << ":" << map.value(str); }

22. QStack & QQueue • QStack & QQueue are convenience classes based on QVector & QList respectively, which provide last-in-first-out (LIFO) and first-in-first-out (FIFO) semantics（语义）. • QStack adds the following methods to QVector API: • T pop (); • void push ( const T & t ); • T & top (); • QQueue introduces the following methods to QList API: • T dequeue (); • void enqueue ( const T & t ); • T & head ();

23. Container growth strategies • To avoid reallocation of elements every time containers grow, Qt usually allocates more memory that necessary in advance and performs a reallocation only when that memory runs out. For example: • QHash and QSet grows by power of 2 every time • QList and QString grow as follows: • Grows 8 bytes at a time until it reaches size 40 bytes • From 40 to 8168 it grow to the next power of 2 minus 24 bytes • Above it grows by 4096 bytes • Some containers, e.g. QVector & QHash, provide methods to manually preallocate a number of elements: • void reserve ( int size ); • void squeeze (); • int capacity () const;

24. Algorithms • Similarly to STL, Qt comes bundled with a set of algorithms, which can be used to perform certain frequent operations on containers and sets of their elements. • qDeleteAll() - deletes a range of elements from a container • qBinaryFind() - finds an element in a container using binary search • qFind() - finds an element in a container • qSwap() - exchanges two values • qSort() - sorts a set of values • qStableSort() - sorts a set of items without changing the order of equal items • qFill() - fills a range of elements with particular values • qCopy() - copies a range of elements from one container to another • qCount() - returns the number of occurrences of an element in a range of elements

25. Algorithms Different algorithms can have different requirements for the iterators they accept. For example, qSort(), qBinarySearch() and qStableSort() require two random access iterators - iterators which can be used to jump to any element in any direction. Only QList and QVector’s modifiable iterators fulfill all requirements of random access iterators (because their elements are stored in a contiguous memory region). Other algorithms have less strict requirements and can be used with all modifiable/non-modifiable STL-style iterators.

26. Algorithms - examples QVector<int> vector; vect << 3 << 10 << 4 << 6 << 12 << 8; qSort( vector.begin(), vector.end() ); // 3,4,6,8,10,12 QVector<int>::iterator i = qBinaryFind( vector.begin(), vector.end(), 12 ); bool isLastItem = (i == vector.end()-1); // isLastItem == true qFill( vector.begin(), vector.begin()+2, 5 ); // 5,5,5,8,10,12 int count; qCount( vector.begin(), vector.end(), 5, count ); // count = 3 QList<int> list; list << 5 << 5 << 5 << 8 << 10; bool isEqual = qEqual( vector.begin(), vector.end(), list.begin() ); // isEqual == false list << 12; isEqual = qEqual( vector.begin(), vector.end(), list.begin() ); // isEqual == true

27. More information • For those, who need more detailed information on each of the containers provided by Qt, here are some references: • http://doc.trolltech.com/qq/qq19-containers.html • http://doc.qt.nokia.com/4.7-snapshot/containers.html • http://doc.qt.nokia.com/4.7-snapshot/qtalgorithms.html • http://doc.qt.nokia.com/4.7-snapshot/qvector.html • http://doc.qt.nokia.com/4.7-snapshot/qlist.html • http://doc.qt.nokia.com/4.7-snapshot/qlinkedlist.html • http://doc.qt.nokia.com/4.7-snapshot/qmap.html • http://doc.qt.nokia.com/4.7-snapshot/qhash.html • http://doc.qt.nokia.com/4.7-snapshot/qset.html

28. Strings in Qt

29. Qstring • QString is the basic Qt class for handling Unicode strings. • Every character within QString is represented by a 16-bit Unicode 4.0 (5.1?) QChar character. • Behind the scenes, QString uses implicit sharing (copy-on-write) to reduce memory usage and to avoid the needless copying of data. • Traditional 8-bit ‘\0’-terminated strings and arrays of raw 8-bit data are represented in Qt by QByteArray class. • QString class provides a large number of overloaded methods meant to make using it with traditional string literals and character arrays as easy and intuitive as possible. • QString str = "Hello";

30. QString API - string manipulation • QString contains a large number of methods for performing all sorts of basic string manipulation, concatenation and searching: • QString & append ( const QString & str ); • QString & insert ( int position, const QString & str ); • QString & prepend ( const QString & str ); • QString & replace ( int position, int n, const QString & after ); • QString right ( int n ) const; • QString left ( int n ) const; • QString mid ( int position, int n = -1 ) const; • QString toUpper () const; • QString toLower () const; • int indexOf ( const QString & str, int from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive ) const; • int lastIndexOf ( const QString & str, int from = -1, Qt::CaseSensitivity cs = Qt::CaseSensitive ) const;

31. QString API - number-string conversion(Switch) • QString provides a number of methods for converting between numbers and strings. Here are only a few examples: • float toFloat ( bool * ok = 0 ) const; • int toInt ( bool * ok = 0, int base = 10 ) const; • long toLong ( bool * ok = 0, int base = 10 ) const; • short toShort ( bool * ok = 0, int base = 10 ) const; • … • QString & setNum ( int n, int base = 10 ); • QString & setNum ( long n, int base = 10 ); • QString & setNum ( short n, int base = 10 ); • QString & setNum ( double n, char format = 'g', int precision = 6 ); • …

32. QString API - number-string conversion • There are also a few static functions, which produce a string representation of a given number: • QString number ( long n, int base = 10 ); • QString number ( double n, char format = 'g', int precision = 6 ); • QString number ( ulong n, int base = 10 ); • QString number ( int n, int base = 10 ); • … long n = 127; bool ok; QString str = QString::number(n, 16); // str == 7f int value = str.toInt(&ok); // value = 0; ok == false J:Means convert failed value = str.toInt(&ok, 16); // value = 127; ok == true J:means convert succeed. str.setNum(50505); // str == “50505“

33. QString API - arguments • QString provides a family of printf-like functions for easy substitution of numbers and strings into another string: • QString arg ( const QString & a, int fieldWidth = 0, const QChar & fillChar = QLatin1Char( ' ' ) ) const; • QString arg ( int a, int fieldWidth = 0, int base = 10, const QChar & fillChar = QLatin1Char( ' ' ) ) const; • … QString str = QString(“File no %1”).arg(100); // str == “File no 100” str = QString(“Could not load file %1 from %2 - error code: %3”).arg(“myfile.doc”).arg(“\home\papa\”).arg(3); str = QString(“%1 is %2 in hexadecimal notation”).arg(255).arg(255,0,16); QLocale::setDefault(QLocale(QLocale::English, QLocale::UnitedStates)); str = QString("%L1") .arg(12345); // str == 12,345

34. String conversions • While QString stores its character data in Unicode format, it is also possible to convert it to various 8-bit encodings should it be necessary. • QString provides the following methods for this: • toAscii() - uses the coded returned by QTextCodec::codecForCStrings() • toLatin1() • toUtf8() • toLocal8Bit() - uses system’s local encoding • Similar methods for reverse convertion ( fromXXX() ) also exist. • By default, C strings are converted to Unicode using toAscii() if no explicit conversion is requested.

35. String conversions • Encodings to be used when applying default conversion can be changed by using QTextCodec::setCodecForCStrings() static method. • On systems which use other encodings than Latin-1, there is a risk that implicit conversion will use an incorrect encoding if appropriate one is not set. • To minimize the risk, one can turn implicit conversion off using one or both of the following macros: • QT_NO_CAST_FROM_ASCII • QT_NO_CAST_TO_ASCII • If the first above macro has been defined, the following line will fail: • QString s = “Hello world”; // implicit conversion - compilation error • QString s = QString::fromLatin1(“Hello world”); // explicit conversion works

36. Other string classes in Qt • To facilitate working with Latin-1 encoded 8-bit strings Qt provides QLatin1Char and QLatin1String classes. • These classes are very thin wrappers around char and char* respectively, and sometimes allow optimizing the source code to avoid constructing temporary QString objects. QString str = …; if (str == "papa" || str == "mama") { ... } // works only if implicit conversion is on if (str == QLatin1String("papa") || str == QLatin1String("mama")) { … } • QStringRef class allows to eliminate unnecessary copying of character data when handling substrings of already existing QStrings. • QString hello("hello"); • QStringRef ref(&hello, 1, 3); // ref points to “ell” in “hello” • QStringRef provides read-only API. It is somewhat similar to TPtrC in Symbian.

37. String translation - tr() • In Qt, static method tr() from QObject class is used for translating strings: • QString QObject::tr ( constchar * sourceText, constchar * disambiguation = 0, int n = -1 ); • Its parameters are: • Text to be translated • A comment/hint for the translator to help him distinguish words with multiple meanings • If plurals(复数)are used in the sentence, number makes it clear what the value is • Examples: • QLabel* senderLabel = new QLabel(tr("Name:")); • QString message( tr(“Hello dear user!”) ); • QPushButton* button = new QPushButton( tr(“&Open”, ”open new window”) ); • int n = messages.count(); • showMessage(tr("%n message(s) saved", "", n));

38. String translation(ToHere) tr() function looks up the string passed to it (i.e. the plain not translated version) in the translation files currently installed in the application using QTranslator. Then, it returns the translated version of the string. Translations in Qt are indexed by so-called translation context. Translation context for a QObject subclass is defined inside of the Q_OBJECT macro. If Q_OBJECT macro is not defined, context from the base class will be used. For translation to work, one or more QTranslator objects must be installed in the application at the time this method is called.

39. String translation - QTranslator Loading Qt translations Loading app-specific translations • In order to install translations from particular file: • Load the file using QTranslator::load() • Install the translator using QCoreApplication::installTranslator() • Many translations can be loaded simultaneously. int main(int argc, char *argv[]) { QApplication app(argc, argv); QTranslator qtTranslator; qtTranslator.load("qt_" + QLocale::system().name(), QLibraryInfo::location(QLibraryInfo::TranslationsPath)); app.installTranslator(&qtTranslator); QTranslator myappTranslator; myappTranslator.load("myapp_" + QLocale::system().name()); app.installTranslator(&myappTranslator); ... return app.exec(); }

40. String translation • Installing a new QTranslator or removing one of the previously installed ones (using QCoreApplication::removeTranslator()) generates a QEvent::LanguageChange event propagated to all top-level windows. • QTranslators are searched in reverse order and look-up ends as soon as first matching translation is found. • You may have noticed that QObject::tr() takes char* as a parameter, but returns QString. • The conversion between 8-bit and Unicode 16-bit encoding is done using the codec returned by QTextCodec::codecForTr(); • Codec may be changed to a different one using • void QTextCodec::setCodecForTr ( QTextCodec * c );

41. String translation • Tr() function is only available directly in methods of QObject subclasses, because it is implemented in QObject. • If there is a need to mark a string in a global function for translation, one can: • Use fully qualified name: e.g. QObject::tr() • Use QApplication’s translate() method • QString str = QString( qApp->translate(“SomeContext”, “Translated string”) ); • If there is a need to translate a string completely outside of a function, e.g. in a global string array, one can use one of these macros: • QT_TR_NOOP( “text for translation” ) • QT_TRANSLATE_NOOP( “context”, “text for translation” )

42. String translation • By declaring the following macro at the very beginning of a class which does not inherit from QObject, developer can add translation facilities to it: • Q_DECLARE_TR_FUNCTIONS(ClassName) • This macro adds tr() and trUtf8() methods that can be used to translate strings in the class. class MyContainer { Q_DECLARE_TR_FUNCTIONS(MyContainer) public: MyContainer() { QString str = tr( “Hello to my container” ); } ~MyContainer(); }

43. String translation - other steps • After all strings have been marked with tr() or QT_TR*_NOOP macros and QTranslator object has been installed, you should also make sure that the following steps were performed: • All translation files are included in .pro file in the TRANSLATIONS section • lupdate utility has been used to generate .ts files for each language • Strings in .ts files have been translated to appropriate languages, e.g. in Qt Linguist • lrelease utility has been used to compile .ts files to .qm format used by QTranslator

44. Additional information • Further information on QString API is available in its class reference: • http://doc.qt.nokia.com/4.7-snapshot/qstring.html • http://doc.qt.nokia.com/4.7-snapshot/qlatin1string.html • http://doc.qt.nokia.com/4.7-snapshot/qchar.html • A few more details about character encodings can be found here: • http://doc.qt.nokia.com/4.7-snapshot/qtextcodec.html • Information about application internationalization are available here: • http://doc.qt.nokia.com/4.7-snapshot/internationalization.html • http://doc.qt.nokia.com/4.7-snapshot/i18n-source-translation.html • http://doc.qt.nokia.com/4.7-snapshot/linguist-manual.html • http://doc.qt.nokia.com/4.7-snapshot/linguist-hellotr.html • http://doc.qt.nokia.com/4.7-snapshot/qcoreapplication.html#translate • http://doc.qt.nokia.com/4.7-snapshot/qobject.html#tr • http://doc.qt.nokia.com/4.7-snapshot/qtranslator.html

45. URLs and regular expressions

46. QUrl class • A uniform resource locator (URL) is represented in Qt by QUrl class. • QUrl implements the following functionality: • Constructing and parsing URLs in both encoded and unencoded form • Support for internationalized domain names (IDNs) • QUrl conforms to URI syntax specification from RFC 3986, scheme extensions from RFC 1738 and folding rules from RFC 3491. • According to that specification, an URL consists of several parts: • Scheme • Authority • Path • Fragment • Query strings

47. URL parts • ftp://mike:pass@ftp.example.com:2021/cgi-bin/draw.cgi?color=green • Scheme - ftp • User - mike • Password - pass • User info - mike:pass • Host - ftp.example.com • Port - 2021 • Authority - mike:pass@ftp.example.com:2021 • Path - /cgi-bin/ • Query string - color=green

48. QUrl API • QUrl provides methods for retrieving and setting the value of each of the parts mentioned previously, e.g.: • QString authority () const; • QString host () const; • QString scheme () const; • void setUserName ( const QString & userName ); • Simplest way to create a QUrl object is to pass it a QString version of the path: QUrl url("http://doc.qt.nokia.com/4.7-snapshot/qurl.html"); QString str = url.scheme() + “://” + url.host(); if( url.path().contains(“4.7”) ) qDebug << “Using new Qt!!”;

49. QUrl • The following methods of QUrl are typically used to encode/decode the URL: • QByteArray toEncoded ( FormattingOptions options = None ) const; • QUrl fromEncoded ( const QByteArray & input ); • QByteArray toPercentEncoding ( const QString & input, const QByteArray & exclude = QByteArray(), const QByteArray & include = QByteArray() ); • QString fromPercentEncoding ( const QByteArray & input ); • There are also a few methods for use with relative URLs: • bool isRelative () const; • QUrl resolved ( const QUrl & relative ) const; QUrl baseUrl("http://qt.nokia.com/support"); QUrl relativeUrl("../products/solutions"); qDebug(baseUrl.resolved(relativeUrl).toString()); // prints "http://qt.nokia.com/products/solutions"

50. Regular expressions • Regular expressions in Qt are represented by QRegExp class. • QRegExp’s syntax is modeled on Perl’s regular expressions and it has full support for Unicode. • QRegExp in one of several modes. These include for example: • QRegExp::RegExp -- default Qt regular expressions • QRegExp::Wildcard -- simple pattern matching like in shells • QRegExp::FixedString -- matching with all metacharacters excaped • Developers can switch between those using setPatternSyntax() method.