/MEng/String

ClassPath:	MEng.String
Parent ClassPath:	MEng.Formattable
Copyable:	Yes
Final:	Yes

MEng.String represents a set of characters. Note that the CML language is Unicode based, so a character is a Unicode code point, not ASCII or Latin1 or other code page you might be used to using. The low 127 code points of Unicode are basically the same as ASCII, but it represents a far larger set of characters than ASCII.

CML uses the UTF-16 format for Unicode characters internally under Windows, and doesn't really do anything special to deal with surrogate pairs, so it might not do the right thing if you pull in any text that causes surrogate pairs to be created. For instance, the length of the string is the number of UTF-16 items in the string, so if a single character is represented by a surrogate pair, the length will be one more than the actual characters represented in the string. This is unlikely to be of much concern in general, but it is something to keep in mind.

To get text into a string from an external format, or vice versa, use the TextXCoder class, which transcodes text to and from various external encodings.

Note that all all indexes in CML are zero based, so the first character of the string is at index (or offset if you prefer to look at it like that) zero, and the second character is at index one, and so forth.

Information about Unicode is available at: http://www.unicode.org/.

Nested Classes:

Enum=StringErrors
    BadIndex    : "The index %(1) is invalid for this string";
    BadRange    : "The index and count %(1)/%(2) is invalid for ...
    CantConvert : "Can't convert '%(1)' to a %(2) binary form";
    NotDecDigit : "%(1) is not a decimal digit";
EndEnum;
This enumerated type defines the string specific exceptions that this class might throw. Note though that other exceptions might be thrown from other classes used by this class or passed in as exceptions.

Literals:

Card4 kLeading;
Card4 kTrailing;
Card4 kMiddle;
Card4 kTotal;
Card4 kLeadTrail;
Card4 kFull;
Card4 kComplete;

Constructors:

Constructor();
Constructor([In] MEng.String InitVal);
There is one default constructor, which will set the initial value to empty string, and a constructor that takes an initial value to copy.

Final, Const Methods:

Add([In] MEng.String ToAppend) Returns MEng.String;
operator+
(
    [In] MEng.String Src1
    , [In] MEng.String Src2
) Returns MEng.String;
Adds the two objects and returns the result, leaving both objects unaffected. They do the same thing, and are only syntactically different. For this class, 'addition' means concatenating the two strings together, so the result will be the two strings put together.
CvtDecDigitAt([In] MEng.Card4 AtInd) Returns MEng.Card4;
Gets the character at the AtInd index in this string, which must be a decimal digit (i.e. 0..9) and converts it to it's binary representation and returns that binary version as a Card4 value. So '0' becomes 0, '1', becomes 1, and so forth.
If the index is bad, a BadIndex exception will be thrown. If the character at the given index is not a decimal digit, a NotDecDigit exception will be thrown.
Equal([In] MEng.String ToComp) Returns MEng.Boolean;
operator=([In] MEng.String Src1, [In] MEng.String Src2) Returns MEng.Boolean;
Compares the two objects and returns True if they are equal and False if they are unequal. Neither object is affected. They do the same thing, are only only syntactically different.
ExtractCard4([In] MEng.Card4 Ind, [In] MEng.Card4 Count) Returns MEng.Card4;
ExtractCard4R
(
    [In] MEng.Card4 Index
    , [In] MEng.Card4 Count
    , [In] Radices Radix
) Returns MEng.Card4;
ExtractCard8([In] MEng.Card4 Ind, [In] MEng.Card4 Count) Returns MEng.Card8;
ExtractCard8R
(
    [In] MEng.Card4 Index
    , [In] MEng.Card4 Count
    , [In] Radices Radix
) Returns MEng.Card8;
ExtractFloat8([In] MEng.Card4 Ind, [In] MEng.Card4 Count) Returns MEng.Float8;
ExtractInt4([In] MEng.Card4 Ind, [In] MEng.Card4 Count) Returns MEng.Int4;
ExtractInt4R
(
    [In] MEng.Card4 Index
    , [In] MEng.Card4 Count
    , [In] Radices Radix
) Returns MEng.Int4;
These are convenience methods that are basically a combination of ExtractSubStr() and then a call to one of the ToXXX() methods to convert the extracted substring to a binary value of the indicated type. So all of the documented parameters and exceptions from those other methods apply here, about the validity of the range of characters and whether they can successfully be converted.
For the Int/Card conversions, there is one set that automatically senses the radix of the value based on what it sees, and another set that allow you to force a particular radix. In either case, if it cannot be converted to a number, a CantConvert error will be thrown.
ExtractSubStr
(
    [In] MEng.Card4 StartInd
    , [In] MEng.Card4 Count
    , [Out] MEng.String ToFill
);
Extracts a substring from this string into the ToFill parameter, starting at StartInd within this string and including Count characters. If the index is bad, a BadIndex exception will be thrown. If the range is bad, it will be a BadRange exception.
If you want to extract the rest of the string from StartInd, you can pass in Card4.kMaxValue as the count, which is not interpreted as an actual count but an indication to just take everything from StartInd forward.
ExtractUpTo
(
    [In]   MEng.Card4 StartInd
    , [In] MEng.Char TermCh
    , [Out] MEng.String ToFill
) Returns Card4;
Extracts a substring from this string into the ToFill parameter, starting at StartInd within this string and going until either the TermCh character is seen, or the end of the string is hit. The TermCh character itself is not extracted to the target string. The return indicates the index after the term character. So it will either be where you want to start looking for the next value, or the length of this string if the end is hit.
If the index is bad, a BadIndex exception will be thrown. If the range is bad, it will be a BadRange exception.
FindFirstChar
(
    [In]    MEng.Char ToFind
    , [Out] MEng.Card4 FoundAt
    , [In]  MEng.Boolean CaseSensitive
) Returns MEng.Boolean;

FindLastChar
(
    [In] MEng.Char ToFind
    , [Out] MEng.Card4 FoundAt
    , [In] MEng.Boolean CaseSensitive
) Returns MEng.Boolean;

FindNextChar
(
    [In] MEng.Char ToFind
    , [InOut] MEng.Card4 FoundAt
    , [In] MEng.Boolean CaseSensitive
) Returns MEng.Boolean;
Finds the first/subsequent or last instances of the character ToFind in this string, if present. If found, the return is True and the FoundAt parameter is updated with the index where the character was found. Else, the return is False and the FoundAt parameter is unchanged. For FindNextChar, FoundAt is an input parameter and should be set to the position of the last find, i.e. just keep passing in the location of the previously located character.
The CaseSensitive parameter, as you might imagine, controls whether the search is case sensitive or not.
If the incoming FoundAt to FindNextChar is beyond the end of the string, a BadIndex exception will be found. Since you always pass back in the index of the last find, and that can never be past the last character, FoundAt can never be beyond that last character.
FindSubStr
(
    [In] 	MEng.String  ToFind
    , [OUT] MEng.Card4   FoundAt
    , [In] MEng.Boolean CaseSensitive
) Returns MEng.Boolean;
Finds the first instance of the substring ToFind in this string. If found, the return is True and FoundAt is set to the index of the substring found. If not found then the return is False and FoundAt is unchanged. The CaseSensitive parameter, as you might imagine, controls whether the search is case sensitive or not.
FindTokenList(Out] MEng.String ToFill) Returns MEng.Boolean;
This method will search the string and return the characters for all of the replacement tokens that are in the string. This can be an efficient thing to do if you could have a large number of tokens that could be present, and don't want to have to get together any information for any tokens that aren't there. So you can search the string first, get the info together, and then go through and replace them all. The return indicates whether any tokens were found.
GetAt([In] MEng.Card4 At) Returns MEng.Char;
Returns the character at the given index. The index must be less than the length of the string, since the last legal character is always length-1, or the BadIndex exception will be thrown.
GetLast() Returns MEng.Char;
Returns the last character of the string. If the string is empty, it will return a null character, i.e. a character with an ordinal of zero.
GetLength() Returns MEng.Card4;
Returns the number of characters in the string. If zero, then the string is empty.
GetPath([Out] String ToFill) Return MEng.Boolean;
GetExt([Out] String ToFill) Return MEng.Boolean;
GetNameExt([Out] String ToFill) Return MEng.Boolean;
These are the same as their 'Extract' versions below, except that they do not remove the value from the path, they just get a copy of those values out, leaving this string unchanged.
GtThan([In] MEng.String ToComp) Returns MEng.Boolean;
operator>([In] MEng.String Src1, [In] MEng.String Src2) Returns MEng.Boolean;
GtThanEq([In] MEng.String ToComp) Returns MEng.Boolean;
operator>=([In] MEng.String Src1, [In] MEng.String Src2) Returns MEng.Boolean;
Compares the two objects and returns True if the left hand object is greater (or greater than or equal), else it returns False. Neither object is affected. The two sets do the same thing, and are just syntactically different. The collation order is the standard Unicode order.
LsThan([In] MEng.String ToComp) Returns MEng.Boolean;
operator<([In] MEng.String Src1, [In] MEng.String Src2) Returns MEng.Boolean;
LsThanEq([In] MEng.String ToComp) Returns MEng.Boolean;
operator<=([In] MEng.String Src1, [In] MEng.String Src2) Returns MEng.Boolean;
Compares the two objects and returns True if the left hand object is less than (or less than or equal) the right hand object, else it returns False. Neither object is affected. The two sets do the same thing, and are just syntactically different. The collation order is the standard Unicode order.
HasExt() Returns MEng.Boolean;
HasName() Returns MEng.Boolean;
HasPath() Returns MEng.Boolean;
Assumes this string contains a file type path, and indicates whether it has a file type extension, a name part, or a path part or not. You can alo get or extract the parts of the path using the GetXXX() methods above or ExtractXXX() methods below.
IsEmpty() Returns MEng.Boolean;
If the string is empty, this method returns True. Else, it returns False. This is basically the same as checking whether the length is zero or not, but is more self documenting and probably a little more more efficient.
ParseVersion() Returns MEng.Card8;
Parses this string as a three part version number, e.g. 1.2.3, and returns the values embedded in a Card8 value, where the major version is in the high 16 bits, the minor version is in the third 16 bits, and the revision number is in the low 32 bits. This makes it easy to do comparisons of versions as numbers for greater or less than.
RemoveTrailingSep() MEng.Boolean;
Assumes this string contains a file type path. If it ends with a separator, that separator will be removed. The return indicates whether it removed anything or not.
StartsWith
(
    [In] MEng.String PrefixToCheck
    , [In] MEng.Boolean CaseSensitive
) Returns MEng.Boolean;
Checks to see if this string starts with the passed prefix string. Returns True if so, else False. You can choose to make the check case sensitive or insensitive.
SumChars
(
    [In] MEng.Card4 StartOfs
    , [In] MEng.Card4 Count
) Returns MEng.Card4;
This method will sum the values of Count characters, starting at StartOfs. The sum is of the Unicode characters that make up the internal representation of characters in CML. The accumulator is allowed to overflow but it's not very likely since it is a Card4 value.
ToCard4() Returns MEng.Card4;
ToCard4R(Radices Radix) Returns MEng.Card4;
ToCard8() Returns MEng.Card8;
ToCard8R(Radices Radix) Returns MEng.Card8;
ToInt4() Returns MEng.Int4;
ToInt4R(BaseInfo.Radices Radix) Returns MEng.Int4;
ToFloat8() Returns MEng.Float8;
Tries to convert this string's value to one of the fundamental binary values. The entire string contents is used in these cases, so there cannot be any extra content that isn't part of the value to be converted.
For the Int/Card conversions, there is one set that automation senses the radix of the value based on what it sees, and another set that allow you to force a particular radix. In either case, if it cannot be converted to a number, a CantConvert error will be thrown.

Final, Non-Const Methods:

AddLevel([In] MEng.String ToAdd);
Will append the passed string to this string, after adding a path divider (if it is needed, i.e. there's not one either at the end of this string or at the beginning of the one passed.)
Append([In] MEng.String ToAppend);
Appends the passed string onto the end of this object's string value.
AppendCard1([In] MEng.Card1 ToAppend, [In] Radices Radix);
AppendCard2([In] MEng.Card2 ToAppend, [In] Radices Radix);
AppendCard4([In] MEng.Card4 ToAppend, [In] Radices Radix);
AppendFloat4([In] MEng.Float4 ToAppend, [In] MEng.Card4 DecDigits);
AppendFloat8([In] MEng.Float8 ToAppend, [In] MEng.Card4 DecDigits);
AppendInt1([In] MEng.Int1 ToAppend, [In] Radices Radix);
AppendInt2([In] MEng.Int2 ToAppend, [In] Radices Radix);
AppendInt4([In] MEng.Int4 ToAppend, [In] Radices Radix);
These are specialized formatted append methods for the intrinsic numeric types. You can pass objects of all of these types to AppendFmt() below, because it can accept anything derived from the Formattable class. But these are more efficient if you know what type you are dealing with, and they allow you to control the radix (for Int/Card types) or the number of decimal digits to append (for floating point types), which isn't available via the generic method below.
AppendChar([In] MEng.Char ToAppend);
Appends the passed character onto the end of this object's string value.
AppendEnum([In] MEng.Enum ToAppend, [In] MEng.Boolean UseName);
Appends either the name or text of the current value of the passed enumerated value to this string. All enumerated classes derive from MEng.Enum, so this method can take any enumerated type. UseName indicates whether the name of the current enumerated value, or it's text, should be appended.
AppendFmt([In] MEng.Formattable ToAppend);
This method will take objects of any class derived from the formattable class and will format it to text format and then append it to the end of this string object. This is a very convenient class, though it could be a little piggy. And, since you don't have control over the formatting settings, you will get a default format.
CapAt([In] MEng.Card4 CapAt);
Terminates the string at the indicated index. This allows you to throw away trailing characters in the string that you no longer want. The CapAt index must be less than the length of the string, or the BadIndex exception will be thrown. The last index position of a string is always length-1 unless the string is empty already, in which case this method is illegal because CapAt cannot ever be a legal value.
Note that, since indexes are zero based, capping at at index N creates a string N characters long, so it can be thought of as a length as well.
Clear();
Empties the string out, leaving it with zero length.
Cut([In] MEng.Card4 StartInd, [In] MEng.Card4 Count);
Cuts a substring out of this string, starting at StartInd within this string and including Count characters. If the index is bad, a BadIndex exception will be thrown. If the range is bad, it will be a BadRange exception.
If you want to cut the rest of the string from StartInd, you can pass in Card4.kMaxValue as the count, which is not interpreted as an actual count but an indication to just cut everything from StartInd forward. You could also use CapAt() to achieve this functionality.
DelLast();
Deletes the last character of the string, i.e. it makes the string one character shorter than it currently is. If the string is already empty, no action will be taken.
ExtractPath([Out] String ToFill) Return MEng.Boolean;
ExtractExt([Out] String ToFill) Return MEng.Boolean;
ExtractNameExt([Out] String ToFill) Return MEng.Boolean;
Assumes that this string contains a file system type path, and removes one of more part of the path and returns the removed part in ToFill. If the path does not have the indicated part, then it does nothing. The return value indicates whether it found and removed the requested part or not. For the extension extraction, it does not return the period; and, note that, if the path ends in a period, then it could both return True and an empty ToFill. The path part is that part between any volume info (the \\UNCName or X: parts) and any name and extension.
FmtToField
(
    [In] MEng.Formattable ToFmt
    , [In] MEng.Card4 FldWidth
    , [In] BaseInfo.HorzJustify Justification
    , [In] MEng.Char FillChar
);
This method will format the passed formattable object to text. Then it will set this string to FldWidth chars of the FillChar character, and then put the formatted value into that resulting field of characters, justified in the indicated way. So, for instance, if the parameters were "A String", 12, HorzJustify_Right, '^', this string would end up wit the value "^^^^A String".
InsertCharAt(In] MEng.Char ToInsert, [In] MEng.Card4 InsertAt);
InsertStrAt([In] MEng.String ToInsert, In] MEng.Card4 InsertAt);
Inserts a character or string into this string at the indicated index. So it will go in before the character at the indicated index. If the InsertAt point is not legal for this string, a BadIndex exception will be thrown.
PlusEq([In] MEng.String SrcVal);
operator+=([In] MEng.String SrcVal);
Adds the passed object to this object, updating this object with the resulting value. They do the same thing, and are only syntactically different. For this class, 'addition' means appending, so this will append the passed string to this string. This has the same effect as Append does, so it is just a matter of style as to which you use.
PutAt([In] MEng.Card4 At, [In] MEng.Char ToPut);
Puts the passed char, ToPut, into the string at the indicated index. This is not an insert, it is an overwrite, so there must already be a character at the given index, and it will be replaced. So At must always be less than the length, or the BadIndex exception will be thrown.
Prepend([In] MEng.String ToPrepend);
Prepends the passed string onto the beginning of this object's string value.
PrependChar([In] MEng.Char ToPrepend);
Prepends the passed character onto the beginning of this object's string value.
ReplaceChar([In] MEng.Char ToReplace, [In] MEng.Char ReplaceWith);
Replaces all instances of ToReplace with Replace with.
ReplaceToken
(
    [In] MEng.Char ToReplace
    , [In] MEng.Formattable ReplaceData
);
This method will find the token with the given character and will replace it with the formatted version of the passed formattable object. So any object derived from MEng.Formattable can be passed, and it will be formatted to text and that textual representation will be used to replace the token. Tokens are in the following form:
%(C), %(C,W), %(C,W,F)
So there are three forms, where C is the character that identifies the token, W is the width of the desired field, and F is the fill character. If the width or fill is not provided, they default to zero and space. If the non-zero width is negative it means left justify, else right justify. For example:
Source String Replacement Text Results
"%(A)" "123" "123"
"%(A,5)" "123" " 123"
"%(A,-5) "123" "123 "
"%(A,5,$)" "123" "$$123"
If the token indicated does not exist, then no action is taken.
RemoveLevel() Returns MEng.Boolean;
Assumes this string contains a file type path. If so, it will try to remove one level of the path (i.e. if there's a name.ext at the end, it will remove that, if there is a trailing directory level part, it will remove that.) If it's down to the volume indentifier, then nothing will happen. The return indicates if it removed something.
Split([Out] String SecHalf, [In] Char SplitCh, [In] Boolean CaseSensitive) Returns MEng.Boolean;
Splits this string into two parts, at the first instance of the SplitCh character. So if it finds an instance of the split character in this string, it will copy all chars from the split character forward into the SecHalf parameter, and cap this string at the split character index. The check for the split character can be case sensitive or insensitive.
If the split character is found, then the return is True. Else the return is False and the SecHalf parameter will be empty.
StripChars([In] String ToStrip);
Removes all of the leading and trailing characters from the string. The list of characters are passed in the ToStrip parameter.
StripChars2([In] String ToStrip, [In] Card4 Flags);
A more flexible generic character stripper than StripChars above. Like StripChars it takes a list of characters to strip out. But it also takes a set of flags that indicate how to do the stripping. The flags are available as a set of nested literal values of this class. There are a set of base flags that can be OR'd together, and a set of common combinations of those flags. They are as follows:

Literal Name	Value	Description
kLeading	0x0001	Strip leading characters
kTrailing	0x0002	Strip trailing characters
kMiddle	0x0004	Strip characters inside the string. Actual effect is controlled by kTotal.
kTotal	0x0008	If kMiddle is set, this flag controls how the actual middle characters are stripped. If kTotal is not set, then any sequence of stripped characters is replaced by a single space. If kTotal is set, then the characters are just stripped out completely. This can be used, for instance, to reduce a sequence of tabs down to a single space, or to remove them altogether.

kLeadTrail	0x0003	Combines the leading and trailing flags, though you could just call StripChars() to get the same effect.
kFull	0x0007	Combines leading, trailing and middle, without the kTotal flag.
kComplete	0x000F	Combines leading, trailing, and middle, and turns on the kTotal flag.

StripWhitespace();
Strips all leading and trailing white space from this string. This includes, space characters, tabs, new lines, etc...
ToLower();
ToUpper();
Converts this string to either all upper or all lower case, as defined by the Unicode specification.