BlitzMax Extended  0.8.18
Pushing Blitz to the Max.
Data Structures | Macros | Enumerations | Functions | Variables
blitz_string.h File Reference

Functionality for UCS-2 character strings. More...

#include "_common.h"
#include "blitz_array.h"
#include "blitz_object.h"

Go to the source code of this file.

Data Structures

struct  BBString
 Fixed-length string object. More...

Macros

#define BBSTRING_SIZE(str)
 Gets the size a string takes up in memory.
#define BBSTRING_MAX_LENGTH
 The maximum length of a string object.
#define BBNULLSTRING
 A typesafe NULL pointer for strings.
#define BBSTRING_NOTFOUND
 Shows that a string was not found within the given data.

Enumerations

enum  BBStringSide { BBSTRING_SIDE_BOTH, BBSTRING_SIDE_LEFT, BBSTRING_SIDE_RIGHT }
 Specifies the side of a string. More...

Functions

BBStringbbStringToString (const BBString *str)
 Passes a string through without changing anything.
BBInt bbStringCompare (const BBString *str, const BBString *rhs) __attribute__((pure))
 Compares two strings.
BBStringbbStringClone (const BBString *str)
 Creates an exact new copy of a string.
BBStringbbStringNew (BBInt len)
 Creates a new string.
BBStringbbStringFromChar (BBInt codepoint)
 Creates a new string from a character code.
BBStringbbStringFromInt (BBInt number)
 Creates a new string from an integer number.
BBStringbbStringFromLong (BBLong number)
 Creates a new string from a long integer number.
BBStringbbStringFromFloat (BBFloat number)
 Creates a new string from a single-precision floating point number.
BBStringbbStringFromDouble (BBDouble number)
 Creates a new string from a double-precision floating point number.
BBStringbbStringFromBytes (const char *buf, BBInt size)
 Creates a new string from a buffer of byte data.
BBStringbbStringFromShorts (const BBShort *buf, BBInt size)
 Creates a new string from a buffer of short integer data.
BBStringbbStringFromInts (const BBInt *buf, BBInt size)
 Creates a new string from a buffer of integer data.
BBStringbbStringFromArray (const BBArray *arr)
 Creates a new string from an array's data.
BBStringbbStringFromCString (const char *c_str)
 Creates a new string from a null-terminated string.
BBStringbbStringFromWString (const BBChar *w_str)
 Creates a new string from a null-terminated wide character string.
BBStringbbStringFromUTF8String (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.
BBStringbbStringConcat (const BBString *str, const BBString *rhs)
 Concatenates two strings together to a new one.
BBStringbbStringTrim (const BBString *str, BBStringSide side)
 Removes whitespace from the specified sides of a string.
BBStringbbStringPad (const BBString *str, BBInt len, BBStringSide side)
 Pads a string to a given length.
BBStringbbStringSlice (const BBString *str, BBInt begin, BBInt end)
 Gives a section of a string.
BBStringbbStringReplace (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.
BBArraybbStringFindAll (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.
BBStringbbStringToLower (const BBString *str)
 Gives a lowercase version of a string.
BBStringbbStringToUpper (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.
BBCharbbStringToWString (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.
BBStringArraybbStringSplit (const BBString *str, const BBString *separator)
 Splits a string into bits delimited by a separator.
BBStringbbStringJoin (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.
BBStringbbStringReverse (const BBString *str)
 Reverses a string.
BBStringbbStringRotate (const BBString *str, BBInt count)
 Rotates a string.
BBStringbbStringTimes (const BBString *str, BBInt count)
 Repeats and concatenates a string multiple times.
BBStringbbStringSub (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.

Detailed Description

Functionality for UCS-2 character strings.

Author:
Mark Sibly
Fabian Niemann

Macro Definition Documentation

#define BBNULLSTRING

A typesafe NULL pointer for strings.

This NULL equivalent for a BBString pointer can be used to show that an operation was out of range, could not be performed or a string could not be allocated.

See also:
BBNULL, BBNULLARRAY
#define BBSTRING_MAX_LENGTH

The maximum length of a string object.

Todo:
New formular. Experimental one is absolute maximum and not guaranteed to work. The other one is stable but could be too small.

Referenced by bbReadStdin(), bbStringConcat(), bbStringFromBytes(), bbStringFromInts(), bbStringFromShorts(), bbStringFromUTF8String(), bbStringNew(), bbStringPad(), bbStringReplace(), and bbStringTimes().

#define BBSTRING_NOTFOUND

Shows that a string was not found within the given data.

See also:
bbStringFind, bbStringFindLast

Referenced by bbStringAsc(), bbStringFind(), bbStringFindAny(), bbStringFindLast(), bbStringReplace(), and bbStringSplit().

#define BBSTRING_SIZE (   str)

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.

Parameters:
strThe string to calculate the size of
Returns:
The complete size of the given string in bytes.

Enumeration Type Documentation

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.

See also:
bbStringTrim, bbStringPad
Enumerator:
BBSTRING_SIDE_BOTH 

The operation will affect both sides of the string.

BBSTRING_SIDE_LEFT 

The operation will only affect the beginning of the string.

BBSTRING_SIDE_RIGHT 

The operation will only affect the end of the string.


Function Documentation

BBInt bbStringAsc ( const BBString str)

Gives the UCS-2 character code of the first character of a string.

Parameters:
strThe string of which the code point will be extracted
Returns:
The code point as a BBInt number, or BBSTRING_NOTFOUND in case of an empty string.
BBString* bbStringClone ( const BBString str)

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.

Parameters:
strThe string which should be cloned
Returns:
A new string object, or BBNULLSTRING on failure.
BBInt bbStringCompare ( const BBString str,
const BBString rhs 
)

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.

Note:
Passing the same string to str and rhs will return 0.
See also:
bbStringEquals
Parameters:
strThe string to be compared
rhsThe right hand side string that is compared against the first one
Returns:
The difference between the two strings, 0 if they are equal.
BBString* bbStringConcat ( const BBString str,
const BBString rhs 
)

Concatenates two strings together to a new one.

Note:
The BlitzMax compiler automatically concatenates constant strings at compile time. All run time adding operations use this function.
Parameters:
strThe string to be at the beginning of the newly composed string
rhsThe string to be appended to the first one
Returns:
A newly created string containing both given strings' data. In case of an error BBNULLSTRING is returned.
BBBool bbStringContains ( const BBString str,
const BBString sub 
)

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.

See also:
bbStringCount, bbStringFind
Parameters:
strThe string to be searched in
subThe substring which is searched for
Return values:
BBTRUEif the given string contains the substring
BBFALSEif the substring is not found in the given string
BBInt bbStringCount ( const BBString str,
const BBString sub 
)

Counts all occurances of substring in a string.

If either the string or the substring is empty, the result is 0.

Parameters:
strThe string which is searched
subThe substring to search for
Returns:
The number of times a match for the substring is found in the string.
BBBool bbStringEndsWith ( const BBString str,
const BBString sub 
)

Checks if a string ends with a given substring.

Parameters:
strThe string to be searched in
subThe substring which is searched for
Returns:
BBTRUE if the given string ends with the substring, otherwise BBFALSE.
BBBool bbStringEquals ( const BBString str,
const BBString rhs 
)

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.

Note:
When given two strings pointing to the same location, BBTRUE is returned.
Parameters:
strThe first string against which the other one is compared
rhsThe string to compare against the first one
Returns:
BBTRUE in case the strings equal, otherwise BBFALSE.
BBInt bbStringFind ( const BBString str,
const BBString sub,
BBInt  index 
)

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.

Note:
Any negative index parameter is set to 0 before searching.
See also:
bbStringFindLast, bbStringFindAll
Parameters:
strThe string which is searched in
subThe substring which is looked for
indexThe start position for the search
Returns:
The position of the match in the str if found, otherwise BBSTRING_NOTFOUND.
BBArray* bbStringFindAll ( const BBString str,
const BBString sub,
BBInt  index 
)

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.

See also:
bbStringFind
Parameters:
strThe string which is searched in
subThe substring which is looked for
indexThe start position for the search
Returns:
An array containing all indexes where the substring was found. If no match was found BBNULLARRAY is returned.
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.

Parameters:
strThe string which is searched in
all_subsA string array containing all substrings to be searched for
indexThe start position of the search
Returns:
The first position any of the given substrings was found at, or BBSTRING_NOTFOUND.
BBInt bbStringFindLast ( const BBString str,
const BBString sub,
BBInt  index 
)

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.

See also:
bbStringFind
Parameters:
strThe string which is searched in
subThe substring which is looked for
indexThe start position for the search
Returns:
The position of the match in the str if found, otherwise BBSTRING_NOTFOUND.
BBString* bbStringFromArray ( const BBArray arr)

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.

Parameters:
arrAn array containing UCS-2 code points
Returns:
A string containing all of the array's elements as code points, or BBNULLSTRING.
BBString* bbStringFromBytes ( const char *  buf,
BBInt  size 
)

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.

Parameters:
bufA buffer of byte values
sizeThe length of the buffer
Returns:
A new string containing the buffer's data, or BBNULLSTRING.
BBString* bbStringFromChar ( BBInt  codepoint)

Creates a new string from a character code.

If the given code is out of UCS-2 range, a BBRuntimeException will be thrown.

Parameters:
codepointA UCS-2 character code
Returns:
A new one character long string.
BBString* bbStringFromCString ( const char *  c_str)

Creates a new string from a null-terminated string.

If c_str is NULL, then BBNULLSTRING is returned.

Parameters:
c_strA null-terminated ASCII string
Returns:
A new string containing the C-style string's data, or BBNULLSTRING.
BBString* bbStringFromDouble ( BBDouble  number)

Creates a new string from a double-precision floating point number.

Parameters:
numberThe double-precision floating point number that should be converted to a string
Returns:
A new string containing the double's value, or BBNULLSTRING.
BBString* bbStringFromFloat ( BBFloat  number)

Creates a new string from a single-precision floating point number.

Parameters:
numberThe single-precision floating point number that should be converted to a string
Returns:
A new string containing the float's value, or BBNULLSTRING.
BBString* bbStringFromInt ( BBInt  number)

Creates a new string from an integer number.

Use this to convert BBByte, BBShort, BBInt, BBSize and BBBool variables to a string.

Parameters:
numberThe integer number that should be converted to a string
Returns:
A new string containing the integer's value, or BBNULLSTRING.
BBString* bbStringFromInts ( const BBInt buf,
BBInt  size 
)

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.

Todo:
Better way to deal with code points above BMP.

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.

Parameters:
bufA buffer of integer values
sizeThe length of the buffer
Returns:
A new string containing the buffer's data, or BBNULLSTRING.
BBString* bbStringFromLong ( BBLong  number)

Creates a new string from a long integer number.

Parameters:
numberThe long integer number that should be converted to a string
Returns:
A new string containing the long integer's value, or BBNULLSTRING.
BBString* bbStringFromShorts ( const BBShort buf,
BBInt  size 
)

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.

Parameters:
bufA buffer of short integer values
sizeThe length of the buffer
Returns:
A new string containing the buffer's data, or 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.

Exceptions:
BBRuntimeExceptionIn case a Code Point is out of UCS-2 range.
Parameters:
utf8_strA UTF-8 encoded null-terminated string
Returns:
A string containing the UTF-8 string's data in UCS-2 encoding, or BBNULLSTRING.
BBString* bbStringFromWString ( const BBChar w_str)

Creates a new string from a null-terminated wide character string.

If w_str is NULL then BBNULLSTRING is returned.

Parameters:
w_strA null-terminated wide string.
Anew string containing the wide string's data, or BBNULLSTRING.
BBBool bbStringIsASCII ( const BBString str)

Checks if a string only contains ascii characters.

When given an empty string as a paremeter BBTRUE is returned.

Parameters:
strThe string to be checked
Return values:
BBTRUEif the string only contains ASCII characters
BBFALSEif there are any character codes above 127
BBBool bbStringIsLower ( const BBString str)

Checks if the string only consists of lowercase characters.

When given an empty string as a paremeter BBTRUE is returned.

Parameters:
strThe string to check
Return values:
BBTRUEif the string only contains lowercase characters
BBFALSEif there is at least one uppercase character
BBBool bbStringIsUpper ( const BBString str)

Checks if the string only consists of lowercase characters.

When given an empty string as a paremeter BBTRUE is returned.

Parameters:
strThe string to check
Return values:
BBTRUEif the string only contains uppercase characters
BBFALSEif 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.

BBString* bbStringNew ( BBInt  len)

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.

Parameters:
lenThe length of the new string
Returns:
A pointer to the newly created string object if successful, otherwise &bbEmptyString.
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 whitespace
Parameters:
strThe string to be padded
lenThe final length of the padded string
sideThe side or sides of the string to be edited
Anew 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.

Parameters:
strThe input string
subThe substring which should be replaced
replacementThe string that will be used to replace sub in str
Returns:
A new string with all occurances of sub replaced with replacement, or BBNULLSTRING.
BBString* bbStringReverse ( const BBString str)

Reverses a string.

If the given string is empty, BBNULLSTRING is returned.

Parameters:
strThe string which should be reversed
Returns:
A new string object with reversed characters or the given str.
BBString* bbStringRotate ( const BBString str,
BBInt  count 
)

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.

Parameters:
strThe string to be rotated
countThe amount of which the characters should be rotated
Returns:
A new string with every character rotated or the given str.
BBString* bbStringSlice ( const BBString str,
BBInt  begin,
BBInt  end 
)

Gives a section of a string.

If the end position is lesser than the begin position, BBNULLSTRING is returned.

See also:
bbStringSub
Parameters:
strThe string to be sliced
beginThe first position in str to start sclicing
endThe last position in to end slicing
Returns:
A new string containing the given string section's data, or 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.

Parameters:
strThe string to be split
separatorThe separator that is used to split the string
Returns:
An array with all the parts of the split string.
BBBool bbStringStartsWith ( const BBString str,
const BBString sub 
)

Checks if a string begins with a given substring.

Parameters:
strThe string to be searched in
subThe substring which is searched for
Return values:
BBTRUEif the given string starts with the substring
BBFALSEin any other case.
BBString* bbStringSub ( const BBString str,
BBInt  index,
BBInt  len 
)

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.

Note:
The len parameter specifies the maximal length of the substring.
See also:
bbStringSlice
Parameters:
strThe string from which the substring is taken
indexThe start position from where the substring is taken
lenThe maximum length of the substring.
Returns:
A new string which is a part of the given one, or BBNULLSTRING.
BBString* bbStringTimes ( const BBString str,
BBInt  count 
)

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.

Parameters:
strThe string which should be repeated
countThe number of times the string should be repeated
Returns:
A new string containing the given string multiple times.
char* bbStringToCString ( const BBString str)

Converts a string to a null-terminated character string.

Note:
The memory references by the returned pointer must be manually freed.
See also:
bbStringToWString, bbStringToUTF8String
Parameters:
strThe string to be converted
Returns:
A pointer to a newly allocated null-terminated string. NULL in case of an error.
BBDouble bbStringToDouble ( const BBString str)

Parses a double-precision floating point number from a string.

Parameters:
strThe string containing the number as character string
Returns:
The parsed number as a BBDouble value
BBFloat bbStringToFloat ( const BBString str)

Parses a single-precision floating point number from a string.

Parameters:
strThe string containing the number as character string
Returns:
The parsed number as a BBFloat value
BBInt bbStringToInt ( const BBString str)

Parses an integer number from a string.

Parameters:
strThe string containing the number as character string
Returns:
The parsed number as a BBInt value
void bbStringToLong ( const BBString str,
BBLong result 
)

Parses a long integer number from a string.

Parameters:
strThe string containing the number as character string
resultA pointer to a BBLong variable in which the result is stored
Returns:
Nothing, the parsed value is stored in the variable pointed to by the result parameter.
BBString* bbStringToLower ( const BBString str)

Gives a lowercase version of a string.

See also:
bbStringIsLower, bbStringToUpper
Parameters:
strThe string to convert to lower case
Returns:
A new lowercase-only string or BBNULLSTRING
BBString* bbStringToString ( const BBString str)

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.

Parameters:
strThe string to be passed through
Returns:
The given string
BBString* bbStringToUpper ( const BBString str)

Gives an uppercase version of a string.

See also:
bbStringIsUpper, bbStringToLower
Parameters:
strThe string to convert to upper case
Returns:
A new uppercase-only string or BBNULLSTRING
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.

Note:
The memory references by the returned pointer must be manually freed.
Parameters:
strThe string to be converted to a null-terminated UTF-8 string
Returns:
A pointer to the newly allocated UTF-8 string data. NULL in case of an error.
BBChar* bbStringToWString ( const BBString str)

Converts a string to a null-terminated wide character string.

Note:
The memory references by the returned pointer must be manually freed.
Parameters:
strThe string that is to be converted to a null-terminated wide character string
Returns:
A pointer to the newly allocated wide character string data. NULL in case of an error.
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 string

Any other value is handled like BBSTRING_SIDE_BOTH

Parameters:
strThe string to remove whitespace from
sideThe side or sides of the string to be edited
Returns:
A string with all whitespace characters removed.

Variable Documentation

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.

Note:
For compatibility reasons, this does not contain the extended functions.