polserver/docs/docs.polserver.com/pol100/basicem.xml

<?xml version='1.0' encoding="iso-8859-1"?>
<?xml-stylesheet type="text/xsl" href="escript.xslt" ?>
<!DOCTYPE ESCRIPT SYSTEM "escript.dtd">
<ESCRIPT>  
  <fileheader fname="Basic.em">
    <filedesc>Functions for converting and manipulating number, character, and string values.</filedesc>
    <datemodified>08/20/2020</datemodified>
<constant>const TRIM_LEFT  := 0x1; // Trim whitespace from Left of string.</constant>
<constant>const TRIM_RIGHT := 0x2; // Trim whitespace from Right of string.</constant>
<constant>const TRIM_BOTH  := 0x3; // Trim whitespace from Left and Right of string.</constant>
<constant>// TypeOfInt() constants</constant>
<constant>const OT_UNKNOWN          :=  0;</constant>
<constant>const OT_UNINIT           :=  1;</constant>
<constant>const OT_STRING           :=  2;</constant>
<constant>const OT_LONG             :=  3;</constant>
<constant>const OT_DOUBLE           :=  4;</constant>
<constant>const OT_ARRAY            :=  5;</constant>
<constant>const OT_APPLICPTR        :=  6;</constant>
<constant>const OT_APPLICOBJ        :=  7;</constant>
<constant>const OT_ERROR            :=  8;</constant>
<constant>const OT_DICTIONARY       :=  9;</constant>
<constant>const OT_STRUCT           := 10;</constant>
<constant>const OT_PACKET           := 11;</constant>
<constant>const OT_BINARYFILE       := 12;</constant>
<constant>const OT_XMLFILE          := 13;</constant>
<constant>const OT_XMLNODE          := 14;</constant>
<constant>const OT_XMLATTRIBUTES    := 15;</constant>
<constant>const OT_POLCOREREF       := 16;</constant>
<constant>const OT_ACCOUNTREF       := 17;</constant>
<constant>const OT_CONFIGFILEREF    := 18;</constant>
<constant>const OT_CONFIGELEMREF    := 19;</constant>
<constant>const OT_DATAFILEREF      := 20;</constant>
<constant>const OT_DATAELEMREF      := 21;</constant>
<constant>const OT_GUILDREF         := 22;</constant>
<constant>const OT_PARTYREF         := 23;</constant>
<constant>const OT_BOUNDINGBOX      := 24;</constant>
<constant>const OT_DEBUGCONTEXT     := 25;</constant>
<constant>const OT_SCRIPTEXREF      := 26;</constant>
<constant>const OT_PACKAGE          := 27;</constant>
<constant>const OT_MENUREF          := 28;</constant>
<constant>const OT_MOBILEREF        := 29;</constant>
<constant>const OT_OFFLINEMOBILEREF := 30;</constant>
<constant>const OT_ITEMREF          := 31;</constant>
<constant>const OT_BOATREF          := 32;</constant>
<constant>const OT_MULTIREF         := 33;</constant>
<constant>const OT_CLIENTREF        := 34;</constant>
<constant>// Only applicable if SQL is active and compiled.</constant>
<constant>const OT_SQLCONN          := 35;</constant>
<constant>const OT_SQLRESULT        := 36;</constant>
<constant>const OT_SQLROW           := 37;</constant>
<constant>  </constant>
<constant>const OT_BOOLEAN          := 38;</constant>
<constant>const OT_FUNCOBJECT       := 39;</constant>
<constant>const OT_EXPORTEDSCRIPT   := 40;</constant>
  </fileheader>

  <function name="CAsc"> 
    <prototype>CAsc(str)</prototype>
    <parameter name="str" value="String to convert" />
    <explain>
      Converts the first character of string to an ASCII code
    </explain>
    <return>ASCII code</return>
  </function>

  <function name="CAscZ"> 
    <prototype>CAscZ(str, nullterm := 0)</prototype>
    <parameter name="str" value="String to convert" />
    <parameter name="nullterm" value="If true, adds a 0x00 to the end of the array" />
    <explain>
      Converts the string to an array of the character's ASCII codes
    </explain>
    <return>Array of ASCII values</return>
  </function>

  <function name="CChr">
    <prototype>CChr(number)</prototype>
    <parameter name="number" value="Integer to convert" />
    <explain>
      Converts an ASCII value to a string consisting of one character.
    </explain>
    <return>A character</return>
  </function>

  <function name="CChrZ">
    <prototype>CChrZ(intarray, break_at_first_null := 0)</prototype>
    <parameter name="intarray" value="Array of ASCII values" />
    <parameter name="break_at_first_null" value="If true, stops when 0x00 found" />
    <explain>
      Converts an array of ASCII values to a string
    </explain>
    <return>A string</return>
  </function>

  <function name="CDbl">
    <prototype>CDbl(expr)</prototype>
    <parameter name="expr" value="A variable Int or String" />
    <explain>
      Converts a string or int to a real. Only strings containing digits and '.' will return a predicatable result. 
Ints will be expanded.
    </explain>
    <return>A Real</return>
  </function>

  <function name="CInt">
    <prototype>CInt(expr)</prototype>
    <parameter name="expr" value="A variable Real or String" />
    <explain>
      Converts a string or real to an integer. Only strings containing digits and '.' will return a predicatable 
result. Doubles will be truncated.
    </explain>
    <return>An Int</return>
  </function>

  <function name="CStr">
    <prototype>CStr(expr)</prototype>
    <parameter name="expr" value="A variable Int or Real" />
    <explain>
      Converts a real or int to a string.
    </explain>
    <return>A String</return>
  </function>

  <function name="Find">
    <prototype>Find(str, search, start)</prototype>
    <parameter name="str" value="The string to search in" />
    <parameter name="search" value="The string to search for" />
    <parameter name="start" value="The index to start searching at" />
    <explain>
      Returns the index of the first occurance of 'search' after 'start' within 'string'
    </explain>
    <return>An int</return>
  </function>

  <function name="Hex">
    <prototype>Hex(number)</prototype>
    <parameter name="number" value="The number to convert" />
    <explain>
      Returns the hexidecimal value of 'number'
    </explain>
    <return>A hexidecimal</return>
  </function>

  <function name="Len">
    <prototype>Len(str_or_array)</prototype>
    <parameter name="str_or_array" value="A string or array" />
    <explain>
      For strings, returns string length. For arrays, returns number of elements. Does not work for structs or dictionaries, use .size() for those.
    </explain>
    <return>An Int</return>
  </function>

  <function name="Lower">
    <prototype>Lower(str)</prototype>
    <parameter name="str"  value="A string to convert" />
    <explain>
      Converts 'string' to lowercase (doesn't work with high-ascii characters or unicode)
    </explain>
    <return>A string</return>
  </function>

  <function name="Pack">
    <prototype>Pack(expr)</prototype>
    <parameter name="expr" value="An object to pack" />
    <explain>
      Packs a variable into POL's packed data string format. Note that object references CANNOT be saved with the world, but may be passed to other running scripts, or with an event.
    </explain>
    <return>A string</return>
  </function>

  <function name="SizeOf">
    <prototype>SizeOf(obj)</prototype>
    <parameter name="obj" value="Any object" />
    <explain>
      Returns an estimate of the memory used in bytes.
    </explain>
    <return>An int</return>
  </function>

  <function name="SplitWords">
    <prototype>SplitWords( str, delimiter := " ", max_split := -1 )</prototype>
    <parameter name="str" value="The string to split" />
    <parameter name="delimiter" value="The delimiter to use" />
    <parameter name="max_split" value="Number of max splits. -1 = unlimited" />
    <explain>
      Returns an array of words contained in 'string'. Words are separated by the delimiter.
    </explain>
    <return>An array</return>
  </function>

  <function name="TypeOf">
    <prototype>TypeOf(expr)</prototype>
    <parameter name="expr" value="a script var" />
    <explain>
      Returns a string, depending on the variable type of the parameter. Is one of: "Dictionary", 
      "AccountRef", "ConfigFileRef", "ConfigElemRef", "DataFileRef", "DataElemRef", "ScriptExRef", "GuildRef", 
      "BoundingBox", "DebugContext", "Package", "MenuRef", "MobileRef", "OfflineMobileRef",
      "ItemRef", "BoatRef", "MultiRef", "Unknown", "Uninit", "String", "Integer", "Double", "Array", "ApplicPtr",
      "ApplicObj", "Error", "Struct", "Packet".
    </explain>
    <return>A string</return>
  </function>

  <function name="Unpack">
    <prototype>Unpack(str)</prototype>
    <parameter name="str" value="A string to unpack" />
    <explain>
      Unpacks a "packed data string" into the variable it represents. See Pack().
    </explain>
    <return>A variable</return>
  </function>

  <function name="Upper">
    <prototype>Upper(str)</prototype>
    <parameter name="str" value="A string to convert" />
    <explain>
      Converts 'string' to uppercase (doesn't work with high-ascii characters or unicode)
    </explain>
    <return>A string</return>
  </function>

  <function name="Bin">
    <prototype>Bin(number)</prototype>
    <parameter name="number" value="The number to convert" />
    <explain>
      Returns the binary coded value of 'number'
    </explain>
    <return>A binary coded number</return>
  </function>

  <function name="SubStr">
    <prototype>SubStr(str, start, length)</prototype>
    <parameter name="str" value="The string to search within" />
    <parameter name="start" value="The index to start getting the substring from" />
    <parameter name="length" value="The length of the substring" />
    <explain>
      Returns the substring of 'string' beginning at 'start' for 'length'. This functions the same as virtual Substrings within eScript such as String[4,6]
    </explain>
    <return>A String</return>
  </function>

  <function name="Compare">
    <prototype>Compare(str1, str2, pos1_start:=0, pos1_end:=0, pos2_start:=0, pos2_end:=0)</prototype>
    <parameter name="str1" value="First string to compare" />
    <parameter name="str2" value="Second string to compare" />
    <parameter name="pos1_start" value="The index to start from first string" />
    <parameter name="pos1_end" value="The index to end from first string" />
    <parameter name="pos2_start" value="The index to start from second string" />
    <parameter name="pos2_end" value="The index to end from second string" />
    <explain>
      Can be used in 3 overloaded ways. Returns 1 on compare success.
<code>
Compare(string1, string2)
Compare(string1, string2, string1_index, string1_length)
Compare(string1, string2, string1_index, string1_length, string2_index, string2_length)
</code>
Index is a starting position to begin the compare in the string, and length 
is the length to compare from the index. When using the 3rd method, 
you can compare substrings in both strings instead of just the 
substring of string1 to entire string2.
    </explain>
    <return>1 on compare success/0</return>
    <error>"Index must not be negative for param 1"</error>
    <error>"Index out of range for param 1"</error>
    <error>"Index must not be negative for param 2"</error>
    <error>"Index out of range for param 2"</error>
    <error>"Length out of range for param 1"</error>
    <error>"Length must not be negative for param 1"</error>
    <error>"Length out of range for param 2"</error>
    <error>"Length must not be negative for param 2"</error>
  </function>

  <function name="Trim">
    <prototype>Trim(str, type:=TRIM_BOTH, to_trim:=" ")</prototype>
    <parameter name="str" value="The string to trim" />
    <parameter name="type" value="The trim type to use" />
    <parameter name="to_trim" value="The string containing the character, or set of characters, to trim as whitespace" />
    <explain>Trims whitespaces from strings.</explain>
    <explain>basic.em constants for type value:
<code>
const TRIM_LEFT  := 0x1; // Trim whitespace from Left of string.
const TRIM_RIGHT := 0x2; // Trim whitespace from Right of string.
const TRIM_BOTH  := 0x3; // Trim whitespace from Left and Right of string.</code></explain>
    <return>A String</return>
  </function>

  <function name="StrReplace">
    <prototype>StrReplace(str, to_replace, replace_with)</prototype>
    <parameter name="str" value="The string to modify" />
    <parameter name="to_replace" value="The string to replace" />
    <parameter name="replace_with" value="The string to replace with" />
    <explain>Replace all instances of to_replace in the string with replace_with. </explain>
    <return>A String</return>
  </function>

  <function name="SubStrReplace">
    <prototype>SubStrReplace(str, replace_with, start, length:=0)</prototype>
    <parameter name="str" value="The string to modify" />
    <parameter name="replace_with" value="The string to replace" />
    <parameter name="start" value="Integer start index" />
    <parameter name="length" value="Integer length" />
    <explain>Replace portion of string using replace_with, beginning at start for length.</explain>
    <return>A String</return>
    <error>"Index must not be negative"</error>
    <error>"Index out of range"</error>
    <error>"Length out of range"</error>
    <error>"Length must not be negative"</error>
  </function>

  <function name="TypeOfInt">
    <prototype>TypeOfInt( expr )</prototype>
    <parameter name="expr" value="The string to parse" />
    <explain>returns Integer representation of TypeOf string.</explain>
    <return>An Integer</return>
  </function>

  <function name="PackJSON">
    <prototype>PackJSON( expr, prettify )</prototype>
    <parameter name="expr" value="An object to pack" />
    <parameter name="prettify" value="If true, prettify the output string" />
    <explain>Returns a JSON-serialization of the object to pack. If `prettify` is true, the output string will be indented with new lines.</explain>
    <explain>The following conversions are done:</explain>
    <explain>eScript -&gt; JSON</explain>
    <explain>double -&gt; number</explain>
    <explain>int -&gt; number</explain>
    <explain>string -&gt; string</explain>
    <explain>array -&gt; array</explain>
    <explain>struct -&gt; object</explain>
    <explain>dict -&gt; object</explain>
    <explain>bool -&gt; bool</explain>
    <explain>everything else -&gt; null</explain>
    <return>string</return>
  </function>

  <function name="UnpackJSON">
    <prototype>UnpackJSON( str )</prototype>
    <parameter name="str" value="A JSON serialized string" />
    <explain>Returns an eScript object representing the serialized JSON string.</explain>
    <explain>The following conversions are done:</explain>
    <explain>JSON -&gt; eScript</explain>
    <explain>number -&gt; double</explain>
    <explain>string -&gt; string</explain>
    <explain>array -&gt; array</explain>
    <explain>object-&gt; struct</explain>
    <explain>bool -&gt; bool</explain>
    <explain>null -&gt; uninitialized object</explain>
    <return>Any one of: double, string, array, struct, boolean, or uninit.</return>
  </function>
  
  <function name="Boolean">
    <prototype>Boolean( number )</prototype>
	<parameter name="number" value="1/0" />
    <explain>Converts a number to an boolean value.</explain>
    <return>Returns an Boolean object.</return>
  </function>

  <function name="EncodeBase64">
    <prototype>EncodeBase64( str )</prototype>
    <parameter name="str" value="a string" />
    <explain>Returns a base64 encoded string string.</explain>
    <return>A String</return>
  </function>

  <function name="DecodeBase64">
    <prototype>DecodeBase64( str )</prototype>
    <parameter name="str" value="a string" />
    <explain>Takes a base64 encoded string and converts it back to standard.</explain>
    <return>A String</return>
  </function>
  
  
</ESCRIPT>