strings/strmanip.bi

Summary
strings/strmanip.bi
LicenseCopyright © 2007-2011, FreeBASIC Extended Library Development Group
ext.strings
Functions
RepeatReturns a string of length n consisting of as many characters with the ascii code ascii_code.
RepeatReturns a string of length n * len(subject) consisting of consecutive copies of subject.
ReplaceReplaces all unique occurences of oldtext found within subject, from beginning to end, and replaces them with newtext.
ReplaceReplaces all unique occurrences of each of the strings in oldtext, in order, that are found within subject, with newtext.
ReplaceReplaces all unique occurrences of each of the strings in oldtext, in order, that are found within subject, with corresponding strings in newtext, or the empty string (“”) if there are no corresponding strings.
ReplaceReplaces all unique occurrences of oldtext, that are found within each of the strings in subject, with newtext.
ReplaceReplaces all unique occurrences of each of the strings in oldtext, in order, that are found within each of the strings in subject, with newtext.
ReplaceReplaces all unique occurrences of each of the strings in oldtext, in order, that are found within each of the strings in subject, with corresponding strings from newtext, or the empty string (“”) if there are no corresponding strings.
ReplaceCopyReturns a copy of subject with all unique occurrences of oldtext replaced with newtext.
ReplaceCopyReturns a copy of subject with all unique occurrences of each of the strings in oldtext, in order, with newtext.
ReplaceCopyReturns a copy of subject with all unique occurrences of each of the strings in oldtext replaced by corresponding strings in newtext.
ReplaceCopyAssigns the strings in result the value of the corresponding strings in subject with each unique occurrence of oldtext, found from beginning to end, with newtext.
ReplaceCopyAssigns the strings in result, starting with string at index, the value of the corresponding strings in subject with each unique occurrence of oldtext, found from beginning to end, with newtext.
ReplaceCopy
ReplaceCopy
ReverseReverses the order of the characters in subject.
ReverseReverses the order of the characters in each of the strings in subject.
ReverseCopyReturns a copy of subject with the order of the characters reversed.
ReverseCopyAssigns the strings in result the values of the corresponding strings in subject with the order of the characters in each string reversed.
ReverseCopyAssigns the strings in result, starting with the string at index, the values of the corresponding strings in subject, starting with the first string, with the order of the characters in each string reversed.
Rot13The ROT13 encoding simply shifts every letter by 13 places in the alphabet while leaving non-alpha characters untouched.
Rot13CopyThe ROT13 encoding simply shifts every letter by 13 places in the alphabet while leaving non-alpha characters untouched.
shuffleRandomly shuffles the characters in the string.
ShuffleRandomly shuffles the characters in each of an array of strings.
ShuffleCopyRandomly shuffles the characters in the string.
ShuffleCopyRandomly shuffles the characters in each of an array of strings.
UCWordsCapitalizes every word in a string.
UCWordsCopyCapitalizes every word in 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

Summary
Functions
RepeatReturns a string of length n consisting of as many characters with the ascii code ascii_code.
RepeatReturns a string of length n * len(subject) consisting of consecutive copies of subject.
ReplaceReplaces all unique occurences of oldtext found within subject, from beginning to end, and replaces them with newtext.
ReplaceReplaces all unique occurrences of each of the strings in oldtext, in order, that are found within subject, with newtext.
ReplaceReplaces all unique occurrences of each of the strings in oldtext, in order, that are found within subject, with corresponding strings in newtext, or the empty string (“”) if there are no corresponding strings.
ReplaceReplaces all unique occurrences of oldtext, that are found within each of the strings in subject, with newtext.
ReplaceReplaces all unique occurrences of each of the strings in oldtext, in order, that are found within each of the strings in subject, with newtext.
ReplaceReplaces all unique occurrences of each of the strings in oldtext, in order, that are found within each of the strings in subject, with corresponding strings from newtext, or the empty string (“”) if there are no corresponding strings.
ReplaceCopyReturns a copy of subject with all unique occurrences of oldtext replaced with newtext.
ReplaceCopyReturns a copy of subject with all unique occurrences of each of the strings in oldtext, in order, with newtext.
ReplaceCopyReturns a copy of subject with all unique occurrences of each of the strings in oldtext replaced by corresponding strings in newtext.
ReplaceCopyAssigns the strings in result the value of the corresponding strings in subject with each unique occurrence of oldtext, found from beginning to end, with newtext.
ReplaceCopyAssigns the strings in result, starting with string at index, the value of the corresponding strings in subject with each unique occurrence of oldtext, found from beginning to end, with newtext.
ReplaceCopy
ReplaceCopy
ReverseReverses the order of the characters in subject.
ReverseReverses the order of the characters in each of the strings in subject.
ReverseCopyReturns a copy of subject with the order of the characters reversed.
ReverseCopyAssigns the strings in result the values of the corresponding strings in subject with the order of the characters in each string reversed.
ReverseCopyAssigns the strings in result, starting with the string at index, the values of the corresponding strings in subject, starting with the first string, with the order of the characters in each string reversed.
Rot13The ROT13 encoding simply shifts every letter by 13 places in the alphabet while leaving non-alpha characters untouched.
Rot13CopyThe ROT13 encoding simply shifts every letter by 13 places in the alphabet while leaving non-alpha characters untouched.
shuffleRandomly shuffles the characters in the string.
ShuffleRandomly shuffles the characters in each of an array of strings.
ShuffleCopyRandomly shuffles the characters in the string.
ShuffleCopyRandomly shuffles the characters in each of an array of strings.
UCWordsCapitalizes every word in a string.
UCWordsCopyCapitalizes every word in a string.

Functions

Repeat

declare function Repeat overload (byval ascii_code as integer,
byval n as integer) as string

Returns a string of length n consisting of as many characters with the ascii code ascii_code.

Parameters

ascii_codethe ascii code of the character to repeat
nthe number of times to repeat ascii_code

Returns

string containing the repeated ascii_code

Repeat

declare function Repeat (byref subject as const string,
byval n as integer) as string

Returns a string of length n * len(subject) consisting of consecutive copies of subject.

Parameters

subjectthe string to repeat.
nthe number of times to repeat subject

Returns

The string containing the repeated subject

Replace

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

Replaces all unique occurences of oldtext found within subject, from beginning to end, and replaces them with newtext.

Parameters

subjectthe text to search and replace in.
oldtexttext to search for in the string.
newtexttext to replace oldtext with

If the length of either subject or oldtext is zero (0), ext.strings.Replace does nothing.

Replace

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

Replaces all unique occurrences of each of the strings in oldtext, in order, that are found within subject, with newtext.

Parameters

subjectthe text to search and replace in.
oldtext()the array of strings to search for.
newtextthe string to replace oldtext() with.

For every string i in [lbound(oldtext), ubound(oldtext)],

ext.strings.Replace(subject, oldtext(i), newtext)

is called.

Replace

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

Replaces all unique occurrences of each of the strings in oldtext, in order, that are found within subject, with corresponding strings in newtext, or the empty string (“”) if there are no corresponding strings.

Parameters

subjectthe string to search and replace in.
oldtext()the array of strings to search for.
newtext()the array of strings to replace with.

For every string i in [lbound(oldtext), lbound(oldtext) + n-1], where n is the minimum size between oldtext and newtext,

ext.strings.Replace(subject, oldtext(i), newtext(i))

is called.  If oldtext contains more strings to find as there are replcements in newtext, then for every string i in [n-1, ubound(oldtext)],

ext.strings.Replace(subject, oldtext(i), "")

is called.

Replace

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

Replaces all unique occurrences of oldtext, that are found within each of the strings in subject, with newtext.

Parameters

subject()string array to search and replace in.
oldtexttext to search for.
newtexttext to replace with.

For every string i in [lbound(subject), ubound(subject)],

ext.strings.Replace(subject(i), oldtext, newtext)

is called.

Replace

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

Replaces all unique occurrences of each of the strings in oldtext, in order, that are found within each of the strings in subject, with newtext.

Parameters

subject()string array to search and replace in.
oldtext()array of strings to search for.
newtextstring to replace with.

For every string i in [lbound(subject), ubound(subject)],

ext.strings.Replace(subject(i), oldtext(), newtext)

is called.

Replace

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

Replaces all unique occurrences of each of the strings in oldtext, in order, that are found within each of the strings in subject, with corresponding strings from newtext, or the empty string (“”) if there are no corresponding strings.

Parameters

subject()string array to search and replace in.
oldtext()array of strings to search for.
newtext()array of strings to replace with.

For every string i in [lbound(subject), ubound(subject)],

ext.strings.Replace(subject(i), oldtext(), newtext())

is called.

ReplaceCopy

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

Returns a copy of subject with all unique occurrences of oldtext replaced with newtext.

Parameters

subjectthe text to search in
oldtexttext to search for in the string.
newtexttext to replace oldtext with

Behaves like,

var tmp = subject
ext.strings.Replace(tmp, oldtext, newtext)
return tmp

ReplaceCopy

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

Returns a copy of subject with all unique occurrences of each of the strings in oldtext, in order, with newtext.

Parameters

subjectthe text to search.
oldtext()the array of strings to search for.
newtextthe string to replace with.

Behaves like,

var tmp = subject
ext.strings.Replace(tmp, oldtext(), newtext)
return tmp

ReplaceCopy

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

Returns a copy of subject with all unique occurrences of each of the strings in oldtext replaced by corresponding strings in newtext.

Parameters

subjectthe string to search.
oldtext()the array of strings to search for.
newtext()the array of strings to replace with.

Behaves like,

var tmp = subject
ext.strings.Replace(tmp, oldtext(), newtext())
return tmp

ReplaceCopy

declare sub ReplaceCopy (subject() as const string,
byref oldtext as const string,
byref newtext as const string,
result() as string)

Assigns the strings in result the value of the corresponding strings in subject with each unique occurrence of oldtext, found from beginning to end, with newtextresult is resized occordingly.

Parameters

subject()array of string to search.
oldtexttext to search for.
newtextstring to replace with.
result()variable-length string array to store results.

Behaves like,

redim result(lbound(subject), ubound(subject)) as string
for i as integer = lbound(subject) to ubound(subject)
    result(i) = ext.strings.Replace(subject(i), oldtext, newtext)
next i

ReplaceCopy

declare sub ReplaceCopy (subject() as const string,
byref oldtext as const string,
byref newtext as const string,
result() as string,
byval index as integer)

Assigns the strings in result, starting with string at index, the value of the corresponding strings in subject with each unique occurrence of oldtext, found from beginning to end, with newtextresult is assumed to be large enough.

Parameters

subject()array of string to search.
oldtexttext to search for.
newtextstring to replace with.
result()variable-length string array to store results.
indexstarting index of result array.

Behaves like,

redim result(lbound(subject), ubound(subject)) as string
for i as integer = lbound(subject) to ubound(subject)
    result(i) = ext.strings.Replace(subject(i), oldtext, newtext)
next i

ReplaceCopy

declare sub ReplaceCopy (subject() as const string,
oldtext() as const string,
byref newtext as const string,
result() as string)

Parameters

subject()array of string to search.
oldtext()array of strings to search for.
newtextstring to replace with.
result()string array to copy modifications to.

Behaves like,

redim result(lbound(subject), ubound(subject)) as string
for i as integer = lbound(subject) to ubound(subject)
    result(i) = ext.strings.Replace(subject(i), oldtext(), newtext)
next i

ReplaceCopy

declare sub ReplaceCopy (subject() as const string,
oldtext() as const string,
newtext() as const string,
result() as string)

Parameters

subject()array of string to search.
oldtext()array of strings to search for.
newtext()array of strings to replace with.
result()string array to copy modifications to.

Behaves like,

redim result(lbound(subject), ubound(subject)) as string
for i as integer = lbound(subject) to ubound(subject)
    result(i) = ext.strings.Replace(subject(i), oldtext(), newtext())
next i

Reverse

declare sub Reverse overload (byref subject as string)

Reverses the order of the characters in subject.

Parameters

subjectthe string to reverse.

Reverse

declare sub Reverse (subject() as string)

Reverses the order of the characters in each of the strings in subject.

Parameters

subject()array of strings to reverse.

Behaves like,

for i as integer = lbound(subject) to ubound(subject)
    ext.strings.Reverse(subject)
next i

ReverseCopy

declare function ReverseCopy overload (byref subject as const string) as string

Returns a copy of subject with the order of the characters reversed.

Parameters

subjectthe string to reverse.

Behaves like,

var tmp = subject
ext.strings.Reverse(subject)
return tmp

ReverseCopy

declare sub ReverseCopy (subject() as const string,
result() as string)

Assigns the strings in result the values of the corresponding strings in subject with the order of the characters in each string reversed.  result is resized so that its upper and lower bounds are the same as subject

Parameters

subject()array of strings to reverse.
result()array of strings to return results in.

For every n in [lbound(subject), ubound(subject)],

result(n) = ext.strings.Reverse(subject(n))

is called.

ReverseCopy

declare sub ReverseCopy (subject() as const string,
result() as string,
byval index as integer)

Assigns the strings in result, starting with the string at index, the values of the corresponding strings in subject, starting with the first string, with the order of the characters in each string reversed.  result is assumed to be large enough to hold ubound(subject)-lbound(subject)+1 number of strings.

Parameters

subject()array of strings to reverse.
result()array of strings to return results in.
indexstarting index of result array.

For every n in [lbound(subject), ubound(subject)] and m in [index, index + (ubound(subject)-lbound(subject) + 1)],

result(m) = ext.strings.Reverse(subject(n))

Rot13

declare sub Rot13 (byref subject as string)

The ROT13 encoding simply shifts every letter by 13 places in the alphabet while leaving non-alpha characters untouched.  Encoding and decoding are done by the same function, passing an encoded string as argument will return the original version.

Parameters

subjectstring to encode or decode.

Rot13Copy

declare function Rot13Copy (byref subject as const string) as string

The ROT13 encoding simply shifts every letter by 13 places in the alphabet while leaving non-alpha characters untouched.  Encoding and decoding are done by the same function, passing an encoded string as argument will return the original version.

Parameters

subjectstring to encode or decode.

Returns

the modified string.

shuffle

Randomly shuffles the characters in the string.

Parameters

subjectthe string to shuffle.

Shuffle

declare sub Shuffle (subject() as string)

Randomly shuffles the characters in each of an array of strings.

Parameters

subject()array of strings to shuffle

ShuffleCopy

declare function ShuffleCopy overload (byref subject as const string) as string

Randomly shuffles the characters in the string.

Parameters

subjectthe string to shuffle.

Returns

the modified string.

ShuffleCopy

declare sub ShuffleCopy (subject() as const string,
result() as string)

Randomly shuffles the characters in each of an array of strings.

Parameters

subject()array of strings to shuffle
result()array to place results in

UCWords

declare sub UCWords (byref subject as string)

Capitalizes every word in a string.

Parameters

subjectthe string to capitalize.

UCWordsCopy

declare function UCWordsCopy (byref subject as const string) as string

Capitalizes every word in a string.

Parameters

subjectthe string to capitalize.

Returns

the modifed string.

declare function Repeat overload (byval ascii_code as integer,
byval n as integer) as string
Returns a string of length n consisting of as many characters with the ascii code ascii_code.
declare sub Replace overload (byref subject as string,
byref oldtext as const string,
byref newtext as const string)
Replaces all unique occurences of oldtext found within subject, from beginning to end, and replaces them with newtext.
declare function ReplaceCopy overload (
   byref subject as const string,
   byref oldtext as const string,
   byref newtext as const string
) as string
Returns a copy of subject with all unique occurrences of oldtext replaced with newtext.
declare sub Reverse overload (byref subject as string)
Reverses the order of the characters in subject.
declare function ReverseCopy overload (byref subject as const string) as string
Returns a copy of subject with the order of the characters reversed.
declare sub Rot13 (byref subject as string)
The ROT13 encoding simply shifts every letter by 13 places in the alphabet while leaving non-alpha characters untouched.
declare function Rot13Copy (byref subject as const string) as string
The ROT13 encoding simply shifts every letter by 13 places in the alphabet while leaving non-alpha characters untouched.
declare sub Shuffle (subject() as string)
Randomly shuffles the characters in each of an array of strings.
declare function ShuffleCopy overload (byref subject as const string) as string
Randomly shuffles the characters in the string.
declare sub UCWords (byref subject as string)
Capitalizes every word in a string.
declare function UCWordsCopy (byref subject as const string) as string
Capitalizes every word in a string.