Data Transmission

Chat, link messages, linkset data, notecards and HTTP all carry strings. Lists, numbers, vectors, rotations and keys must be turned into strings to be sent or stored, then parsed back on the other side.

This page is about formats, not channels: see communications for how strings travel and data storage for where they are kept.

Choose a format both sides understand: a delimited string for simple fields, CSV for lists of values, JSON for nested data or web services, and Base64 for binary or compact values.

Concepts

The most common format is a list joined with a separator
- Parsing splits it again (or keeps empty fields)
- Typecasts or llList2* functions such as llList2Integer convert each field to its type; llGetListEntryType tells what a field holds
- CSV is a ready-made variant, parsed back into a list
JSON represents nested objects and arrays, and is the format web services expect
- LSL can build JSON from lists, read and change values by path, and convert JSON arrays and objects back to lists
Encoding
- Base64 makes arbitrary text or integers safe to embed in other formats
- URL escaping prepares values for HTTP
- Characters convert to codepoints and back
Parsing strings: string functions find, cut and replace text
- Strings are UTF-8 internally but indexed by character
Working with lists: received lists often need searching, slicing, sorting or reshaping
- Strided lists store records as repeating groups of fields
Keys (UUIDs) identify avatars, objects and assets
- Generate unique keys for request IDs and records
Integrity: hashes, HMACs and RSA signatures let a receiver check that a message has not been changed and came from the expected sender

Functions and events

`string`	`llDumpList2String(list src, string separator)`
`list`	`llParseString2List(string src, list separators, list spacers)`
`string`	`llList2CSV(list src)`
`list`	`llCSV2List(string src)`
`string`	`llList2Json(string type, list values)`
`list`	`llJson2List(string src)`
`string`	`llJsonGetValue(string json, list specifiers)`
`string`	`llJsonSetValue(string json, list specifiers, string value)`
`string`	`llStringToBase64(string str)`
`string`	`llBase64ToString(string str)`
`key`	`llGenerateKey()`
`string`	`llHMAC(string private_key, string msg, string algorithm)`

JSON

Build with llList2Json using JSON_OBJECT or JSON_ARRAY; a missing path or bad input gives JSON_INVALID.

Types

See the list, string and key types.

Scripting Details

Lists and delimited strings

`string`	`llDumpList2String(list src, string separator)` Returns a string that is the list src converted to a single string, with separator placed between each entry.
`list`	`llParseString2List(string src, list separators, list spacers)` Breaks the string src into a list of substrings, discarding any separators, keeping spacers, and omitting any empty null values. separators and spacers accept up to 8 string entries each.
`list`	`llParseStringKeepNulls(string src, list separators, list spacers)` Breaks the string src into a list of substrings, discarding separators and keeping spacers, while preserving empty null values (unlike llParseString2List). separators and spacers accept up to 8 string entries each.
`string`	`llList2CSV(list src)` Returns a string of comma-separated values taken in order from the list src.
`list`	`llCSV2List(string src)` Parses the comma-separated string src and returns it as a list.
`string`	`llList2String(list src, integer index)` Returns the string value at index in the list src. Returns an empty string if the index is out of bounds.
`integer`	`llList2Integer(list src, integer index)` Returns the integer value at index in the list src. Returns 0 if the index is out of bounds or if the value cannot be type-cast.
`float`	`llList2Float(list src, integer index)` Returns the float value at index in the list src. Returns 0.0 if the index is out of bounds or if the value cannot be type-cast.
`key`	`llList2Key(list src, integer index)` Returns the key (UUID) value at index in the list src. Returns a null string/key if the index is out of bounds or if the value cannot be type-cast.
`vector`	`llList2Vector(list src, integer index)` Returns the vector value at index in the list src. Returns ZERO_VECTOR if the index is out of bounds or if the value cannot be type-cast.
`rotation`	`llList2Rot(list src, integer index)` Returns the rotation value at index in the list src. Returns ZERO_ROTATION if the index is out of bounds or if the value cannot be type-cast.
`integer`	`llGetListEntryType(list src, integer index)` Returns an integer representing the variable type (TYPE_*) of the list entry at index in the list src.

JSON functions

`string`	`llList2Json(string type, list values)` Converts the list values into a JSON string of the specified type (either a JSON_ARRAY or a JSON_OBJECT). Returns JSON_INVALID if an error is encountered.
`list`	`llJson2List(string src)` Parses the JSON string src and returns a list representing its top-level elements.
`string`	`llJsonGetValue(string json, list specifiers)` Parses the JSON string json and returns the value found by traversing the specified path of specifiers as a string.
`string`	`llJsonSetValue(string json, list specifiers, string value)` Returns a new JSON string representing json with the target located at specifiers set to value. Supports JSON_APPEND to append elements. Writing JSON_DELETE deletes the target. Overwriting array bounds or setting non-array levels with array indices returns JSON_INVALID.
`string`	`llJsonValueType(string json, list specifiers)` Parses the JSON string json and returns the JSON type constant (JSON_*) representing the value found at specifiers.

Encoding

`string`	`llStringToBase64(string str)` Returns the Base64 representation string of str, interpreting it as a UTF-8 byte sequence.
`string`	`llBase64ToString(string str)` Decodes the Base64-encoded string str into a conventional string, interpreting the bytes as a UTF-8 character sequence. Unprintable characters are converted to question marks.
`string`	`llIntegerToBase64(integer number)` Returns an 8-character Base64 string representing the big-endian encoded value of number.
`integer`	`llBase64ToInteger(string str)` Returns an integer representing the Base64-decoded big-endian value of str. Returns zero if str is longer than 8 characters; the return value is unpredictable if str contains fewer than 6 characters.
`string`	`llXorBase64(string str1, string str2)` Correctly performs a bitwise exclusive OR (XOR) on Base64 strings str1 and str2, returning the result as a Base64 string. The string str2 repeats if it is shorter than str1.
`string`	`llEscapeURL(string url)` Returns a string representing the escaped/encoded version of url, replacing spaces with '%20' and non-alphanumeric characters with their '%xx' hexadecimal UTF-8 equivalent.
`string`	`llUnescapeURL(string url)` Returns a string representing the unescaped/decoded version of url, replacing '%20' with spaces and decoding raw UTF-8 characters.
`string`	`llChar(integer val)` Constructs and returns a single-character string from the given Unicode codepoint ordinal.
`integer`	`llOrd(string val, integer index)` Returns the ordinal (Unicode copepoint integer) of the character at index in the string val. Negative indices count backward from the end of the string.

Parsing strings

`integer`	`llSubStringIndex(string source, string pattern)` Returns the codepoint index of the first occurrence of pattern inside the string source. Returns -1 if not found. No regex.
`string`	`llGetSubString(string src, integer start_index, integer end_index)` Returns a copy of the substring from src within the inclusive codepoint range start_index..end_index. Negative indices count backward from the end of the string. If start_index is greater than end_index, the substring is the excluded range.
`string`	`llDeleteSubString(string src, integer start_index, integer end_index)` Returns a copy of the string src with the characters from start_index to end_index (inclusive) removed. Negative indices count backward from the end of the string. If start_index is greater than end_index, the deletion excludes the specified range.
`string`	`llInsertString(string dst, integer index, string src)` Returns a copy of dst with src inserted at the given codepoint index.
`string`	`llReplaceSubString(string src, string pattern, string replacement_pattern, integer count)` Returns a copy of src with count occurrences of pattern replaced by replacement_pattern. Setting count to 0 replaces all occurrences; positive counts process left-to-right, while negative counts process right-to-left.
`integer`	`llStringLength(string str)` Returns the number of unicode codepoints in the string.
`string`	`llStringTrim(string src, integer type)` Returns a copy of the string src with leading, trailing, or both types of whitespace (including spaces, tabs, and line feeds) eliminated, according to the specified trim type.
`string`	`llToLower(string src)` Returns a lowercase copy of the string src. Converts all unicode characters, not just ASCII.
`string`	`llToUpper(string src)` Returns an uppercase copy of the string src. Converts all unicode characters, not just ASCII.

Working with lists

`integer`	`llGetListLength(list src)` Returns an integer representing the total number of elements in the list src.
`list`	`llList2List(list src, integer start_index, integer end_index)` Returns a new list containing the subset of entries from src within the inclusive range specified by the start and end indices. Negative indices count backward from the end.
`list`	`llList2ListSlice(list src, integer start_index, integer end_index, integer stride, integer slice_index)` Returns a list containing the slice_index'th element of every stride within the inclusive range from start to end in the strided list src. Stride must be a positive integer.
`list`	`llList2ListStrided(list src, integer start_index, integer end_index, integer stride)` Returns a new list containing the first element of every stride in the strided list src within the inclusive range from start to end.
`integer`	`llListFindList(list src, list test)` Returns the integer index of the first instance of list test within the list src (returns -1 if not found).
`integer`	`llListFindListNext(list src, list test, integer instance)` Returns the integer index of the specified instance of list test within the list src (returns -1 if not found).
`integer`	`llListFindStrided(list src, list test, integer start_index, integer end_index, integer stride)` Returns the integer index of the first instance of list test in the strided list src within the range from start to end (stepping through by stride). Returns -1 if not found.
`list`	`llListInsertList(list dest, list src, integer start)` Returns a new list containing all elements of dest with the elements of src inserted starting at index start. Does not modify dest itself.
`list`	`llListReplaceList(list dest, list src, integer start_index, integer end_index)` Returns a copy of the list dest with the inclusive range from start to end removed, and the elements of src inserted in its place at start.
`list`	`llDeleteSubList(list src, integer start_index, integer end_index)` Returns a copy of the list src with the slice from start_index to end_index (inclusive) removed. Negative indices count backward from the end of the list. If start_index is greater than end_index, the deletion excludes the specified range.
`list`	`llListSort(list src, integer stride, integer ascending)` Returns a copy of the list src, sorted into blocks of stride in ascending order (if ascending is TRUE) or descending order (if FALSE). Only works if the first entry of each block shares the same datatype.
`list`	`llListSortStrided(list src, integer stride, integer stride_index, integer ascending)` Returns a copy of the list src sorted into blocks of stride by the element at stride_index in each block. Sorted in ascending order (if ascending is TRUE) or descending order (if FALSE).
`list`	`llListRandomize(list src, integer stride)` Returns a randomized copy of the list src by blocks of size stride. If the list length is not perfectly divisible by stride, no randomization occurs.
`float`	`llListStatistics(integer operation, list src)` Returns the numeric result of the statistical aggregate function operation (a LIST_STAT_* constant) on the numeric list src.

Keys and identifiers

`key`	`llGenerateKey()` Generates and returns a unique versioned UUID key (utilizing SHA-1 hashing). Due to being versioned, it will not return NULL_KEY; however, the exact UUID version is an implementation detail that should not be relied upon.
`key`	`llGetKey()` Returns the key (UUID) of the prim containing the script.
`key`	`llGetLinkKey(integer link)` Returns the key (UUID) of the linked prim or avatar specified by link.
`key`	`llGetObjectLinkKey(key object_id, integer link)` Returns the key (UUID) of the linked child prim specified by link within the linkset identified by object_id.
`key`	`llGetOwnerKey(key id)` Returns the key (UUID) of the owner of the prim specified by id.

Integrity and signatures

`integer`	`llHash(string val)` Returns an integer representing the 32-bit hash value of the string val (returns 0 if the string is empty).
`string`	`llComputeHash(string message, string algorithm)` Returns a hex-encoded hash digest string of message using the specified cryptographic algorithm.
`string`	`llHMAC(string private_key, string msg, string algorithm)` Returns a Base64-encoded HMAC hash of msg using the secret key private_key and the specified digest algorithm (md5, sha1, sha224, sha256, sha384, or sha512).
`string`	`llMD5String(string src, integer nonce)` Returns a string of 32 hex characters representing the MD5 checksum of src salted with nonce (formatted as ':' + nonce).
`string`	`llSHA1String(string src)` Returns a string of 40 hex characters representing the SHA-1 security hash of src.
`string`	`llSHA256String(string src)` Returns a string of 64 hex characters representing the SHA-256 security hash of src.
`string`	`llSignRSA(string private_key, string msg, string algorithm)` Returns the Base64-encoded RSA signature of msg using the PEM-formatted private_key and the specified digest algorithm (sha1, sha224, sha256, sha384, or sha512). Can be paired with llVerifyRSA to pass verifiable messages.
`integer`	`llVerifyRSA(string public_key, string msg, string signature, string algorithm)` Returns TRUE if the Base64-formatted signature is verified as valid for the message msg when using the digest algorithm and public_key. Returns FALSE otherwise.

Additional

llList2Json — what to build
- JSON_OBJECT — the list is strided key-value pairs, encoded as an object
- JSON_ARRAY — the list is encoded as an array
- JSON_INVALID — returned for badly formed input, an invalid type, or a nonexistent location
llJsonSetValue — JSON_APPEND appends to the array at the given level
llJsonValueType — returns a type such as JSON_STRING or JSON_NUMBER
llGetListEntryType — field types
- TYPE_INTEGER, TYPE_FLOAT, TYPE_STRING, TYPE_KEY, TYPE_VECTOR, TYPE_ROTATION — the stored type
- TYPE_INVALID — the entry is invalid
llStringTrim — which end to trim
- STRING_TRIM — both ends
- STRING_TRIM_HEAD — the beginning
- STRING_TRIM_TAIL — the end
llListStatistics — operations such as LIST_STAT_MEAN, LIST_STAT_MEDIAN, LIST_STAT_SUM or LIST_STAT_STD_DEV

Reference

Constant groups ListEntryType 7 StringTrimType 3 ListStatisticsOperation 10

See also Page list type Category List Category JSON SL Wiki Json usage in LSL Category Data Conversion Page string type Category String Page key type Category UUID Category CryptographyPlanned Guide: sending nested data as JSONPlanned Guide: parsing strings and typecasting fields