Strings

Version:1.0
Status:Unspecified
Date:June 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1998-2001. All rights reserved.



Description

The Strings module provides a variety of string functions that are common to most programming languages and operating systems. This includes support for string conversions, searching, merging and so forth. This module supports strings of an unlimited length, so you do not need to worry about any possible limitations. As a bonus, this means that you can also use the string functions on large text files and documents (so long as you null terminate them).

The most important thing to remember is that some functions will return strings that have had their space allocated with the AllocMemory() function. If this is the case for a function you are using, make sure you call FreeMemory() on the resulting string before your program exits.

Function Index
FloatToStr  Converts a floating point number to a string.
IntToStr  Converts an integer to a string.
StrBuildArray  Builds an array of strings from a sequential string list.
StrCalculate  Calculates the total of any string containing calculations.
StrCapitalise  Capitalises a string.
StrClone  Clones string data.
StrCopy  Copies the characters of one string to another.
StrExpand  Expands the size of a string by inserting spaces.
StrInsert  Inserts a string into another string.
StrLength  Calculates the length of a string.
StrLineLength  Determines the line-length of a string.
StrLower  Changes a string so that all alpha characters are in lower-case.
StrNextLine  Returns a pointer to the next line in a string buffer.
StrReplace  Replaces all occurances of a keyword or phrase within a given string.
StrSearch  Searches a string for a particular keyword/phrase.
StrShrink  Shrinks strings by destroying data.
StrSort  Used to sort string arrays.
StrToFloat  Converts strings to floating point numbers.
StrToInt  Converts a string to an integer.
StrTranslate  Translates object references that have been declared within strings.
StrUpper  Changes a string so that all alpha characters are in upper-case.

 

Function:FloatToStr()
Short:Converts a floating point number to a string.
Synopsis:LONG FloatToStr(DOUBLE Number, STRING String, LONG Size)
Arguments:
Number  The floating point number that you want to convert.
String  Points to a string that must be long enough to hold all the characters that the number will translate to.
Size  The byte-size of the destination String buffer.

This function converts 64-bit floating point numbers into strings. It supports both negative and positive numbers (in the case of negative numbers, the resulting string will lead with a minus sign).

You are required to supply your own String buffer to this function and define the Size of that buffer. If the floating point number cannot fit in the amount of space that you have provided, remaining digits will be cut-off.

Result
Returns the total amount of characters that were written to the string, not including the null byte at the end. Zero is returned if an error occurred.

 

Function:IntToStr()
Short:Converts an integer to a string.
Synopsis:LONG IntToStr(LARGE Integer, STRING String, LONG StringSize)
Arguments:
Integer  The value that you want to convert into a string.
String  Points to a string that must be long enough to hold all the characters that the Integer will translate to.
Size  The byte-size of the destination String buffer.

This function converts integers into strings. It supports both negative and positive numbers (in the case of negative numbers, the resulting string will lead with a minus sign).

You are required to supply your own String buffer to this function and define the Size of that buffer. If the integer value cannot fit in the amount of space that you have provided, remaining digits will be cut-off.

Result
Returns the total amount of characters that were written to the string, not including the null byte at the end. Zero is returned if an error occurred.

 

Function:StrBuildArray()
Short:Builds an array of strings from a sequential string list.
Synopsis:STRING * StrBuildArray(STRING List, LONG Size, LONG AmtEntries, LONG Flags)
Arguments:
List  Pointer to a list of sequentially arranged strings.
Size  The total byte size of the List.
AmtEntries  The total number of strings specified in the List.
Flags  Set to SBF_SORT to sort the list, or SBF_NODUPLICATES to sort the list and remove duplicated strings.

This function is helpful for converting a buffer of sequential strings into a more easily managed string array. A "sequentially arranged list of strings" is basically a number of strings arranged one after the other in a single byte array. It is similar in arrangement to a CSV file, except the comma separators are replaced with null-terminators.

To convert such a string list into an array, you need to know the total byte size of the list, as well as the total number of strings in the list. If you don't know this information, you will need to alter your routine to make provisions for it.

Once you call this function, it will allocate a memory block to contain the array and string information. The list will then be converted into the array, which will be terminated with a NULL pointer at its end. If you have specified the SBF_SORT or SBF_NODUPLICATES Flags then the array will be sorted into alphabetical order for your convenience. The SBF_NODUPLICATES flag also removes duplicated strings from the array.

Remember to free the allocated array when you are finished with it.

Result
Returns an array of STRING pointers, or NULL if failure.

 

Function:StrCalculate()
Short:Calculates the total of any string containing calculations.
Synopsis:ERROR StrCalculate(STRING String, DOUBLE *Result)
Arguments:
String  A string containing the calculation text.
Result  Must refer to a DOUBLE variable that will store the calculated number.

This function can be used for making simple calculations that involve numeric values and plus, minus, multiply and divide operations. The string that is passed to the function may only consist of numbers, mathematical operators, spaces and brackets. An example of a valid string is:

   "100/50+(12*14)"

The following string is invalid, and would return an error code of ERR_BadData:

   "35*96A+x14"

This function is based on 64-bit floating point operations for maximum accuracy, and will return a floating point number as the result on success.

Result
ERR_Okay  Success - the Result contains the calculated floating point number.
ERR_BadData  The string that was supplied contains invalid characters.
ERR_Args  Invalid arguments were specified.

 

Function:StrCapitalise()
Short:Capitalises a string.
Synopsis:void StrCapitalise(STRING String)
Arguments:
String  Points to the string that you want to capitalise.

This function will will capitalise a string so that every word starts with a capital letter. All letters following the first capital of each word will be driven to lower-case characters. Numbers and other non-alphabetic characters will not be affected by this function. Here is an example:

   "every WOrd starts WITH a 2apital" = "Every Word Starts With A 2apital"

 

Function:StrClone()
Short:Clones string data.
Synopsis:STRING StrClone(STRING String)
Arguments:
String  Pointer to the string that you want to clone.

This function allows you to create an exact duplicate of a string. It analyses the length of the supplied String, allocates a private memory block for it and then copies the string characters into the new string buffer.

You are expected to free the resulting memory block when you are finished with it.

Result
Returns an exact duplicate of the String. If this function fails, NULL is returned.

 

Function:StrCopy()
Short:Copies the characters of one string to another.
Synopsis:LONG StrCopy(STRING Source, STRING Destination, LONG Length)
Arguments:
Source  Pointer to the string that you are copying from.
Destination  Pointer to the buffer that you are copying to.
Length  The total number of characters to be copied. Set to NULL to copy all characters in the Source.

This function copies part of one string over to another. If the Length is set to zero then this function will copy the entire Source string over to the Destination. Note that if this function encounters the end of the Source string (i.e. the null byte) while copying, then it will stop automatically to prevent copying of junk characters.

Please note that the Destination string will always be null-terminated by this function, so if you were to copy "123" into the middle of string "ABCDEFGHI" then the result would be "ABC123". The "GHI" part of the string would be lost. In situations such as this, StrReplace() or StrInsert() are probably the functions that you should be using.

Result
Returns the total amount of characters that were copied, not including the null byte at the end.

 

Function:StrExpand()
Short:Expands the size of a string by inserting spaces.
Synopsis:LONG StrExpand(STRING String, LONG Position, LONG TotalChars)
Arguments:
String  The string that you want to expand.
Position  The character position that you want to start expanding from.
TotalChars  The total number of spaces that you want to insert.

This function will expand a string by inserting spaces into a specified position. The String that you are expanding must be placed in a memory area large enough to accept the increased size, or you will almost certainly corrupt other memory areas.

Result
Returns the new length of the expanded string, not including the null byte.

 

Function:StrInsert()
Short:Inserts a string into another string.
Synopsis:ERROR StrInsert(STRING String, STRING Destination, LONG Position)
Arguments:
String  The string characters that you want to insert.
Destination  The string that you want to insert the characters into.
Position  The position at which the insertion will start.

This function is used to insert the characters of one String into a Destination string. It works on the assumption that the Destination string is large enough to contain the extra characters specified in the String argument.

You can set the position at which the characters will be inserted with the Position field.

Result
ERR_Okay  Insertion successful.
ERR_Args  Invalid arguments were specified.

 

Function:StrLength()
Short:Calculates the length of a string.
Synopsis:LONG StrLength(STRING String)
Arguments:
String  Pointer to the string you want to examine.

This function will calculate the length of a String, not including the null byte.

Result
Returns the length of the string.

 

Function:StrLineLength()
Short:Determines the line-length of a string.
Synopsis:LONG StrLineLength(STRING String)
Arguments:
String  Pointer to an address inside a character buffer.

This is a simple function that calculates the length of a String up to the first carriage return, line-break or null byte. This function is commonly used on large text files where the String points to a position inside a large character buffer.

Result
Returns the length of the first line in the string, not including the return code.

 

Function:StrLower()
Short:Changes a string so that all alpha characters are in lower-case.
Synopsis:void StrLower(STRING String)
Arguments:
String  Pointer to the string that you want to change to lower-case.

This function will alter a string so that all upper case characters are changed to lower-case. Non upper-case characters are unaffected by this function. Here is an example:

   "HeLLo world" = "hello world"

 

Function:StrNextLine()
Short:Returns a pointer to the next line in a string buffer.
Synopsis:STRING StrNextLine(STRING Buffer);
Arguments:
Buffer  Pointer to an address inside a character buffer.

This function scans a character buffer for a carriage return or line feed and returns a pointer to the following line. If no return code is found, NULL is returned.

This function is commonly used for scanning text files on a line by line basis.

Result
Returns a pointer to the string following the next line, or NULL if no further lines are present.

 

Function:StrReplace()
Short:Replaces all occurances of a keyword or phrase within a given string.
Synopsis:ERROR StrReplace(STRING Source, STRING Keyword, STRING Replacement, STRING *Result, LONG CaseSensitive)
Arguments:
Source  Points to the source string that contains occurances of the Keyword that you are searching for.
Keyword  Identifies the keyword or phrase that you want to replace.
Replacement  Identifies the string that will replace all occurances of the Keyword.
Result  Must refer to a STRING variable that will store the resulting memory block.
CaseSensitive  Set to TRUE if the keyword search should be case-sensitive.

This function will search a string and replace all occurances of a Keyword or phrase with the supplied Replacement string. If the Keyword is found, a new string will be returned which has all matches replaced with the Replacement string.

If the Keyword is never found, an error code of ERR_Search will be returned. If you want to know whether the Keyword actually exists before performing a replacement, consider calling the StrSearch() function first.

The new string that is created will be stored in the Result variable as a standard memory block. You are expected to free the memory block once you are finished with it.

Result
ERR_Okay  A replacement string was found and replaced.
ERR_Args  Invalid arguments were specified.
ERR_Search  The Keyword could not be found in the Source string.
ERR_AllocMemory  Memory for the resulting string could not be allocated.

 

Function:StrSearch()
Short:Searches a string for a particular keyword/phrase.
Synopsis:LONG StrSearch(STRING Keyword, STRING String, LONG CaseSensitive)
Arguments:
Search  A string that specifies the keyword/phrase you are searching for.
String  The string data that you wish to search.
CaseSensitive  Set to TRUE if the search should be case sensitive, otherwise FALSE.

This function allows you to search for a particular Keyword or phrase inside a String. You may search on a case sensitive or case insensitive basis.

Result
Returns the byte position of the first occurance of the Keyword within the String (possible values start from position 0). If the Keyword could not be found, this function returns a value of -1.

 

Function:StrShrink()
Short:Shrinks strings by destroying data.
Synopsis:void StrShrink(STRING String, LONG Position, LONG AmtChars)
Arguments:
String  Pointer to the string that you want to shrink.
Position  The byte position that you want to start shrinking the string from. The position must be shorter than the full length of the string.
AmtChars  The amount of characters that you want to get rid of.

This function allows you to shrink the size of a string by destroying some if its data. You can inform the function where exactly you want to start destroying characters and how many characters you want to delete. For example, StrShrink("Hello World", 4, 5) gives "Helrld" by deleting the characters "lo Wo".

This function operates entirely upon the String that you pass to it, so no memory will be allocated or returned to you. The String will be null terminated and its new length will be returned as a result.

Result
Returns the new length of the shrunken string, not including the null byte.

 

Function:StrSort()
Short:Used to sort string arrays.
Synopsis:ERROR StrSort(STRING *List)
Arguments:
List  Must point to an array of string pointers, terminated with a NULL entry.

This function is used to sort string arrays into alphabetical order. You will need to provide the list of unsorted strings in a block of string pointers, terminated with a NULL entry. For example:

  STRING List[] = {
     "banana",
     "apple",
     "orange",
     "kiwifruit",
     NULL
  }

The sorting routine will work within the confines of the array that you have provided and will not allocate any memory when performing the sort.

Result
ERR_Okay  The list has been sorted.
ERR_Args  Invalid arguments were specified.

 

Function:StrToFloat()
Short:Converts strings to floating point numbers.
Synopsis:DOUBLE StrToFloat(STRING String)
Arguments:
String  Pointer to the string that is to be converted to a floating point number.

This function converts strings into 64-bit floating point numbers. It supports negative numbers (if a minus sign is at the front) and skips leading spaces and non-numeric characters that occur before any digits.

If the function encounters a non-numeric character once it has started its number crunching, it immediately stops and returns the value that has been calculated up to that point.

Result
Returns the floating point value that was calculated from the String.

 

Function:StrToInt()
Short:Converts a string to an integer.
Synopsis:LARGE StrToInt(STRING String)
Arguments:
String  Pointer to the string that is to be converted to an integer.

This function converts a String to its integer equivalent. It supports negative numbers (if a minus sign is at the front) and skips leading spaces and non-numeric characters that occur before any digits.

If the function encounters a non-numeric character once it has started its digit processing, it immediately stops and returns the result calculated up to that point.

Here are some string conversion examples:

   String         Result
   183        =   183
     2902a6   =   2902
   hx239      =   239
   -45        =   -45
    jff-9     =   -9

Result
Returns the integer value that was calculated from the String.

 

Function:StrTranslate()
Short:Translates object references that have been declared within strings.
Synopsis:ERROR StrTranslate(STRING Buffer, LONG Length)
Arguments:
Buffer  The buffer that you wish to translate.
Length  The total size of the Buffer.

This function is used to translate strings that make object and field references using the standard referencing format. References are made to objects by enclosing statements within square brackets. As a result of calling this function, all references within the Buffer will be translated to their relevant format. The Buffer needs to be large enough to accommodate these adjustments as it will be expanded during the translation. It is recommended that the Buffer is at least two times the actual length of the string that you are translating.

Valid references can be made to an object by name, ID or relative parameters. Here some examples illustrating the different variations:

ReferenceType
[render]Name reference.
[#49302]ID reference.
[self]Relative reference to the object that has the current context.
[container]  Relative reference to the current object's container.

Object references are always converted to their ID equivalent when StrTranslate() is called, so the [render], [self], and [container] statements will all be converted to their associated ID numbers - for example [#96043]. ID references that already exist in a string prior to translation will not be affected in any way.

Field references are a slightly different matter and will be converted to the value of the field that they are referencing. A field reference is defined using the object referencing format, but they contain a '.fieldname' extension. Here are some examples:

   [render.width]
   [file.location]

A string such as "[mywindow.height] + [mywindow.width]" could be translated to "255 + 120" for instance. References to string based fields can expand the Buffer very quickly, which is why large buffer spaces are recommended for all-purpose translations.

Result
ERR_Okay  Translation successful.
ERR_Args  Invalid arguments were specified.
ERR_BadData  The buffer does not contain any object references.
ERR_Failed  One of the references is invalid or does not refer to an actual object.

 

Function:StrUpper()
Short:Changes a string so that all alpha characters are in upper-case.
Synopsis:void StrUpper(STRING String)
Arguments:
String  Pointer to the string that you want in upper-case.

This function will alter a String so that all upper-case characters are changed to lower-case. Non lower-case characters are unaffected by this function. Here is an example:

   "HeLLo world" = "HELLO WORD"