![]() |
BlitzMax Extended
0.8.16
Pushing Blitz to the Max.
|
Functionality for UCS-2 character strings. More...
Go to the source code of this file.
Data Structures | |
struct | BBString |
Fixed-length string object. More... |
Macros | |
#define | BBSTRING_SIZE(str) BBSTRING_SIZE_CALC((str)->length) |
Gets the size a string takes up in memory. | |
#define | BBSTRING_MAX_LENGTH ((BBSize)(65536 / sizeof (BBChar) - sizeof (BBString))) |
The maximum length of a string object. | |
#define | BBSTRING_ALLOC(len) |
Allocates a new string using the GC. | |
#define | BBNULLSTRING (&bbEmptyString) |
Convience macro for using a pointer to bbEmptyString. | |
#define | BBSTRING_NOTFOUND (-1) |
Shows that a string was not found within the given data. |
Enumerations | |
enum | BBStringSide { BBSTRING_SIDE_BOTH = 0, BBSTRING_SIDE_LEFT = -1, BBSTRING_SIDE_RIGHT = 1 } |
Specifies the side of a string. More... |
Functions | |
BBString * | bbStringToString (const BBString *str) |
Passes a string through without changing anything. | |
BBInt | bbStringCompare (const BBString *str, const BBString *rhs) __attribute__((pure)) |
Compares two strings. | |
BBString * | bbStringClone (const BBString *str) |
Creates an exact new copy of a string. | |
BBString * | bbStringNew (BBInt len) |
Creates a new string. | |
BBString * | bbStringFromChar (BBInt codepoint) |
Creates a new string from a character code. | |
BBString * | bbStringFromInt (BBInt number) |
Creates a new string from an integer number. | |
BBString * | bbStringFromLong (BBLong number) |
Creates a new string from a long integer number. | |
BBString * | bbStringFromFloat (BBFloat number) |
Creates a new string from a single-precision floating point number. | |
BBString * | bbStringFromDouble (BBDouble number) |
Creates a new string from a double-precision floating point number. | |
BBString * | bbStringFromBytes (const char *buf, BBInt size) |
Creates a new string from a buffer of byte data. | |
BBString * | bbStringFromShorts (const BBShort *buf, BBInt size) |
Creates a new string from a buffer of short integer data. | |
BBString * | bbStringFromInts (const BBInt *buf, BBInt size) |
Creates a new string from a buffer of integer data. | |
BBString * | bbStringFromArray (const BBArray *arr) |
Creates a new string from an array's data. | |
BBString * | bbStringFromCString (const char *c_str) |
Creates a new string from a null-terminated string. | |
BBString * | bbStringFromWString (const BBChar *w_str) |
Creates a new string from a null-terminated wide character string. | |
BBString * | bbStringFromUTF8String (const char *utf8_str) |
Creates a new string from an UTF-8 encoded null-terminated string. | |
BBBool | bbStringStartsWith (const BBString *str, const BBString *sub) __attribute__((pure)) |
Checks if a string begins with a given substring. | |
BBBool | bbStringEndsWith (const BBString *str, const BBString *sub) __attribute__((pure)) |
Checks if a string ends with a given substring. | |
BBBool | bbStringContains (const BBString *str, const BBString *sub) __attribute__((pure)) |
Checks if a string contains a substring. | |
BBString * | bbStringConcat (const BBString *str, const BBString *rhs) |
Concatenates two strings together to a new one. | |
BBString * | bbStringTrim (const BBString *str, BBStringSide side) |
Removes whitespace from the specified sides of a string. | |
BBString * | bbStringPad (const BBString *str, BBInt len, BBStringSide side) |
Pads a string to a given length. | |
BBString * | bbStringSlice (const BBString *str, BBInt begin, BBInt end) |
Gives a section of a string. | |
BBString * | bbStringReplace (const BBString *str, const BBString *sub, const BBString *replacement) |
Replaces all occurances of a given substring in a string. | |
BBInt | bbStringAsc (const BBString *str) __attribute__((pure)) |
Gives the UCS-2 character code of the first character of a string. | |
BBInt | bbStringFind (const BBString *str, const BBString *sub, BBInt index) __attribute__((pure)) |
Finds the first occurance of a substring in a string. | |
BBInt | bbStringFindLast (const BBString *str, const BBString *sub, BBInt index) __attribute__((pure)) |
Finds the last occurance of a substring in a string. | |
BBArray * | bbStringFindAll (const BBString *str, const BBString *sub, BBInt index) |
Finds all occurances of a subtring in a string. | |
BBInt | bbStringFindAny (const BBString *str, const BBStringArray *all_subs, BBInt index) __attribute__((pure)) |
Finds the first occurance of any of the given substrings. | |
BBString * | bbStringToLower (const BBString *str) |
Gives a lowercase version of a string. | |
BBString * | bbStringToUpper (const BBString *str) |
Gives an uppercase version of a string. | |
BBInt | bbStringToInt (const BBString *str) |
Parses an integer number from a string. | |
BBFloat | bbStringToFloat (const BBString *str) |
Parses a single-precision floating point number from a string. | |
BBDouble | bbStringToDouble (const BBString *str) |
Parses a double-precision floating point number from a string. | |
void | bbStringToLong (const BBString *str, BBLong *result) |
Parses a long integer number from a string. | |
char * | bbStringToCString (const BBString *str) |
Converts a string to a null-terminated character string. | |
BBChar * | bbStringToWString (const BBString *str) |
Converts a string to a null-terminated wide character string. | |
char * | bbStringToUTF8String (const BBString *str) |
Converts a string to a null-terminated UTF-8 encoded character string. | |
BBStringArray * | bbStringSplit (const BBString *str, const BBString *separator) |
Splits a string into bits delimited by a separator. | |
BBString * | bbStringJoin (const BBString *str, const BBStringArray *bits) |
Joins an array of bits together using the given string as glue. | |
BBBool | bbStringEquals (const BBString *str, const BBString *rhs) __attribute__((pure)) |
Checks two strings for equality. | |
BBInt | bbStringCount (const BBString *str, const BBString *sub) __attribute__((pure)) |
Counts all occurances of substring in a string. | |
BBString * | bbStringReverse (const BBString *str) |
Reverses a string. | |
BBString * | bbStringRotate (const BBString *str, BBInt count) |
Rotates a string. | |
BBString * | bbStringTimes (const BBString *str, BBInt count) |
Repeats and concatenates a string multiple times. | |
BBString * | bbStringSub (const BBString *str, BBInt index, BBInt len) |
Gives a substring of a string. | |
BBBool | bbStringIsLower (const BBString *str) __attribute__((pure)) |
Checks if the string only consists of lowercase characters. | |
BBBool | bbStringIsUpper (const BBString *str) __attribute__((pure)) |
Checks if the string only consists of lowercase characters. | |
BBBool | bbStringIsASCII (const BBString *str) __attribute__((pure)) |
Checks if a string only contains ascii characters. |
Variables | |
BBClass | bbStringClass |
Contains all operations that can be performed on strings. | |
BBString | bbEmptyString |
A typesafe NULL pointer for strings. |
Functionality for UCS-2 character strings.
#define BBNULLSTRING (&bbEmptyString) |
Convience macro for using a pointer to bbEmptyString.
Returned in case a search, calculation or parsing action was unsuccessful.
#define BBSTRING_ALLOC | ( | len | ) |
Allocates a new string using the GC.
This is a utility macro which does not perform any additional checking. It only fills in the right parameters for allocating a string object with the GC.
Only use this if you can ensure a valid length. Otherwise it's better to use the bbStringNew function which does the checking for you and is the standard way of creating new string objects.
len | The length of the new string |
Referenced by bbStringClone(), bbStringConcat(), bbStringFromBytes(), bbStringFromChar(), bbStringFromInts(), bbStringFromShorts(), bbStringJoin(), bbStringNew(), bbStringPad(), bbStringReplace(), bbStringReverse(), bbStringRotate(), bbStringSub(), bbStringTimes(), bbStringToLower(), bbStringToUpper(), and bbStringTrim().
The maximum length of a string object.
Referenced by bbReadStdin(), bbStringConcat(), bbStringFromBytes(), bbStringFromInts(), bbStringFromShorts(), bbStringFromUTF8String(), bbStringNew(), bbStringPad(), bbStringReplace(), and bbStringTimes().
#define BBSTRING_NOTFOUND (-1) |
Shows that a string was not found within the given data.
Referenced by bbStringAsc(), bbStringFind(), bbStringFindAny(), bbStringFindLast(), bbStringReplace(), and bbStringSplit().
#define BBSTRING_SIZE | ( | str | ) | BBSTRING_SIZE_CALC((str)->length) |
Gets the size a string takes up in memory.
The amount of memory the string uses is calculated from the size of "struct BBString" and the size of its buffer.
str | The string to calculate the size of |
enum BBStringSide |
Specifies the side of a string.
Choosing a specific side of a string to be worked with/upon can be useful to make string handling function more flexible.
Gives the UCS-2 character code of the first character of a string.
str | The string of which the code point will be extracted |
Creates an exact new copy of a string.
This creates a new string with the same attribtues and content as the one given as a parameter.
Note that this is only useful in special cases, as the string API always returns a new string object when anything is to be changed. For example bbStringToLower already creates a new string with a buffer filled with the lowercase characters.
str | The string which should be cloned |
Compares two strings.
The strings are compared by testing all of their characters for equality. When a non-equal character is found, the difference between the code point of str and rhs at that position is returned.
If all characters are equal the difference between both strings' length is returned.
0
.str | The string to be compared |
rhs | The right hand side string that is compared against the first one |
0
if they are equal. Concatenates two strings together to a new one.
str | The string to be at the beginning of the newly composed string |
rhs | The string to be appended to the first one |
Checks if a string contains a substring.
If the given substring is longer than the string in which it is seached in, or is empty, than BBFALSE is returned.
str | The string to be searched in |
sub | The substring which is searched for |
BBTRUE | if the given string contains the substring |
BBFALSE | if the substring is not found in the given string |
Counts all occurances of substring in a string.
If either the string or the substring is empty, the result is 0.
str | The string which is searched |
sub | The substring to search for |
Checks if a string ends with a given substring.
str | The string to be searched in |
sub | The substring which is searched for |
Checks two strings for equality.
Two strings equal when they have the same length and all of their characters are the same. The memory location does not matter here.
If both strings are empty, the result is BBTRUE.
str | The first string against which the other one is compared |
rhs | The string to compare against the first one |
Finds the first occurance of a substring in a string.
The given string is searched from the beginning to the end for a matching substring. If none is found, BBSTRING_NOTFOUND is returned.
If the given substring is longer than the haystack string in which is searched, BBSTRING_NOTFOUND is returned.
str | The string which is searched in |
sub | The substring which is looked for |
index | The start position for the search |
Finds all occurances of a subtring in a string.
This is an easier and faster way to find all substrings in a string than calling bbStringFind multiple times.
If the given substring is longer than the haystack string in which is searched, BBNULLARRAY is returned.
str | The string which is searched in |
sub | The substring which is looked for |
index | The start position for the search |
BBInt bbStringFindAny | ( | const BBString * | str, |
const BBStringArray * | all_subs, | ||
BBInt | index | ||
) |
Finds the first occurance of any of the given substrings.
If either the length of str or all_subs is 0
, BBSTRING_NOTFOUND
is returned. The same happens if all_subs is not a string array.
If the given start index is negative, it is set to 0
. If it is larger than the input string's length, BBNULLSTRING
is returned.
str | The string which is searched in |
all_subs | A string array containing all substrings to be searched for |
index | The start position of the search |
BBSTRING_NOTFOUND
. Finds the last occurance of a substring in a string.
In contrast to bbStringFind, the search is performed in reverse. That means the given string's buffer is searched from the end to the beginning. Therefore making this version more performant when it can be expected that the substring is located at the end.
str | The string which is searched in |
sub | The substring which is looked for |
index | The start position for the search |
Creates a new string from an array's data.
Reads all elements from a BByte
, BBShort
or BBInt
array and uses them as UCS-2 code points to create a string.
If the array's length is negative or 0
, BBNULLSTRING
is returned. If the array's length is larger than BBSTRING_MAX_LENGTH
it is clamped. In debug mode a BBRuntimeException
is also thrown in that case.
arr | An array containing UCS-2 code points |
BBNULLSTRING
. Creates a new string from a buffer of byte data.
All values in the buffer are interpreted as unsigned char
, therefore the first 256 UCS-2 code points can be read from the buffer.
If size is negative or 0
, BBNULLSTRING
is returned. If size is larger than BBSTRING_MAX_LENGTH
it is clamped. In debug mode a BBRuntimeException
is also thrown in that case.
buf | A buffer of byte values |
size | The length of the buffer |
BBNULLSTRING
. Creates a new string from a character code.
If the given code is out of UCS-2 range, a BBRuntimeException
will be thrown.
codepoint | A UCS-2 character code |
BBString* bbStringFromCString | ( | const char * | c_str | ) |
Creates a new string from a null-terminated string.
If c_str is NULL
, then BBNULLSTRING
is returned.
c_str | A null-terminated ASCII string |
BBNULLSTRING
. Creates a new string from a double-precision floating point number.
number | The double-precision floating point number that should be converted to a string |
double's
value, or BBNULLSTRING
. Creates a new string from a single-precision floating point number.
number | The single-precision floating point number that should be converted to a string |
float's
value, or BBNULLSTRING
. Creates a new string from an integer number.
Use this to convert BBByte
, BBShort
, BBInt
, BBSize
and BBBool
variables to a string.
number | The integer number that should be converted to a string |
BBNULLSTRING
. Creates a new string from a buffer of integer data.
All values in the buffer are interpreted as signed int
, therefore all code points from the Basic Multilingual Plane can be read from the buffer.
Code points out of the BMP will be clamped.
If size is negative or 0
, BBNULLSTRING
is returned. If size is larger than BBSTRING_MAX_LENGTH
it is clamped. In debug mode a BBRuntimeException
is also thrown in that case.
buf | A buffer of integer values |
size | The length of the buffer |
BBNULLSTRING
. Creates a new string from a long integer number.
number | The long integer number that should be converted to a string |
BBNULLSTRING
. Creates a new string from a buffer of short integer data.
All values in the buffer are interpreted as unsigned short int
, therefore all code points from the Basic Multilingual Plane (BMP) can be read from the buffer.
If size is negative or 0
, BBNULLSTRING
is returned. If size is larger than BBSTRING_MAX_LENGTH
it is clamped. In debug mode a BBRuntimeException
is also thrown in that case.
buf | A buffer of short integer values |
size | The length of the buffer |
BBNULLSTRING
. BBString* bbStringFromUTF8String | ( | const char * | utf8_str | ) |
Creates a new string from an UTF-8 encoded null-terminated string.
If utf8_str is NULL
, BBNULLSTRING
is returned.
BBRuntimeException | In case a Code Point is out of UCS-2 range. |
utf8_str | A UTF-8 encoded null-terminated string |
BBNULLSTRING
. Creates a new string from a null-terminated wide character string.
If w_str
is NULL then BBNULLSTRING
is returned.
w_str | A null-terminated wide string. |
A | new string containing the wide string's data, or BBNULLSTRING . |
Checks if a string only contains ascii characters.
When given an empty string as a paremeter BBTRUE
is returned.
str | The string to be checked |
BBTRUE | if the string only contains ASCII characters |
BBFALSE | if there are any character codes above 127 |
Checks if the string only consists of lowercase characters.
When given an empty string as a paremeter BBTRUE
is returned.
str | The string to check |
BBTRUE | if the string only contains lowercase characters |
BBFALSE | if there is at least one uppercase character |
Checks if the string only consists of lowercase characters.
When given an empty string as a paremeter BBTRUE
is returned.
str | The string to check |
BBTRUE | if the string only contains uppercase characters |
BBFALSE | if there is at least one lowercase character |
BBString* bbStringJoin | ( | const BBString * | str, |
const BBStringArray * | bits | ||
) |
Joins an array of bits together using the given string as glue.
Creates a new string.
Allocates a new string object with the GC and initializes it with the given length.
If the len parameter is negative or zero, a pointer to bbEmptyString is returned instead of a new string. The same happens if memory allocation with the GC failed, or the len is greater than BBSTRING_MAX_LENGTH
.
len | The length of the new string |
BBString* bbStringPad | ( | const BBString * | str, |
BBInt | len, | ||
BBStringSide | side | ||
) |
Pads a string to a given length.
If the resulting length len is smaller than or equal to the length of the given string str, the same string is returned without any padding.
BBSTRING_SIDE_LEFT
Pads the beginning of the string with whitespace BBSTRING_SIDE_RIGHT
Pads the end of the string with whitespace BBSTRING_SIDE_BOTH
Pads both sides of the string with whitespacestr | The string to be padded |
len | The final length of the padded string |
side | The side or sides of the string to be edited |
A | new string padded to the given length, or the given one. |
BBString* bbStringReplace | ( | const BBString * | str, |
const BBString * | sub, | ||
const BBString * | replacement | ||
) |
Replaces all occurances of a given substring in a string.
If the resulting string's length is 0
, BBNULLSTRING
is returned. If the resulting string's length is greater than BBSTRING_MAX_LENGTH
, is is clamped. In debug mode a BBRuntimeException
is also thrown in that case.
str | The input string |
sub | The substring which should be replaced |
replacement | The string that will be used to replace sub in str |
BBNULLSTRING
. Reverses a string.
If the given string is empty, BBNULLSTRING is returned.
str | The string which should be reversed |
Rotates a string.
The rotation is circular, therefore a number of rotations larger than the string's length – positive or negative – will start the rotation again at the beginning or end of the string respectively.
If either the given string is too short (< 2
), count is 0
or equals the string's length, the given string str is returned without rotation.
str | The string to be rotated |
count | The amount of which the characters should be rotated |
Gives a section of a string.
If the end position is lesser than the begin position, BBNULLSTRING
is returned.
str | The string to be sliced |
begin | The first position in str to start sclicing |
end | The last position in to end slicing |
BBNULLSTRING
. BBStringArray* bbStringSplit | ( | const BBString * | str, |
const BBString * | separator | ||
) |
Splits a string into bits delimited by a separator.
Searched the input string for occurances of the separator and splits it at every found position. If no match is found, the input string is returned as the first element in the result string array.
str | The string to be split |
separator | The separator that is used to split the string |
Checks if a string begins with a given substring.
str | The string to be searched in |
sub | The substring which is searched for |
BBTRUE | if the given string starts with the substring |
BBFALSE | in any other case. |
Gives a substring of a string.
This is an alternate way to get a substring out of a given string. The difference between this one and bbStringSlice is, that here the length of the substring is specified, not the last position in the original string.
A negative index results in counting the given value down from the end of the original string. If this goes below zero (when the negative index is too long) BBNULLSTRING
is returned. If the index is larger than the length of the original string, BBNULLSTRING
is returned immediately.
The length parameter can be longer than the given string. In this case the returned substring is as long as possible. If the given length is zero or lower, BBNULLSTRING
is returned.
str | The string from which the substring is taken |
index | The start position from where the substring is taken |
len | The maximum length of the substring. |
Repeats and concatenates a string multiple times.
This adds the given string multiple times to itself.
If the count parameter is zero or less, BBNULLSTRING
is returned.
If the count parameter has the exact value of 1
, the given string is simply returned.
If the length of the resulting string exceeds BBSTRING_MAX_LENGTH
, the number of concatenations will be reduced until it no longer exceeds that maximum length. In addition to that a BBRuntimeException
will be thrown in debug mode.
str | The string which should be repeated |
count | The number of times the string should be repeated |
char* bbStringToCString | ( | const BBString * | str | ) |
Converts a string to a null-terminated character string.
str | The string to be converted |
Parses a double-precision floating point number from a string.
str | The string containing the number as character string |
Parses a single-precision floating point number from a string.
str | The string containing the number as character string |
Parses an integer number from a string.
str | The string containing the number as character string |
Parses a long integer number from a string.
str | The string containing the number as character string |
result | A pointer to a BBLong variable in which the result is stored |
Gives a lowercase version of a string.
str | The string to convert to lower case |
Passes a string through without changing anything.
This function only exists to ensure uniformity of classes. When you operate from C/C++ and know that your object is a string, it makes no sense to use it.
str | The string to be passed through |
Gives an uppercase version of a string.
str | The string to convert to upper case |
char* bbStringToUTF8String | ( | const BBString * | str | ) |
Converts a string to a null-terminated UTF-8 encoded character string.
This encodes the internal UCS-2 data of a given string to a valid UTF-8 string. Obviously the encoded string will only contain code points from the BMP.
str | The string to be converted to a null-terminated UTF-8 string |
Converts a string to a null-terminated wide character string.
str | The string that is to be converted to a null-terminated wide character string |
BBString* bbStringTrim | ( | const BBString * | str, |
BBStringSide | side | ||
) |
Removes whitespace from the specified sides of a string.
BBSTRING_SIDE_LEFT
Removes whitespace from the beginning of the string BBSTRING_SIDE_RIGHT
Removes whitespace from the end of the string BBSTRING_SIDE_BOTH
Removes whitespace from both sides of the stringAny other value is handled like BBSTRING_SIDE_BOTH
str | The string to remove whitespace from |
side | The side or sides of the string to be edited |
BBString bbEmptyString |
A typesafe NULL
pointer for strings.
This NULL
equivalent for a BBString
pointer can be used in a wide range of situations to show that an operation was out of range, could not be performed or a string could not be allocated.
BBClass bbStringClass |
Contains all operations that can be performed on strings.
Since strings are a final built-in class, in this case the class is not as important as it is for user-defined classes.