splash.doc

SPLASH is a c++ class library that implements many of the Perl constructs and data types, including

                        opts: (a const char * with default "")
                         i - Forces case insensitive match
  int m(const Regexp& exp, SPStringList& l)
                        Same as above but takes a precompiled
                        regular expression.
  int tr(search, repl [,opts])   replaces all occurrences of
                        characters in `search` with the
                        equivalent character in `repl`. If
                        `repl` is empty then just counts the
                        characters.
                        opts: (a const char *) default is ""
                         c - complements the `search`
                             pattern. Replaces all characters that
                             are not in `search`, with the last
                             character specified in `repl`.
                         d - deletes characters in `search`
                             that don't have an equivalent `repl`
                         cd - deletes characters not in
                              `search`
                         s - compresses sequences of translated
                             characters in resulting string
  int s(exp, repl [,opts])  substitute the first substring
                        matched by `exp` with the string `repl`.
                        $& in `repl` will be replaced by the
                        entire matching string, $1 $9 will be
                        replaced by the respective subexpression
                        match. \$ or \\ will insert a $ or \
                        respectively.
                        opts: (a const char *) default is ""
                         g - causes all occurrences of `exp`
                             in the string to be replaced by
                             `repl`
                         i - Forces case insensitive matching

class Assoc<T>   an associative array whose key is a SPString and
                 the value is any type T
  Assoc(SPString defkey, T defvalue)  Constructor for an
                        associative array, `defkey` becomes the
                        default key, and `defvalue` is the
                        default value. The default value is used
                        to create a new Association if a key is
                        specified that doesn't yet exist.
  T& operator(SPString str) returns a reference to the value
                        that is associated with the key `str`.
                        This may be used as an lvalue, and is in
                        the only way to make an association. If
                        the key didn't exist it will be entered
                        with the default value, if it was
                        specified in the constructor, and a
                        reference to that is returned. If no
                        default was specified, then the value
                        will be undefined
  Binar& operator[n]   Returns the (key, value) pair found at
                        index `n` of the associative array
  SPStringList keys()  Returns a list of all the keys in the
                        associative array.
  SPList<T> values()   Returns a list of all the values in the
                        associative array.
  int isin(SPString key)    Returns 1 if the string `key` is a
                        valid key in the associative array.
                        Returns 0 otherwise.
  T adelete(SPString key)   deletes the entry whose key matches
                        the string `key`. The value of the
                        deleted entry is returned. Nothing
                        happens if the key is not found.

class Range      stores the range used in Regexp
  Range(s, e)          creates a range whose start is at
                        position `s` and the last character in
                        the range is at position `e`. (inclusive
                        range)
  int start()          returns the start of the range
  int end()            returns the end of the range (the
                        position of the last character in the
                        range)
  int length()         returns the length of the range
  set(s, e)            sets the start of the range to `s` and
                        the end of the range to `e`

class Slice      allows the creation of a set of index ranges for
                 use in SPList to create SubLists. The order in
                 which elements of an SPList is accessed is the
                 same as the order that the indices are added to
                 the Slice.
                 
  Slice(const char *s) creates a slice specified by `s` where
                        `s` is a string that specifies a set of
                        indices.
                        `s` can be:-
                        "2..6" or "2-6" which specifies a
                        continuous range from 2 thru 6.
                        "2,5,7" which specifies individual
                        indices 2 5 7.
                        "5..9,11,16" which specifies a range 5
                        thru 9 and individual indices 11 and 16.
  Slice(int i1, i2, ... , -1)    creates a slice from a set of
                        indices specified by `i1` `i2` upto a
                        parameter that is -1. This is a variable
                        number of arguments terminated by a -1.
                        NOTE that this is not type safe.
  Slice(Range rng)     creates a slice that is a range
                        specified by `rng`.
  add(int i)           allows the dynamic creation of a slice
                        by adding individual indices to the
                        slice.
  compact()            may be used after add()'ing indices to a
                        Slice, and before using the Slice to
                        optimise it. (Optional)

class Regexp     Henry Spencers regular expression package oo-
                 ized
  Regexp(exp [,opts])  Compiles a regular expression that can
                        be passed to one of the m() functions.
                        opts: (an int with default 0)
                          Regexp::nocase - Forces case
                           insensitive match
  int match(targ)      returns 1 if the compiled RE matches
                        `targ` returns 0 if not
  int groups()         returns 1 + the number of subexpression
                        matches found in the last match(). If
                        the previous match() succeeded then the
                        whole match is included in the count
                        (hence +1)
  Range getgroup(n)    returns the range of the `n`th subgroup.
                        `n` = 0 is the range of the entire match

Class SPListIter Allow Iteration through a SPList
  SPListIter(T)        Inititialise an iterator for the SPList
                        T
  reset()              Reset the Iterator to start again
  operator()           Return the next list item
  operator++           Prefix and postfix increments of the
                        iterator
  FOREACH(ty, var, list)    Iterates through the list of type
                        ty assigning the next value to var each
                        time through the loop
  ENDFOREACH           Used to terminate a FOREACH command

Miscellaneous
                 
  SPStringList m(exp, targ [,opts])   returns a list of all the
                        subexpression matches that occured when
                        applying the regular expression `exp` to
                        the string `targ`. element 0 of the list
                        is the first subexpression, element 1
                        the next, etc. opts: (a const char *
                        with default "")
                         i - Forces case insensitive match
  xin >> astring       Text from the stream xin is loaded into
                        astring, the text is expected to be
                        terminated by '\n', which is removed
                        from the stream, but not put into
                        astring. asring is cleared first.
  xin >> astringlist   Each Text line, as defined above, is
                        loaded into an element of astringlist,
                        which is reset first.
To pre-compile a regular expression use Regexp(const char *,
iflg).
eg
     Regexp rexp("...([a-z*)$");
     // Regexp rexp("...([a-z*)$", Regexp::nocase); // for case
     insensitive SPString s;
     for(int i=0;i<large_number;i++){
          ... load s with string ...
          if(s.m(rexp)) ... do something when matched
     }