Functions reference for UTF8 Store

UTF8 Store documentation; version 1.0

Converts value to string according to UTF8Store ucode.
value must be number in range defined by ucode or null, NaN or string.
true is saved as 1, false as 0, Date is saved as number of ms since 1/1/1970, other object is saved as NaN.
+/- Infinity is saved only in 5 chars, otherwise according to the error&12.

If the value cannot be placed to result string due its type or size, it is stored according to the error:

1, 2. bits	&3	Floating point numbers	0 to texts	1 as rounded to max decimals	2 as NaN	3 returns null
3, 4. bits	&12	Too big and too small numbers	0 to texts	4 as maximal / minimal number	8 as NaN	12 returns null
5, 6. bits	&48	Strings	0 to texts	16 as empty string ""	32 as NaN	48 returns null
7. bit	&64	Full or unset texts in 0 options			0 as NaN	64 returns null

Value 1 is ignored, if ucode decimals is used to multiply to increase the value.

The ucode specifies the main coding and can be Basic or Complex ucode.
The converted value is returned as Unicode string.
If the value cannot be converted according to the ucode option, it is stored in texts (for error = 0) and to returned Unicode string is encoded the index to texts.

The ucode first 15 bits controls the value conversion. It specifies especially number of bytes of the converted number, usually 1, 2, 3 or 5.
The ucode next 11 bits in complex ucode can be set to control converting the values that cannot be converted using the first 15 bits option.
The converted number is always stored in more bytes. 1 byte to 2 bytes; 2 or 3 bytes to 5 bytes.
The converted number is saved to utexts as Unicode string and to returned Unicode string is encoded the index to utexts.
If the value cannot be converted either by this option, it is stored in texts and to utexts is stored the index.
If the utexts is not set, the converted value is stored also in the texts.

The texts can be shared among all ucode options, but note that every ucode has different maximum texts to store in the texts and if the maximum is reached, the ucode option cannot store more texts.
The texts is placed as array in column or Cfg Texts or to ReadValue.
The utexts can be shared only among ucode with the same chars, because every item in utexts has the same size.
The utexts can be joined together without any separator and placed to column UTexts or to ReadValue as one string.

The options = 0 - numbers in string type are coded always as strings. 1 - tries to convert string type to number (slower). 3 - tries to convert string type to number only if the reverse conversion produces the same string (the slowest).
If set options&4, takes all dates for ucode 0x4 - 0x7, 0x14 - 0x17, 0x24, 0x25, 0x34 as UTC date instead of local date - in JavaScript uses Date.getUTC...() instead of Date.get...() methods for reading, in C# converts the date by ToUniversalTime() before reading.
If set options&64, it fills counts of saved texts into texts / utexts to be later sorted by SortTexts.
Converts all values in the values array to UTF8 string and returns it.
ucodes is array of ucode types for the values, ucodes has the same length as values.
If some item in ucodes is null, the first item in ucodes is used. If ucodes is integer, it is taken for all the values as the ucode.
If set positions, fills this array by positions of the coded individual values in the returned string. The filled values can be floating point for ucode = 0x8 - 0xF.
If set start, starts from this index in values / ucodes. If set length, codes only this count of values / ucodes.
If set options&16 and called with two or more ucodes, the second and next values store the strings to utexts instead of texts. Other options as WriteValue
The parameters and functionality are more described in WriteValue() function.
Use especially if some values are coded in bits by ucode 0x8 - 0xF. Returns original value from UTF8 string coded by WriteValue().
Usually not needed to use with FastGrid, the conversion is done automatically by GetValue from U and by GetAttr from B.
Reads the string from U starting on index and converts it to value according to the ucode options.
ucode options are listed in WriteValue.
index is position in U in chars regardless on ucode size. For example index = 5 for ucode = 0x21 (3 chars) the UTF8 string is U.slice(5,8). index can be floating point value for ucode = 0x8 - 0xF.
If set floating point index and the ucode is not bits (less than 0x8 or higher than 0xF), it is rounded to the next value only if set index_out.
texts is array of strings that were not coded into U.
utexts is single string, it is joined utexts (without any separator) filled by WriteValue. For ucode 0xC0 - 0xFF the utexts is array of strings like texts.
The options = 0 - strings from texts / utexts are returns always as strings. 1 - tries to convert strings to number (slower). 3 - tries to convert strings to number only if the reverse conversion produces the same string (the slowest).
If set options&4, returns all dates for ucode 0x4 - 0x7, 0x14 - 0x17, 0x24, 0x25, 0x34 as UTC date instead of local date - in JavaScript creates the date by new Date(Date.UTC(...)) instead of new Date(), in C# converts the date by ToLocalTime().
If set options&8, returns all dates for ucode 0x4 - 0x7, 0x14 - 0x17, 0x24, 0x25, 0x34 as number of milliseconds since 1/1/1970 (in C# it is done automatically on cast).
If set options&128 in PHP, the index and index_out are in bytes instead of chars.
If set index_out, the function sets index_out[0] to the next index where starts the next value in U. Use for variable length strings (ucode&0x40) or bits (ucode = 0x8 - 0xF) to get position of the next value.
Setting index_out adds 4ms to the decoding times.
Reads the value by ReadValue and returns it as 32 bit integer. If the value cannot be converted to 32 bit integer, returns 0x7FFFFFFF for bigger value, -0x80000000 for smaller value and 0 for the others. Reads the value by ReadValue and returns it as JavaScript number / Double type. If the value cannot be converted to number, returns 0. Reads the value by ReadValue and returns it as string. For stored null or NaN returns empty string. Reads the value by ReadValue and returns it as JavaScript Date / C# DateTime / JAVA LocalDateTime object. The date is converted from long number as count of milliseconds since 1/1/1970. For null or NaN returns null.
In JAVA there is also method ReadUtilDate() to get java.util.Date object instead of LocalDateTime.
If set options&4, return all dates for ucode 0x4 - 0x7, 0x14 - 0x17, 0x24, 0x25, 0x34 as UTC date instead of local date.
Reads the value by ReadValue and returns it as JavaScript Date / C# DateOnly / JAVA LocalDate object. In JavaScript clears time part. The date is converted from long number as count of milliseconds since 1/1/1970. For null or NaN returns null.
If set options&4, return all dates for ucode 0x4 - 0x7, 0x14 - 0x17, 0x24, 0x25, 0x34 as UTC date instead of local date.
Reads the value by ReadValue and returns it as JavaScript Date / C# TimeOnly / JAVA LocalTime object. In JavaScript sets date to 1/1/1970. The date is converted from long number as count of milliseconds since 1/1/1970. For null or NaN returns null.
If set options&4, return all dates for ucode 0x4 - 0x7, 0x14 - 0x17, 0x24, 0x25, 0x34 as UTC date instead of local date.
Returns array of original values from UTF8 string coded by WriteValue().
Usually not needed to use with FastGrid, the conversion is done automatically by GetValue from U and by GetAttr from B.
Reads ucodes.length values from index position in U. ucodes contain ucode types for the values conversion.
ucode can be one integer to read all values of this type till U end.
If U does not contain enough values for ucodes, it returns less values.
If set values_out, fills this array by values instead of creating new one and returns it.
If set start, fills the values in the array from this index. Otherwise starts from 0 or if set values_out, from its length.
If set options&16 and called with two or more ucodes, the second and next values read the strings from utexts instead of texts. utexts must be an array of strings in this case.
If set options&32, the start affects also starting position in ucodes as start % ucodes.length.
Other options are the same as in ReadValue.
The parameters and functionality are more described in ReadValue() function.
Use especially if some values are coded in bits by ucode 0x8 - 0xF. Calculates UTF8 Store complex ucode (or FastGrid attribute UCode) number from its parameters.
Returns negative number between -1 and -13 on incorrect input, the returned negative value is position of the incorrect parameter (from -1), e.g. -3 is incorrect decimals. Note, it returns correct negative number if base is outside range <1,32767>.
Parameters are described in ucode complex options.
base is base number subtracted from the number before stored and added back when number returned from store. It cannot be set with chars2.
If set chars2, the chars2, sign2, decimals2, multiple2, limits2 are used for coding numbers in UTexts if the first option cannot code the value to string.
In JavaScript the GetUCode accepts the parameters also in name = value array, like GetUCode( { chars:2, sign:1, limits:1 } );. If the object contains unknown parameter, it returns -16.
Adds given parameters to given basic ucode and returns the updated ucode.

base can be a number to add it as base to the ucode. If the ucode contains base, the base is subtracted from the coded number before it is stored and added back when returned the number from store. It cannot be set with signed2.
The stored base is integer number in range <1,32767> or rounded to two singnificant digits and forced in integer range (-1e150,1e150) and minimal decimal 1e-13.
If set decimals to divide (only options 5-12 for chars = 1 or 9-12 for chars = 2), the base is divided by the decimals before storing to ucode.
The base can be used to shorten the stored numbers if they oscillate around some base number to save only the difference. It is often used for dates.
Using base outside range <1,32767> or with floating point will produce negative ucode as 32bit integer.
Used mostly to add base to basic ucode 0x8 - 0xF.

Or base can be a string with single character as separator for separated strings in basic ucode 0xC0 - 0xDF.

Or base can be length of the first string in adjacent strings in basic ucode 0xD0 - 0xFF. Optional length of the second string is in len2.

Or base can be a date to add it as base date for dates in basic ucode 0x4 - 0x7, 0x14 - 0x17, 0x24, 0x25, 0x34. If set len2&4, takes the base as UTC date.

esc is added as 1 = 0x100 / 2 = 0x200 / 3 = 0x300 to any basic ucode that can save strings to escape them accordingly.
Finds the best UTF8 Store ucode number (or FastGrid attribute UCode) for given values, to be coded as small as possible.
It can test possibility of all basic except dates and complex ucodes except: fixed length string (0x41 - 0x80), separated string (0xc0 - 0xdf) and adjacent strings (0xc0 - 0xef).
Returns two dimensional array of all possible ucodes sorted from the best, the returned value [0][0] is the best ucode number found.
Every item in the array is an array as returned by TestUCode function.

type specifies which ucode will be tested against the values. The more tests, the slower the function is.
1. bit &1 - tests also base,
2. bit &2 - tests also second ucode with 3 best results for the first ucode,
3. bit &4 - variable strings instead of storing strings texts, the ucode will generate variable length results!
4. bit &8 - can reduce digits (precision) also in integer numbers - tests also limits 1 (0x2000), 2 (0x4000), 3 (0x6000) for chars 2, 3 and 5.

error specifies if the numbers can be rounded or limited or saved as strings, it is the same as in WriteValue.
options - 1.bit &1 - if permits converting strings to numbers when storing.
maxvalues - tests only given count of values against all ucodes. And for the best maxcount ucodes tests all values. The result bytes are reported always for all values.
The last returned array contains spent times in milliseconds as: [Iterate, Sort, Numbers, maxtest, ucode 1 char, ucode 2 chars, maxtest2]
Tries to code the values by given ucode. Returns null if it is not possible.
Otherwise returns array as: [ucode,size,numbers_size,texts_size,texts_count,utexts_size,utexts_count], where:
    [0] - ucode is the ucode number, already includes the base,
    [1] - size is size in bytes of values coded by the ucode,
    [2] - numbers_size is size in bytes of the values coded directly,
    [3] - texts_size is size in bytes of values coded in texts (indluding one byte for separators),
    [4] - texts_count is count of strings placed to texts,
    [5] - utexts_size is size in bytes of values coded in utexts,
    [6] - utexts_count is count of strings placed to utexts.
base can be base number that is added to ucode.
error specifies if the numbers can be rounded or limited or saved as strings, it is the same as in WriteValue.
Returns size in chars of given ucode.
For variable length strings in ucode&0x80 returns 0, for unused basic ucode returns -1.
For bit size ucode = 0x8 - 0xF returns floating point value.
Add size in chars of given ucode to position number to get position of the next value.
For variable length strings in ucode&0x80 does not modify the position.
For bit size ucode = 0x8 - 0xF adds floating point value.
Parses given ucode to array.
For complex ucode returns the parameters to GetUCode as [chars, sign, decimals, multiple, limits, varstrings, escape, base, chars2, sign2, decimals2, multiple2, limits2].
For basic ucode returns [base_ucode, base, separator, len1, len2, varstrings, escape].
If set options&4, returns base date for ucode 0x4 - 0x7, 0x14 - 0x17, 0x24, 0x25, 0x34 as UTC date instead of local date - in JavaScript creates the date by new Date(Date.UTC(...)) instead of new Date(), in C# converts the date by ToLocalTime().
If set options&8, returns base date for ucode 0x4 - 0x7, 0x14 - 0x17, 0x24, 0x25, 0x34 as number of milliseconds since 1/1/1970 (in C# it is done automatically on cast).
Returns information about given ucode in string.
Lists all ucodes by DebugUCode. Without second ucode, base, escape, multiple and fixed length data.
If set settings&1, returns HTML code with colored incorrect and var string ucodes.
Returns number of bytes that given text string will allocates in UTF8 encoding.
Sorts texts filled by WriteValues / WriteValue functions (in their parameters texts / utexts). Returns false if texts are null or empty.
It can be used to shorten the final saved data by double storing like:
UTF8Store.WriteValues(Values,ucodes,error,texts,utexts,options|8); UTF8Store.SortTexts(texts); UTF8Store.SortTexts(utexts); var UStore = UTF8Store.WriteValues(Values,ucodes,error,texts,utexts,options); Returns all the texts in one string, separated by separator.
escape = 1 escapes characters \t, \r, \n, \", \\ by \\; 2 replaces also 007F character by "\\x7F"; 3 replaces also all 0000 - 001F characters by "\\xXX".