basic_super_string< char_type > Class Template Reference

#include <super_string.hpp>

List of all members.

Detailed Description

template<class char_type>
class basic_super_string< char_type >

Souped up string class that includes fancy query, replacement, and conversion functions.

Overall, this class is mostly a convience wrapper around functions available in boost.string_algo and boost.regex.

Examples:

test/ss_example.cpp.


Public Member Functions

Construction
Various constructors

 basic_super_string ()
 Default constructor.
 basic_super_string (const char_type *const s)
 Construct from a char pointer.
 basic_super_string (const base_string_type &s)
 Construct from std::basic_string type.
 basic_super_string (iterator_type beg, iterator_type end)
 Construct from iterators.
Basic Queries
Content checking query functions to check for substrings.

bool contains (const base_string_type &s) const
 Query function to see if a string contains given string.
bool contains_regex (const base_string_type &s) const
 Query function using regular expression This is meant to function much like the perl =~ operator.
bool starts_with (const base_string_type &s, size_type offset=0) const
 Query function to see if a string or substring starts with a given string.
bool ends_with (const base_string_type &s) const
 Query function to see if a string or substring ends with a given string.
Case Insentitive Queries
Case Insensitive content checking query functions to check for substrings.

bool icontains (const base_string_type &s) const
 Case insensitive query function to see if a string contains a given string.
bool istarts_with (const base_string_type &s, size_type offset=0) const
 Case insensitive query function to see if a string or substring starts with a given string.
bool iends_with (const base_string_type &s) const
 Case insensitive query function to see if a string or substring ends with a given string.
Split Functions
Split the string based on the predicate string

unsigned int split (const base_string_type &predicate, string_vector &result) const
 Split a string into a string of vectors based on equality to a string.
unsigned int split_regex (const base_string_type &predicate_regex, string_vector &result) const
 Split a string into a string of vectors based regex string.
Acquire File Content
Append contents of a file to the string

basic_super_string & append_file (const base_string_type &filepath)
 Make a string from the contents of a file.
Replace Functions
Enhanced replace functions

basic_super_string & replace_all_regex (const base_string_type &match_regex, const base_string_type &replace_regex)
 Replace the all instance of the match_string with the replace_format.
basic_super_string & replace_first (const base_string_type &match_string, const base_string_type &replace_string)
 Replace the first instance of the match_string with the replace_string Has no effect on the string if there is match_string does not appear in the string.
basic_super_string & replace_last (const base_string_type &match_string, const base_string_type &replace_string)
 Replace the last instance of the match_string with the replace_string Has no effect on the string if there is match_string does not appear in the string.
basic_super_string & replace_nth (const base_string_type &match_string, const base_string_type &replace_string, size_type n)
 Replace the nth instance of the match_string with the replace_string Has no effect on the string if there is no 'nth' version of the match string.
basic_super_string & replace_all (const base_string_type &match_string, const base_string_type &replace_string)
 Replace the all instance of the match_string with the replace_string Has no effect on the string if there are no instances of match_string in the string.
Replace Functions - case insensitve
Case insensitive enhanced replace functions

basic_super_string & ireplace_first (const base_string_type &match_string, const base_string_type &replace_string)
 Case insensitive replace the first instance of the match_string with the replace_string.
basic_super_string & ireplace_last (const base_string_type &match_string, const base_string_type &replace_string)
 Case insensitive replace of the last instance of the match_string with the replace_string.
basic_super_string & ireplace_nth (const base_string_type &match_string, const base_string_type &replace_string, size_type n)
 Case insensitive replace of the nth instance of the match_string with the replace_string.
basic_super_string & ireplace_all (const base_string_type &match_string, const base_string_type &replace_string)
 Case insensitive replace the all instance of the match_string with the replace_string Has no effect on the string if there are no instances of match_string in the string.
Trim Functions
White space trimming functions

basic_super_string & trim ()
 Trim in-place whitespace from the both sides of the string.
basic_super_string & trim_left ()
 Trim in-place whitespace from the left side of the string.
basic_super_string & trim_right ()
 Trim in-place whitespace from the right side of the string.
Case Conversion Functions
Convert the string case using the global locale.

basic_super_string & to_upper ()
 Change to upper case using the global locale The global local can be replaced by calling std::global(locale).
basic_super_string & to_lower ()
 Change to lower case using the global locale The global local can be replaced by calling std::global(locale).
Basic Type Conversion
Convert and append, prepend, and insert a streamable type to the the string.

template<typename T1, typename T2, typename T3, typename T4, typename T5>
basic_super_string< char_type > & append (const T1 &val1, const T2 &val2, const T3 &val3, const T4 &val4, const T5 &val5)
 Generic function to append 5 values This function will work with any type that is OutputStreamable.
template<class T>
basic_super_string< char_type > & prepend (const T &value)
 Generic function to prepend any type to the string This function will work with any type that is OutputStreamable.
template<class T>
basic_super_string< char_type > & insert_at (size_type pos, const T &value)
 Generic function to insert an OutputStreamable type into the string.
Basic Type Conversion with supplied Stringstream
Convert and append a streamable type to the string.

template<typename T1, typename T2, typename T3, typename T4, typename T5>
basic_super_string< char_type > & append (const T1 &val1, const T2 &val2, const T3 &val3, const T4 &val4, const T5 &val5, string_stream_type &ss)
 Generic function to append any type to the string This is a faster version of the convert and append function.
Formatted Type Conversion
Use formatting strings to append arbitrary types to string.

template<typename T1, typename T2, typename T3, typename T4, typename T5>
basic_super_string< char_type > & append_formatted (const T1 &val1, const T2 &val2, const T3 &val3, const T4 &val4, const T5 &val5, const base_string_type &fmt)
 Generic function to append 5 values of any to the string including formatting Users can append up to 5 values at once.

Member Function Documentation

template<class char_type>
template<typename T1, typename T2, typename T3, typename T4, typename T5>
basic_super_string< char_type > & basic_super_string< char_type >::append (  const T1 &  val1,
const T2 &  val2,
const T3 &  val3,
const T4 &  val4,
const T5 &  val5,
string_stream_type &  ss
)  [inline]
 

Generic function to append any type to the string This is a faster version of the convert and append function.

Use this version if doing a large number of conversions. This version of the function also allows the user to control format settings on the conversion by applying changes to the stringstream used to do the conversion. This function will work with any type that is OutputStreamable.

    std::ostringstream ss;
    s.setprecision(
    super_string s;
    ss << std::setprecision(3);
    double dbl = 1.987654321;
    int i = 1000;
    s.append(dbl, i, i, " stuff", dbl, ss);
    //s == "1.99 1000 1000 1.99 stuff"
    //ss -- has been modified
Parameters:
val1 First value to be appended to the string.
val2 Second value to be appended to the string.
val3 Third value to be appended to the string.
val4 Fourth value to be appended to the string.
ss A stream to use in the conversion -- all data will be reset.
Returns:
Returns self-reference for chained operations

template<class char_type>
template<typename T1, typename T2, typename T3, typename T4, typename T5>
basic_super_string< char_type > & basic_super_string< char_type >::append (  const T1 &  val1,
const T2 &  val2,
const T3 &  val3,
const T4 &  val4,
const T5 &  val5
)  [inline]
 

Generic function to append 5 values This function will work with any type that is OutputStreamable. 

    super_string s;
    double dbl = 1.543;
    int i = 10;
    s.append("value is: ", dbl, " int: ", i);
    //s == "double: 1.543 int: 10"
Parameters:
value Value to be appended to the string.
Returns:
Returns self-reference for chained operations

template<class char_type>
basic_super_string< char_type > & basic_super_string< char_type >::append_file (  const base_string_type &  filepath  )  [inline]
 

Make a string from the contents of a file. 

    super_string data;
    data.append_file("data1.txt").append_file(data2.txt);
Returns:
String built from reading in the entire file.
Parameters:
filepath Path to the file

template<class char_type>
template<typename T1, typename T2, typename T3, typename T4, typename T5>
basic_super_string< char_type > & basic_super_string< char_type >::append_formatted (  const T1 &  val1,
const T2 &  val2,
const T3 &  val3,
const T4 &  val4,
const T5 &  val5,
const base_string_type &  format
)  [inline]
 

Generic function to append 5 values of any to the string including formatting Users can append up to 5 values at once.

See: Boost Format specification syntax for details on the formmatting strings.

    super_string s;
    double dbl = 1.123456789;
    int i = 1000;
    s.append_formatted(dbl, i , dbl, i, "a string", "%-7.2f %-7d %-7.2f %-7d %s");
    //s == "1.12   1000  1.12   1000   a string"
    
    //other overloadings available with less parameters
    super_string s1;
    s1.append_formatted(dbl, "This is the value: %-7.2f");
    //s1 == "This is the value: 1.12"

- The value to append to the end of the string. - Formatting string for the value.

Returns:
Returns self-reference for chained operations
Exceptions:
Boost format exceptions: see Boost Format Exceptions. for details.

template<class char_type>
bool basic_super_string< char_type >::contains (  const base_string_type &  predicate_string  )  const [inline]
 

Query function to see if a string contains given string. 

    super_string s("hello");
    s.contains("lo"); //true
    s.contains("hi"); //false

Parameters:
predicate_string string to check against

template<class char_type>
bool basic_super_string< char_type >::contains_regex (  const base_string_type &  predicate_regex  )  const [inline]
 

Query function using regular expression This is meant to function much like the perl =~ operator.

Note:
Requires the liking of boost.regex library.
    super_string s("hello 2006-02-23");
    s.contains_regex("\\d{4}-\\d{2}-\\d{2}")); //true
    s.contains_regex("[A-Z]")); //false

Parameters:
predicate_regex regular expression predicate_string string to check against
Exceptions:
boost::regex_error if predicate_string is not a valid regular expression
Examples:
test/ss_example.cpp.

template<class char_type>
bool basic_super_string< char_type >::ends_with (  const base_string_type &  predicate_string  )  const [inline]
 

Query function to see if a string or substring ends with a given string. 

    super_string s("hello");
    s.ends_with("lo"); //true
    s.ends_with("hi"); //false

Parameters:
predicate_string string to check against

template<class char_type>
bool basic_super_string< char_type >::icontains (  const base_string_type &  predicate_string  )  const [inline]
 

Case insensitive query function to see if a string contains a given string. 

    super_string s("hELlo");
    s.icontains("llO"); //true
    s.icontains("Hi");  //false

Parameters:
predicate_string string to check against

template<class char_type>
bool basic_super_string< char_type >::iends_with (  const base_string_type &  predicate_string  )  const [inline]
 

Case insensitive query function to see if a string or substring ends with a given string. 

    super_string s("hELlo");
    s.iends_with("llO"); //true
    s.iends_with("Hi")   //false

Parameters:
predicate_string string to check against

template<class char_type>
template<class T>
basic_super_string< char_type > & basic_super_string< char_type >::insert_at (  size_type  position,
const T &  value
)  [inline]
 

Generic function to insert an OutputStreamable type into the string. 

    super_string s( "Hello  There");
    double dbl = 1.543;
    s.insert_at(6, dbl);
    //s == "Hello 1.543 There"
Parameters:
position Zero-based index of location in string to insert data
value Value to insert into the string
Returns:
Returns self-reference for chained operations
Examples:
test/ss_example.cpp.

template<class char_type>
basic_super_string< char_type > & basic_super_string< char_type >::ireplace_all (  const base_string_type &  match_string,
const base_string_type &  replace_string
)  [inline]
 

Case insensitive replace the all instance of the match_string with the replace_string Has no effect on the string if there are no instances of match_string in the string. 

    super_string s("foo FOO Foo");
    s.ireplace_all("foo", "bar", 1);
    //s == "bar bar bar"
Parameters:
match_string String to find and replace against
replace_string String to use in replacement

template<class char_type>
basic_super_string< char_type > & basic_super_string< char_type >::ireplace_first (  const base_string_type &  match_string,
const base_string_type &  replace_string
)  [inline]
 

Case insensitive replace the first instance of the match_string with the replace_string.

Has no effect on the string if there match_string does not appear in the string. 

    super_string s("FOO foo foo");
    s.ireplace_first("foo", "bar");
    //s == "bar foo foo"
Parameters:
match_string String to find and replace against
replace_string String to use in replacement

template<class char_type>
basic_super_string< char_type > & basic_super_string< char_type >::ireplace_last (  const base_string_type &  match_string,
const base_string_type &  replace_string
)  [inline]
 

Case insensitive replace of the last instance of the match_string with the replace_string.

Has no effect on the string if there match_string does not appear in the string. 

    super_string s("foo foo FOO");
    s.ireplace_last("foo", "bar");
    //s == "foo foo bar"
Parameters:
match_string String to find and replace against
replace_string String to use in replacement

template<class char_type>
basic_super_string< char_type > & basic_super_string< char_type >::ireplace_nth (  const base_string_type &  match_string,
const base_string_type &  replace_string,
size_type  n
)  [inline]
 

Case insensitive replace of the nth instance of the match_string with the replace_string.

Has no effect on the string if there is no 'nth' version of the match string. 

    super_string s("foo FOO foo");
    s.ireplace_nth("foo", "bar", 1);
    //s == "foo bar foo"
Parameters:
match_string String to find and replace against
replace_string String to use in replacement
n The instance to replace starting at 0

template<class char_type>
bool basic_super_string< char_type >::istarts_with (  const base_string_type &  predicate_string,
size_type  offset = 0
)  const [inline]
 

Case insensitive query function to see if a string or substring starts with a given string. 

    super_string s("hELlo");
    s.istarts_with("el", 1); //returns true
Parameters:
predicate_string string to check against
offset point in string to start at - 0 is first position.

template<class char_type>
template<class T>
basic_super_string< char_type > & basic_super_string< char_type >::prepend (  const T &  value  )  [inline]
 

Generic function to prepend any type to the string This function will work with any type that is OutputStreamable. 

    super_string s( "Hello There");
    double dbl = 1.543;
    s.prepend(dbl);
    //s == "1.543 Hello There"

Returns:
Returns self-reference for chained operations

template<class char_type>
basic_super_string< char_type > & basic_super_string< char_type >::replace_all (  const base_string_type &  match_string,
const base_string_type &  replace_string
)  [inline]
 

Replace the all instance of the match_string with the replace_string Has no effect on the string if there are no instances of match_string in the string. 

    super_string s("foo foo foo");
    s.replace_all("foo", "bar", 1);
    //s == "bar bar bar"
Parameters:
match_string String to find and replace against
replace_string String to use in replacement

template<class char_type>
basic_super_string< char_type > & basic_super_string< char_type >::replace_all_regex (  const base_string_type &  match_regex,
const base_string_type &  replace_format
)  [inline]
 

Replace the all instance of the match_string with the replace_format.

Note:
Requires the liking of boost.regex library. 
    super_string s("(abc)3333()(456789) [123] (1) (cde)");
    
    //replace parens around digits with #--the digits--#
    s.replace_all_regex("\\(([0-9]+)\\)", "#--$1--#");

    //s == "(abc)3333()#--456789--# [123] #--1--# (cde)"
Exceptions:
boost::regex_error if match_regex is not a valid regular expression
Parameters:
match_regex Regular expression to match against
replace_format Replacement expresssion
Examples:
test/ss_example.cpp.

template<class char_type>
basic_super_string< char_type > & basic_super_string< char_type >::replace_first (  const base_string_type &  match_string,
const base_string_type &  replace_string
)  [inline]
 

Replace the first instance of the match_string with the replace_string Has no effect on the string if there is match_string does not appear in the string. 

    super_string s("foo foo foo");
    s.replace_first("foo", "bar");
    //s == "bar foo foo"
Parameters:
match_string String to find and replace against
replace_string String to use in replacement

template<class char_type>
basic_super_string< char_type > & basic_super_string< char_type >::replace_last (  const base_string_type &  match_string,
const base_string_type &  replace_string
)  [inline]
 

Replace the last instance of the match_string with the replace_string Has no effect on the string if there is match_string does not appear in the string. 

    super_string s("foo foo foo");
    s.replace_last("foo", "bar");
    //s == "foo foo bar"
Parameters:
match_string String to find and replace against
replace_string String to use in replacement

template<class char_type>
basic_super_string< char_type > & basic_super_string< char_type >::replace_nth (  const base_string_type &  match_string,
const base_string_type &  replace_string,
size_type  n
)  [inline]
 

Replace the nth instance of the match_string with the replace_string Has no effect on the string if there is no 'nth' version of the match string. 

    super_string s("foo foo foo");
    s.replace_nth("foo", "bar", 1);
    //s == "foo bar foo"
Parameters:
match_string String to find and replace against
replace_string String to use in replacement
n The instance to replace starting at 0

template<class char_type>
unsigned int basic_super_string< char_type >::split (  const base_string_type &  predicate,
string_vector &  result
)  const [inline]
 

Split a string into a string of vectors based on equality to a string. 

    super_string stuff("first-|-second-|-third");
    super_string::string_vector out_vec;
    if (stuff.split("-|-", out_vec)) {
      //iterate thru the vector and process
      //out_vec[0] == first
      //out_vec[1] == second
      //out_vec[2] == third
    }
Returns:
count of splits found
Parameters:
predicate String used to test against.
result Returns the each split string or the whole string as the first element of the vector.

template<class char_type>
unsigned int basic_super_string< char_type >::split_regex (  const base_string_type &  predicate_regex,
string_vector &  result
)  const [inline]
 

Split a string into a string of vectors based regex string.

Note:
Requires the liking of boost.regex library. 
    super_string s("These   are   some    \t words--with whitespace");
    super_string::string_vector out_vec;
    unsigned int count = s.split_regex("\\s+|--", out_vec);

    if (count) {
      //iterate thru the vector and process
      //out_vec[0] == These
      //out_vec[4] == with
    }
Returns:
count of splits found
Parameters:
predicate_regex Regular expression used to find string split points.
result Returns the each split string or the whole string as the first element of the vector.
Examples:
test/ss_example.cpp.

template<class char_type>
bool basic_super_string< char_type >::starts_with (  const base_string_type &  predicate_string,
size_type  offset = 0
)  const [inline]
 

Query function to see if a string or substring starts with a given string.

Parameters:
predicate_string string to check against
offset point in string to start at - 0 is first position.

template<class char_type>
basic_super_string< char_type > & basic_super_string< char_type >::to_lower (   )  [inline]
 

Change to lower case using the global locale The global local can be replaced by calling std::global(locale). 

    super_string s("UPPsdf sdf sdf E sdf d 123&88))");
    s.to_lower();
    //s == "uppsdf sdf sdf e sdf d 123&88
Returns:
Returns self-reference for chained operations

template<class char_type>
basic_super_string< char_type > & basic_super_string< char_type >::to_upper (   )  [inline]
 

Change to upper case using the global locale The global local can be replaced by calling std::global(locale). 

    super_string s("lower");
    s.to_upper();
    check("to upper test", s == std::string("LOWER"));

Returns:
Returns self-reference for chained operations
Examples:
test/ss_example.cpp.

template<class char_type>
basic_super_string< char_type > & basic_super_string< char_type >::trim (   )  [inline]
 

Trim in-place whitespace from the both sides of the string. 

    super_string s( " \t  hello world  ");
    s.trim();
    //s == "hello world"

Returns:
Returns self-reference for chained operations
Examples:
test/ss_example.cpp.

template<class char_type>
basic_super_string< char_type > & basic_super_string< char_type >::trim_left (   )  [inline]
 

Trim in-place whitespace from the left side of the string.

Returns:
Returns self-reference for chained operations

template<class char_type>
basic_super_string< char_type > & basic_super_string< char_type >::trim_right (   )  [inline]
 

Trim in-place whitespace from the right side of the string.

Returns:
Returns self-reference for chained operations

The documentation for this class was generated from the following file:
Generated on Sun Jul 9 15:43:03 2006 for SuperString by  doxygen 1.4.6