STLAlgorithmExtensions/Algorithm Standards

• Documentation Outline
• Physical Organization
• Namespaces
• Naming Conventions
• Range Interfaces

Documentation Outline

Detailed documentation for each algorithm should include the following elements:

///\brief A brief description of the algorithm.  This is the text that will
/// attract users to investigate the algorithm, so keep it short, clear, and
/// meaningful.
///
///\description A longer, complete yet succinct, description that includes
/// complexity details.  The long description can (and should) span many lines.
///
///\tparam Name describe a template parameter; name the iterator category or
/// concept that applies, if any.
///\tparam Name describe another template parameter
///
///\param Name describe a formal parameter's purpose and usage; if all are
/// intuitively obvious, there's no need to call them out
///\param Name describe another template parameter
///
///\pre describe a precondition (a condition that must hold upon entering the
/// function; which implies that satisfying the condition is the caller's
/// responsibility)
///\pre describe another precondition
///\post describe a postcondition (a condition that is guaranteed to hold upon
/// function return)
///\post describe another postcondition
///
///\code example code illustrating how to use the algorithm \endcode

Physical Organization

The current plans for organizing algorithms in Boost is to put most, if not all, algorithms in the Boost.Algorithm library. Algorithms will be put into appropriate subdirectories beneath boost/algorithm. The following subdirectories are currently recognized:

• parallel - Algorithms that divide a task into parts executed in parallel.
• sequence - Algortihms that operate on ordinary sequences.
• string - String-specific algorithms.

The String-algo library currently deviates from this notion of organizing algorithms as it contains sequence algorithms as well as string-specific algorithms.

Namespaces

All algorithm names should be namespace qualified. The namespace name to use should be that of the directory to which the algorithm belongs. See the Physical Organization section.

No algorithm names should be hoisted into the global or boost namespace unless there is a particularly compelling reason to do so. Users are free to add using directives or using declarations to do that should they feel the need. Adding a special header that includes all algorithms from a nested namespace and hoists those algorithms into the outer namespace are acceptable, but should be provided only as a convenience for users that want that behavior, rather than as the preferred interface.

Naming Conventions

Common Names

Suffixes

• _copy The mutating operation produces a copy of the (possibly modified) input sequence in another sequence. The copy may be returned or may be populated via an output iterator.
• _n The algorithm repeats an action N times.
• _if The algorithm uses a predicate to control its behavior.

The prefixes may be combined in the following order: name[_copy][_n][_if].

Range Interfaces

All algorithms should include both an iterator interface and a range-based interface. Whether the range version should return an iterator or a range depends upon the algorithm. Returning a range permits chaining range-based algorithms, but returning an iterator may be more useful or more consistent with the iterator version.