STLplus C++ Library Collection - Strings Library
Author: Andy Rushton

# STLplus C++ Library Collection

Website Collection

# Strings Library

- Browse Header strings.hpp
- Contents
- Dependencies
- Introduction
- Overview
- Include Files

## Contents

The components provided are:

- string_basic.hpp: Printing Basic Types
- string_stl.hpp: Printing STL Containers
- string_stlplus.hpp: Printing STLplus Containers
- string_utilities.hpp: Other String-Processing Utilities

## Dependencies

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.

## Introduction

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.

## Overview

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, ":");
    }

## Include Files

Print Functions
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

String-Formatting Functions
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