// doc/util.dox

// Copyright 2009-2011 Microsoft Corporation

// See ../../COPYING for clarification regarding multiple authors

//

// Licensed under the Apache License, Version 2.0 (the "License");

// you may not use this file except in compliance with the License.

// You may obtain a copy of the License at

// http://www.apache.org/licenses/LICENSE-2.0

// THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

// KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED

// WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE,

// MERCHANTABLITY OR NON-INFRINGEMENT.

// See the Apache 2 License for the specific language governing permissions and

// limitations under the License.

namespace kaldi {

/**

\page util Other Kaldi utilities

This page gives an overview of various categories of utility functions that

we use in Kaldi code. This excludes important utilities that have been

dealt with in their own sections, including the \ref matrix "matrix library",

\ref io "I/O", \ref error "logging and error-reporting",

and \ref parse_options "command-line parsing".

\section util_sec_text Text utilities

In \ref text-utils.h are various functions for manipulating strings, mostly

used in parsing. Important ones include the templated function

ConvertStringToInteger(), and the overloaded ConvertStringToReal() functions which are

defined for float and double. There is also the SplitStringToIntegers() template whose

output is a vector of integers, and SplitStringToVector() which splits a string into

a vector of strings.

\section util_sec_stl STL utilities

In \ref stl-utils.h are templated functions for manipulating STL types. A commonly used

one is SortAndUniq(), which sorts and removes duplicates from a vector (of an arbitrary type).

The function CopySetToVector() copies the elements of a set into a vector, and is part

of a larger category of similar functions that move data between sets, vectors and maps

(see a list in \ref stl-utils.h).

There are also the hashing-function types VectorHasher (for vectors of integers) and

StringHasher (for strings); these are for use with the STL unordered_map and unordered_set

templates. Another commonly used function is DeletePointers(), which deletes pointers

in a std::vector of pointers, and sets them to NULL.

\section util_sec_math Math utilities

In \ref kaldi-math.h, apart from a number of standard \#defines which are provided in case they

are not in the system header math.h, there are some math utility functions. These include

most importantly:

- Functions for random number generation: RandInt(), RandGauss(), RandPoisson().

- LogAdd() and LogSub() functions

- Functions for testing and asserting approximate math (in)equalities, i.e. ApproxEqual(), AssertEqual(),

AssertGeq() and AssertLeq().

\section util_sec_other Other utilities

In \ref const-integer-set.h is a class ConstIntegerSet that stores a set of

integers in an efficient way and allows fast querying. The caveat is that

the set cannot be changed after initializing the object. This is used e.g.

in decision-tree code. Depending on the value of the integers in the set, it may store them internally

as vector<bool> or as a sorted vector of integers.

A class Timer for timing programs in a platform-independent way is in \ref timer.h.

Other utility-type functions and classes are in \ref simple-io-funcs.h and

\ref hash-list.h, but these have more specialized uses. Some additional utility functions

and macros, mostly quite specialized, that the \ref matrix "matrix" code depends on, are in

\ref kaldi-utils.h; these include things like byte swapping, memory alignment,

and mechanisms for compile-time assertions (useful in templates).

*/

}