molib documentation

Languages Available: français español

CLASS

moWCString

NAME

g_empty_string -- the empty string

VERSION

Version: 1.2.0

DESCRIPTION

Use this string whenever you need an empty string. This way you avoid a call to the constructor and the destructor.

COPYRIGHTS

This documentation and the code being documented is proprietary and cannot be duplicated without the express and written consent of Made to Order Software Coporation.

Copyright (c) 1999-2007 by Made to Order Software Corporation
All rights reserved.

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Constructor - create an moWCString object
Copy operator - copy an moWCString object
Destructor - destroys an moWCString object

VERSION

Version: 1.2.0

SYNOPSIS

moWCString(void);
moWCString(const char *str, int length = -1, encoding_t encoding);
moWCString(const mc_t *str, int length = -1, encoding_t encoding);
moWCString(const wch_t *str, int length = -1, encoding_t encoding);
moWCString(const wchar_t *str, int length = -1);
moWCString(const moWCString& string, int length = -1);
virtual ~moWCString();

PARAMETERS

str - a standard null terminated C string
string - an moWCString object to copy
length - the maximum number of characters to copy
or -1 for all
encoding - the encoding of the input string

DESCRIPTION

These constructors initialize a string object from the given parameters. The default operator creates an empty string.

The copy operators create a new string with data equal to what was defined in the source string.

ERRORS

These functions call the Init() function member which can generate a memory error long(MO_ERROR_MEMORY).

SEE ALSO

mowc library

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

private:
Init - initialize a string object

VERSION

Version: 1.2.0

SYNOPSIS

void Init(void);

DESCRIPTION

This function is used internally to initialize a new string object. It will allocate a buffer to hold the string data.

ERRORS

When the string allocation fails, a throw long(MO_ERROR_MEMORY) is done.

SEE ALSO

Size, Set

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

IsEmpty -- returns true if a string is empty
Empty -- makes a string empty
Clear -- make the string empty and clear the memory

VERSION

Version: 1.2.0

SYNOPSIS

bool IsEmpty(void) const;
moWCString& Empty(void);
moWCString& Clear(void);

DESCRIPTION

The IsEmpty() function returns true if the tested string is empty (has a Length() equal to zero or this pointer is NULL).

Empty() empties a string.

Clear() ensures the string is empty and cleared (all the characters are zeroes). This is similar to the Empty() of strings marked as passwords.

It is much more efficient to use the same string over and over again instead of creating a new string each time you need one. To clear the string for reuse, use Empty() which is equivalent to the default constructor: moWCString(void);.

NOTES

When either of the Empty() or Clear() functions are called, it also deletes the buffer used to save the string created when calling the SavedMBData() function. The string can't be used after this call.

RETURN VALUE

IsEmpty returns a boolean value.

Empty & Clear return a reference to this string.

SEE ALSO

NoNewLine

BUGS

The buffer allocated to hold the string stays allocated as is in memory. In other words, if one used a really large string (several kilobytes or even megabytes) then all the memory remains allocated.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

CurrentMaxLength - the current maximum length of the string
Length - returns the current length in characters
MBLength - returns the length in bytes to encode in UTF-8

VERSION

Version: 1.2.0

SYNOPSIS

size_t CurrentMaxLength(void) const;
size_t Length(void) const;
size_t MBLength(void) const;

DESCRIPTION

The CurrentMaxLength() defines the number of characters which can be held by the string before its buffer will be enlarged. This can be used when a list of available strings is kept and a larger or smaller one is needed.

The Length() function returns the length in characters of the string (NOT including the nul terminator).

The MBLength() function returns the number of bytes necessary to convert the UCS-4 string in a UTF-8 string of characters (NOT including the nul terminator).

RETURN VALUE

Length() the number of characters in this string, not including the
nul terminator.

MBLength() the number of bytes necessary to save the string in UTF-8,
not including the nul terminator.

SEE ALSO

IsEmpty, Empty

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Password - mark the string as a string holding a password

VERSION

Version: 1.2.0

SYNOPSIS

void Password(void);

DESCRIPTION

The Password() function marks the givens string as a password string. Such strings need to be cleared from memory before the corresponding buffer is returned to the system.

Whenever possible, this flag is duplicated from one string to another. It is not possible to clear this flag once set.

SEE ALSO

Empty, Destructor

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Data - returns a pointer on the string data
MBData - returns a pointer to a newly allocate buffer with
the string data converted to UTF-8
SavedMBData - returns a pointer to a UTF-8 version of the string

// STL like inline functions
wc_str - like Data
c_str - like SavedMBData

VERSION

Version: 1.2.0

SYNOPSIS

const wc_t *Data(void) const;
char *MBData(char *string = 0, size_t size = 0) const;
const char *SavedMBData(void) const;

// STL like functions
const wc_t *wc_str(void) const;
const char *c_str(void) const;

PARAMETERS

string - a user defined string buffer
size - the size of the user string buffer

DESCRIPTION

The Data() function returns a pointer to the internal buffer used to hold the null terminated C string. The buffer is always garantied to be null terminated.

The pointer returned by this function will change when a non-constant function is called.

The MBData() function returns a string encoded in UTF-8. The user can specify its own string, in which case the function doesn't allocate a string. Otherwise the function will determine the necessary length and convert this string from INTERNAL UCS-4 in a newly allocated buffer.

It is the user responsability to delete the returned string when he didn't supply ones own buffer. One way to call this function is by using the stack as in the following example:

unsigned long len = string.MBLength() + 1; char str[len]; string.MBData(str, len); ... // use str until you exit this block

The SavedMBData() or c_str() function will convert the string to multibyte (UTF-8) and return a pointer to an internal buffer. This buffer will be valid until SavedMBData() is called again and the string has changed. The string returned by this function needs to be used right away and not saved in a variable.

RETURN VALUE

Data() the pointer of the internal string buffer

MBData() the user string pointer or a newly allocated
buffer; use delete [] <str> once you are done
with a newly created buffer

SavedMBData() an internally allocated string with the string
converted to UTF-8; do NOT delete this string
and don't use it after you modified the string

wc_str() same as Data()

c_str() same as SavedMBData()

ERRORS

The function will throw a memory error if a new string buffer can't be allocated.

SEE ALSO

IsEmpty

BUGS

The buffer pointer will most probably change between calls. Do not store it and reuse it. Always get the pointer using this function as required.

The buffer internally allocated by SavedMBData() is private to the moWCString and can't be deleted. Also, it can't safely be used after the string changed and SavedMBData() is called again.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Get - get a character
Get - get a string
operator [] - get and/or set a character in an moWCString
FirstChar - get the first character
LastChar - get the last character

VERSION

Version: 1.2.0

SYNOPSIS

mowc::wc_t Get(int index) const;
moWCString Get(int from, int to) const;

moWCStringCharacter operator [] (int index);
mowc::wc_t operator [] (int index) const;

mowc::wc_t FirstChar(void) const;
mowc::wc_t LastChar(void) const;

PARAMETERS

index - position of the character to be overwritten or read
from - the starting position (inclusive)
to - the ending position (inclusive)

DESCRIPTION

The array operator ([]) can be used to read and write characters in a string.

The specified indexes must be between 0 (first character) and the length of the string minus one (Length() - 1), except for the Get(from, to) function where the parameters 'from' and 'to' are being clamped. Note that 'to' can be set to -1 to specify the end of the string.

RETURN VALUE

Get() return the character at specified index

Get() return a string composed of the characters from
the specified character to the specified character
(both included); when the parameter from is larger
than the parameter to, then resulting string will
also be reversed (see the Reverse() function);
you can use really large values for the position
in which case they are clamped to the maximum
length; WARNING: negative values are viewed as
really large values (i.e. -1 means the end of
the string)

operator [] the constant version returns the character value
at the given character position

the non constant version returns an moWCStringCharacter
object which can subsequently be used to modify the
moWCString (with the operator =)

FirstChar() returns the first character, equivalent to Get(0).

LastChar() returns the last character, equivalent to
Get(Length() - 1) but usually more efficient.

ERRORS

When the index is out of bounds an moError is thrown.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

private:
Size - ensure the string can hold data for the given size

VERSION

Version: 1.2.0

SYNOPSIS

void Size(int length);

DESCRIPTION

This function is used internally to resize the string buffer.

NOTES

The coherency of the string object is always kept. It simply won't be modified if an error occurs.

ERRORS

When the string allocation fails, a throw long(MO_ERROR_MEMORY) is done.

SEE ALSO

Init, Set

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Set - copy a constant C string in the string object

VERSION

Version: 1.2.0

SYNOPSIS

void Set(const char *str, int length = -1, encoding_t encoding = MO_ENCODING_UTF8);
void Set(const mc_t *str, int length = -1, encoding_t encoding = MO_ENCODING_UCS2_INTERNAL);
void Set(const wc_t *str, int length = -1, encoding_t encoding = MO_ENCODING_UCS4_INTERNAL);
void Set(const wchar_t *str, int length = -1);
moWCString& operator = (const char *str);
moWCString& operator = (const mc_t *str);
moWCString& operator = (const wc_t *str);
moWCString& operator = (const wchar_t *str);
moWCString& operator = (const moWCString& string);

DESCRIPTION

These functions can be used to set the string buffer equal to a C null terminated string or another moWCString.

When length is set to -1, the whole source string is copied. Otherwise, a maximum of length characters are copied.

ERRORS

When the string allocation fails, a throw long(MO_ERROR_MEMORY) is done.

SEE ALSO

Init, Size

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Compare - compare two strings together

VERSION

Version: 1.2.0

SYNOPSIS

compare_t Compare(const moBase& object) const;
compare_t Compare(const moWCString& string, unsigned int pos = 0, int length = -1) const;
compare_t Compare(const char *str, unsigned int pos = 0, int length = -1) const;
compare_t CaseCompare(const char *str, unsigned int pos = 0, int length = -1) const;

bool operator == (const moBase& object) const;
bool operator != (const moBase& object) const;
bool operator < (const moBase& object) const;
bool operator <= (const moBase& object) const;
bool operator > (const moBase& object) const;
bool operator >= (const moBase& object) const;

bool operator == (const char *str) const;
bool operator != (const char *str) const;
bool operator < (const char *str) const;
bool operator <= (const char *str) const;
bool operator > (const char *str) const;
bool operator >= (const char *str) const;

PARAMETERS

object - another string or inherited string object
string - a string object
str - a null terminated C string
pos - the position at which the comparison starts in this string
length - number of characters compared

DESCRIPTION

These functions compare two strings.

The comparison of the Compare() function is case sensitive. The comparison of the CaseCompare() function is not.

SEE ALSO

BUGS

At this time, even when a length is given a null terminated string must be specified since strlen() is used on it.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

SoundEx - transform a string to it's SoundEx (phonetic representation)

VERSION

Version: 1.2.0

SYNOPSIS

moWCString SoundEx(bool full = false) const;

PARAMETERS

full - whether the entire word is converted (true)
or the first letter is kepts as is (false)

DESCRIPTION

This function computes the SoundEx of the words in a string.

The resulting string can then be compared with another to know whether two strings have the same English phonetic.

The result only returns lowercase characters.

Note that only the 26 non-accentuated latin characters are taken in account at this time.

NOTES

Source: http://physics.nist.gov/cuu/Reference/soundex.html Author: Kevin Setter, 8/27/97

SoundEx Coding Guide

1 = B,P,F,V 2 = C,S,G,J,K,Q,X,Z 3 = D,T 4 = L 5 = M,N 6 = R

The letters A,E,I,O,U,Y,H, and W are not coded.

SEE ALSO

Compare, CaseCompare

BUGS

This algorithm should be changed to support Unicode characters.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

NoNewLine - return a string without an ending new line character

VERSION

Version: 1.2.0

SYNOPSIS

moWCString NoNewLine(void) const;

DESCRIPTION

This function copies this string and return the copy without a new line as the last character.

SEE ALSO

Clip, Strip, Replace

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

ConvertFromEncoding - convert this string from given encoding

VERSION

Version: 1.2.0

SYNOPSIS

int ConvertFromEncoding(const moWCString& encoding);

DESCRIPTION

The ConvertFromEncoding() function assumes that the current moWCString was created as a stream of bytes (i.e. using mowc::MO_ENCODING_ISO8859_1 as the encoding of the string-- i.e. the string will be untouched by the constructor).

Then, once the string is fully defined, you call the convertion function to transform the stream of bytes to the corresponding Unicode encoding.

Internally, the string uses an moIConv object to do the necessary conversions.

RETURN VALUE

This function returns the new length of the string (0 or more)
or -1 when an error occurs.

A usual error is to specify the name of an unknown encoding.
See the iconv utility to know what encodings are supported
on your system (or type 'iconv -l' in your console).

SEE ALSO

Constructor, mowc::moIConv object

BUGS

This function is destructive and thus it can be applied only once to a string, until you empty the string and put a new stream of bytes to convert.

The string needs to be defined with a stream of bytes which don't represent Unicode characters. This is not very clean, but on the other hand, it gives you the flexibility of using an moWCString object to create the input buffer for the convertion function.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Clip - return a string without leading and ending spaces
Strip - apply the Clip() function on this string

VERSION

Version: 1.2.0

SYNOPSIS

moWCString Clip(unsigned long sides = WC_STRING_CLIP_BOTH) const;
void Strip(unsigned long sides = WC_STRING_CLIP_BOTH);

PARAMETERS

sides -- which of the start and end to strip

DESCRIPTION

The Clip() function copies this string and return a copy without any spaces at the beginning and at the end.

The Strip() function doesn't copy this string and remove the spaces at the beginning and at the end.

The sides parameter can be used to specify which sides you want to clip:

WC_STRING_CLIP_START only strip the start WC_STRING_CLIP_END only strip the end WC_STRING_CLIP_NEWLINE also remove '\r' and '\n' characters WC_STRING_CLIP_BOTH strip both sides

RETURN VALUE

Clip() returns a copy of the input string clipped

SEE ALSO

NoNewLine

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Delete - remove one or more characters from a string

VERSION

Version: 1.2.0

SYNOPSIS

moWCString Delete(unsigned int from, unsigned int to) const;

PARAMETERS

from - delete from this character
to - delete up to this character

DESCRIPTION

This function creates a new string which is the source string with the characters 'from' to 'to' removed.

If to is small than from, the function automatically swaps from and to before applying the operation.

If you want to apply this function to a string, then use the following syntax:

my_str = my_str.Delete(from, to);

SEE ALSO

Insert, Append, Concat

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Concat - concatenate two strings and return the result

VERSION

Version: 1.2.0

SYNOPSIS

moWCString Concat(const char *str, int length = -1) const;
moWCString Concat(const moWCString& str, unsigned int pos = 0, int length = -1) const;

PARAMETERS

str - a C null terminated string
string - an moWCString object
pos - copy from this position in the source
length - copy at most this many characters

DESCRIPTION

This function creates a new string which is the concatenation of this string and the string parameter.

When length is -1, the whole source string is copied.

SEE ALSO

Insert

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Append - append a string at the end of this string

VERSION

Version: 1.2.0

SYNOPSIS

moWCString& Append(const char *str, int length = -1, encoding_t encoding = MO_ENCODING_UTF8) const;
moWCString& Append(const wchar_t *str, int length = -1) const;
moWCString& Append(const moWCString& str, unsigned int pos = 0, int length = -1) const;

moWCString& operator += (const moWCString& string);
moWCString& operator += (const char *str);
moWCString& operator += (const mowc::mc_t *str);
moWCString& operator += (const mowc::wc_t *str);
moWCString& operator += (const wchar_t *str);
moWCString& operator += (char c);
moWCString& operator += (mowc::mc_t c);
moWCString& operator += (mowc::wc_t c);
moWCString& operator += (wchar_t c);

moWCString operator + (const moWCString& string) const;
moWCString operator + (const char *str) const;
moWCString operator + (const mowc::mc_t *str) const;
moWCString operator + (const mowc::wc_t *str) const;
moWCString operator + (const wchar_t *str) const;
friend moWCString operator + (const char *str, const moWCString& string);
friend moWCString operator + (const wchar_t *str, const moWCString& string);
moWCString operator + (char c) const;
moWCString operator + (mowc::mc_t c) const;
moWCString operator + (mowc::wc_t c) const;
moWCString operator + (wchar_t c) const;

PARAMETERS

str - a C null terminated string
string - an moWCString object
pos - copy from this position in the source
length - copy at most this many characters

DESCRIPTION

This function creates a new string which is the concatenation of this string and the string parameter.

When length is -1, the whole source string is copied.

The += operators automatically copy the whole parameter string.

SEE ALSO

Insert

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Insert - insert a string within this string

VERSION

Version: 1.2.0

SYNOPSIS

moWCString Insert(const char *str, unsigned int where = (unsigned int) -1, int length = -1, mowc::encoding_t encoding = mowc::MO_ENCODING_UTF8) const;
moWCString Insert(const mowc::mc_t *str, unsigned int where = (unsigned int) -1, int length = -1, mowc::encoding_t encoding = mowc::MO_ENCODING_UTF16_INTERNAL) const;
moWCString Insert(const mowc::wc_t *str, unsigned int where = (unsigned int) -1, int length = -1, mowc::encoding_t encoding = mowc::MO_ENCODING_UTF32_INTERNAL) const;
moWCString Insert(const wchar_t *str, unsigned int where = (unsigned int) -1, int length = -1) const;
moWCString Insert(const moWCString& string, unsigned int where = (unsigned int) -1, unsigned int pos = 0, int length = -1) const;

PARAMETERS

str - a C null terminated string
string - an moWCString object
where - the position at which the string is inserted
pos - copy from this position in the source
length - copy at most this many characters

DESCRIPTION

This function creates a new string which is this string with the string parameter inserted at the specified position (where). If 'where' is set to the size of this string (or any larger size) then the Insert() has the same effect as the Concat() function.

At most 'length' characters are inserted, unless 'length' is set to -1 in which case the whole parameter string is copied.

When an moWCString object is inserted in another, the position at which the copy starts in the source can be specified with the 'pos' parameter (with other strings, you can yourself add the position to your string).

SEE ALSO

Insert

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Integer - transform the string in an integer
Float - transform the string in a double

VERSION

Version: 1.2.0

SYNOPSIS

bool IsInteger(int base = 0) const;
long Integer(int base = 0) const;
long long LargeInteger(int base = 0) const;
double Float(void) const;
bool IsFloat(void) const;
int IsTrue(unsigned long flags) const;
int IsFalse(unsigned long flags) const;
bool IPv4(unsigned long& address, unsigned long& port,
unsigned long& mask) const;

PARAMETERS

base - the base used to test the value (0 = automatic selection)
flags - a set of flags to tell which type of true & false is supported
address - placeholder for the IP version 4 address
port - placeholder for the port number (0 if undefined)
mask - placeholder for the mask address (-1 by default)

DESCRIPTION

These function members can be used to get the value the string represents.

The Integer() and IsInteger() functions accept a base parameter which by default is 0. When base is set to 0, the function tries to determine the base in which the value was written. The rules are the same as in C/C++: if the value starts with 0x or 0X it must be an hexadecimal value; if the value starts with 0, it must be an octal value; otherwise try to read the value as a decimal value.

The Float() function expect a value float definition. It accepts a sign (+ or -) an integral part, a fractional part separated with a period (.) and a power of 10 exponent separated with the letter 'e' or 'E' and an optional sign (+ or -).

The IsInteger() and IsFloat() functions will test the string and return 'true' only if the entire string represents a valid value.

The IsTrue() and IsFalse() functions test for a valid boolean value. They can return an error (-1). The type of tests done on this string to determine the result depends on the flags passed to the functions. These flags are as follow and can be ored (|) together.

. WC_STRING_BOOLEAN_TEST_INTEGER_C

If the whole string clipped (i.e. removing the spaces) represent an integer (as per IsInteger() definition) then the IsTrue() function returns true if the represented integer is not null.

. WC_STRING_BOOLEAN_TEST_INTEGER_ADA

If the whole string clipped represent an integer, then the IsTrue() function returns true if the represented integer is 1 and false if the integer is 0. All other values generate an error.

This flag has no effect if the INTEGER_C flag was also used.

. WC_STRING_BOOLEAN_TEST_FLOAT

If the whole string clipped represent a float, then the IsTrue() function returns true if the represented float is not 0.0 and false in all other cases.

This flag has priority over the INTEGER flags since a float can be represented as a decimal integer. Note that integer will still be checked out since the value may have been written in hexadecimal (octal values are taken as floats when the FLOAT flag is set...).

. WC_STRING_BOOLEAN_TEST_NAMED

Expects the one of 'true' or 'false' spelled as is in any case ('True', 'TRUE', 'truE' are all the same). The function returns an error if the string is neither 'true' nor 'false'.

. WC_STRING_BOOLEAN_TEST_TEXT

This flag is tested last, thus if another flag has an effect, it will be ignored. Otherwise, it will return true whenever the string isn't empty and false when the string is empty.

The IPv4() function takes a string with one of the following formats:

a.b.c.d[:p][/w.x.y.z] a.b.c.d[:p][/m]

The port and mask are optional. The port is set to 0 if undefined. The mask is set to -1 if undefined.

The values represented by the letters a, b, c, d, w, x, y and z can be any value between 0 and 255. The letter p representing the port can be defined between 0 and 65535 (note that 0 will no generate an error). The letter m represents the number of bits set to zero in the mask. It can be any value from 0 to 32 inclusive. 32 means that the mask is 0 (i.e. all addresses are acceptable).

Note that the address can be preceeded and followed by spaces.

ERRORS

Integer - returns -1 if the string is not a valid value and sets errno to EINVAL

Float - retuns -1.0 if the string is not a valid float and sets errno to EINVAL

IsTrue & IsFalse - return 0 if the expression represents false, return 1 f the expression represents true and -1 if the expression is viewed as a non boolean value

IsInteger & IsFloat - can't return an error

Note: errno is always set to a value (0 or an error) and it can directly be used to check the outcome of this function call

IPv4 - returns true when the address is valid and false if an error occurs; the entire string needs to represent the address; if anything other than spaces preceeds or follows the address, then an error is generated

SEE ALSO

strtol(3), strtod(3)

BUGS

These functions don't check for range overflow. This is because many times a value is written in such a way it represents an unsigned value which wouldn't overflow if read as an unsigned value instead of a signed long. The result, thought, is the same.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

FindChar - find the first instance of a character in a string
FindRChar - find the last instance of a character in a string

VERSION

Version: 1.2.0

SYNOPSIS

moWCString FindChar(mowc::wc_t c, long position = 0, long length = -1) const;
moWCString FindRChar(mowc::wc_t c, long position = -1, long length = -1) const;

PARAMETERS

c - the character searched

DESCRIPTION

These functions search for the character c and return the rest of the string (i.e. equivalent to a Get(pos, -1) call) from that character.

Note that the character is included in the result.

If the character doesn't exist in the string, then an empty string is returned.

FindChar() will search for the first instance of the given character.

FindRChar() will search for the last instance of the given character.

Both functions accept a position where the search starts (position included in case of FindChar() and not included int case of the FindRChar() function). This is why we have a special value of -1 as the default FindRChar() position which is automatically changed to the length of the string (i.e. search the entire string).

The 'length' parameter can be used to avoid searching the entire string.

RETURN VALUE

A copy of the string from the character c or
an empty string.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

FindAny - find the first instance of any one character in a string
FindRAny - find the last instance of any one character in a string

VERSION

Version: 1.2.0

SYNOPSIS

moWCString FindAny(const moWCString& string, long position = 0, long length = -1) const;
moWCString FindRAny(const moWCString& string, long position = 0, long length = -1) const;

PARAMETERS

string - the set of characters to search
position - the position to start the seach in this string
length - the maximum number of characters to search in this string

DESCRIPTION

These functions search for any one character from the parameter 'string' in this string and return the position at which it was found. Note that the position is the position of the found character.

The length can be set to -1 in which case the search will go on up to the end (start) of the string.

If the character doesn't exist in the string, then -1 is returned.

FindAny() will search for the first instance of the given characters moving foward. Using the position, one can call the FindAny() function multiple times. The next time, call it with the last result + 1 until the function returns -1.

FindRAny() will search for the last instance of the given characters (starting at position and moving backward). In this case the position should start at the end of the string (i.e. this->Length()). The length parameter is the number of characters to test going backward from the position. If you want to call this function multiple times, use the length of the string the first time and then the result - 1 until the function returns -1.

RETURN VALUE

The position where one of the characters was found
or -1 when none were found.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

FindInString - find the first instance of a string in a string
FindInCaseString - find the first instance of a string in a string
FindInRString - find the last instance of a string in a string
FindInRCaseString - find the last instance of a string in a string
FindString - find the first instance of a string in a string
FindCaseString - find the first instance of a string in a string
FindRString - find the last instance of a string in a string
FindRCaseString - find the last instance of a string in a string

VERSION

Version: 1.2.0

SYNOPSIS

long FindInString(const moWCString& string, long position = 0, long length = -1) const;
long FindInCaseString(const moWCString& string, long position = 0, long length = -1) const;
long FindRInString(const moWCString& string, long position = 0, long length = -1) const;
long FindRInCaseString(const moWCString& string, long position = 0, long length = -1) const;
moWCString FindString(const moWCString& string, long position = 0, long length = -1) const;
moWCString FindCaseString(const moWCString& string, long position = 0, long length = -1) const;
moWCString FindRString(const moWCString& string, long position = 0, long length = -1) const;
moWCString FindRCaseString(const moWCString& string, long position = 0, long length = -1) const;

PARAMETERS

string - the string searched
position - the position to start the search
length - the maximum number of characters to be compared

DESCRIPTION

The Find...() functions search for 'string' in 'this' string and return either a string or the position at which 'string' was found.

The functions including [In] will return a position between 0 and 'this->Length() - 1' when 'string' is found and -1 when the string isn't found.

The other functions return a string composed of 'this' string starting at the found 'string'. When 'string' can't be found, an empty string is returned.

The [Case] in the name of these functions means the CaseCompare() is used instead of the Compare(). In other words, these functions are case insensitive.

The [R] in the name means "reverse". In other words, the search starts at the end of the word and moves toward the start.

A 'position' can be specified in which case the search starts at that position. A positive position is taken from the start to the end of the string. A negative position is taken from the end of the string to the start. -1 is taken as the position right after the last character.

A 'length' can be specified in which case at most that many characters from 'this' string will be tested against the input 'string'.

NOTES

The input 'string' is always checked in full within 'this' string. If 'this' string is smaller the user specified 'string' then these functions will always fail to find it and return -1 or the empty string.

RETURN VALUE

Find[R][Case]String
A copy of the string from 'string' or an empty string.

Find[R]In[Case]String
The position at which the string was found
or -1 when not found

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Reverse - reverse the characters in a string

VERSION

Version: 1.2.0

SYNOPSIS

moWCString& Reverse(void);

DESCRIPTION

This function reverse all the characters in a string. The first character becomes the last and the last becomes the first. The second character becomes the one before the last, and vice versa. And so on with each character.

Note that this function doesn't make a copy of the string.

RETURN VALUE

The reversed string.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Glob - compare a string against a shell pattern

VERSION

Version: 1.2.0

SYNOPSIS

bool Glob(const moWCString& pattern) const;

PARAMETERS

pattern - a shell pattern (such as *.c)

DESCRIPTION

This function compares this string with the given pattern.

The pattern must be a shell compatible pattern and include the following elements:

* - an asterisk, meaning one or more of any character ? - a question mark, meaing any one character [...] - a set of characters between square brackets meaning that any (or none when the opening square bracket is followed by a ^ or ! character) of the specified characters are accepted

RETURN VALUE

true when the pattern matched

SEE ALSO

Match

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Match - does a regular expression pattern matching

VERSION

Version: 1.2.0

SYNOPSIS

bool Match(const moWCString& pattern) const;

PARAMETERS

pattern - a regular expression pattern (such as "^a.*(b|c)&x24;")

DESCRIPTION

This function uses the regex interface to test whether this string matches the user specified pattern. You should use the ^ and &x24; if you want to make sure that the entire string is a match.

Please, try 'man 7 regex' to have more info about the pattern.

The whole string & pattern must match. The GNU options are accepted. The . won't accept the NUL and new line characters. The class characters are understood. The pipe (|) is used to seperate two possible alternatives. The parenthesis are used as use to group expressions.

RETURN VALUE

true when the pattern matched

SEE ALSO

Glob, moRegExpr

BUGS

The function always returns false when an invalid pattern is specified.

At this time the wide characters are not tested directly. Instead, the strings are changed to multi-characters which very certainly are not compatible with the regcomp/regexec functions.

'This' string and the pattern must both be small enough to fit in static strings of 256 characters once converted to multi-byte characters.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Replace - replace some strings in a srting

VERSION

Version: 1.2.0

SYNOPSIS

moWCString Replace(const moWCString& what) const;

PARAMETERS

what - a list of strings to replace and how

DESCRIPTION

This function searches for the strings specified in what and replaces them with what the user specified.

The what string syntax is as follow:

<string>=<replace>';'

If replace needs to include a ';' then it can be escaped with a backslash.

At this time the source <string> is case sensitive and there is no way to make it otherwise.

This function can be used to replace backslashed characters with their corresponding ASCII equivalents:

\\n=\n;\\r=\r;\\\\=\\...

Or to the contrary, used to add backslashes:

\n=\\\\n;\r=\\\\r;\\=\\\\\\\\...

Because a backslash is escaped and also require to be escaped by a backslash in a C string, you need to use many as the previous example shows if the replacements involve backslashes. Note that the following C string:

'=\\'

has no effect in Replace(). However, the following:

'=\\\\'

will add a backslash in front of any single quote (').

Note that the string is parsed only once. One will have to call the function several times until the result equals the input if it is necessary to apply the patterns several times.

NOTES

The source strings (in 'what') used to match the input string will support regular expressions later. Similarly, the result strings could include \(1\). This isn't available yet.

RETURN VALUE

a copy of the source string with the given strings
replaced

SEE ALSO

FromBackslash, Strip, Clip, NoNewLine

BUGS

Terminate a string with a backslash will include that backslash in the result. This is a side effect which shouldn't cause many trouble. One can suppress the backslash or add the missing character.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

FromBackslash - replace backslashed characters

VERSION

Version: 1.2.0

SYNOPSIS

moWCString FromBackslash(void) const;

DESCRIPTION

The FromBackslash() function creates a duplicate of the input string and removes the backslashed characters (i.e. \r becomes the character 0x0D).

The understood backslash characters are all described in the mowc::backslash_char() function.

The characters written in UNICODE notation are also converted automatically. It accepts any digit written in this way:

"U+####"

Each digit is part of an hexadecimal value. One to eight digits will be accepted (though the standard is to read 4 to 8). There is no restriction to the accepted characters except that it has to be in the range 0 to 0x7FFFFFFF.

RETURN VALUE

a copy of the source string without backslashed characters

SEE ALSO

Replace, mowc::backslash_char()

BUGS

Terminate a string with a backslash will include that backslash in the result. This is a side effect which shouldn't cause many trouble. One can suppress the backslash or add the missing character.

All the entries which generate '\0' are actually not used (i.e. these characters are skipped).

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

FilenameHasExtension - check whether there is a filename extension
FilenameExtension - search for a filename extension

VERSION

Version: 1.2.0

SYNOPSIS

bool FilenameHasExtension(void) const;
moWCString FilenameExtension(void) const;

DESCRIPTION

These functions search for a filename extension. If none is found FilenameHasExtension() returns false and FilenameExtension() returns an empty string. Otherwise they respectively return true or a copy of the extension including the period.

A name which starts with a period is considered as being a hidden filename and therefore is never returned as an extension of a filename.

NOTES

an empty extension will be returned as a lone period (when a filename ends with a period)

RETURN VALUE

FilenameHasExtension:
true if the filename has an extension

FilenameExtension:
a copy of the extension including the period or an empty string

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

FilenameBasename - search for a basename

VERSION

Version: 1.2.0

SYNOPSIS

moWCString FilenameBasename(const moWCString& extension = "") const;

PARAMETERS

extension - the extension to be removed
".*" to remove any extension
or "" to not remove any extension

DESCRIPTION

This function removes all the directories and eventually the specified extension.

The extension must include the period if it is to be removed (i.e. ".c++")

The special ".*" extension can be used to remove any extension.

NOTES

if the extension doesn't match the specified extension then nothing is removed from the end of the filename.

RETURN VALUE

a copy of the filename without the directories and
eventually without extension

BUGS

At this time, the extensions are tested in a case sensitive manner. On a system with no case sensitivity, one should call Uppercase() or Lowercase() before this function.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

FilenameDirname - search for the dirname

VERSION

Version: 1.2.0

SYNOPSIS

moWCString FilenameDirname(void) const;

DESCRIPTION

This function removes the basename from a filename. In effect leaving only the path to the directory containing the file (assuming it exists).

No trailing "/" is kept in the resulting pathname except for the root directory (ie. "/" remains "/").

Note that this function can be called multiple times in order to remove some trailing directory names from a path.

When there is no directory path, then "." is returned.

RETURN VALUE

a copy of the filename with only the directory names
or "." when no name is defined.

SEE ALSO

FilenameBasename, FilenameChild, FilenameClean

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

FilenameChild - search for a basename

VERSION

Version: 1.2.0

SYNOPSIS

moWCString FilenameChild(const moWCString& child) const;

DESCRIPTION

This function appends a filename to a path making sure there is a valid separator between both.

NOTES

If this string (the path) is empty, then child is returned as is.

If the child filename is empty, then the function will at least ensure that the path ends with a slash (unless the path is empty in which case an empty string is returned).

If the child starts with a slash, it is not duplicated in the resulting string.

RETURN VALUE

The concatenation of this string (the path) and the child
filename.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

FilenameExpand - braces expension of filename

VERSION

Version: 1.2.0

SYNOPSIS

bool FilenameExpand(moListOfWCStrings& list, bool skip_variables = false) const;

PARAMETERS

list - a user list where the filenames will be saved
skip_variables - whether &x24;{...} should be skipped (not
taken as a brace expension)

DESCRIPTION

This function parses a string and expends it in a list of strings. The new names are appended to the user supplied list. If other names where already available, they won't first be removed.

The expension rules are the same as for the brace expension of bash. A brace expension can include an optional prefix, a list of brace expension and an optional postfix. Note that braces can be nested and multiple can be included in the same string. Also, path separators are totally ignored and thus the expension can be used to expend names including such separators.

Like for the separators, pattern characters (*, ?, [ and ]) are ignored when the brace expension is applied.

Braces within the input string can be taken as regular characters when preceeded by a backslash. Backslashes are preserved in the resulting list of strings.

For example:

abc{d,e,f}ghi

expands as the three names:

abcdghi abceghi abcfghi

And you can write complicated expressions such as:

/usr/{etc/lib*{/exec*,c/exec*},lib/{module,plugins}/{exec*.so.*}}

The order expected when reading the braces is kept.

NOTES

Thought this should be an error, if there are missing closing braces (}), the function works as if the end of string was the missing closing braces. This can be detected testing the returned value (which is false when there are missing braces).

This function allocates a new string for each entry in the user list. Emptying the list will release each string and thus you won't have any memory leak.

RETURN VALUE

If there was one closing brace for each opening brace, then
the function returns true, otherwise it returns false.

The function doesn't test for valid variables ("&x24;{...}").
The start of the variable can be skipped (when skip_variable
is set to true), but the closing brace won't be searched.
If there are braces within variables, they will be expended
as expected. You could first expand variables, then braces
to avoid this side effect.

BUGS

At this time, the resulting list may include duplicates. Especially if the braces include duplicates as in:

a{b,b,b}c -> abc abc abc

This is actually a feature, but you have to keep it in mind!

The input list can't be sorted because of the way this function rely on the moList::Append() putting new names at the end of the list.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

FilenameClean - remove useless entries in a filename

VERSION

Version: 1.2.0

SYNOPSIS

moWCString FilenameClean(void) const;

DESCRIPTION

This function looks within a filename and remove things such as "//", "/./" and "/../" as possible without changing the final path making it canonical.

It will remove a starting "./" or ending "/.".

Note that a path such as "test/.." is transformed into the path "./". Also, the path "/.." is equivalent to "/".

When the input is an empty string, the path "." is returned. If you need to know if the input string is empty, use the IsEmpty() function on the input.

NOTES

The resulting path may or may not end with a slash. There is currently no rule about that. (i.e in some cases you could get "." and others "./" as an answer)

RETURN VALUE

a canonical version of the path and filename

SEE ALSO

FilenameBasename, FilenameChild

BUGS

By cleaning a path before testing whether the file pointing to exists will eventually result in a valid path even thought the original path wasn't valid. Thus, a path such "/I-don't-exist/.." is transformed to "/" which is valid.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Uppercase - return a string with only uppercase characters
Lowercase - return a string with only lowercase characters
Switchcase - return a string with inverted case characters
Capitalize - return a string with only the first letter after each '.' capitalized
CapitalizeWords - return a string with each word capitalized

VERSION

Version: 1.2.0

SYNOPSIS

moWCString Uppercase(void) const;
moWCString Lowercase(void) const;
moWCString Switchcase(void) const;
moWCString Capitalize(void) const;
moWCString CapitalizeWords(void) const;

DESCRIPTION

These functions copy this string and replace all the lower or upper case letters in the appropriate case.

The Switchcase() function will read each character and switch lower case characters in upper case and vice versa.

SEE ALSO

CaseCompare

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

Format - format a string with a standard C format string

VERSION

Version: 1.2.0

SYNOPSIS

static moWCString VFormat(const char *format, mowc::encoding_t encoding, va_list args);
static moWCString VFormat(const mowc::mc_t *format, mowc::encoding_t encoding, va_list args);
static moWCString VFormat(const mowc::wc_t *format, mowc::encoding_t encoding, va_list args);
static moWCString VFormat(const wchar_t *format, va_list args);
static moWCString Format(const char *format, mowc::encoding_t encoding, ...);
static moWCString Format(const mowc::mc_t *format, mowc::encoding_t encoding, ...);
static moWCString Format(const mowc::wc_t *format, mowc::encoding_t encoding, ...);
static moWCString Format(const wchar_t *format, ...);

DESCRIPTION

The format function can be used to create a string with the result of a formatted set of arguments.

The VFormat() accepts a variable list of arguments as obtained by va_start(args, <last parameter>).

It doesn't use the standard wprintf() function of the C library because otherwise it would transform the different characters depending on environment defined settings. Instead, the whole function format was reprogrammed.

Please, though it doesn't use the wprintf(), you certainly want to see this function documentation for more information about the default formats supported by the function.

The following is a list of the flags supported by this implementation:

The format of a conversion is as follow:

'%' [<position>'&x24;'] [<flags>] [<width>] ['.'<precision>] [<length>] <conversion>

There is one special case: "%%" will be used to insert a percent in the output.

Position:

Defines the position of the argument in the list of parameters. This is useful to write the parameters in run-time varying order.

The positions start at 1 from the first parameter after the format.

Flags:

# introducer; when used as in %#o, prepend a "0"; when used as in %#x or %#X, include a "0x" or "0X" respectively; when used with one of the floating conversions, ensures that a decimal point always appears.

' ' (space) writes a space wherever a signed and positive value is written

+ writes a plus for positive and signed values (unsigned value conversions ignore this flag).

0 zero pad on the left up to either precision or width digits

- left justify (default to right justification).

` write out thousands in decimal conversions.

Width:

The width is a decimal value which can be defined as a direct value an asterisk or an asterisk followed by a position (<position>'&x24;'). When an asterisk is specified, the width is taken from the list of parameters as an 'int'.

Precision:

The precision is a decimal value which can be defined as a direct value, an asterisk or an asterisk followed by a position (<position>'&x24;'). When an asterisk is specified, the precision is taken from the list of parameters as an 'int'.

Length:

hh A character.

h A short.

<none> An integer.

l A long.

ll A long long.

L A long double.

q A long long (like ll).

j An intmax_t.

z or Z A size_t (the 'Z' is deprecated and should never be used).

t A ptrdiff_t.

Conversions:

D,d,i Writes out a decimal number. 'D' is deprecated. It can be used to write out a long value (i.e. use %ld instead). All the sizes, except 'L' can be used with this conversion. '#' has no effect.

U,u,O,o,X,x Writes out an unsigned number in decimal (u,U), octal (o,O) or hexadecimal (x,X) notation. The U and O are deprecated. It can be used to write out a long value (i.e. use %lu and %lo instead). All the sizes, except the 'L' can be used with this conversion. '#' has no effect on the u and U conversions. With the o and O is ensures the value always starts with a zero. With the x and X is introduces the value with 0x and 0X respectively.

e,E,f,F,g,G,a,A Writes out a floating point number. The 'e' and 'E' can be used to write number in scientific notation (always including an exponent). The 'f' can be used to always avoid an exponent (watch out for really large or small values!). The 'F' is deprecated and works like 'f'. The 'g' and 'G' will select between 'f' and 'e' or 'E' depending on the value to be written. When the value can be written in a reasonable width using 'f', then it is used. The 'a' and 'A' print out the value in hexadecimal floating point. In all cases, the capital version makes the exponent letter be written in capital. The only two length accepted are <none> and 'L'.

c,C Writes out one character. The C notation is deprecated. It can be used to output of a long character (use %lc instead). The lengths accepted are 'hh' (char), 'h' (mc_t), <none> or 'll' (wc_t) and 'l' (wchar_t).

s,S Writes out a string of characters. The S notation is deprecated. It can be used to output of a string of long characters (use %ls instead). The lengths accepted are 'hh' (char), 'h' (mc_t), <none> or 'll' (wc_t) and 'l' (wchar_t).

p,P Writes out a pointer. The format used is "%#x" with the adequate size. The capital 'P' can be used to have the hexadecimal letters (and the 0X) in uppercase. This conversion doesn't accept a length.

n Used to query the number of characters written at the point where this "conversion" appears. By default, the type expected for this parameter is an 'int'. You can use the length argument to change the type to any length except 'L'.

m Writes out a string as returned by strerror(<arg>); where <arg> is an integer. The string will automatically be transformed to unicode as required.

SEE ALSO

FromBackslash

BUGS

A common mistake is to type something like this:

moWCString string;

string.VFormat(...);

in which case the result is lost. One needs to use the function as a static function instead:

moWCString string;

string = moWCString::VFormat(...);

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCStringCharacter

NAME

Constructor - initialize an moWCStringCharacter object
operator = - set a character in an moWCString
operator char - get a character in an moWCString

VERSION

Version: 1.2.0

SYNOPSIS

moWCStringCharacter(moWCString *string, int index);
moWCStringCharacter(const moWCStringCharacter& string_character);
moWCStringCharacter& operator = (wc_t c);
operator char (void) const;

PARAMETERS

string - the moWCString pointer referenced
index - the position of the character referenced
string_character - the source moWCStringCharacter to be copied
c - the new character value

DESCRIPTION

This class is used whenever the array operator ([]) is used on an moWCString object. It enables anyone to read or write a string character at the specified position.

Note that an invalid index will still throw an error.

RETURN VALUE

'operator =' sets the character at the position index.
'operator char' returns the character at the position index.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moWCString

NAME

operator << - prints a string in a specified output

VERSION

Version: 1.2.0

SYNOPSIS

std::ostream& operator << (std::ostream& output_stream, const moWCString& string);

PARAMETERS

output_stream - the stream where the string will be written
string - the string to write in the output

DESCRIPTION

This function will be used to print out an moWCString in a standard C++ stream (such as cerr or cout).

RETURN VALUE

the output_stream reference

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

Links:
molib
the sandbox