The components provided are:
The strings library has a soft dependency on the containers and portability libraries. This means that it only requires these two libraries in order to make their contents persistent. If there is no need for that functionality, then it is possible to compile the strings library to exclude them.
To compile the strings library in stand-alone mode, you need to add the following
pre-processor switch to the compiler setup. If you are building using the provided makefile
system, then this can be added to the file strings/Makefile.
CPPFLAGS += -DNO_STLPLUS_CONTAINERS CPPFLAGS += -DNO_STLPLUS_INF
In fact, these lines are already present in the makefile, but commented out.
You will also need to provide these switches in any program that uses the strings library, since it controls what's visible in the headers that are included into your code.
You will also need to comment out the dependencies:
#LIBRARIES += ../portability #LIBRARIES += ../containers
Note the # comment at the start of the line to comment out these dependencies.
The strings library provides the ability to print or perform in-string formatting of data structures. It's main purpose is diagnostic printouts of data structures, since the fomatting available is fairly simple. However, it can be extended to use in data file generation, for example.
The library also contains some string-processing utilities which I have found I often use but aren't available in a portable form in any operating system.
The approach taken with the strings library is to provide a toolkit which makes it easy if not trivial to make a data structure printable. However, it is not totally automatic - C++ is too flexible a language to be able to take any data structure and just print it. This is why the approach has been to provide a toolkit out of which printing routines can be written.
The library provides a set of functions for printing out container classes in terms of print functions for printing out the contained type. So, a complex data structure can be printed by assembling print routines in layers corresponding to the layers of the data structure. Funtions are provided in pairs: a print function for use with iostream and a to_string function for in-string formatting.
For example, a std::vector of std::string is printed by repeatedly calling the dump routine for string. The elements are separated by a user-defined separator string.
The same concept is applied to all the container classes. Therefore, to make a container printable, all you have to do is supply print and/or to_string functions for the contained type. If the contained type is a basic C or C++ type, then these functions are already provided and the data structure is already printable.
The print functions for simple types are non-templates. For example, here is the print functions for std::string:
void print_string(std::ostream& device, const std::string& value);
The name of the function is always print_type.
The in-string formatting function does not take an ostream paremeter, but instead returns the string representation:
std::string string_to_string(const std::string& value);
This function seems pointless - but in fact is necassary because it can then be passed to a higher-level print function. For example, to generate a string representation of a vector of strings, you use vector_to_string which has the following parameter profile:
template<typename T, typename S>
std::string vector_to_string(const std::vector<T>& values,
S to_string_fn,
const std::string& separator);
So, the first parameter is the data to be formatted, the second is a pointer to a function - such as string_to_string - to be used to format the elements of the vector.
std::string result = stlplus::vector_to_string(data, stlplus::string_to_string, ",");
This assembly of functions can be continued indefinitely. For example, to print a list of vectors of strings, simply add the next layer. The list functions are:
template<typename T, typename S>
std::string list_to_string(const std::list<T>& values,
S to_string_fn,
const std::string& separator);
However, the S parameter - the to_string_fn - must be a single-parameter function. This means you need to wrap the existing vector_to_string call into a specialisation function:
std::string string_vector_to_string(const std::vector<std::string>& data)
{
return stlplus::vector_to_string(data, stlplus::string_to_string, ",");
}
It is now possible to implement the list formatting function, and of course, this can then be wrapped into a two-parameter function to be used in yet another level of data structure.
std::string string_vector_list_to_string(const std::list<std::vector<std::string> >& data)
{
return stlplus::list_to_string(data, stlplus::string_vector_to_string, ":");
}
| Type | Library | Include | Function Names |
|---|---|---|---|
| bool | C | print_bool.hpp | print_bool |
| short | C | print_int.hpp | print_short |
| unsigned short | C | print_int.hpp | print_unsigned_short |
| int | C | print_int.hpp | print_int |
| unsigned | C | print_int.hpp | print_unsigned |
| long | C | print_int.hpp | print_long |
| unsigned long | C | print_int.hpp | print_unsigned_long |
| inf | STLplus | print_inf.hpp | print_inf |
| float | C | print_float.hpp | print_float |
| double | C | print_float.hpp | print_double |
| T* | C/C++ | print_pointer.hpp | print_pointer |
| shared_ptr<T> | STL | print_shared_ptr.hpp | print_shared_ptr |
| smart_ptr<T> | STLplus | print_smart_ptr.hpp | print_smart_ptr |
| simple_ptr<T> | STLplus | print_simple_ptr.hpp | print_simple_ptr |
| char* | C | print_cstring.hpp | print_cstring |
| string | STL | print_string.hpp | print_string |
| bitset<N> | STL | print_bitset.hpp | print_bitset |
| complex<T> | STL | print_complex.hpp | print_complex |
| deque<T> | STL | print_deque.hpp | print_deque |
| list<T> | STL | print_list.hpp | print_list |
| vector<T> | STL | print_vector.hpp | print_vector |
| pair<T1,T2> | STL | print_pair.hpp | print_pair |
| triple<T1,T2,T3> | STLplus | print_triple.hpp | print_triple |
| foursome<T1,T2,T3,T4> | STLplus | print_foursome.hpp | print_foursome |
| hash<K,T,H,E> | STLplus | print_hash.hpp | print_hash |
| map<K,T> | STL | print_map.hpp | print_map |
| multimap<K,T> | STL | print_multimap.hpp | print_multimap |
| set<T> | STL | print_set.hpp | print_set |
| multiset<T> | STL | print_multiset.hpp | print_multiset |
| digraph<N,A> | STLplus | print_digraph.hpp | print_digraph |
| matrix<T> | STLplus | print_matrix.hpp | print_matrix |
| ntree<T> | STLplus | print_ntree.hpp | print_ntree |
| Type | Library | Include | Function Names |
|---|---|---|---|
| bool | C | string_bool.hpp | bool_to_string |
| short | C | string_int.hpp | short_to_string |
| unsigned short | C | string_int.hpp | unsigned_short_to_string |
| int | C | string_int.hpp | int_to_string |
| unsigned | C | string_int.hpp | unsigned_to_string |
| long | C | string_int.hpp | long_to_string |
| unsigned long | C | string_int.hpp | unsigned_long_to_string |
| inf | STLplus | string_inf.hpp | inf_to_string |
| float | C | string_float.hpp | float_to_string |
| double | C | string_float.hpp | double_to_string |
| T* | C/C++ | string_pointer.hpp | pointer_to_string |
| shared_ptr<T> | STL | string_smart_ptr.hpp | smart_ptr_to_string |
| smart_ptr<T> | STLplus | string_smart_ptr.hpp | smart_ptr_to_string |
| simple_ptr<T> | STLplus | string_smart_ptr.hpp | smart_ptr_to_string |
| char* | C | string_cstring.hpp | cstring_to_string |
| string | STL | string_string.hpp | string_to_string |
| bitset<N> | STL | string_bitset.hpp | bitset_to_string |
| complex<T> | STL | string_complex.hpp | complex_to_string |
| deque<T> | STL | string_deque.hpp | deque_to_string |
| list<T> | STL | string_list.hpp | list_to_string |
| vector<T> | STL | string_vector.hpp | vector_to_string |
| pair<T1,T2> | STL | string_pair.hpp | pair_to_string |
| triple<T1,T2,T3> | STLplus | string_triple.hpp | triple_to_string |
| foursome<T1,T2,T3,T4> | STLplus | string_foursome.hpp | foursome_to_string |
| hash<K,T,H,E> | STLplus | string_hash.hpp | hash_to_string |
| map<K,T> | STL | string_map.hpp | map_to_string |
| multimap<K,T> | STL | string_multimap.hpp | multimap_to_string |
| set<T> | STL | string_set.hpp | set_to_string |
| multiset<T> | STL | string_multiset.hpp | multiset_to_string |
| digraph<N,A> | STLplus | string_digraph.hpp | digraph_to_string |
| matrix<T> | STLplus | string_matrix.hpp | matrix_to_string |
| ntree<T> | STLplus | string_ntree.hpp | ntree_to_string |