Strings

Version:1.0
Status:Stable
Date:January 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1998-2004. 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
CharCopy  Copies the characters of one string to another.
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.
StrDatatype  Determines the data type of a string.
StrExpand  Expands the size of a string by inserting spaces.
StrFormat  Formats a string using printf() style arguments.
StrFormatDate  Formats the content of a Time object into a date string.
StrInsert  Inserts a string into a buffer, with optional replace.
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.
StrReadColour  Converts a colour string into its equivalent RGB values.
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.
UTF8CharacterLength  Returns the number of bytes used to define a single UTF-8 character.
UTF8CharacterOffset  Retrieves the byte position of a character in a UTF-8 string.
UTF8Length  Returns the total number of characters in a UTF-8 string.
UTF8OffsetToCharacter  Converts a byte offset into a character position.
UTF8PrevLength  Gets the byte length of the previous character at a specific position in a UTF-8 string.
UTF8ReadValue  Converts UTF-8 characters into 32-bit unicode values.
UTF8WriteValue  Writes a 32-bit unicode value into a UTF-8 character buffer.

 

Function:CharCopy()
Short:Copies the characters of one string to another.
Synopsis:LONG CharCopy(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 number of characters to copy.

This function copies a string of characters to a destination. It will copy the exact number of characters as specified by Length, unless the source String terminates before the total number of characters have been copied.

This function will not null-terminate the destination. This function is not 'safe', in that it is capable of overflowing the destination buffer. Use StrCopy() if you want to copy a complete string with a limit on the destination buffer size.

Result
Returns the total amount of characters that were copied.


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, STRING Buffer, LONG BufferSize)
Arguments:
String  A string containing the calculation text.
Result  Refers to a DOUBLE variable that will store the calculated number, if you are only interested in calculating a final figure (optional).
Buffer  A result buffer is required if you want to interpret the resulting calculation as a string (recommended).
BufferSize  The size of the Buffer, in bytes.

This function can be used for performing simple calculations on numeric values and strings. It can return a result in either a numeric format or in a string buffer if the calculation involves non-numeric characters. Here are some examples of valid strings:

   "100/50+(12*14)"
   "0.05 * 100 + '%'"

Currently acceptable operators are plus, minus, divide and multiply. String references must be enclosed in single quotes or will be ignored. Brackets may be used to organise the order of operations during calculation.

Special operators include:

  p    This character immediately followed with an integer allows you to change
       the floating-point precision of output values.
  f    The same as the 'p' operator except the precision is always guaranteed
       to be fixed at that value through the use of trailing zeros (so a fixed
       precision of two used to print the number '7' will give a result of
       '7.00'.

The StrCalculate() function uses 64-bit floating point operations for maximum accuracy.

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 maximum number of characters to copy, including the NULL byte. The Length typically indicates the buffer size of the Destination pointer. Setting the Length to COPY_ALL will copy all characters from 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 regardless of whether you set the Length or not. For example, 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, functions such as CharCopy(), StrReplace() or StrInsert() should be used instead.

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


Function:StrDatatype()
Short:Determines the data type of a string.
Synopsis:LONG StrDatatype(STRING String)
Arguments:
String  The string that you want to analyse.

This function analyses a string and returns its data type. Valid return values are STR_FLOAT for floating point numbers, STR_NUMBER for whole numbers and STR_STRING for any other string type. In order for the string to be recognised as one of the number types, it must be limited to numbers and qualification characters, such as a decimal point or negative sign.

Result
Returns STR_FLOAT, STR_NUMBER or STR_STRING.


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 byte position that you want to start expanding from. Give consideration to UTF-8 formatting.
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:StrFormat()
Short:Formats a string using printf() style arguments.
Synopsis:LONG StrFormat(STRING Buffer, LONG BufferSize, STRING Format, Args...);
Arguments:
Buffer  Reference to a destination buffer for the formatted string.
Length  The length of the destination Buffer, in bytes.
Format  The string format to use for processing.
Args  A tag-list of arguments that match the parameters in the Format string.

Undocumented.

Result
Returns the total number of characters written to the buffer (not including the NULL terminator).


Function:StrFormatDate()
Short:Formats the content of a Time object into a date string.
Synopsis:ERROR StrFormatDate(STRING Buffer, LONG Length, STRING Format, *Time)
Arguments:
Buffer  Pointer to a buffer large enough to receive the formatted data.
Length  The length of the Buffer, in bytes.
Format  String specifying the required date format.
Time  Pointer to a Time structure that contains the date to be formatted.

The StrFormatDate() function is used to format dates into a human readable string format. The Format argument defines how the time information is printed to the display. Time formatting follows accepted conventions, as illustrated in the following format table:

StringExample
h24-Hour: 9
hh24-Hour: 09
H12-Hour: 9
HH12-Hour: 09
nMinute: 7
nnMinute: 07
sSecond: 42
ssSecond: 42
dDay: 3
ddDay: 03
DDay of week: T
dddDay of week: sat
ddddDay of week: saturday
mMonth: 11
mmMonth: 11
mmmMonth: nov
mmmmMonth: november
yyYear: 03
yyyyYear: 2003

By default, strings are printed in lower-case. For example, "ddd" prints "sat". If you want to capitalise the characters, use capitals in the string formatting instead of the default lower case. For example "Ddd" prints "Sat" and "DDD" prints "SAT".

Where the interpreter encounters unrecognised characters, it will print them out unaltered. For example "hh:nn:ss" might print "05:34:19" with the colons intact. If you need to include characters such as 'h' or 'd' and want to prevent them from being translated, preceed them with the backslash character. For instance to print "0800 hours", we would use the format "hh00 \hours".

The Time structure that you provide needs to contain values in the Year, Month, Day, Hour, Minute and Second fields. If you know that you do not plan on printing information on any particular date value, you can optionally choose not to set that field.

Result
ERR_Okay  The date was formatted successfully.
ERR_Args  Invalid arguments were specified.
ERR_BufferOverflow  The buffer was not large enough to hold the formatted string (the result will be correct, but truncated).

Function:StrInsert()
Short:Inserts a string into a buffer, with optional replace.
Synopsis:ERROR StrInsert(STRING Insert, STRING Buffer, LONG Position, LONG ReplaceChars, LONG BufferSize)
Arguments:
Insert  The string characters that you want to insert.
Buffer  The string that you want to insert the characters into.
Position  The byte position at which the insertion will start. Give consideration to UTF-8 formatting.
ReplaceCount  The number of characters to replace (set to zero for a normal insert).
BufferSize  The byte size of the Buffer.

This function is used to insert a series of characters into a Buffer. The position of the insert is determined by the byte offset declared in the Position field. You can opt to replace a specific number of characters in the destination by setting the ReplaceChars argument to a value greater than zero. To prevent buffer over-runs, you must declare the size of the Buffer in the BufferSize argument.

Result
ERR_Okay  Insertion successful.
ERR_Args  Invalid arguments were specified.
ERR_BufferOverflow  There is not enough space in the destination buffer for the insert.

Function:StrLength()
Short:Calculates the length of a string.
Synopsis:LONG StrLength(STRING String)
Arguments:
String  Pointer to the string that 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:StrReadColour()
Short:Converts a colour string into its equivalent RGB values.
Synopsis:ERROR ReadColour(STRING Colour, LONG *Red, LONG *Green, LONG *Blue, LONG *Alpha)
Arguments:
Colour  Pointer to a string containing the colour.
Red  Pointer to a 32-bit value that will hold the red component.
Green  Pointer to a 32-bit value that will hold the green component.
Blue  Pointer to a 32-bit value that will hold the blue component.
Alpha  Pointer to a 32-bit value that will hold the alpha component.

Use the StrReadColour() function to convert a colour from its string format to equivalent red, green and blue values. The colour that is referenced must be in hexadecimal or separated-decimal format. For example a pure red colour may be expressed as a string of "#ff0000" or "255,0,0".

Result
ERR_Okay  The colour conversion was successful.
ERR_Args  Invalid arguments were specified.

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 not 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 TotalBytes)
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.
TotalBytes  The total number of bytes that you want to eliminate.

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, LONG Flags)
Arguments:
List  Must point to an array of string pointers, terminated with a NULL entry.
Flags  Optional flags may be set here.

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.

Optional flags include SBF_NODUPLICATES, which strips duplicated strings out of the array; SBF_CASE to acknowledge case differences when determining string duplication and SBF_DESC to sort in descending order.

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, LONG Flags)
Arguments:
Buffer  The buffer that you wish to translate.
Length  The total size of the Buffer.
Flags  Currently unused, set to NULL.

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 are some examples illustrating the different variations:

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

Object references are always converted to their ID equivalent when StrTranslate() is called, so the [render], [self], and [owner] 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"

Function:UTF8CharacterLength()
Short:Returns the number of bytes used to define a single UTF-8 character.
Synopsis:LONG UTF8CharacterLength(STRING String)
Arguments:
String  Pointer to a UTF-8 string.

This function will return the total number of bytes used to create a single UTF-8 character. You are only required to supply a pointer to the start of the character string that you want to analyse.

Result
Returns the number of bytes used to create the UTF-8 character referred to by the String argument.


Function:UTF8CharacterOffset()
Short:Retrieves the byte position of a character in a UTF-8 string.
Synopsis:LONG UTF8CharacterOffset(STRING String, LONG Position)
Arguments:
String  A null-terminated UTF-8 string.
Position  The character number that you need a byte offset for.

This function is used for determing the actual byte position of a character within a UTF-8 string. It should be used in situations where you need to know the precise location of a character within a UTF-8 string.

Result
Returns the byte offset of the character.


Function:UTF8Length()
Short:Returns the total number of characters in a UTF-8 string.
Synopsis:LONG UTF8Length(STRING String)
Arguments:
String  Pointer to a UTF-8 string.

This function will return the 'real' length of a UTF-8 string. Using the StrLength() will return the number of bytes in a UTF-8 string, but to find out the actual number of characters, you must use UTF8Length().

Result
Returns the total number of characters used in the supplied UTF-8 string.


Function:UTF8OffsetToCharacter()
Short:Converts a byte offset into a character position.
Synopsis:LONG UTF8OffsetToCharacter(STRING String, LONG Position)
Arguments:
String  A null-terminated UTF-8 string.
Position  The byte offset that you need a character number for.

This function is used for determing the character number of a byte position within a UTF-8 string. It should be used in situations where you need to know the precise location of a character within a UTF-8 string.

Result
Returns the number of the character at the given byte position.


Function:UTF8PrevLength()
Short:Gets the byte length of the previous character at a specific position in a UTF-8 string.
Synopsis:LONG UTF8PrevLength(STRING String, LONG Index)
Arguments:
String  Pointer to a UTF-8 string.
Index  The byte index from which the size of the previous character should be calculated.

If you need to get the byte-length of the previous character from within a UTF-8 string, you can use this function. You need to provide the byte Index from which you want to calculate the previous character in the text as specified by String.

Result
Returns the byte-length of the previous character.


Function:UTF8ReadValue()
Short:Converts UTF-8 characters into 32-bit unicode values.
Synopsis:LONG UTF8ReadValue(STRING String, LONG *Length)
Arguments:
String  Pointer to a character in a UTF-8 string that you want to convert.
Length  Optional argument that will store the resulting number of bytes that make up the UTF-8 character.

This function is used to convert UTF-8 characters into 32-bit unicode values. Simply provide it with the address of the UTF-8 character that you need to convert and it will return the calculated unicode value. If you need to know how many bytes where used in making up the UTF-8 character, set the Length argument so that the function can return the total number of bytes to you.

Result
Returns the extracted unicode value.


Function:UTF8WriteValue()
Short:Writes a 32-bit unicode value into a UTF-8 character buffer.
Synopsis:LONG UTF8WriteValue(LONG Value, STRING String, LONG StringSize)
Arguments:
Value  The 32-bit unicode value that you want to write.
String  Pointer to a string buffer that will hold the UTF-8 characters.
StringSize  The size of the destination string buffer (does not need to be any larger than 6 bytes).

This function is used to write out unicode values in UTF-8 string format. You need to provide a string buffer, keeping in mind that anything from 1 to 6 bytes may be written to the buffer, depending on the size of the unicode value.

If the buffer is not large enough to hold the UTF-8 string then the function will do nothing and return a value of zero. Otherwise, the character will be written and the total number of bytes used will be returned.

This function will not add a null terminator to the end of the UTF-8 string.

Result
Returns the total amount of characters written to the string buffer.