1 This document present the STLport namespace schema and give additionnal 2 information about how STLport replace the native C++ Standard library 3 coming with your compiler. 4 5 1. What is the STLport namespace ? 6 7 As STLport is a C++ Standard library implementation the STLport namespace 8 is 'std'. In normal use this is all you need to know and you can stop reading 9 here. 10 11 2. How does STLport replace native C++ Standard library ? 12 13 STLport defines a macro 'std' that replaces all references of std in the 14 user code by a different name. This technique has has some drawback but also 15 advantages. The drawback is that you cannot declared Standard component like 16 that: 17 18 19 //foo.h 20 namespace std 21 { 22 template <class _Tp> 23 class allocator; 24 } 25 26 void f1(const std::allocator<int>&); 27 28 29 //foo.cpp 30 #include "foo.h" 31 #include <memory> 32 33 void f1(const std::allocator<int>& alloc) 34 { 35 //implementation 36 } 37 38 //bar.cpp 39 #include "foo.h" 40 #include <memory> 41 42 int main(int, char**) 43 { 44 std::allocator<int> alloc; 45 f1(alloc); 46 } 47 48 If you build this code you will surely have a compilation error as f1 is declared 49 as taking a std::allocator parameter but you are calling it using an STLport allocator 50 instance that is not in the std namespace. The good news is that this drawback is easy 51 to detect as it will generate compilation error or at least link time error. The only 52 workaround is to include an arbitrary Standard header before the allocator declaration. 53 Good candidates for that are <utility> or <cerrno> as they are small headers. Including 54 those headers will replace std with the STLport namespace. 55 56 The advantage of this macro replacement is that we can customize the STLport namespace 57 depending on the compilation options. For instance the STLport safe mode you can use by 58 defining _STLP_DEBUG is not binary compatible with a normal debug build. To ensure that 59 no one will ever build code without _STLP_DEBUG and link with STLport library built with 60 this option the namespace is different so that it will generate link time error rather 61 than random crashes during application execution. 62 63 3. Why not having use namespace injection ? 64 65 An other way to replace native Standard C++ library implementation would have been to 66 use namespace injection: 67 68 namespace std 69 { 70 using namespace stlport; 71 } 72 73 This solution has a first major drawback which is that STLport would be much more sensible 74 to native headers. If you include a C++ native headers that indirectly define for instance 75 the vector class it is going to conflict with the STLport vector definition. 76 77 Moreover this solution just does not work for a very simple reason. The C++ Standard 78 allows users to specialized some of the Standard algorithms. This specialization has to 79 be done in the same namespace as the main template declaration: 80 81 //In an STLport header: 82 namespace stlport 83 { 84 template <class _Tp> 85 struct less 86 { 87 bool operator () (const _Tp& x, const _Tp& y) const; 88 }; 89 } 90 91 //User code: 92 93 struct MyStruct; 94 95 namespace std 96 { 97 template <> 98 struct less<MyStruct> 99 { 100 }; 101 } 102 103 As you can see the specialization is not in the STLport less namespace and it 104 won't be used in associative containers for instance. 105 106 4. What is the STLport specific namespace ? 107 108 The official STLport namespace is: stlport. Once again this is not the real namespace 109 where all the Standard stuff are. As the real STLport namespace change depending on compilation 110 options you cannot use it directly. So stlport is an alias of the real STLport namespace. 111 112 5. What are the other STLport namespaces ? 113 114 Those names are given for information purpose and should never be used in any user code. The 115 default STLport namespace is: stlp_std. Here is the list of the customized namespaces: 116 117 - stlpd_std : when _STLP_DEBUG is defined 118 - stlpx_std : when you use STLport as a shared library linked to the static version of the native 119 runtime or when you build the static STLport library linked with the dynamic version. This option 120 is only supported by a limited number of compilers. 121 - stlpmtx_std : when building STLport as not thread safe. 122 123 You can also have combination of those extension like stlpdxmtx_std or stlpdmtx_std... 124 125 There is also an other STLport namespace for STLport internal functions or struct/class: priv. 126 127 namespace stlport 128 { 129 namespace priv 130 { 131 } 132 } 133 134
