Utility routines

These C++ routines can be found in SPutils.h and SPutils.cxx and are not available from Python.

 void SPreadColUnits(CCfits::ExtHDU&, const string, string&)

Read the units associated with a column.

 void SPwriteColUnits(CCfits::Table&, const string, const string)

Write the units associated with a column.

```
 string SPstringTform(const StringVector& Data)
```
Returns the tform string for the longest string in the input vector.
```
 Integer SPcopyHDUs(const string infile, const string outfile)
```
Copy from infile to outfile all HDUs which are not manipulated by this library.

 Integer SPcopyCols(const string infile, const string outfile,
                    const string HDUname, const Integer HDUnumber = 1);

Copy non-critical columns from infile to outfile for the HDUnumber instance of the HDUname HDU.

 Integer SPcopyKeys(const string infile, const string outfile,
                    const string HDUname, const Integer HDUnumber = 1)

 Integer SPcopyKeys(const string infile, const string outfile, 
                    string HDUname, const string outHDUname,
                    const Integer HDUnumber = 1,
                    const Integer outHDUnumber = 1 )

Copy non-critical keywords from infile to outfile for HDUname extension with EXTVER HDUnumber.

 Integer SPwriteCreator(const string filename, const string HDUname,
                        const string creator, const Integer HDUnumber = 1)

Write the creating program and version id string into the CREATOR keyword in the specified file.

 IntegerVector SPfindExtensions(const string filename,
                                const string keyname, const string value,
                                Integer& Status);

Find the numbers of any extensions containing keyword keyname=keyvalue

 bool SPisValidXUnits(const string xUnits)

Checks whether xUnits are supported.

```
 Integer SPcalcXfactor(const string xUnits, bool& isWave, Real& xFactor)
```
Calculates the conversion factor for xUnits energies/wavelength to keV. If xUnits is wavelength then returns isWave as true.

 bool SPisValidYUnits(const string yUnits)

Checks whether yUnits are supported.

```
 Integer SPcalcYfactor(const string yUnits, bool& isEnergy, bool& perWave,
                       Real& yFactor)
```
Calculates the conversion factor for yUnits to ph/cm/s. If yUnits contains an energy numerator (eg ergs) then returns isEnergy as true. If yUnits contains a wavelength denominator (eg micron) returns perWave as true.
```
 void SPreportError(const int errorNumber,
                    const string optionalString = “”)
```
Add to the error stack errorNumber along with an optional string containing additional information.
```
 string SPgetErrorStack()
```
Write the entire error stack into a string.
```
 string SPclearErrorStack()
```
Clear the error stack.
```
 StringVector SPreadStrings(const string& filename)
```
Read a text file and place each row into its own element of a StringVector.

 StringVector SPtokenize(const string & str, const string & delim)

Divide a string into substrings delimited using delim.

 string SPmatchString(const string& str, 
                      const StringVector& strArray, int& nmatch)

Partial match a string from a vector of strings.

```
 string SPtrimString(const string& str)
```
Remove leading and trailing blanks from a string.

 bool SPstring2Real(const StringVector& str,
                    RealVector& value)

 bool SPstring2Real(const string& str, Real& value)

Convert a string or vector of strings into a Real or vector of Reals.

 bool SPstring2double(const StringVector& str,
                      std::vector<double>& value)

 bool SPstring2double(const string& str, double& value)

Convert a string or vector of strings into a double or vector of doubles.

 bool SPstring2float(const StringVector& str,
                     std::vector<float>& value)

 bool SPstring2float(const string& str, float& value)

Convert a string or vector of strings into a float or vector of floats.

 bool SPstring2Integer(const StringVector& str,
                       IntegerVector& value)

 bool SPstring2Integer(const string& str, Integer& value)

Convert a string or vector of strings into an Integer or vector of Integers.

```
 bool SPrangeString2IntegerList(const string& str, const string& delim1, 
                                const string& delim2, IntegerVector& list)
```
Convert a string of delimited range specifications of form n1"delim2"n2 meaning n1 to n2 inclusive or n3 meaning just n3. Ranges are delimited using delim1.

 void SPcalcShift(const RealVector& Low,
                  const RealVector& High, const IntegerVector& vStart,
                  const IntegerVector& vEnd, const RealVector& vShift,
                  const RealVector& vFactor,
                  std::vector<std::vector<size\_t> >& fromIndex,
                  std::vector<RealVector>& Fraction)

Calculate factors for shifting an array

```
 template <class T> void SPfind(const T& array,
                                const Real& target, Integer& index)
```
Find the position in the array of the target value. If array is increasing the index is the last element in array $\leq$ target; if target array[0] then index = -1; if target $\geq$ array[array.size()-1] then index = array.size()-1. If array is decreasing the index is the last element in array $\geq$ target; if target array[0] then index = -1; if target $\leq$ array[array.size()-1] then index = array.size()-1. The template class T can be either vector or valarray of Real or Integer.

 template <class T> void SPbisect(Integer& lower, Integer& upper,
                                  const T& array, const Real& target,
                                  bool increasing)

Do a bisection search between indices lower and upper on array to find target. On exit lower and upper are set to the indices which bracket target.

 IntegerVector SPcalcOptBins(const RealVector& FWHM,
                             const IntegerVector& counts)

Calculate the Kaastra & Bleeker optimal binsizes based on input FWHM and counts arrays.

 bool SPcheckStokesConsistency(const string& stokesP1,
                               const string& stokesW1,
                               const string& stokesP2,
                               const string& stokesW2)

Check for consistency between two sets of Stokes information