Editing Guide to madagascar API (section)

==C++ interface==

The C++ clip function is listed below.
<syntaxhighlight lang="cpp">
/* Clip the data. */

#include <valarray>
#include <rsf.hh>

int main(int argc, char* argv[])
{
    sf_init(argc,argv); // Initialize RSF
    
    iRSF par(0), in; // input parameter, file
    oRSF out;        // output file

    int n1, n2;      // trace length, number of traces
    float clip;
    
    in.get("n1",n1);
    n2=in.size(1);

    par.get("clip",clip); // parameter from the command line

    std::valarray<float> trace(n1);

    for (int i2=0; i2 < n2; i2++) { // loop over traces
	in >> trace; // read a trace

	for (int i1=0; i1 < n1; i1++) { // loop over samples
	    if      (trace[i1] >  clip) trace[i1]=clip;
	    else if (trace[i1] < -clip) trace[i1]=-clip;
	}

	out << trace; // write a trace
    }

    exit(0);
}
</syntaxhighlight>

Let us examine it line by line. 
<syntaxhighlight lang="cpp">
#include <rsf.hh>
</syntaxhighlight>

Including "<tt>rsf.hh</tt>" is required for accessing the RSF C++
interface.
<syntaxhighlight lang="cpp">
    sf_init(argc,argv); // Initialize RSF
</syntaxhighlight>

A call to <tt>sf_init</tt> is required to initialize the internally stored
table of command-line arguments.
<syntaxhighlight lang="cpp">
    iRSF par(0), in; // input parameter, file
    oRSF out;        // output file
</syntaxhighlight>

Two classes: <tt>iRSF</tt> and <tt>oRSF</tt> are used to define input and
output files. For simplicity, the command-line parameters are also handled 
as an <tt>iRSF</tt> object, initialized with zero.
<syntaxhighlight lang="cpp">
    in.get("n1",n1);
    n2=in.size(1);
</syntaxhighlight>

Next, we read the data dimensions from the input RSF file object called
<tt>in</tt>: the trace length is a parameter called "<tt>n1</tt>" and the
number of traces is the size of <tt>in</tt> remaining after excluding the
first dimension. It is extracted with the <tt>size</tt> method.
<syntaxhighlight lang="cpp">
    par.get("clip",clip); // parameter from the command line
</syntaxhighlight>
 
The clip parameter should be specified on the command line, for
example, as <tt>clip=10</tt>. It is extracted with the <tt>get</tt>
method of <tt>iRSF</tt> class from the <tt>par</tt> object.
<syntaxhighlight lang="cpp">
    std::valarray<float> trace(n1);
</syntaxhighlight>

The trace object has the single-precision floating-point type and is a
1-D array of length <tt>n1</tt>. It is declared and allocated using
the <tt>valarray</tt> template class from the standard C++ library.
<syntaxhighlight lang="cpp">
    for (int i2=0; i2 < n2; i2++) { // loop over traces
	in >> trace; // read a trace

	for (int i1=0; i1 < n1; i1++) { // loop over samples
	    if      (trace[i1] >  clip) trace[i1]=clip;
	    else if (trace[i1] < -clip) trace[i1]=-clip;
	}

	out << trace; // write a trace
    }
</syntaxhighlight>

Next, we loop through the traces, read each trace from <tt>in</tt>, clip it
and write the output to <tt>out</tt>.
===Compiling===
To compile the C++ program, run
<pre>
c++ clip.cc -I&#36;RSFROOT/include -L&#36;RSFROOT/lib -lrsf++ -lrsf -lm
</pre>
Change <tt>c++</tt> to the C++ compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>&#36;RSFROOT/share/madagascar/etc/config.py</tt>.