Falcon::String Class Reference

Core string This class is called "Core String" because it represents the strings as the internal VM and engine sees them. More...

#include <string.h>

Inheritance diagram for Falcon::String:

Inheritance graph
[legend]

List of all members.

Public Types

enum  constants { npos = csh::npos, no_id = 0xFFFFFFFF }

Public Member Functions

String & A (uint32 chr)
 Cumulative version of append.
String & A (int chr)
 Cumulative version of append.
String & A (const String &str)
 Cumulative version of append.
String & adopt (wchar_t *buffer, uint32 size, uint32 allocated)
 Adopt a pre-allocated dynamic buffer (wide char version).
String & adopt (char *buffer, uint32 size, uint32 allocated)
 Adopt a pre-allocated dynamic buffer.
void allocated (uint32 s)
 Changes the amount of allocated memory.
uint32 allocated () const
 Returns the amount of allocated memory in the deep buffer.
void append (uint32 chr)
void append (const String &source)
void backTrim ()
String & bufferize ()
 Forces this string to get buffer space to store even static strings.
String & bufferize (const String &other)
 Creates a String forcing bufferization of the original one.
void c_ize ()
 Adds an extra '' terminator past the end of the string.
bool change (int32 start, int32 end, const String &other)
bool change (int32 start, const String &other)
bool checkPosBound (int32 &pos)
 Checks the position to be in the string, and eventually changes it if it's negative.
bool checkRangeBound (int32 &begin, int32 &end)
 Checks the range to be in the string, and eventually changes it if it's negative.
int compare (const String &other) const
 Compares a string to another ignoring the case.
int compare (const wchar_t *other) const
 Compares a string to another.
int compare (const char *other) const
 Compares a string to another.
int compareIgnoreCase (const wchar_t *other) const
 Compares a string to another ignoring the case.
int compareIgnoreCase (const char *other) const
 Compares a string to another ignoring the case.
int compareIgnoreCase (const String &other) const
 Compares a string to another ignoring the case.
void copy (const String &other)
 Copies the original string as-is.
bool deserialize (Stream *in, bool bStatic=false)
 Load the string from a stream.
bool endsWith (const String &str, bool icase=false) const
 Compares a string with the end of this string.
void escape (String &target) const
 Escapes a string for external representation.
void escapeFull (String &target) const
 Escapes a string for external representation - full version.
void exported (bool e)
 Sets wether this string should be exported in international context or not.
bool exported () const
 Return wether this exact string instance should be internationalized.
uint32 find (const String &element, uint32 start=0, uint32 end=csh::npos) const
bool fromUTF8 (const char *utf8)
 Bufferize an UTF-8 string.
void frontTrim ()
 Remove efficiently 'what' at the beginning of the string.
uint32 getCharAt (uint32 pos) const
byte * getRawStorage () const
 Return the raw storage for this string.
void id (uint32 val)
uint32 id () const
void insert (uint32 pos, uint32 len, const String &source)
bool isCore () const
bool isStatic () const
uint32 length () const
 Return the length of the string in characters.
bool less (const String &other) const
 Order predicate.
void lower ()
 Convert the string to all lower case.
void manipulator (csh::Base *m)
 Set the manipulator.
const csh::Base * manipulator () const
 Return the manipulator of the class.
String & N (double number, const String &format)
 Cumulative version of writeNumber.
String & N (double number)
 Cumulative version of writeNumber.
String & N (int64 number, const String &format)
 Cumulative version of writeNumber.
String & N (int32 number)
 Cumulative version of writeNumber.
String & N (int64 number)
 Cumulative version of writeNumber.
bool operator! ()
 Returns true if this string is empty.
String & operator+= (const wchar_t *other)
String & operator+= (wchar_t other)
String & operator+= (const char *other)
String & operator+= (char other)
String & operator+= (uint32 other)
String & operator+= (const String &other)
String & operator= (const char *other)
 Assign from a const char string.
String & operator= (uint32 chr)
String & operator= (const String &other)
const uint32 operator[] (uint32 pos) const
 Access to a single character.
bool parseBin (uint64 &target, uint32 pos=0) const
 Minimal numerical conversion.
bool parseDouble (double &target, uint32 pos=0) const
 Minimal numerical conversion.
bool parseHex (uint64 &target, uint32 pos=0) const
 Minimal numerical conversion.
bool parseInt (int64 &target, uint32 pos=0) const
 Minimal numerical conversion.
bool parseOctal (uint64 &target, uint32 pos=0) const
 Minimal numerical conversion.
void prepend (const String &source)
void prepend (uint32 chr)
void readIndex (const Item &index, Item &target)
void readProperty (const String &prop, Item &item)
void remove (uint32 pos, uint32 len)
void reserve (uint32 size)
 Reserve buffer space in the target string.
uint32 rfind (const String &element, uint32 start=0, uint32 end=csh::npos) const
void serialize (Stream *out) const
 Save the string to a stream.
void setCharAt (uint32 pos, uint32 chr)
bool setCharSize (uint32 nsize, uint32 subst=0xFFFFFFFF)
 Alters the character size of this string.
void setRawStorage (byte *b, int size)
 Changes the raw storage in this string.
void setRawStorage (byte *b)
 Changes the raw storage in this string.
void shrink ()
 Reduces the size of allocated memory to fit the string size.
void size (uint32 s)
 Changes the amount of bytes the string is considered to occupy.
uint32 size () const
 Returns the amount of bytes the string occupies.
bool startsWith (const String &str, bool icase=false) const
 Compares a string with the beginning of this string.
 String (const String &other, uint32 begin, uint32 end=csh::npos)
 Substring constructor.
 String (const String &other)
 Copies a string.
 String (uint32 prealloc)
 Creates a bufferized string with preallocated space.
 String (const wchar_t *data, int32 len)
 Allows on-the-fly core string creation from static data.
 String (const char *data, int32 len)
 Allows on-the-fly core string creation from static data.
 String (const wchar_t *data)
 Adopt a static buffer as the internal buffer.
 String (const char *data)
 Adopt a static buffer as the internal buffer.
 String ()
 Creates an empty string.
String subString (int32 start) const
String subString (int32 start, int32 end) const
uint32 toCString (char *target, uint32 bufsize) const
 Tranforms the string into a zero-terminated string.
uint32 toWideString (wchar_t *target, uint32 bufsize) const
 Tranforms the string into a zero-terminated wide string.
void trim ()
void trim (int mode)
 Remove efficiently whitespaces at beginning and end of the string.
csh::t_type type () const
 Return the type of the string.
void unescape (String &other) const
 Unescape this string placing the result in another one.
void unescape ()
 Unescape this string.
void upper ()
 Convert the string to all upper case.
void writeIndex (const Item &index, const Item &target)
void writeNumber (int64 number, const String &format)
void writeNumber (double number, const String &format)
 Converts a number to a string and appends it to this string.
void writeNumber (double number)
 Converts a number to a string and appends it to this string.
void writeNumber (int64 number)
 Converts a number to a string and appends it to this string.
void writeNumberHex (uint64 number, bool uppercase=true)
 Converts a number to a string and appends it to this string.
void writeNumberOctal (uint64 number)
 Converts a number to a string and appends it to this string.
 ~String ()
 Destroys the String.

Static Public Member Functions

static bool isWhiteSpace (uint32 chr)
static void uint32ToHex (uint32 number, char *buffer)

Protected Member Functions

 String (csh::Base *cl)
 sym Creates the core string.

Protected Attributes

uint32 m_allocated
bool m_bCore
bool m_bExported
 True if this string is exportable - importable in GC context.
byte m_bFlags
const csh::Base * m_class
uint32 m_id
uint32 m_size
byte * m_storage

Friends

class csh::Base
class csh::Buffer
class csh::Buffer16
class csh::Buffer32
class csh::Byte
class csh::Static
class csh::Static16
class csh::Static32

Detailed Description

Core string This class is called "Core String" because it represents the strings as the internal VM and engine sees them.

This class is highly configurable and may manage any string that Falcon will ever need to mangle with.

A set of fields is used to store the informations about the memory buffer where the string is actually held. The "kind" of string is determined by its manager. The manager is a special friend class that is in charge to effect all the needed operations on a particular kind of string. In example, there's a manager for static C strings, one for memAlloc() allocated strings, and in future also for chunked (multi buffer) stings and a parallel set of managers for international strings.

The kind of the string can be changed by just changing its manager; this is often done automatically by an appropriate constructor or when some operation occour (i.e. a static string may be turned into a chunked one at write operations, and a chunked may get transformed into a buffered one if a linear access on the whole string is needed.

String have a set of specialized subclasses which actually does nothing if not construct the base String with the appropriate string manager. Every corestring class is BOUND having not any private data member, because the derived String may be turned in something else at every moment without changing its memory position or layout. There's no RTTI information about this changes; all the polimorphism needed is applied by changing the string manager.

However, String sublcass may define some new function members to handle initialization steps before "unmasking" the String structure and handle it back to the rest of the system. Also, as the String subclass may be determined by looking at the manager, a subclass with special operations (new member function) may be casted later on safely. The only requisite is that there's a 1:1 mapping between corestring subclasses and the manager they use.

Member Enumeration Documentation

enum Falcon::String::constants

Enumerator:
npos 
no_id 

Constructor & Destructor Documentation

Falcon::String::String ( csh::Base *  cl  )  [inline, explicit, protected]

sym Creates the core string.

This method is protected. It can be accessed only by subclasses.

Falcon::String::String (  )  [inline]

Creates an empty string.

The string is created non-zero terminated with length 0. It has also no valid internal storage at creation time.

Falcon::String::String ( const char *  data  ) 

Adopt a static buffer as the internal buffer.

This version of the string adopts the given buffer and becomes a "static string".

A static string is just meant to carry around a pre-existing unchangeable (read-only) static buffer. The passed buffer must stay vaild for the whole duration of this string (i.e. it may be allocated as static string in some module).

The string is automatically "bufferized" when some write operations are performed, so the original static data stays untouched even if this string is modified.

This constructor allows for automatic fast char-to-string conversion in temporary operations.

Note:
No assumption is made of the encoding of the source string. The data is just accepted as a mere sequence of bytes.

The method bufferize() may be used later to force copy of the contents of this string. In that case, the underlying data must just stay valid until bufferize() is called.

See also:
adopt
Parameters:
data the source data to be copied

Falcon::String::String ( const wchar_t *  data  ) 

Adopt a static buffer as the internal buffer.

This is the wide char version. This version of the string adopts the given buffer and becomes a "static string".

A static string is just meant to carry around a pre-existing unchangeable (read-only) static buffer. The passed buffer must stay vaild for the whole duration of this string (i.e. it may be allocated as static string in some module).

The string is automatically "bufferized" when some write operations are performed, so the original static data stays untouched even if this string is modified.

This constructor allows for automatic fast char-to-string conversion in temporary operations.

Note:
No assumption is made of the encoding of the source string. The data is just accepted as a mere sequence of wide characters.

The method bufferize() may be used later to force copy of the contents of this string. In that case, the underlying data must just stay valid until bufferize() is called.

See also:
adopt
Parameters:
data the source data to be copied

Falcon::String::String ( const char *  data,
int32  len 
)

Allows on-the-fly core string creation from static data.

The resulting string is a bufferized copy of the static data; the source may be destroyed or become invalid, while this string will be still useable.

Note:
To adopt an undestroyable buffer, use String( const char* ) version.

No assumption is made of the encoding of the source string. The data is just accepted as a mere sequence of bytes.

Parameters:
data the source data to be copied
len the length of the string in buffer (in bytes). Pass -1 to make the constructor to determine the buffer length by scanning it in search for '\0'

Falcon::String::String ( const wchar_t *  data,
int32  len 
)

Allows on-the-fly core string creation from static data.

This is the wide string version.

The resulting string is a bufferized copy of the static data; the source may be destroyed or become invalid, while this string will be still useable.

Note:
To adopt an undestroyable buffer, use String( const wchar_t* ) version.

No assumption is made of the encoding of the source string. The data is just accepted as a mere sequence of wide characters.

Parameters:
data the source data to be copied
len the length of the buffer (in wide characters). Pass -1 to make the constructor to determine the buffer length by scanning it in search for '\0'

Falcon::String::String ( uint32  prealloc  )  [explicit]

Creates a bufferized string with preallocated space.

Falcon::String::String ( const String &  other  )  [inline]

Copies a string.

If the copied string is a bufferized string, a new bufferzied string is created, else a static string pointing to the same location of the original one is created.

Note:
Static strings are constructed by simpling pointing the other string start position. Remember: static strings are meant to "carry" underlying memory and interpret it as a string, so the underlying memory must stay valid.
Use bufferize() on this string to ensure that it is deep-copied.

Falcon::String::String ( const String &  other,
uint32  begin,
uint32  end = csh::npos 
)

Substring constructor.

This constructor is used to extract a substring from the original one, and is used in the subString() metod to return a string & as an inline call. Being an inline call, the optimized version optimizes the involved copy away. However, a string copy will still be present in debug.

Note:
Static strings are constructed by simpling pointing the other string start position. Remember: static strings are meant to "carry" underlying memory and interpret it as a string, so the underlying memory must stay valid.
Use bufferize() on this string to ensure that it is copied.

Falcon::String::~String (  )  [inline]

Destroys the String.

As the method is not virtual (neither the class is), different kind of strings are destroyed by calling the destroy() method of their manipulators.

Member Function Documentation

String& Falcon::String::A ( uint32  chr  )  [inline]

Cumulative version of append.

This method can be used to concatenate strings and number such as for String s = String( "You got ").N( msg_count ).A( " messages " );

String& Falcon::String::A ( int  chr  )  [inline]

Cumulative version of append.

This method can be used to concatenate strings and number such as for String s = String( "You got ").N( msg_count ).A( " messages " );

String& Falcon::String::A ( const String &  str  )  [inline]

Cumulative version of append.

This method can be used to concatenate strings and number such as for String s = String( "You got ").N( msg_count ).A( " messages " );

String& Falcon::String::adopt ( wchar_t *  buffer,
uint32  size,
uint32  allocated 
)

Adopt a pre-allocated dynamic buffer (wide char version).

This function takes the content of the given buffer and sets it as the internal storage of the string. The buffer is considered dynamically allocated with memAlloc(), and will be destroyed with memFree().

This string is internally transformed in a raw buffer string; any previous content is destroyed.

String is considered a wide char width string.

Parameters:
buffer the buffer to be adopted
size the size of the string contained in the buffer (in character count)
allocated the size of the buffer as it was allocated (in bytes)
Returns:
itself

String& Falcon::String::adopt ( char *  buffer,
uint32  size,
uint32  allocated 
)

Adopt a pre-allocated dynamic buffer.

This function takes the content of the given buffer and sets it as the internal storage of the string. The buffer is considered dynamically allocated with memAlloc(), and will be destroyed with memFree().

This string is internally transformed in a raw buffer string; any previous content is destroyed.

String is considered a single byte char width string.

Parameters:
buffer the buffer to be adopted
size the size of the string contained in the buffer (in bytes)
allocated the size of the buffer as it was allocated (in bytes)
Returns:
itself

void Falcon::String::allocated ( uint32  s  )  [inline]

Changes the amount of allocated memory.

Used in buffers strings or in general in contiguous memory strings. Other kind of strings may ignore this (and so let it undefined) or use it for special purposes (i.e. amount of free memory on the last chunk in chunked strings.)

uint32 Falcon::String::allocated (  )  const [inline]

Returns the amount of allocated memory in the deep buffer.

Used in buffers strings or in general in contiguous memory strings. Other kind of strings may ignore this (and so let it undefined) or use it for special purposes (i.e. amount of free memory on the last chunk in chunked strings.)

void Falcon::String::append ( uint32  chr  ) 

void Falcon::String::append ( const String &  source  ) 

Referenced by Falcon::operator+().

void Falcon::String::backTrim (  )  [inline]

String& Falcon::String::bufferize (  ) 

Forces this string to get buffer space to store even static strings.

Returns:
itself

String& Falcon::String::bufferize ( const String &  other  ) 

Creates a String forcing bufferization of the original one.

This function copies the foreign string in a buffer responding to the toCstring requirements (zero terminate 8-bit strings, i.e. char* or UTF8). As clone and copy (and copy constructor) try to preserve remote string static allocation, this function is required when a bufferized copy is explicitly needed.

Parameters:
other the string to be copied.
Returns:
itself

Referenced by Falcon::VMachine::retval().

void Falcon::String::c_ize (  ) 

Adds an extra '' terminator past the end of the string.

This makes the string data (available through getRawStorage()) suitable to be sent to C functions compatible with the character size of this string.

Eventually, it should be preceded by a call to setCharSize().

bool Falcon::String::change ( int32  start,
int32  end,
const String &  other 
) [inline]

bool Falcon::String::change ( int32  start,
const String &  other 
) [inline]

References Falcon::csh::npos.

bool Falcon::String::checkPosBound ( int32 &  pos  )  [inline]

Checks the position to be in the string, and eventually changes it if it's negative.

This is just a nice inline shortuct so that the string constructor for substrings can be called safely.

Parameters:
pos the position to be checked and eventually turned into a positive value.
Returns:
false if pos is outside thte string

bool Falcon::String::checkRangeBound ( int32 &  begin,
int32 &  end 
) [inline]

Checks the range to be in the string, and eventually changes it if it's negative.

This is just a nice inline shortuct so that the string constructor for substrings can be called safely.

Parameters:
begin the start to be checked and eventually turned into a positive value.
end the end to be checked and eventually turned into a positive value.
Returns:
false if the range cannot be mapped in string.

int Falcon::String::compare ( const String &  other  )  const

Compares a string to another ignoring the case.

This metod returns -1 if this string is less than the other, 0 if it's the same and 1 if it's greater.

Parameters:
other the other string to be compared
Returns:
-1 if this is less than the other, 0 if it's the same, 1 if it's greater.

int Falcon::String::compare ( const wchar_t *  other  )  const

Compares a string to another.

Optimized to match against wide characters C strings.

See also:
compare( const String &other )
Parameters:
other the other string to be compared
Returns:
-1 if this is less than the other, 0 if it's the same, 1 if it's greater.

int Falcon::String::compare ( const char *  other  )  const

Compares a string to another.

Optimized to match against C strings.

See also:
compare( const String &other )
Parameters:
other the other string to be compared
Returns:
-1 if this is less than the other, 0 if it's the same, 1 if it's greater.

Referenced by Falcon::operator!=(), Falcon::StringPtrCmp::operator()(), Falcon::operator<(), Falcon::operator<=(), Falcon::operator==(), Falcon::operator>(), and Falcon::operator>=().

int Falcon::String::compareIgnoreCase ( const wchar_t *  other  )  const

Compares a string to another ignoring the case.

Optimized to match against C strings.

See also:
compareIgnoreCase( const String &other )
Parameters:
other the other string to be compared
Returns:
-1 if this is less than the other, 0 if it's the same, 1 if it's greater.

int Falcon::String::compareIgnoreCase ( const char *  other  )  const

Compares a string to another ignoring the case.

Optimized to match against C strings.

See also:
compareIgnoreCase( const String &other )
Parameters:
other the other string to be compared
Returns:
-1 if this is less than the other, 0 if it's the same, 1 if it's greater.

int Falcon::String::compareIgnoreCase ( const String &  other  )  const

Compares a string to another ignoring the case.

This metod returns -1 if this string is less than the other, 0 if it's the same and 1 if it's greater.

Before checking them, uppercase characters are converted in the equivalent lowercase version; in this way "aBc" and "AbC" are considered the same.

TODO - more caseization of accentuated letters

Parameters:
other the other string to be compared
Returns:
-1 if this is less than the other, 0 if it's the same, 1 if it's greater.

void Falcon::String::copy ( const String &  other  ) 

Copies the original string as-is.

If the original string is of a static type, the buffer is just referenced, else a deep copy is performed.

Parameters:
other the string to be copied.
Returns:
itself

bool Falcon::String::deserialize ( Stream *  in,
bool  bStatic = false 
)

Load the string from a stream.

The string is deserialized from the stream and allocated in memory. This means that if the original was a static string, the deserialized one will be a string buffer of compatible type.

If the string cannot be de-serialized the function returns false and the value is left as it were before calling the function. If the de serialization is succesful, the bufferized string is initializated and the function returns true.

A failure usually means a stream corruption or an incompatible format.

Parameters:
in the input stream where the string must be read from
bStatic true to create a self-destroryable static string
Returns:
true on success, false on failure.

bool Falcon::String::endsWith ( const String &  str,
bool  icase = false 
) const

Compares a string with the end of this string.

If str is empty, returns true, if it's larger than this string returns false.

Parameters:
str The string to be compared against the end of this string.
icase true to perform a case neutral compare
Returns:
true on success.

void Falcon::String::escape ( String &  target  )  const

Escapes a string for external representation.

Convert special control characters to "\" prefixed characters, so tha the resulting string can be used in a source code to regenerate the same string in parsing.

Characters below 0x0008 (backspace) are turned into hexadecimal representation, while international characters (from 0x0080 up) are left unchanged. This means that the resulting string must still be sent through an encoder to be safely saved on a stream.

Parameters:
target the target string

void Falcon::String::escapeFull ( String &  target  )  const

Escapes a string for external representation - full version.

Convert special control characters to "\" prefixed characters, so tha the resulting string can be used in a source code to regenerate the same string in parsing.

Characters below 0x0008 (backspace) and international characters (from 0x0080 up) are turned into hexadecimal representation. This means that the resulting string can be safely written on an output file without concerns for final encoding.

Parameters:
target the target string

void Falcon::String::exported ( bool  e  )  [inline]

Sets wether this string should be exported in international context or not.

bool Falcon::String::exported (  )  const [inline]

Return wether this exact string instance should be internationalized.

Note:
exported() attribute is not copied across string copies.

uint32 Falcon::String::find ( const String &  element,
uint32  start = 0,
uint32  end = csh::npos 
) const [inline]

bool Falcon::String::fromUTF8 ( const char *  utf8  ) 

Bufferize an UTF-8 string.

This is an efficient shortcut for the very common case of UTF8 strings being turned into falcon string. There isn't a drect constructor that understands that the input char * is an UTF8 string, but the proxy generators UTF8String and UTF8String serve to this purpose.

After the call, the previous content of this string is destroyed.

In case of an invalid UTF8 sequence, up to what is possible to decode is read, and the function return false.

Parameters:
utf8 the utf8 string to be loaded
Returns:
true on success, false if the sequence is invalid.

Referenced by Falcon::UTF8String().

void Falcon::String::frontTrim (  )  [inline]

Remove efficiently 'what' at the beginning of the string.

If what is empty, whitespaces are removed.

uint32 Falcon::String::getCharAt ( uint32  pos  )  const [inline]

byte* Falcon::String::getRawStorage (  )  const [inline]

Return the raw storage for this string.

The raw storage is where the strings byte are stored. For more naive string (i.e. chunked), it may return the pointer to a structure helding more informations about the string data.

void Falcon::String::id ( uint32  val  )  [inline]

uint32 Falcon::String::id (  )  const [inline]

Reimplemented in Falcon::StringWithID.

void Falcon::String::insert ( uint32  pos,
uint32  len,
const String &  source 
) [inline]

bool Falcon::String::isCore (  )  const [inline]

bool Falcon::String::isStatic (  )  const [inline]

References Falcon::csh::cs_static, Falcon::csh::cs_static16, and Falcon::csh::cs_static32.

static bool Falcon::String::isWhiteSpace ( uint32  chr  )  [inline, static]

uint32 Falcon::String::length (  )  const [inline]

Return the length of the string in characters.

The string length may vary depending on the string manipulator. This function calls a method in the manipuplator that selects the right way to calculate the string character count. Being not a pure accessor, is actually better to cache this value somewhere if repeteadly needed.

bool Falcon::String::less ( const String &  other  )  const [inline]

Order predicate.

This predicate is used to sort Falcon::String objects and is provided mainly as an interface for the stl container classes.

Parameters:
other the other string to check for
Returns:
true if this string is considered less (smaller in collation order) than the other one.

void Falcon::String::lower (  ) 

Convert the string to all lower case.

void Falcon::String::manipulator ( csh::Base *  m  )  [inline]

Set the manipulator.

Changing the manipulator also changes the meaning of the class deep data, and finally the correct subclass of String to which this item can be safely casted. Actually this method should be called only by internal functions, or only if you are really knowing what you are doing.

const csh::Base* Falcon::String::manipulator (  )  const [inline]

Return the manipulator of the class.

The manipulator is the function vector (under the form of a pure-virtual without-data class) that is used to handle the string. The manipulator identifies also the type of string, and so the subclass of the String that this strings currently belongs to.

String& Falcon::String::N ( double  number,
const String &  format 
) [inline]

Cumulative version of writeNumber.

This method can be used to concatenate strings and number such as for String s = String( "You got ").N( msg_count ).A( " messages " );

String& Falcon::String::N ( double  number  )  [inline]

Cumulative version of writeNumber.

This method can be used to concatenate strings and number such as for String s = String( "You got ").N( msg_count ).A( " messages " );

String& Falcon::String::N ( int64  number,
const String &  format 
) [inline]

Cumulative version of writeNumber.

This method can be used to concatenate strings and number such as for String s = String( "You got ").N( msg_count ).A( " messages " );

String& Falcon::String::N ( int32  number  )  [inline]

Cumulative version of writeNumber.

This method can be used to concatenate strings and number such as for String s = String( "You got ").N( msg_count ).A( " messages " );

String& Falcon::String::N ( int64  number  )  [inline]

Cumulative version of writeNumber.

This method can be used to concatenate strings and number such as for String s = String( "You got ").N( msg_count ).A( " messages " );

bool Falcon::String::operator! (  )  [inline]

Returns true if this string is empty.

String& Falcon::String::operator+= ( const wchar_t *  other  )  [inline]

Reimplemented in Falcon::CoreString.

String& Falcon::String::operator+= ( wchar_t  other  )  [inline]

Reimplemented in Falcon::CoreString.

String& Falcon::String::operator+= ( const char *  other  )  [inline]

Reimplemented in Falcon::CoreString.

String& Falcon::String::operator+= ( char  other  )  [inline]

Reimplemented in Falcon::CoreString.

String& Falcon::String::operator+= ( uint32  other  )  [inline]

Reimplemented in Falcon::CoreString.

String& Falcon::String::operator+= ( const String &  other  )  [inline]

Reimplemented in Falcon::CoreString.

String& Falcon::String::operator= ( const char *  other  )  [inline]

Assign from a const char string.

If this string is not empty, its content are destroyed; then this object is changed into a static zero terminated C string and the phisical location of the const char assigned to this string is taken as undestroyable reference. This operation is meant for C string phisically stored somewhere in the program and that stay valid for the whole program duration, or at least for the whole lifespan of this Falcon::String object.

Reimplemented in Falcon::CoreString.

String& Falcon::String::operator= ( uint32  chr  )  [inline]

Reimplemented in Falcon::CoreString.

String& Falcon::String::operator= ( const String &  other  )  [inline]

Reimplemented in Falcon::CoreString.

const uint32 Falcon::String::operator[] ( uint32  pos  )  const [inline]

Access to a single character.

Please, notice that Falcon strings are polymorphic in assignment, so they cannot support the following syntax: 

         s[n] = c; // can't work with Falcon strings.

This operator is provided as a candy grammar for getCharAt().

bool Falcon::String::parseBin ( uint64 &  target,
uint32  pos = 0 
) const

Minimal numerical conversion.

If this string represents a valid integer in octal format, the integer is returned. Pos must start after the octal marker \b.

Parameters:
target place where to store the number
pos initial position in the string from which to start the conversion
Returns:
true if succesful, false if parse failed

bool Falcon::String::parseDouble ( double &  target,
uint32  pos = 0 
) const

Minimal numerical conversion.

If this string represents a valid floating point number, the number is returned. The string is considered a valid number also if it is followed by non-numerical data. Floating point number may be in scientific notation.

Parameters:
target place where to store the number
pos initial position in the string from which to start the conversion
Returns:
true if succesful, false if parse failed

bool Falcon::String::parseHex ( uint64 &  target,
uint32  pos = 0 
) const

Minimal numerical conversion.

If this string represents a valid integer in hexadecimal format, the integer is returned. Pos must start after the octal marker \x.

Parameters:
target place where to store the number
pos initial position in the string from which to start the conversion
Returns:
true if succesful, false if parse failed

bool Falcon::String::parseInt ( int64 &  target,
uint32  pos = 0 
) const

Minimal numerical conversion.

If this string represents a valid integer, the integer is returned. The string is considered a valid integer also if it is followed by non-numerical data.

Parameters:
target place where to store the number
pos initial position in the string from which to start the conversion
Returns:
true if succesful, false if parse failed

bool Falcon::String::parseOctal ( uint64 &  target,
uint32  pos = 0 
) const

Minimal numerical conversion.

If this string represents a valid integer in octal format, the integer is returned. Pos must start after the octal marker \0 or \c.

Parameters:
target place where to store the number
pos initial position in the string from which to start the conversion
Returns:
true if succesful, false if parse failed

void Falcon::String::prepend ( const String &  source  )  [inline]

void Falcon::String::prepend ( uint32  chr  ) 

void Falcon::String::readIndex ( const Item &  index,
Item &  target 
)

void Falcon::String::readProperty ( const String &  prop,
Item &  item 
)

void Falcon::String::remove ( uint32  pos,
uint32  len 
) [inline]

References Falcon::core::len().

void Falcon::String::reserve ( uint32  size  )  [inline]

Reserve buffer space in the target string.

This ensures that the space allocated in the string is bufferzed and at least wide enough to store the requested bytes.

Note:
the width is in bytes.
Parameters:
size minimal space that must be allocated as writeable heap buffer (in bytes).

uint32 Falcon::String::rfind ( const String &  element,
uint32  start = 0,
uint32  end = csh::npos 
) const [inline]

void Falcon::String::serialize ( Stream *  out  )  const

Save the string to a stream.

The function never fails, but on failure something weird will happen on the stream. This may raise an exception, if the exceptions on the stream are turned on.

Parameters:
out the stream on which to save the string.

void Falcon::String::setCharAt ( uint32  pos,
uint32  chr 
) [inline]

bool Falcon::String::setCharSize ( uint32  nsize,
uint32  subst = 0xFFFFFFFF 
)

Alters the character size of this string.

Changes the number of bytes used to represent a single character in this string. The number of byte used can be 1, 2 or 4.

If the new character size of this string is smaller than the original one, characters that cannot be represented are substituted with a subst value (by default, the maximum value allowed for the given character size).

If the original character size was different, the string is bufferized into a new memory area, otherwise the string is unchanged.

Note:
subst param is not currently implemented.
Parameters:
nsize The new character size for the string.
subst The substitute character to be used when reducing size.
Returns:
True if the nsize value is valid, false otherwise.

void Falcon::String::setRawStorage ( byte *  b,
int  size 
) [inline]

Changes the raw storage in this string.

This makes the string to point to a new memory position for its character data.

void Falcon::String::setRawStorage ( byte *  b  )  [inline]

Changes the raw storage in this string.

This makes the string to point to a new memory position for its character data.

void Falcon::String::shrink (  )  [inline]

Reduces the size of allocated memory to fit the string size.

Use this method to shrink the allocated buffer storing the string to the minimal size needed to hold the string. This is useful when i.e. a buffered string was allocated to provide extra space for more efficient iterative appending, and the iterative appending is over.

This has no effect on static string.

Note:
use wisely as the shrink operation may require a string copy.

void Falcon::String::size ( uint32  s  )  [inline]

Changes the amount of bytes the string is considered to occupy.

This is the byte-size of the string, and may or may not be the same as the string length.

uint32 Falcon::String::size (  )  const [inline]

Returns the amount of bytes the string occupies.

This is the byte-size of the string, and may or may not be the same as the string length.

bool Falcon::String::startsWith ( const String &  str,
bool  icase = false 
) const

Compares a string with the beginning of this string.

If str is empty, returns true, if it's larger than this string returns false.

Parameters:
str The string to be compared against the beginning of this string.
icase true to perform a case neutral compare
Returns:
true on success.

String Falcon::String::subString ( int32  start  )  const [inline]

String Falcon::String::subString ( int32  start,
int32  end 
) const [inline]

uint32 Falcon::String::toCString ( char *  target,
uint32  bufsize 
) const

Tranforms the string into a zero-terminated string.

This function fills a buffer that can be fed in libc and STL function requiring a zero terminated string. The string manager will ensure that the data returned has one zero at the end of the string.

8-bit strings are left unchanged.

International strings are turned into UTF-8 strings (so that they can be fed into internationalized STL and libc functions).

The operation is relatively slow. Use when no other option is avalaible, and cache the result.

Provide a reasonable space. Safe space is size() * 4 + 1.

Parameters:
target the buffer where to place the C string.
bufsize the size of the target buffer in bytes.
Returns:
npos if the buffer is not long enough, else returns the used size.

uint32 Falcon::String::toWideString ( wchar_t *  target,
uint32  bufsize 
) const

Tranforms the string into a zero-terminated wide string.

This function returns fills a buffer that can be fed in functions accpeting wchar_t strings. Returned strings are encoded in fixed lenght UTF-16, with endianity equivalent to native platform endianity. Character from extended planes are rendered as a single <?> 0x003f.

The operation is relatively slow. Use when no other option is avalaible, and cache the result.

Required space is constant, and exactly (lenght() + 1) * sizeof(wchar_t) bytes (last "+1" is for final wchar_t "0" marker).

Parameters:
target the buffer where to place the wchar_t string.
bufsize the size of the target buffer in bytes.
Returns:
npos if the buffer size is not large enough, else returns the string length in wchar_t count

void Falcon::String::trim (  )  [inline]

References trim().

Referenced by trim().

void Falcon::String::trim ( int  mode  ) 

Remove efficiently whitespaces at beginning and end of the string.

If whitespaces are only at the end of the string, the lenght of the string is simply reduced; this means that static strings may stay static after this process. In case of whitespaces at beginning, the string will be resized, and eventually allocated, moving the characters back to the beginning position.

Parameters:
mode 0 = all, 1 = front, 2 = back

csh::t_type Falcon::String::type (  )  const [inline]

Return the type of the string.

The type is determined by the manipulator. Warning: this method calls a function virtually, so is quite slow. Better use it rarely. An acid test could be performed by matching the manipulator pointer with the standard manipulators.

static void Falcon::String::uint32ToHex ( uint32  number,
char *  buffer 
) [static]

void Falcon::String::unescape ( String &  other  )  const [inline]

Unescape this string placing the result in another one.

See also:
unescape()

References unescape().

void Falcon::String::unescape (  ) 

Unescape this string.

Unescaping string is always an operation that leaves the string unchanged or shortened, so it can be done in place. Static strings are converted into buffered strings only if some actual unescape takes place.

String unescaping understands special codes \", \\, \\r, \\n, \\t and \\b, octal numbers \0nnnn and hexadecimal numbers as \xnnnnn, up to 32 bit precision.

Referenced by unescape().

void Falcon::String::upper (  ) 

Convert the string to all upper case.

void Falcon::String::writeIndex ( const Item &  index,
const Item &  target 
)

void Falcon::String::writeNumber ( int64  number,
const String &  format 
)

void Falcon::String::writeNumber ( double  number,
const String &  format 
)

Converts a number to a string and appends it to this string.

This version allows to specify a format to be passed to sprintf in the conversion of the number. Regardless of the fact that sprintf writes a string int 8-bit char space, both the format string and this string where the result is to be appended may be in any char width.

The function does not check for validity of the format.

Parameters:
number the number to be converted.
format the format to be passed to printf for conversion.

void Falcon::String::writeNumber ( double  number  )  [inline]

Converts a number to a string and appends it to this string.

Number is formatted with prinf format "%e"; to specify a different format, use the other version of this method.

Parameters:
number the number to be converted.

void Falcon::String::writeNumber ( int64  number  ) 

Converts a number to a string and appends it to this string.

Parameters:
number the number to be converted.

void Falcon::String::writeNumberHex ( uint64  number,
bool  uppercase = true 
)

Converts a number to a string and appends it to this string.

This version writes the number in hex format.

Parameters:
number the number to be converted.
uppercase true to use ABCDEF letters instead of abdef

void Falcon::String::writeNumberOctal ( uint64  number  ) 

Converts a number to a string and appends it to this string.

This version writes the number in octal format.

Parameters:
number the number to be converted.

Friends And Related Function Documentation

friend class csh::Base [friend]

friend class csh::Buffer [friend]

friend class csh::Buffer16 [friend]

friend class csh::Buffer32 [friend]

friend class csh::Byte [friend]

friend class csh::Static [friend]

friend class csh::Static16 [friend]

friend class csh::Static32 [friend]

Member Data Documentation

uint32 Falcon::String::m_allocated [protected]

bool Falcon::String::m_bCore [protected]

bool Falcon::String::m_bExported [protected]

True if this string is exportable - importable in GC context.

byte Falcon::String::m_bFlags [protected]

const csh::Base* Falcon::String::m_class [protected]

uint32 Falcon::String::m_id [protected]

uint32 Falcon::String::m_size [protected]

byte* Falcon::String::m_storage [protected]

The documentation for this class was generated from the following file:
Generated on Mon Oct 19 10:11:46 2009 for Falcon_Core by  doxygen 1.5.8