STL Supplement Documentation

STL Supplement

Some generic additions to the C++ Standard Template Library
by
Thomas Becker
thomas@styleadvisor.com

Contents

  1. Copyright and Permission Notice
  2. Introduction
  3. Member Function Adapters
  4. Predicate Logic
  5. Composition of Functionals
  6. Binary Search

Copyright and Permission Notice

COPYRIGHT (C) 2000 Thomas Becker

PERMISSION NOTICE:

PERMISSION TO USE, COPY, MODIFY, AND DISTRIBUTE THIS SOFTWARE FOR ANY PURPOSE AND WITHOUT FEE IS HEREBY GRANTED, PROVIDED THAT ALL COPIES ARE ACCOMPANIED BY THE COMPLETE MACHINE-READABLE SOURCE CODE, ALL MODIFIED FILES CARRY PROMINENT NOTICES AS TO WHEN AND BY WHOM THEY WERE MODIFIED, THE ABOVE COPYRIGHT NOTICE, THIS PERMISSION NOTICE AND THE NO-WARRANTY NOTICE BELOW APPEAR IN ALL SOURCE FILES AND IN ALL SUPPORTING DOCUMENTATION.

NO-WARRANTY NOTICE:

THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. ALL IMPLIED WARRANTIES OF FITNESS FOR ANY PARTICULAR PURPOSE AND OF MERCHANTABILITY ARE HEREBY DISCLAIMED.

Introduction

This is a small collection of additions to the C++ Standard Template Library. Everything is contained in the header file StdSuppl.h.

Member Function Adapters

Member Function Adapters for Const Member Functions

The C++ standard has recently added member function adapters to the STL that work for const member functions. Since these are not yet provided in all STL implementations, they are provided here for convenience. To disable them, uncomment the line 
// #define _EXCLUDE_CONST_MEM_FUN_ADAPTERS
in StdSuppl.h.

The const member function adapters are completely analogous to the regular member function adapters. The actual adapters are: 

const_mem_fun_t
const_mem_fun1_t
const_mem_fun_ref_t
const_mem_fun1_ref_t
The corresponding generating non-member functions are simply oveloads of the existing ones: 
mem_fun
mem_fun1
mem_fun_ref
mem_fun1_ref

Member Function Adapters for Member Functions Returning Void

None of the eight STL member function adapters work for member functions returning void. Therefore, StlSuppl.h provides eight more adapters that are precise counterparts to the STL member function adapters, except that they work for member functions returning void. The type names of the actual adapters are: 
void_mem_fun_t
void_mem_fun1_t
void_mem_fun_ref_t
void_mem_fun1_ref_t
void_const_mem_fun_t
void_const_mem_fun1_t
void_const_mem_fun_ref_t
void_const_mem_fun1_ref_t
The corresponding generating non-member functions are not oveloads of the existing ones. That is because it would require for the compiler to handle partial template specialization, which many compilers don't. Instead, the generating non-member functions are: 
void_mem_fun
void_mem_fun1
void_mem_fun_ref
void_mem_fun1_ref

Predicate Logic

The STL provides two adapters that turn predicates into their negations, but no adapters to form the logical conjunction (and) or disjunction (or) of two predicates. The adapters 
unary_and
binary_and
unary_or
binary_or
fill this gap. They come with corresponding generating non-member functions 
and1
and2
or1
or2
Usage of these adapters and generating functions is completely analogous to STL's unary_negation, binary_negation, not1, and not2. The only difference is that you must supply two predicates instead of one, and the signatures of the two predicates must match.

Composition of Functionals

The four adapters 
unary_compose
binary_compose
void_unary_compose
void_binary_compose
provide functionals that represent the composition of two given functionals. The corresponding generating non-member functions are: 
compose1
compose2
void_compose1
void_compose2
Each of these take two functionals f and g as arguments and generate functionals that act as f(g()). In each case, the result type of g must allow a conversion to the type of the sole argument of f.

compose1 and void_compose1 require the inner functional g to take exactly one argument. compose2 and void_compose2 require g to take exactly two arguments. The prefix void_ indicates that the outer functional f must return void.

Some implementations of the STL already contain the non-void versions of composition. If this is the case, you should uncomment the line 

// #define _EXCLUDE_NON_VOID_COMPOSITION_ADAPTERS
in the header file StdSuppl.h.

Binary Search

The algorithms 
template inline
RanIt lower_bound_find(RanIt first, RanIt last, const T& val);
and 
template inline
RanIt lower_bound_find(RanIt first, RanIt last, const T& val, Pred pred);
act like STL's find algorithm, and they guarantee logarithmic complexity. There are two prerequisites for their usage:
  1. The sequence [first, last) must be ordered by the operator < or the predicate pred, respectively.
  2. RanIt must be a random access iterator type.