Character String

Classes
class	elm::String
class	elm::CString
class	elm::StringBuffer

Variables
AutoStringStartup	elm::autostr
AutoStringStartup &	elm::_ = autostr

Detailed Description

This module provides classes making easier the use of character string. There is basically two classes: String and CString. Other classes provides more services like StringBuffer.

Notice that typedefs "string" and "cstring" are only scalar-type-like shortcuts to String and CString classes.

Base Classes

The CString is a simple wrapper around the original C "char *" null-terminated C string. It provides an interface very similar to the String class as possible. The operator "&" may be used to get the hidden "const char *" buffer. When CString operation requires memory allocation, a String object is instead returned as this class has automatic memory management facilities. The CString is either useful to interact with the OS, or to handle constant litteral strings.

The String provides a lot of facilities to handle strings as any other scalar type:

• the memory allocation is automatically handled (counter based),
• the memory allocation is only performed when needed (for concatenation time or for CString conversion),
• the substring building is fast (inducing no memory movement).

String Operations

The string classes implements the concept concept::Array<char>.

The following operators are also available:

• "==", "!=", "<", "<=", ">", ">=" for comparisons,
• "+" for concatenation,
• "=" for assignment,
• "&" to get the character buffer (note that, for String class, this array not ever ended by a null character).

Some automatic conversions are also available:

• CString to String,
• string to boolean (to false for an empty string, to true else).
• String::toCString() provides a way to convert a String to a CString (ensuring a terminating null character),
• litteral C++ string to any string.

Finally, there some methods to perform tests or retrieval of strings:

• indexOf() and lastIndexOf() to retrieve a single character,
• startsWith() and endsWith() to test prefixes and suffixes.

And some methods to build strings:

• substring() to retrieve a sub-string by its position and length,
• concat() to perform concanetation.

StringBuffer Class

String building is very costly because it requires a memory copy of both involved strings. Usually, a string building operation involves many concatenation. The StringBuffer class may be used to reduce this cost.

The string is built in a large buffer that is expanded (inducing a copy operation) less often than the original String class. To makes things easier, this class provides also the same interface as IO io::Output class. To get the completed string, one has only to call the toString() method as in the example below.

for(int i = 0; i < 10; i++) {
    StringBuffer buffer;
    buffer << "Hello world: " << i << io:endl;
    string str = buffer.toString();
    my_function(str);
}

To make things even easier, the ELM library provides an auto-builder and frier of string buffer called elm::_ that avoids the need to declare the string buffer. The previous example uses below this feature:

for(int i = 0; i < 10; i++)
    my_function(_ << "Hello world: " << i << io:endl);

Variable Documentation

AutoStringStartup & elm::_ = autostr

This little object make easier the construction of strings. There is no more to explictely construct a string buffer, concatenates items and buid the string to pass it to a parameter. Just perform the concatenation on the autostr object and all work is done automatically as in the example below.

void call(const String& message);

for(int i = 0; i < 100; i++)
   call(autostr << "Hello world, " << i << " times !");

As the autostr keyword is a bit long, you may replaced it by "_".

for(int i = 0; i < 100; i++)
   call(_ << "Hello world, " << i << " times !");

Referenced by elm::serial2::__serialize(), elm::serial2::__unserialize(), elm::serial2::XOMSerializer::beginCompound(), elm::serial2::XOMUnserializer::beginObject(), elm::serial2::XOMSerializer::beginObject(), elm::serial::XOMUnserializer::close(), elm::sys::System::createRandomFile(), elm::log::Debug::debugPrefix(), elm::serial2::XOMUnserializer::flush(), elm::ini::File::load(), elm::SimpleGC::mark(), elm::serial2::XOMUnserializer::onEnum(), elm::serial2::XOMSerializer::onPointer(), elm::serial2::XOMSerializer::onValue(), elm::sys::System::openRandomFile(), elm::option::Manager::parse(), elm::sys::Plugger::plugFile(), elm::option::EnumOption< T >::process(), elm::serial::XOMUnserializer::readEnum(), elm::serial::XOMUnserializer::readPointer(), elm::serial2::type(), elm::serial2::XOMUnserializer::XOMUnserializer(), and elm::serial::XOMUnserializer::XOMUnserializer().

AutoStringStartup elm::autostr

Refer to elm::_.

Referenced by elm::operator<<().