Distiller.h

#ifndef INCLUDE_DISTILLER_H
#define INCLUDE_DISTILLER_H
/*
 * This is the Loris C++ Class Library, implementing analysis, 
 * manipulation, and synthesis of digitized sounds using the Reassigned 
 * Bandwidth-Enhanced Additive Sound Model.
 *
 * Loris is Copyright (c) 1999-2004 by Kelly Fitz and Lippold Haken
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY, without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 *
 * Distiller.h
 *
 * Definition of class Distiller.
 *
 * Kelly Fitz, 20 Oct 1999
 * loris@cerlsoundgroup.org
 *
 * http://www.cerlsoundgroup.org/Loris/
 *
 */

#include "Partial.h"
#include "PartialList.h"
#include "PartialUtils.h"

#include <algorithm>

//  begin namespace
namespace Loris {

// ---------------------------------------------------------------------------
//  class Distiller
//
//
class Distiller
{
//  -- instance variables --

    double _fadeTime, _gapTime;         // distillation parameters
        
//  -- public interface --
public:
//  -- construction --

    explicit
    Distiller( double partialFadeTime = 0.001    /* 1 ms */,
              double partialSilentTime = 0.0001 /* .1 ms */ );
     
    //  Use compiler-generated copy, assign, and destroy.
    
//  -- distillation --

#if ! defined(NO_TEMPLATE_MEMBERS)
    template< typename Container >
    typename Container::iterator distill( Container & partials );
#else
    inline
    PartialList::iterator distill( PartialList & partials );
#endif

#if ! defined(NO_TEMPLATE_MEMBERS)
    template< typename Container >
    typename Container::iterator operator() ( Container & partials );
#else
    PartialList::iterator operator() ( PartialList & partials );
#endif
    
   #if ! defined(NO_TEMPLATE_MEMBERS)
    template< typename Container >
    static typename Container::iterator 
    distill( Container & partials, double partialFadeTime,
                                  double partialSilentTime = 0.0001 /* .1 ms */ );
#else
    static inline PartialList::iterator
    distill( PartialList & partials, double partialFadeTime,
                                    double partialSilentTime = 0.0001 /* .1 ms */ );
#endif


private:

//  -- helpers --

    void distillOne( PartialList & partials, Partial::label_type label,
                     PartialList & distilled );

    void collateUnlabeled( PartialList & unlabled, Partial::label_type startLabel );
    
};  //  end of class Distiller

// ---------------------------------------------------------------------------
//  distill
// ---------------------------------------------------------------------------
//
#if ! defined(NO_TEMPLATE_MEMBERS)
template< typename Container >
typename Container::iterator Distiller::distill( Container & partials )
#else
inline
PartialList::iterator Distiller::distill( PartialList & partials )
#endif
{
#if ! defined(NO_TEMPLATE_MEMBERS)
    typedef typename Container::iterator Iterator;
#else
    typedef PartialList::iterator Iterator;
#endif

    // Container::iterator dist_begin = partials.begin();
    // Container::iterator dist_end = partials.end();
    //
    //  Using these iterators (as arguments) only makes sense
    //  if distill is changed to return the end of the collated
    //  Partials, rather than the end of the distilled Partials.
    //  In the current implementation, when there are collated
    //  Partials, there is no way to find the end of the range 
    //  of collated Partials after the call to distill, for 
    //  all containers. Making the distill function generic to
    //  all containers will work, but making it work on ranges
    //  requires an interface change.
    
    
    PartialList distilled, savezeros; //  temporary containers of Partials
                  
    //  remember the largest label ever used
    //  in distilling, collated unlabeled Partials
    //  will be assigned labels greater than this:
    Partial::label_type maxlabel = 0;
    
    Iterator lower = partials.begin();
    while ( lower != partials.end() )
    {
        Partial::label_type label = lower->label();

        //  identify the range of Partials having the same label:
        Iterator upper = 
            std::partition( lower, partials.end(),
                            PartialUtils::isLabelEqual( label ) );
                            
        //  upper is the first Partial after lower whose label is not
        //  equal to that of lower.
        
        //  [lowerbound, upperbound) is a range of all the
        //  partials in dist_list labeled label.
        //
        //  distill labeled channel, unless label is 0
        //  (zero-labeled Partials will remain where they
        //  are, and wind up at the front of the list): 
        if ( label != 0 )
        {
            maxlabel = std::max( label, maxlabel );
            
            //  make a container of the Partials having the same 
            //  label, and distill them:
            PartialList samelabel( lower, upper );
            distillOne( samelabel, label, distilled );
        }
        else    //  label == 0
        {
            //  save zero-labeled Partials to splice
            //  back into the original list
            savezeros.insert( savezeros.begin(), lower, upper );
        }

        lower = upper;
    }
        
    //  copy the distilled Partials back into the source container,
    //  enddistilled is the end of the range of distilled Partials
    //  (return this to caller):
    Iterator enddistilled =
        std::copy( distilled.begin(), distilled.end(), partials.begin() );
    
    //  append collated unlabeled Partials, if any,
    //  and remove extra Partials from the end of the 
    //  source collection:
    if ( savezeros.empty() )
    {
        //  remove extra Partials from the end of the source container,
        //  update enddistilled, which may become invalid by
        //  erasure:
        enddistilled = partials.erase( enddistilled, partials.end() );
    }
    else
    {
        //  collate unlabeled (zero-labeled) Partials:
        collateUnlabeled( savezeros, std::max( maxlabel+1, 1 ) );

        //  copy the collated Partials back into the source container
        //  after the range of distilled Partials       
        //  (enddistilled is still the end of the distilled Partials):
        Iterator endcollated = 
            std::copy( savezeros.begin(), savezeros.end(), enddistilled );

        //  remove extra Partials from the end of the source container
        //  (enddistilled is still the end of the distilled Partials,
        //  because it is the position of the first collate Partial, and
        //  there is at least one collated Partial):
        partials.erase( endcollated, partials.end() );
    }
    
    return enddistilled;
}

// ---------------------------------------------------------------------------
//  Function call operator 
// ---------------------------------------------------------------------------
//
#if ! defined(NO_TEMPLATE_MEMBERS)
template< typename Container >
typename Container::iterator Distiller::operator()( Container & partials )
#else
inline
PartialList::iterator Distiller::operator()( PartialList & partials )
#endif
{ 
    return distill( partials );
}

// ---------------------------------------------------------------------------
//  distill
// ---------------------------------------------------------------------------
//
#if ! defined(NO_TEMPLATE_MEMBERS)
template< typename Container >
typename Container::iterator 
Distiller::distill( Container & partials, double partialFadeTime,
                                          double partialSilentTime )
#else
inline
PartialList::iterator 
Distiller::distill( PartialList & partials, double partialFadeTime,
                                            double partialSilentTime )
#endif
{
    Distiller instance( partialFadeTime, partialSilentTime );
    return instance.distill( partials );
}

}   //  end of namespace Loris

#endif /* ndef INCLUDE_DISTILLER_H */

---