| Header file: | bstring.h |
| Object name: | bstring |
| Object index: | 1 of 1 Object |
The bstring object is simply an object to make dealing with strings easier that it would ordinarily be in C++. It provides some easy-to-use interfaces which should prove handy.
Please note that the credit for this component should be directed at Pavel Minayev, who wrote the base bstring class. I went along and added other methods and properties to this base class to make it what it is now.
Note: this class compiles very well under Linux too. You may need to remove (or comment out) the ucase() and lcase() functions under Linux, but that will depend on your setup.
| Name | Description |
| char* data; | This is the pointer to the string's data - and you will use it everywhere. You can modfiy this if you wish, which means that you can apply other string operations on the string other than those provided. When obtaining the data of the string, this member must be used. Please see the sample source code at the end to properly illustrate this properties use. |
| Prototype | Description |
| bstring(const bstring &s); | [Constructor] This constructor allows you to pass along an existing bstring and simply copy that. |
| bstring(char* s); | [Constructor] This constructor allows you to simply create the object with the data specified. |
| int len(void); | This returns the length of the string, not including the null terminator. Therefore, if the string is to "Hello World!", then the length is 12. In the same way, if the string is "Hello World!\0\0", then the length is still 12. |
| char* mid(int Pos, int Length); | Just like the MID command in BASIC - returns a section of the string that starts at pos and goes for length. Returns a pointer to the string. |
| char* mid2(bstring* Result, int Pos, int Length); | This one is just like the usual MID function - but this one doesn't leak memory like the last one. The downside of this is that you need to provide a pointer to a valid bstring that will store the result. Pos is zero based, ie. 0 is the first character, and count is the total number of characters that you want. A null terminator is added onto the end for you. When writing new code, please use mid2() instead of mid() - mid() is only retained for backwards compatibility. |
| char* left(int Length); | DO NOT USE THIS FUNCTION! IT IS FOR BACKWARDS COMPATIBILITY ONLY! This one simply returns the number of characters specified starting from the left side of the string. |
| char* right(int Length); | DO NOT USE THIS FUNCTION! IT IS FOR BACKWARDS COMPATIBILITY ONLY! This one just returns the number of characters specified starting from the right hand side of the string. |
| char* left2(bstring* Result, int Length); | This is the replacement for left() - This one simply returns the number of characters specified starting from the left side of the string. You also need to pass a pointer to a bstring in which to place the result. |
| char* right2(bstring* Result, int Length); | This is the replacement for right() - This one just returns the number of characters specified starting from the right hand side of the string. You also need to pass a pointer to a bstring in which to place the result. |
| char* ucase(void); | Makes all letters in the string uppercase. Returns the uppercase data. However, you don't need to use the return value, as the results are applied to the current string. |
| char* lcase(void); | This one is the same as the last function, except for the fact that it makes all the letters lowercase instead. |
| char* search(int Start, char* Find); | Searches the string for the string specified by Find. It returns the start position of where that string is found. Start specifies where in the string to start searching, and starts at 0 (Zero). |
| char* search_char(int Start, int Character); | This function searches for the next occurence of Character after Start. Specify the character in ASCII: ie. A becomes 65. Start is the number of characters into the string to start searching. |
| char* search_reverse_char(int Start, int Character); | This function replicates the behaviour of the above one except that it searches in reverse. Please note that the Start parameter indicates how much of the string you want to search - it is an offset to the end. If you pass 0 for start, it will search the whole string. If you pass 6, it will search from the sixth character to the end of the string. |
| void alloc_str(int Size); | Pre-allocates a set area size for a string. Useful when defining a string before passing the pointer along to, say, a API function to have a string filled. |
| void empty(void); | Empties the string completely. The string is ready to be reused again, however. |
| char* add(char* String); | This function adds the contents of String to the end of the current string. It returns the whole string. |
| char* add(char* String1, char* String2); | This function clears the current string, and replaces it with the two passed strings added together. String2 is placed after String1. |
| char* tostr(char* Format, ...) | This function is neat and should save you much time. It works just like printf() - pass along a format string, and then as many variables as you wish. These will all be used to make a string and it will replace the current string. |
| char* tostr(char* Format, va_list Arguments); | Again, this function is just like the above function, except that you can use it to pass along a variable-argument stack to make a string. You can see an example of how this works by looking at the Debugf() function in Debug.h. |
| int fromstr(int Base); | This function returns an integer that is a numerical value based on the number specified by the string. If the string has "100" in it, then 100 will be returned. By changing the base, you can change how the function looks at the number - 10 for an integer, 16 for a hexadecimal, or 2 for binary. So, for instance, if the string has "1010" in it, and you specify a base of 2, the result will be 10. If you want to make sure that the number is interpreted as a hexidecimal, proceed the number with 0x (eg. 0xFFFF, which becomes 65535). |
| double fromstr(void); | Instead of returning a boring old integer, this function looks at the string and returns a double implementation of the number (floating point number, with a decimal point, or whatever you want to call it). |
| void addDoubleNull(void); | Quite often Windows calls for lists of files, which are a string of filenames. Each filename is usually seperated by a null character, and two null characters are used to end the list. Adding a second Null can be a pain; so this function will add a second null to the string that is currently in memory. |
| Operator = bstring &s |
This operator simply means that you can make a string equal another string, and it will. It means that you can do this:
bstring TestStringy, AnotherTestStringy;
|
| Operator = char* S |
This operator allows you to make a normal C-Style character string equal the bstring, and it will. You would use it like this:
bstring TestString, SecondTest;
|
The following snippet gives a basic idea of how to use this component.
//The bstring object.
//Create like this:
bstring Stringy;
bstring Stringy2(Stringy); //Create Stringy2, copy Stringy
bstring Stringy3("Hello World!");
void StandardStringFunction(char* CStringPassed)
{
cout << CStringPassed;
};
//Access the string's data with it's .data member.
//The .data member works like any C-Style string.
StandardStringFunction(Stringy3.data);
Stringy = "Hello!!";
//See any documentation on printf() for the
//escape codes to place in the tostr() function.
Stringy.tostr("Numbers: %d,%d,%d!", 1,2,3);
cout << Stringy.data;
//Outputs "Numbers: 1,2,3!"
Stringy.empty();
Stringy.alloc_str(100); //100 character string.
//Make sure you count the
//NULL character.
//Now this mid() and mid2() matter. Here's how:
bstring Result;
... = Stringy.mid2(&Result, 10,20);
//The value returned is the string that you wanted (as a char*)
//and Result also contains the string that you wanted.
//Sorry about that, but otherwise there's a void.
| Back to index | The FreeFoote Foundation Classes Documentation |