Go to the previous, next section.
#include <nihcl/String.h>
Class
String
provides a convenient dynamic string manipulation package. Functions include a full complement of comparison and assignment operators, subscripting, concatenation, substring extraction and replacement, and conversion to upper case, lower case, and ASCII.
Class
String
defines the conversion of
String
objects to and from
const char*
, so you can use them as arguments to C library routines, for example.
When creating a
String
, you may optionally give a hint as to how many extra characters you expect the string to grow by. This can improve efficiency by reducing the number of calls made to the memory allocator. If the string length exceeds this estimate, the allocated space is increased automatically. Space for an additional
DEFAULT_STRING_EXTRA
characters (currently 15) is allocated by default. Note that space for a zero terminating character is always allocated.
The individual characters of a
String
are indexed originating at 0, like C strings and arrays. You can use the substring operator
operator()(unsigned
position, unsigned
length)
to extract, insert, or replace portions of a
String
.
String()
String
with an initial capacity of
DEFAULT_STRING_EXTRA
characters.
String(int
extra)
String(unsigned
extra)
String
with an initial capacity of
extra
characters.
String(const char*
cs)
String(const String&
s)
String(const SubString&
ss)
String
initialized to the specified C string
cs,
String
s, or
SubString
ss
with an initial capacity equal to the length of the argument plus
DEFAULT_STRING_EXTRA
characters.
String(const char*
cs, unsigned
extra)
String(const String&
s, unsigned
extra)
String(const SubString&
ss, unsigned
extra)
String
initialized to the specified C string
cs,
String
s, or
SubString
ss
with an initial capacity equal to the length of the argument plus
extra
characters.
String(char
c, unsigned
l
=1, unsigned
extra
=DEFAULT_STRING_EXTRA)
String
of length
l
with each character initialized to
c. Space for an additional
extra
characters is allocated.
virtual unsigned hash() const
bool operator<(const String&
s) const
bool operator<(const SubString&
ss) const
bool operator<(const char*
cs) const
friend bool operator<(const char*
cs, const String&
s)
bool operator>(const String&
s) const
bool operator>(const SubString&
ss) const
bool operator>(const char*
cs) const
friend bool operator>(const char*
cs, const String&
s)
bool operator<=(const String&
s) const
bool operator<=(const SubString&
ss) const
bool operator<=(const char*
cs) const
friend bool operator<=(const char*
cs, const String&
s)
bool operator>=(const String&
s) const
bool operator>=(const SubString&
ss) const
bool operator>=(const char*
cs) const
friend bool operator>=(const char*
cs, const String&
s)
bool operator==(const String&
s) const
bool operator==(const SubString&
ss) const
bool operator==(const char*
cs) const
friend bool operator==(const char*
cs, const String&
s)
bool operator!=(const String&
s) const
bool operator!=(const SubString&
ss) const
bool operator!=(const char*
cs) const
friend bool operator!=(const char*
cs, const String&
s)
YES
if the indicated relation holds between this
String
and the argument
String
s,
SubString
ss, or C string
cs. The private
SubString
class also defines a similar set of relational operators so that a
SubString
may also appear as the left operand.
virtual int compare(const Object&
ob) const
String
with the argument object
ob, which must also be a kind of class
String
. Returns a negative result if this
String
is alphabetically before
ob, zero if this
String
equals
ob, and a positive result if this
String
is alphabetically after
ob.
virtual bool isEqual(const Object&
ob) const
YES
if
ob
is of species
String
and equals this
String
.
void operator=(const String&
s)
void operator=(const SubString&
ss)
void operator=(const char*
cs)
String
with a copy of
String
s,
SubString
ss, or C string
cs.
virtual void deepenShallowCopy()
String
.
char& operator[](unsigned
i)
char operator[](unsigned
i) const
char& at(unsigned
i)
char at(unsigned
i) const
String
. Characters are indexed from 0 to
size()-1
. If
i
is outside this range, an
NIHCL_INDEXRANGE
exception is raised.
SubString operator()(unsigned
pos, unsigned
len)
const SubString operator()(unsigned
pos, unsigned
len) const
String
, an
NIHCL_SUBSTRERR
exception is raised. You can use the substring operator in an expression to extract a substring of a
String
, or as the left operand of an assignment operator to insert or replace a substring of a
String
. For example:
String s("abcXXXghi"), t("defYY"); s(3,3) = t(0,3); cout << s; // prints abcdefghi
You can use the substring operator to insert one string into another:
String s("abcghi"); s(3,0) = "def"; cout << s; // prints abcdefghi
or to replace a substring by one of shorter or longer length:
String s "abcXXXdef"; s(3,3) = ""; cout << s; // prints abcdef
String s "abcXghi"; s(3,1) = "def"; cout << s; // prints abcdefghi
If a
String
has length
L, the substring operator (L,0) is valid. It extracts a substring of length zero, or appends to the end of a
String
if you use it as the left operand of an assignment operator:
String s "abc"; s(3,0) = "def"; cout << s; // prints abcdef
SubString operator()(const Range&
r)
const SubString operator()(const Range&
r) const
Range
r. Raises an
NIHCL_BADRANGE
exception if
r
is undefined.
String operator&(const String&
s) const
String operator&(const SubString&
ss) const
String operator&(const char*
cs) const
String
that is the result of appending the argument
String
s,
SubString
ss, or C string
cs
to the end of this
String
. These functions are also defined for
SubString
s.
friend String operator&(const char*
cs, const String&
s)
friend String operator&(const char*
cs, const SubString&
ss)
String
formed by appending
String
s
or
SubString
ss
to the end of the C string
cs.
String& operator&=(const String&
s)
String& operator&=(const SubString&
ss)
String& operator&=(const char*
cs)
String
s,
SubString
ss, or C string
cs
to the end of this
String
. This is a more efficient operation than
operator&()
.
operator const char*() const
String
to a pointer to a C-style (i.e. null-terminated) character string.
virtual void toAscii()
virtual void toLower()
virtual void toUpper()
String
to ASCII, lowercase, or uppercase, respectively.
unsigned length() const
virtual unsigned size() const
String
, not including the null terminator.
unsigned reSize(unsigned
newSize)
String
to
newSize
or
length()
, whichever is larger. Returns the resulting string capacity.
virtual unsigned capacity() const
String
can hold, not counting the zero terminator byte, before it will be resized.
virtual void printOn(ostream&
strm
=cout) const
String
on output stream
strm.
virtual void scanFrom(istream&
strm)
String
. Note that
scanFrom()
will not read more than 512 characters, and that an initial empty line on the input stream will be ignored.
virtual const Class* species() const
String
.
virtual void storer(OIOofd&
fd) const
virtual void storer(OIOout&
strm) const
String
on
fd
or
strm.
NIHCL_BADCLASS
,
NIHCL_BADRANGE
,
NIHCL_INDEXRANGE
,
NIHCL_SUBSTRERR
Go to the previous, next section.