QString documentation issue

[seasoned_geek]

While I'm on my documentation bender, near the bottom of this page:

https://www.copperspice.com/docs/cs_api/class_qstring8.html#ae2e2be78a3e7905da42c751866b73c1b

Member Typedef Documentation

Does not declare the header file where size_type (or the others) are declared. If one puts just the QString header file in their source code because they are writing utility functions, not classes, you don't get the typedef. Probably because it isn't a typedef anymore? It certainly doesn't appear to be consistently defined across the framework.

Code: Select all

roland@roland-HP-Z2-SFF-G4-Workstation:/usr/include/copperspice$ grep -irn size_type * | grep -i typedef
QtCore/qvarlengtharray.h:46:   typedef int size_type;
QtCore/regex/regex_raw_buffer.h:97:   typedef std::size_t           size_type;
QtCore/regex/r_object_cache.h:47:   typedef typename list_type::size_type size_type;
QtCore/regex/r_object_cache.h:73:   typedef typename map_type::size_type map_size_type;
QtCore/qcontiguouscache.h:85:   typedef int size_type;
roland@roland-HP-Z2-SFF-G4-Workstation:/usr/include/copperspice$ 
roland@roland-HP-Z2-SFF-G4-Workstation:/usr/include/copperspice$ 
roland@roland-HP-Z2-SFF-G4-Workstation:/usr/include/copperspice$ grep -irn size_type * | grep -i using
QtCore/cs_rcu_list.h:56:      using size_type       = std::ptrdiff_t;
QtCore/qstring8.h:216:      using size_type       = std::ptrdiff_t;
QtCore/qhash.h:55:      using size_type         = typename std::unordered_map<Key, Val, Hash, KeyEqual>::difference_type;
QtCore/qhash.h:139:      using size_type         = typename std::unordered_map<Key, Val, Hash, KeyEqual>::difference_type;
QtCore/qhash.h:231:   using size_type       = typename std::unordered_map<Key, Val, Hash, KeyEqual>::difference_type;
QtCore/cs_string_view.h:38:      using size_type              = typename S::difference_type;
QtCore/qmultimap.h:53:      using size_type         = typename std::multimap<Key, Val, C>::difference_type;
QtCore/qmultimap.h:147:      using size_type       = typename std::multimap<Key, Val, C>::difference_type;
QtCore/qmultimap.h:247:   using size_type       = typename std::multimap<Key, Val, C>::difference_type;   // signed instead of unsigned
QtCore/qmap.h:53:      using size_type         = typename std::map<Key, Val, C>::difference_type;
QtCore/qmap.h:146:      using size_type       = typename std::map<Key, Val, C>::difference_type;
QtCore/qmap.h:246:   using size_type       = typename std::map<Key, Val, C>::difference_type;   // signed instead of unsigned
QtCore/qfuture.h:141:      using size_type = difference_type;
QtCore/qlist.h:56:   using size_type       = typename std::deque<T>::difference_type;      // makes this signed instead of unsigned
QtCore/qlinkedlist.h:46:   using size_type       = typename std::list<T>::difference_type;      // makes this signed instead of unsigned
QtCore/qflatmap.h:56:      using size_type         = typename std::vector<std::pair<Key, Val>>::difference_type;
QtCore/qflatmap.h:150:      using size_type       = typename std::vector<std::pair<Key, Val>>::difference_type;
QtCore/qflatmap.h:268:   using size_type       = typename std::vector<std::pair<Key, Val>>::difference_type;   // signed instead of unsigned
QtCore/qjsonarray.h:42:   using size_type          = QVector<QJsonValue>::size_type;
QtCore/cs_string.h:53:      using size_type              = std::ptrdiff_t;
QtCore/qmultihash.h:55:      using size_type         = typename std::unordered_multimap<Key, Val, Hash, KeyEqual>::difference_type;
QtCore/qmultihash.h:139:      using size_type         = typename std::unordered_multimap<Key, Val, Hash, KeyEqual>::difference_type;
QtCore/qmultihash.h:230:   using size_type       = typename std::unordered_multimap<Key, Val, Hash, KeyEqual>::difference_type;
QtCore/regex/basic_regex.h:214:   using size_type         = std::size_t;
QtCore/regex/basic_regex.h:318:   using traits_size_type  = typename string_type::size_type;
QtCore/regex/basic_regex.h:330:   using size_type         = std::size_t;
QtCore/regex/perl_matcher.h:393:   using traits_size_type   = std::size_t;
QtCore/regex/match_results.h:57:   using size_type          = typename vector_type::size_type;
QtCore/qvector.h:46:   using size_type       = typename std::vector<T>::difference_type;      // makes this signed instead of unsigned
QtCore/qstack.h:37:      using size_type       = typename QVector<T>::difference_type;
QtCore/cs_string_iterator.h:53:      using size_type         = std::ptrdiff_t;
QtCore/cs_encoding.h:32:      using size_type    = std::ptrdiff_t;
QtCore/cs_encoding.h:212:      using size_type    = std::ptrdiff_t;
QtCore/qjsonobject.h:46:   using size_type      = QFlatMap<QString, QJsonValue>::size_type;
QtCore/qstringview.h:49:      using size_type       = typename S::difference_type;
QtCore/qstring16.h:216:      using size_type       = std::ptrdiff_t;
QtCore/qset.h:53:   using size_type       = typename std::unordered_set<T, Hash>::difference_type;      // makes this signed instead of unsigned
QtGui/qtreewidgetitemiterator.h:69:   using size_type     = std::ptrdiff_t;
QtWebKit/qwebelement.h:186:    using size_type = int;
roland@roland-HP-Z2-SFF-G4-Workstation:/usr/include/copperspice$ 

When we have a stand-alone utility function set that performs operations on QString objects, which header file do we need to get size_type or at least the size_type QString expects?

Thanks,

[barbara]

As you mentioned, the following code can be found in the file "src/core/string/qstring8.h". It is part of the definition for the QString8 class.

using difference_type = std:ptddiff_t;
using size_type = std::ptrdiff_t;

Both of these line declare a Type Alias which consists of an (A) identifier and a (B) type-id. The identifier is a new name for the
previously defined type id. There is no difference between a type alias declaration and typedef declaration.

The CopperSpice team prefers the "using" syntax for improved readability.

If you are using the QString class in any application simply include <qstring.h>. If you tried this and received a compiler error please let us know the exact error message.

Barbara

[seasoned_geek]

>There is no difference between a type alias declaration and typedef declaration.

typedef is global.

That's the difference.

Within an application framework a typedef has a singular definition. No matter the class or container, a typedef defined entity is always the exact same.

My issue is the documentation needs to stop calling it a typedef because unlike a typdef alias has no global stability.

If I typedef a dollar to be an American_Dollar it is always an American_Dollar throughout the entire framework.
If I "alias" dollar to American_Dollar and if the framework also has a Canadian class it can also be Canadian_Dollar.

An alias is not a typedef. Calling an alias a typedef gets you into all kinds of trouble.

[barbara]

An alias is not a typedef. Calling an alias a typedef gets you into all kinds of trouble.

The following text was copied directly from cppreference, which is a trusted site for interpreting the C++ standard.

"A type alias declaration introduces a name which can be used as a synonym for the type denoted by type-id. It does not introduce a new type and it cannot change the meaning of an existing type name. There is no difference between a type alias declaration and typedef declaration. This declaration may appear in block scope, class scope, or namespace scope."

typedef is global

This is not how C++ works. Both typedef and type alias declarations (using) can be global or scoped to a class or just a single method or namespace. A typedef or a using declaration can be global, but there is no guarantee and you can not assume the scope based on the kind of declaration.

Since the identifier "size_type" is documented as part of the QString class this means it is a part of the class and not a global declaration. If you look through the API documentation of our libraries or the C++ standard you will see every container has its own definition of "size_type" and they do not conflict nor are they the same.

Barbara