XString.bi

Summary
XString.bi
LicenseCopyright © 2007-2011, FreeBASIC Extended Library Development Group
ext.strings
Enumerations
PAD_OPTION
XStringImplements: Comparable, Equatable, Printable, Assignable
Functions
default cosntructorConstructs an XString
operator letAssigns the value of another XString
operator +=Appends the value of an XString
operator &=Appends the value of an XString
operator -=Removes all occurances of a substring
operator *=Appends the value of the XString a number of times
EmptyReturns ext.true if empty, ext.false otherwise
LenReturns the length, in characters.
argSubstitutes %n with some text.
TrimTrims whitespace from both sides of the XString object
LTrimTrims whitespace from the left side of a XString object
RTrimTrims whitespace from the right side of a XString object
InstrSearchs a string for the first occurence of a substring
UCaseTransforms the alphabetical characters into uppercase
LCaseTransforms the alphabetical characters into lowercase
LeftReturns a string of length characters from the left side of the XString object
RightReturns a string of length characters from the right side of the XString object
MidPerforms an in-object text replace
MidRetrieves a portion of the XString object.
ReplaceReplaces a substring with a string you provide
ReplaceReplaces an array of substrings in a XString object
ReplaceReplaces an array of substrings in a XString object
UCFirstCapitalizes the first letter in the XString object
LCFirstMakes the first letter in the XString object lower case
PadPads a XString object with another string, similiar to php’s str_pad
PadCopyPads a XString object with another string, similiar to php’s str_pad
Rot13Performs a rot13 rotation on a XString object
Rot13CopyPerforms a rot13 rotation on a XString object
CRC32Calculates the 32 bit Cyclic Redundancy Check of a XString object and replaces the string with the hexidecimal representation of the CRC
CRC32CopyCalculates the 32 bit Cyclic Redundancy Check of a XString object
ReplaceCopyPerforms a text substitution in the XString object
ReplaceCopyPerforms a text substitution in a XString object
ReplaceCopyPerforms a text substitution in a XString object
ExplodeSplits the string into an array.
SplitSplits the string into an array.
ShuffleRandomly shuffles the characters in the string.
shuffleCopyRandomly shuffles the characters in the string
SubstrReturns a portion of a string.
SubstrReturns a portion of a string.
SubstrCompareCompares a portion of an XString with another.
SubstrCompareCompares a portion of an XString with another.
SubstrCountFinda the number of strings contained in the XString.
SubstrCountFinda the number of strings contained in the XString.
SubstrReplaceReplaces a portion of the XString with another.
SubstrReplaceReplaces a portion of the XString with another.
PosFind the position of a string in the object
RepeatRepeats the string a certain number of times.
ReverseReverses the string in-place.
ReverseCopyReverses the string.
ucwordsCapitalizes every word in the string.
ucwordsCopyCapitalizes every word in the string.
tConstructs a XString from a String.

License

Copyright © 2007-2011, FreeBASIC Extended Library Development Group

Distributed under the FreeBASIC Extended Library Group license.  See accompanying file LICENSE.txt or copy at http://code.google.com/p/fb-extended-lib/wiki/License

ext.strings

Enumerations

PAD_OPTION

STR_PAD_LEFTCauses the pad method to pad to the left
STR_PAD_RIGHTCauses the pad method to pad to the right
STR_PAD_BOTHCauses the pad method to alternate between right and left padding

XString

Implements: Comparable, Equatable, Printable, Assignable

Enhanced string type fully compatible with standard strings.

Supports the use of the +, &, -(Subtract a substring), -(Negate or reverse) and the * (repetition of the string) operators.

Summary
Functions
default cosntructorConstructs an XString
operator letAssigns the value of another XString
operator +=Appends the value of an XString
operator &=Appends the value of an XString
operator -=Removes all occurances of a substring
operator *=Appends the value of the XString a number of times
EmptyReturns ext.true if empty, ext.false otherwise
LenReturns the length, in characters.
argSubstitutes %n with some text.
TrimTrims whitespace from both sides of the XString object
LTrimTrims whitespace from the left side of a XString object
RTrimTrims whitespace from the right side of a XString object
InstrSearchs a string for the first occurence of a substring
UCaseTransforms the alphabetical characters into uppercase
LCaseTransforms the alphabetical characters into lowercase
LeftReturns a string of length characters from the left side of the XString object
RightReturns a string of length characters from the right side of the XString object
MidPerforms an in-object text replace
MidRetrieves a portion of the XString object.
ReplaceReplaces a substring with a string you provide
ReplaceReplaces an array of substrings in a XString object
ReplaceReplaces an array of substrings in a XString object
UCFirstCapitalizes the first letter in the XString object
LCFirstMakes the first letter in the XString object lower case
PadPads a XString object with another string, similiar to php’s str_pad
PadCopyPads a XString object with another string, similiar to php’s str_pad
Rot13Performs a rot13 rotation on a XString object
Rot13CopyPerforms a rot13 rotation on a XString object
CRC32Calculates the 32 bit Cyclic Redundancy Check of a XString object and replaces the string with the hexidecimal representation of the CRC
CRC32CopyCalculates the 32 bit Cyclic Redundancy Check of a XString object
ReplaceCopyPerforms a text substitution in the XString object
ReplaceCopyPerforms a text substitution in a XString object
ReplaceCopyPerforms a text substitution in a XString object
ExplodeSplits the string into an array.
SplitSplits the string into an array.
ShuffleRandomly shuffles the characters in the string.
shuffleCopyRandomly shuffles the characters in the string
SubstrReturns a portion of a string.
SubstrReturns a portion of a string.
SubstrCompareCompares a portion of an XString with another.
SubstrCompareCompares a portion of an XString with another.
SubstrCountFinda the number of strings contained in the XString.
SubstrCountFinda the number of strings contained in the XString.
SubstrReplaceReplaces a portion of the XString with another.
SubstrReplaceReplaces a portion of the XString with another.
PosFind the position of a string in the object
RepeatRepeats the string a certain number of times.
ReverseReverses the string in-place.
ReverseCopyReverses the string.
ucwordsCapitalizes every word in the string.
ucwordsCopyCapitalizes every word in the string.
tConstructs a XString from a String.

Functions

default cosntructor

Constructs an XString

Parameters

textthe text to construct with

operator let

declare operator let (byref x as const XString)

Assigns the value of another XString

Parameters

xthe XString value to assign

operator +=

declare operator += (byref x as const XString)

Appends the value of an XString

Parameters

xthe XString value to append

operator &=

declare operator &= (byref x as const XString)

Appends the value of an XString

Parameters

xthe XString value to append

operator -=

declare operator -= (byref x as const XString)

Removes all occurances of a substring

Parameters

xthe substring to remove

operator *=

declare operator *= (byval n as ext.SizeType)

Appends the value of the XString a number of times

Parameters

nthe number of times to append

Empty

declare const function Empty ( ) as bool

Returns ext.true if empty, ext.false otherwise

Len

declare const function Len ( ) as ext.SizeType

Returns the length, in characters.

arg

declare function arg (byref x as string) as xstring

Substitutes %n with some text.

Trim

declare sub Trim ( )

Trims whitespace from both sides of the XString object

LTrim

declare sub LTrim ( )

Trims whitespace from the left side of a XString object

RTrim

declare sub RTrim ( )

Trims whitespace from the right side of a XString object

Instr

declare function Instr (byval start as integer =  1,
byref search as const string  ) as integer

Searchs a string for the first occurence of a substring

Parameters

startinteger value specifying what character position in the string to start the search at.
searchstring or XString value specifying the substring to search for.

Returns

Integer value reflecting the character postition of the first occurence of substring.

UCase

declare sub UCase ( )

Transforms the alphabetical characters into uppercase

LCase

declare sub LCase ( )

Transforms the alphabetical characters into lowercase

Left

declare function Left (byval length as integer) as string

Returns a string of length characters from the left side of the XString object

Parameters

lengththe number of characters to return

Returns

Returns the left-most characters.

Right

declare function Right (byval length as integer) as string

Returns a string of length characters from the right side of the XString object

Parameters

lengththe number of characters to return

Returns

Returns the right-most characters.

Mid

declare sub Mid (byref text as const string,
byval start as integer,
byval length as integer)

Performs an in-object text replace

Parameters

textthe text you will be putting in
startthe character position in the object to start replacement
lengththe amount of characters to replace

Mid

declare function Mid (byval start as integer,  
byval length as integer =  0) as string

Retrieves a portion of the XString object.

Parameters

startcharacter position to start at
lengthlength of string to return, 0 for up to length of XString object

Returns

A string containing up to length characters from the XString object

Replace

declare sub Replace (byref oldtext as const string,
byref newtext as const string)

Replaces a substring with a string you provide

Parameters

oldtexttext to search for in the XString object
newtexttext to replace oldtext with

Replace

declare sub Replace (oldtext() as const string,
byref newtext as const string)

Replaces an array of substrings in a XString object

Parameters

oldtext()array of substrings to search for in the XString object
newtextstring to replace with

Replace

declare sub Replace (oldtext() as const string,
newtext() as const string)

Replaces an array of substrings in a XString object

Parameters

oldtext()array of substrings to search for in the XString object
newtext()matched array of strings to replace with

UCFirst

declare sub UCFirst ( )

Capitalizes the first letter in the XString object

LCFirst

declare sub LCFirst ( )

Makes the first letter in the XString object lower case

Pad

declare sub Pad (byval length as integer,  
byref pad_str as const string =  " ",
byval opt as PAD_OPTION =  STR_PAD_RIGHT)

Pads a XString object with another string, similiar to php’s str_pad

Parameters

lengthFinal length the string must reach
pad_strThe string to pad the XString object with
optOptional Padding behaviour, defaults to <STR_PAD_RIGHT>

PadCopy

declare const function PadCopy (
   byval length as integer,  
   byref pad_str as const string =  " ",
   byval opt as PAD_OPTION =  STR_PAD_RIGHT
) as XString

Pads a XString object with another string, similiar to php’s str_pad

Parameters

lengthFinal length the string must reach
pad_strThe string to pad the XString object with
optOptional Padding behaviour, defaults to <STR_PAD_RIGHT>

Returns

Padded string.

Rot13

declare sub Rot13 ( )

Performs a rot13 rotation on a XString object

Rot13Copy

declare const function Rot13Copy ( ) as XString

Performs a rot13 rotation on a XString object

Returns

rot13 encoded string.

CRC32

declare sub CRC32 ( )

Calculates the 32 bit Cyclic Redundancy Check of a XString object and replaces the string with the hexidecimal representation of the CRC

CRC32Copy

declare const function CRC32Copy ( ) as XString

Calculates the 32 bit Cyclic Redundancy Check of a XString object

Returns

Hexidecimal representation of a XString object

ReplaceCopy

declare const function ReplaceCopy (byref oldtext as const string,
byref newtext as const string) as XString

Performs a text substitution in the XString object

Parameters

oldtextthe text to search for
newtextthe text to replace with

Returns

The modified string.

ReplaceCopy

declare const function ReplaceCopy (oldtext() as const string,
byref newtext as const string) as XString

Performs a text substitution in a XString object

Parameters

oldtext()array of strings to look for
newtexttext to replace with

Returns

The modified string.

ReplaceCopy

declare const function ReplaceCopy (oldtext() as const string,
newtext() as const string) as XString

Performs a text substitution in a XString object

Parameters

oldtext()array of strings to look for
newtext()matched array of strings to replace with

Returns

The modified string.

Explode

declare function Explode (byref delimit as const string,
res() as string) as integer

Splits the string into an array.

Parameters

delimitThe delimiter to use when splitting the array, only first character is used.
res()string array that results will be passed into.

Returns

Integer number of delimited strings found.

Split

declare function Split (result() as string,
byref delimiter as const string,
byval limit as integer) as integer

Splits the string into an array.

Parameters

result()string array for results.
delimiterthe delimiter to use when splitting the string.
limitthe maximum number of strings to split into.

Returns

Integer number of delimited strings found.

Shuffle

declare sub Shuffle ( )

Randomly shuffles the characters in the string.

shuffleCopy

Randomly shuffles the characters in the string

Returns

XString object containing the modified string

Substr

declare function Substr (byval offset as integer =  0) as XString

Returns a portion of a string.

Parameters

offsetzero-based offset of substring. if negative, specifies (-offset) chars from the end of the string

Returns

The portion of the string following the offset passed.

Substr

declare function Substr (byval offset as integer,
byval length as integer) as XString

Returns a portion of a string.

Parameters

offsetzero-based offset of substring. if negative, specifies (-offset) chars from the end of the string
lengththe number of characters from offset to include. if negative, specifies all but the remaining (-length) characters.

Returns

The requested sub string.

SubstrCompare

declare const function SubstrCompare (byref b as const string,  
byval offset as integer =  0) as integer

Compares a portion of an XString with another.

Parameters

bA string.
offsetzero-based offset of substring. if negative, specifies (-offset) chars from the end of the string

Returns

Returns a negative, zero or positive value if the substring is less than, equal to or greater than b.

SubstrCompare

declare const function SubstrCompare (byref b as const string,
byval offset as integer,
byval length as integer) as integer

Compares a portion of an XString with another.

Parameters

bA string.
offsetzero-based offset of substring. if negative, specifies (-offset) chars from the end of the string
lengththe number of characters from offset to include. if negative, specifies all but the remaining (-length) characters.

Returns

Returns a negative, zero or positive value if the substring is less than, equal to or greater than b.

SubstrCount

declare const function SubstrCount (byref needle as const string,  
byval offset as integer =  0) as integer

Finda the number of strings contained in the XString.

Parameters

needlesubstring to search for
offsetzero-based offset of substring. if negative, specifies (-offset) chars from the end of the string

Returns

The number of substrings found.

SubstrCount

declare const function SubstrCount (byref needle as const string,
byval offset as integer,
byval length as integer) as integer

Finda the number of strings contained in the XString.

Parameters

needlesubstring to search for
offsetzero-based offset of substring. if negative, specifies (-offset) chars from the end of the string
lengththe number of characters from offset to include. if negative, specifies all but the remaining (-length) characters.

Returns

The number of substrings found.

SubstrReplace

declare sub SubstrReplace (byref replacement as const string,  
byval offset as integer =  0)

Replaces a portion of the XString with another.

Parameters

replacementreplacement string
offsetzero-based offset of substring. if negative, specifies (-offset) chars from the end of the string

SubstrReplace

declare sub SubstrReplace (byref replacement as const string,
byval offset as integer,
byval length as integer)

Replaces a portion of the XString with another.

Parameters

replacementreplacement string
offsetzero-based offset of substring. if negative, specifies (-offset) chars from the end of the string
lengththe number of characters from offset to include. if negative, specifies all but the remaining (-length) characters.

Pos

declare const function Pos (byref needle as const string,  
byval offset as integer =  0) as integer

Find the position of a string in the object

Parameters

needlethe string to search for.
offsetzero-based offset of substring. if negative, specifies (-offset) chars from the end of the string

Returns

The first index of the found string.

Repeat

declare function Repeat (byval n as integer) as XString

Repeats the string a certain number of times.

Parameters

nthe number of times to repeat

Returns

The modified XString object

Reverse

declare sub Reverse ( )

Reverses the string in-place.

ReverseCopy

declare const function ReverseCopy ( ) as XString

Reverses the string.

Returns

The modified XString object.

ucwords

Capitalizes every word in the string.

ucwordsCopy

Capitalizes every word in the string.

Returns

The modified XString object.

t

declare function t(byref rhs as string) as xstring

Constructs a XString from a String.  Will eventually be used for internationalization.

declare operator let (byref x as const XString)
Assigns the value of another XString
declare operator += (byref x as const XString)
Appends the value of an XString
declare operator &= (byref x as const XString)
Appends the value of an XString
declare operator -= (byref x as const XString)
Removes all occurances of a substring
declare operator *= (byval n as ext.SizeType)
Appends the value of the XString a number of times
declare const function Empty ( ) as bool
Returns ext.true if empty, ext.false otherwise
declare const function Len ( ) as ext.SizeType
Returns the length, in characters.
declare function arg (byref x as string) as xstring
Substitutes %n with some text.
declare sub Trim ( )
Trims whitespace from both sides of the XString object
declare sub LTrim ( )
Trims whitespace from the left side of a XString object
declare sub RTrim ( )
Trims whitespace from the right side of a XString object
declare function Instr (byval start as integer =  1,
byref search as const string  ) as integer
Searchs a string for the first occurence of a substring
declare sub UCase ( )
Transforms the alphabetical characters into uppercase
declare sub LCase ( )
Transforms the alphabetical characters into lowercase
declare function Left (byval length as integer) as string
Returns a string of length characters from the left side of the XString object
declare function Right (byval length as integer) as string
Returns a string of length characters from the right side of the XString object
declare sub Mid (byref text as const string,
byval start as integer,
byval length as integer)
Performs an in-object text replace
declare sub Replace (byref oldtext as const string,
byref newtext as const string)
Replaces a substring with a string you provide
declare sub UCFirst ( )
Capitalizes the first letter in the XString object
declare sub LCFirst ( )
Makes the first letter in the XString object lower case
declare sub Pad (byval length as integer,  
byref pad_str as const string =  " ",
byval opt as PAD_OPTION =  STR_PAD_RIGHT)
Pads a XString object with another string, similiar to php’s str_pad
declare const function PadCopy (
   byval length as integer,  
   byref pad_str as const string =  " ",
   byval opt as PAD_OPTION =  STR_PAD_RIGHT
) as XString
Pads a XString object with another string, similiar to php’s str_pad
declare sub Rot13 ( )
Performs a rot13 rotation on a XString object
declare const function Rot13Copy ( ) as XString
Performs a rot13 rotation on a XString object
declare sub CRC32 ( )
Calculates the 32 bit Cyclic Redundancy Check of a XString object and replaces the string with the hexidecimal representation of the CRC
declare const function CRC32Copy ( ) as XString
Calculates the 32 bit Cyclic Redundancy Check of a XString object
declare const function ReplaceCopy (byref oldtext as const string,
byref newtext as const string) as XString
Performs a text substitution in the XString object
declare function Explode (byref delimit as const string,
res() as string) as integer
Splits the string into an array.
declare function Split (result() as string,
byref delimiter as const string,
byval limit as integer) as integer
Splits the string into an array.
declare sub Shuffle ( )
Randomly shuffles the characters in the string.
declare function Substr (byval offset as integer =  0) as XString
Returns a portion of a string.
declare const function SubstrCompare (byref b as const string,  
byval offset as integer =  0) as integer
Compares a portion of an XString with another.
declare const function SubstrCount (byref needle as const string,  
byval offset as integer =  0) as integer
Finda the number of strings contained in the XString.
declare sub SubstrReplace (byref replacement as const string,  
byval offset as integer =  0)
Replaces a portion of the XString with another.
declare const function Pos (byref needle as const string,  
byval offset as integer =  0) as integer
Find the position of a string in the object
declare function Repeat (byval n as integer) as XString
Repeats the string a certain number of times.
declare sub Reverse ( )
Reverses the string in-place.
declare const function ReverseCopy ( ) as XString
Reverses the string.
declare function t(byref rhs as string) as xstring
Constructs a XString from a String.
Implements: Comparable, Equatable, Printable, Assignable