Index : Reference :

general_functions

General functions.

Note: See also Basic Functions

Definition

global general_functions
{
public:

  //General functions
  bool CallButton(BaseList2D bl, int id);
  int TextDialog(string text, int flags);
  float evaluate(string expression);
  void throw(anytype exception);
  int time();
  void gc();


  //Class and type functions
  anytype new(class class,  ...);
  void super( ...);
  class getclass(object obj);
  class getparent(class class);
  bool instanceof(object obj, class class);
  int typeof(anytype object);
  int sizeof(anytype object);


  //Cast functions
  int int(float x);
  float float(int x);
  vector vector(anytype x, anytype y, anytype z);
  vector vector(anytype a);
  string tostring(anytype x, string format);


  //IEE conversion functions
  float mem2iee(bytes mem, int pos, int byteorder);
  float mem2liee(bytes mem, int pos, int byteorder);
  int mem2long(bytes mem, int pos, int byteorder);
  int mem2uword(bytes mem, int pos, int byteorder);
  int mem2word(bytes mem, int pos, int byteorder);
  bytes memadd(bytes mem,  ...);
  bytes memins(bytes mem1, bytes mem2, int pos);
  int memmem(bytes mem, bytes phrase, int pos);
  bytes memmid(bytes mem, int pos, int len);
  bytes memset(bytes mem, int byte, int pos, int num);
  bool uword2mem(int value, bytes mem, int pos, int byteorder);
  bool word2mem(int value, bytes mem, int pos, int byteorder);
  bool iee2mem(float value, bytes mem, int pos, int byteorder);
  bool liee2mem(float value, bytes mem, int pos, int byteorder);
  bool long2mem(float value, bytes mem, int pos, int byteorder);


  //Char functions
  bool isalnum(int char);
  bool isalpha(int char);
  bool isdigit(int char);
  bool isdigit(int char);
  bool isspace(int char);
  bool ispunct(int char);


  //String functions
  string stradd(string str,  ...);
  string strchr(string str, int chr, int pos);
  string strcmp(string str1, string str2);
  string strins(string str1, string str2, int pos);
  string strmid(string str, int pos, int len);
  string strset(string str, int char, int pos, int num);
  int strstr(string str, string phrase, int pos);


  //Console print
  void print(anytype str,  ...);
  void println(anytype str,  ...);


  //Event functions
  void EventAdd(int flags);
  bool SpecialEventAdd(int messageid, int p1, int p2);
  bool SendPluginMessage(BaseContainer msg);
  bool SendPluginMessage(int id, BaseContainer msg);


  //Easy access functions
  BaseObject object(int index);
  BaseTag tag(int index);
  BaseList2D tool();
  RenderData renderdata();
};

Members

bool CallButton(BaseList2D bl, int id)

Button call, the same as clicking a button in the user interface.

Return
bool

TRUE if successful, otherwise FALSE.

Parameters
BaseList2D bl

The object the button belongs to, basically everything that can be displayed in the Attribute Manager.

int id

The ID of the button. Check the resource files for valid IDs.

int TextDialog(string text, int flags)

Opens a simple text dialog, with a selectable icon and some standard buttons.



Example:
  
  // Opens the above dialog with an exclamation mark icon
  var result = TextDialog("Hello World!", DLG_OKCANCEL + DLG_ICONEXCLAMATION);
  
  // Checks the result
  if (result == DLG_R_OK)
  {
    TextDialog("You pressed OK!", DLG_OK);
  }
  

Return
int

The possible return values are, depending on the selected type:

Constant Description

DLG_R_OK

OK clicked

DLG_R_CANCEL

Cancel clicked

DLG_R_ABORT

Abort clicked

DLG_R_RETRY

Retry clicked

DLG_R_IGNORE

Ignore clicked

DLG_R_YES

Yes clicked

DLG_R_NO

No clicked


Parameters
string text

This parameter controls what text is shown.

int flags

The following flags control what combination of buttons is shown:

Constant Description

DLG_OK

OK

DLG_OKCANCEL

OK and Cancel

DLG_ABORTRETRYIGNORE

Abort, Retry and Ignore

DLG_YESNOCANCEL

Yes, No and Cancel

DLG_YESNO

Yes and No

DLG_RETRYCANCEL

Retry and Cancel




They can be combined with the following constants to display an icon:

Constant Description

DLG_ICONSTOP

A stop sign icon

DLG_ICONQUESTION

A question mark icon

DLG_ICONEXCLAMATION

An exclamation mark icon

DLG_ICONASTERISK

An asterisk icon


float evaluate(string expression)

Evaluates a string expression to a numeric value.

Example:
  
  // Outputs "2.500000".
  
  var str = "2.5";
  var x = evaluate(str);
  
  println(x);
  
  
  // Outputs "6.999624".
  
  var str = "2.0 * cos(Pi/4)^2 + 5";
  var x = evaluate(str);
  
  println(x);
  

Return
float

evaluate() evaluates the string expression as a mathematic expression and returns the result as a float. The command handles all the mathematical operators and commands that are allowed in regular CINEMA 4D fields (for example the Coordinates Manager).

If the expression cannot be parsed, or if there is a division by zero, the return value is nil.

Parameters
string expression

expression is a string containing a mathematical expression.

void throw(anytype exception)

Throws an exception.

throw() throws an exception that can be caught and handled with try and catch.

Example:
  
  const var ExSnAFu = 1001;
  
  try
  {
    throw(ExSnAFu);
  }
  catch(ExSnAFu)
  {
    // Do something
  }
  


Note: See also try, catch

Parameters
anytype exception

The exception can be of any type, but normally integer constants are used.

int time()

Returns the time since the program was started.

Example:
  
  // Outputs "CINEMA 4D was started 1927752 seconds ago."
  // (Yes, it *is* a stable program... :-)
  
  println("CINEMA 4D was started ",time()/1000," seconds ago.");
  
  
  // time() can be used to profile the speed of an algorithm.
  //
  // Outputs "Each loop took 0.00012 seconds.".
  
  var i,starttime,endtime,num;
  
  num = 2000.0;
  starttime = time();
  
  for (i=0;i<num;i++)
  {
    // Do some stuff
  }
  
  endtime = time();
  
  println("Each loop took ",(endtime-starttime)/num/1000.0," seconds.");
  
  
  // time() can also be used as seed for the random number
  // generator, when total randomness is wanted.
  
  var random = new(Random);
  random->Init(time());
  


Note: See also Random

Return
int

time() returns the number of milliseconds since CINEMA 4D was started.

void gc()

Triggers garbage collection.

Example:
  
  // The memory allocated for the array is freed.
  
  var a = new(array,1000000);
  a = NULL;
  
  gc();
  

anytype new(class class, ...)

Allocates strings, arrays and byte arrays as well as instances of classes and structures.

Example:
  
  // Allocates a string of length 5.
  
  var str = new(string,5);
  
  
  // Allocates a two-dimensional array of 6 x 7.
  
  var a = new(array,6,7);
  
  
  // Allocates a byte array of length 8.
  
  var mem = new(bytes,8);
  
  
  // Allocates an instance of the structure Complex
  // with real=3 and imag=5.
  
  struct Complex
  {
    var real,imag;
    
    Complex(_real,_imag);
  }
  
  Complex::Complex(_real,_imag)
  {
    real = _real;
    imag = _imag;
  }
  
  var c = new(Complex,3,5);
  
  
  // Allocates an instance of the class myClass.
  
  class myClass
  {
  public:
    myClass(); // Constructor
  }
  
  myClass::myClass()
  {
    // Do stuff
  }
  
  var object = new(myClass);
  


Note: See also var

Return
anytype

new() is the universal allocation function in C.O.F.F.E.E. It allocates an instance of class and passes any additional parameters to the object's constructor. The new() command is used both for classes and structures and for strings, arrays and byte arrays. It returns a reference to the allocated object.

Parameters
class class

The name of the class to be allocated.

...

One or more additional parameters separated by commas

void super( ...)

Calls the constructor of the parent class.

super() should be called at the first line of the constructor of a derived class to run the constructor of the parent class. The parameters are the same as one would pass to the parent if it were allocated with new.

Example:
  
  // myClass calls the constructor of its parent, myParent,
  // and passes its parameter value along using super(x).
  // The parent's constructor then sets its own variable
  // value to x.
  
  class myParent
  {
  private:
    var value;
  public:
    myParent(x);
  }
  
  myParent::myParent(x)
  {
    value = x;
  }
  
  
  class myClass : myParent
  {
  public:
    myClass(x); // Constructor
  }
  
  myClass::myClass(x)
  {
    super(x); // Calls the parent constructor
  }
  
  
  var a = 10.0;
  var obj = new(myClass,a);
  


Note: See also class

Parameters
...

One or many parameters separated by commas.

class getclass(object obj)

Gives the class of an object.

Example:
  
  // Outputs "getclass(obj) = [Class-myClass]".
  
  class myClass
  {
  public:
    myClass(); // Constructor
  }
  
  myClass::myClass()
  {
    // Do stuff
  }
  
  var obj = new(myClass);
  println("getclass(obj) = ",getclass(obj));
  
  
  // getclass() can be used to see if an object is
  // of a certain class. Here are some ways:
  
  if (getclass(obj)==getclass(other_obj))
    doStuff();
    
  if (getclass(obj)==myClass)
    doStuff();
    
  if (instanceof(obj,getclass(other_obj)))
    doStuff();
  
  
  // The returned class can also be instanced itself.
  //
  // Outputs "getclass(new_obj) = [Class-myClass]".
  
  var new_obj = new(getclass(obj));
  println("getclass(new_obj) = ",getclass(new_obj));
  


Note: See also getparent(), instanceof()

Return
class

getclass() returns the class of obj.

Parameters
object obj

obj is an instanced object of a class.

class getparent(class class)

Gives the parent class of a derived class.

Example:
  
  // Outputs "getparent(myClass) = [Class-myParent]
  //          getparent(getclass(obj)) = [Class-myParent]".
  
  class myParent
  {
  public:
    myParent();
  }
  
  myParent::myParent()
  {
    // Do stuff
  }
  
  
  class myClass : myParent
  {
  public:
    myClass(); // Constructor
  }
  
  myClass::myClass()
  {
    super(); // Calls the parent constructor
  }
  
  
  var obj = new(myClass);
  println("getparent(getclass(obj)) = ",getparent(getclass(obj)));
  println("getparent(myClass) = ",getparent(myClass));
  


Note: See also getclass(), instanceof()

Return
class

getparent() returns the parent class of class, that is the class that class was derived from. If class has no parent, the return value is nil.

Parameters
class class

class is a derived class.

bool instanceof(object obj, class class)

Tells if an object is an instance of a certain class.

Example:
  
  // Outputs "instanceof(obj,myClass) = 1".
  
  class myClass
  {
  public:
    myClass(); // Constructor
  }
  
  myClass::myClass()
  {
    // Do stuff
  }
  
  var obj = new(myClass);
  println("instanceof(obj,myClass) = ",instanceof(obj,myClass));
  


Note: See also getparent(), getclass()

Return
bool

instanceof() returns TRUE if obj is of class class, that is if getclass(obj)==class. Otherwise the return value is FALSE.

Parameters
object obj

An instances object of a class.

class class

A class.

int typeof(anytype object)

Gives the type of an object or variable.

Example:
  
  // Outputs "5.500000 is a float.".
  
  int_or_float(x)
  {
    switch(typeof(x))
    {
      case DT_INT:
        return "an integer";
      
      case DT_FLOAT:
        return "a float";
      
      default:
        return "unknown";
    }
  }
  
  var x = 5.5;
  
  println(x," is ",int_or_float(x),".");
  


Note: See also sizeof()

Return
int

typeof() returns the type of object as an integer. This value can be interpreted with the following enumerated constants:

- Constant Label Explanation

Common

DT_NIL

nil

nil

DT_LONG

int

integer

DT_FLOAT

float

floating point

N/A

bool

boolean (either TRUE or FALSE)

DT_VECTOR

vector

vector

DT_VOID

void

void pointer (C/C++)

DT_BYTES

bytes

byte array

DT_STRING

string

string

DT_CLASS

class

class

DT_OBJECT

object

object

DT_ARRAY

array

array

Executable

DT_BYTECODE

bytecode

C.O.F.F.E.E. bytecode

DT_CODE

code

internal C/C++ code

DT_EXTCODE

extcode

external C/C++ code

Other

DT_EXCEPTION

exception

catchable exception

DT_SEXCEPTION

sexception

system exception

DT_INSTANCE

instance

C.O.F.F.E.E. instance

Parameters
anytype object

Any object or variable.

int sizeof(anytype object)

Gives the number of elements in a string, byte array or array.

Example:
  
  // Outputs "sizeof(str) = 12
  //          sizeof(mem) = 7
  //          sizeof(arr) = 20"
  
  var str = "Hello World!";
  var mem = new(bytes,7);
  var arr = new(array,20);
  
  println("sizeof(str) = ",sizeof(str));
  println("sizeof(mem) = ",sizeof(mem));
  println("sizeof(arr) = ",sizeof(arr));
  


Note: See also typeof(), string, bytes, array

Return
int

sizeof() returns the size of object, that is how many elements there are in it. If object is not a string, byte array or array the return value is nil.

Parameters
anytype object

A string, byte array or array.

int int(float x)

Casts a variable to an integer.

Example:
  
  // Outputs "int(x) = 4".
  
  var x = 4.7;
  var a = int(x);
  
  println("int(x) = ",a);
  
  
  // Rounding can be implemented by adding 0.5
  // to the value before calling int().
  //
  // Outputs "round(x) = 5".
  
  round(x)
  {
    return int(x + 0.5);
  }
  
  var x = 4.7;
  var a = round(x);
  
  println("round(x) = ",a);
  


Note: See also float()

Return
int

int() returns the integer part of x cast to an integer. No rounding occurs. Any decimals are omitted.

Parameters
float x

x is a numeric value.

float float(int x)

Casts a variable to a float.

Example:
  
  // Outputs "float(x) = 47.0000000".
  
  var x = 47;
  var a = float(x);
  
  println("float(x) = ",a);
  
  
  // Casting a variable to a float is needed if both
  // variables in a division are integers.
  //
  // Outputs "int: 0  float: 0.571428571".
  
  var x = 4;
  var y = 7;
  
  var a = x/y;
  var b = float(x)/float(y);
  
  println("int: ",a,"  float: ",b");
  


Note: See also int()

vector vector(anytype x, anytype y, anytype z)

vector vector(anytype a)

Returns a three-dimensional vector. The vector is filled with the three passed parameters, one for each element of the vector. If only one parameter is passed, all three elements are filled with it. The parameters are automatically cast to floats.

Example:
  
  // Outputs "v1 = [1.0000,2.0000,3.0000]
  //          v2 = [4.7000,4.7000,4.7000]".
  
  var v1 = vector(1.0,2.0,3.0);
  var v2 = vector(4.7);
  
  println("v1 = ",v1);
  println("v2 = ",v2);
  
  
  // The elements of a vector are accessed with x, y and z.
  //
  // Outputs "x: 1.0000  y: 2.0000  z: 3.0000".
  
  var v1 = vector(1.0,2.0,3.0);
  
  var a = v1.x;
  var b = v1.y;
  var c = v1.z;
  
  println("x: ",a,"  y: ",b,"  z: ",c);
  


Note: See also vlen(), vnorm(), vcross()

string tostring(anytype x, string format)

Converts a variable of any type to a string.

Example:
  
  // Outputs the table above.
  //
  // (N.B. Actually tostring() isn't needed since println()
  // automatically converts its parameters to strings!)
  
  var a = 894716;
  var b = 16.847;
  var c = vector(13.756,78.137,44.863);
  var d = "Hello World";
  
  println("int     ",tostring(a));
  println("float   ",tostring(b));
  println("vector  ",tostring(c));
  println("string  ",tostring(d));
  
  
  // A common use of tostring() is in conjunction with stradd(), when
  // preparing a message to the user, if all types aren't strings.
  //
  // Displays "There are 47 items.".
  
  var n = 47;
  
  var message = stradd("There are ",tostring(n)," items.");
  TextDialog(message);
  
  
  // Some examples of using the formatting string.
  // See a C printf documentation for more information.
  
  // Four digits hexadecimal. Outputs "20F8".
  println(tostring(8440,"04X"));
  
  // Three decimals float. Outputs "47.500".
  println(tostring(47.5,".3f"));
  
  // Three decimals with exponent. Outputs "1.846e+007".
  println(tostring(18461947.23,".3e"));
  


Note: See also string

Return
string

tostring() returns the parameter x converted to a string. The different types are by default formatted as below:

Type Example

int

894716

float

16.847000

vector

[13.756000,78.137000,44.863000]

string

Hello World



All other types are written between brackets, like this: [Array-1e50e14].

Optionally, integers and floats (not vectors) can be formatted using the format string. The formatting syntax is similar to the format field in the C function printf().

Parameters
anytype x

A value of any type.

string format

An optional string that specifies the formatting.

float mem2iee(bytes mem, int pos, int byteorder)

Converts a 32 bit IEE float at a certain position in a byte array into a C.O.F.F.E.E. float.

mem2iee() converts 4 bytes from position pos in the byte array mem as a 32 bit IEE float and returns the result as a float value. The byte ordering is decided by the value of the byteorder parameter.

An IEE float consists of 1 sign bit (0 = positive and 1 = negative), 8 bits for the exponent (unsigned but biased with 127) and 23 bits for the mantissa (a binary fraction with an implied leading 1).

Remember: The first element of a byte array is at position 0.

Example:
  
  // Outputs "18467.447266"
  
  var mem = new(bytes,4);
  
  mem[0]=0x46;
  mem[1]=0x90;
  mem[2]=0x46;
  mem[3]=0xE5;
  
  var motorola = mem2iee(mem,0,GE_MOTOROLA);
  println(motorola);
  
  
  // Outputs "18461.947266"
  
  var mem = new(bytes,4);
  
  mem[0]=0xE5;
  mem[1]=0x3B;
  mem[2]=0x90;
  mem[3]=0x46;
  
  var intel = mem2iee(mem,0,GE_INTEL);
  println(intel);
  


Note: See also bytes, mem2word(), mem2uword(), mem2long(), mem2liee(), word2mem(), uword2mem(), iee2mem(), liee2mem(), long2mem()

Return
float

mem2iee() converts 4 bytes from position pos in the byte array mem as a 32 bit IEE float and returns the result as a float value.

Parameters
bytes mem

A byte array.

int pos

The position within mem.

int byteorder

Either Big Endian or Little Endian.

Constant Description

GE_MOTOROLA

big endian (Motorola)

GE_INTEL

little endian (Intel)


float mem2liee(bytes mem, int pos, int byteorder)

Converts a 64 bit IEE double float at a certain position in a byte array into a C.O.F.F.E.E. float.

mem2liee() converts 8 bytes from position pos in the byte array mem as a 64 bit IEE double float and returns the result as a float value. The byte ordering is decided by the value of the byteorder parameter.

An IEE double float consists of 1 sign bit (0 = positive and 1 = negative), 11 bits for the exponent (unsigned but biased with 1023) and 52 bits for the mantissa (a binary fraction with an implied leading 1).

Remember: The first element of a byte array is at position 0.

Example:
  
  // Outputs "18461.947266"
  
  var mem = new(bytes,8);
  
  mem[0]=0x40;
  mem[1]=0xD2;
  mem[2]=0x07;
  mem[3]=0x7C;
  mem[4]=0xA0;
  mem[5]=0x00;
  mem[6]=0x00;
  mem[7]=0x00;
  
  var motorola = mem2liee(mem,0,GE_MOTOROLA);
  println(motorola);
  
  
  // Outputs "18461.947266"
  
  var mem = new(bytes,8);
  
  mem[0]=0x00;
  mem[1]=0x00;
  mem[2]=0x00;
  mem[3]=0xA0;
  mem[4]=0x7C;
  mem[5]=0x07;
  mem[6]=0xD2;
  mem[7]=0x40;
  
  var intel = mem2liee(mem,0,GE_INTEL);
  println(intel);
  


Note: See also bytes, mem2word(), mem2uword(), mem2long(), mem2iee(), word2mem(), uword2mem(), iee2mem(), liee2mem(), long2mem()

Return
float

Converts a 64 bit IEE double float at a certain position in a byte array into a C.O.F.F.E.E. float.

Parameters
bytes mem

A byte array.

int pos

The position within mem.

int byteorder

Either Big Endian or Little Endian.

Constant Description

GE_MOTOROLA

big endian (Motorola)

GE_INTEL

little endian (Intel)


int mem2long(bytes mem, int pos, int byteorder)

Converts a 32 bit signed long int at a certain position in a byte array into a C.O.F.F.E.E. integer.

mem2long() converts 4 bytes from position pos in the byte array mem as a 32 bit signed long int and returns the result as an integer value. The byte ordering is decided by the value of the byteorder parameter.

Remember: The first element of a byte array is at position 0.

Example:
  
  // Outputs "0xF00B1201 = -267709951
  //          0x01120BF0 = 17959920".
  
  var mem = new(bytes,4);
  
  mem[0] = 0xF0;
  mem[1] = 0x0B;
  mem[2] = 0x12;
  mem[3] = 0x01;
  
  var motorola = mem2long(mem,0,GE_MOTOROLA);
  var intel = mem2long(mem,0,GE_INTEL);
  
  println("0xF00B1201 = ",motorola);
  println("0x01120BF0 = ",intel);
  


Note: See also bytes, mem2word(), mem2uword(), mem2iee(), mem2liee(), word2mem(), uword2mem(), iee2mem(), liee2mem(), long2mem()

Return
int

mem2long() converts 4 bytes from position pos in the byte array mem as a 32 bit signed long int and returns the result as an integer value.

Parameters
bytes mem

A byte array.

int pos

The position within mem.

int byteorder

Either Big Endian or Little Endian.

Constant Description

GE_MOTOROLA

big endian (Motorola)

GE_INTEL

little endian (Intel)


int mem2uword(bytes mem, int pos, int byteorder)

Converts a 16 bit unsigned short int word at a certain position in a byte array into a C.O.F.F.E.E. integer.

mem2uword() converts 2 bytes from position pos in the byte array mem as a 16 bit unsigned short int word and returns the result as an integer value. The byte ordering is decided by the value of the byteorder parameter.

Remember: The first element of a byte array is at position 0.

Example:
  
  // Outputs "0xF00B = 61451
  //          0x0BF0 = 3056".
  
  var mem = new(bytes,2);
  
  mem[0] = 0xF0;
  mem[1] = 0x0B;
  
  var motorola = mem2uword(mem,0,GE_MOTOROLA);
  var intel = mem2uword(mem,0,GE_INTEL);
  
  println("0xF00B = ",motorola);
  println("0x0BF0 = ",intel);
  


Note: See also bytes, mem2word(), mem2iee(), mem2liee(), word2mem(), uword2mem(), iee2mem(), liee2mem(), long2mem()

Return
int

mem2uword() converts 2 bytes from position pos in the byte array mem as a 16 bit unsigned short int word and returns the result as an integer value.

Parameters
bytes mem

A byte array.

int pos

The position within mem.

int byteorder

Either Big Endian or Little Endian.

Constant Description

GE_MOTOROLA

big endian (Motorola)

GE_INTEL

little endian (Intel)


int mem2word(bytes mem, int pos, int byteorder)

Converts a 16 bit signed short int word at a certain position in a byte array into a C.O.F.F.E.E. integer.

mem2word() converts 2 bytes from position pos in the byte array mem as a 16 bit signed short int word and returns the result as an integer value. The byte ordering is decided by the value of the byteorder parameter.

Remember: The first element of a byte array is at position 0.

Example:
  
  // Outputs "0xF00B = -4085
  //          0x0BF0 = 3056".
  
  var mem = new(bytes,2);
  
  mem[0] = 0xF0;
  mem[1] = 0x0B;
  
  var motorola = mem2word(mem,0,GE_MOTOROLA);
  var intel = mem2word(mem,0,GE_INTEL);
  
  println("0xF00B = ",motorola);
  println("0x0BF0 = ",intel);
  


Note: See also bytes, mem2uword(), mem2iee(), mem2liee(), word2mem(), uword2mem(), iee2mem(), liee2mem(), long2mem()

Return
int

mem2word() converts 2 bytes from position pos in the byte array mem as a 16 bit signed short int word and returns the result as an integer value.

Parameters
bytes mem

A byte array.

int pos

The position within mem.

int byteorder

Either Big Endian or Little Endian.

Constant Description

GE_MOTOROLA

big endian (Motorola)

GE_INTEL

little endian (Intel)


bytes memadd(bytes mem, ...)

Creates a new byte array that contains all the byte arrays that are passed.

Example:
  
  // See also the examples for stradd().
  
  // The resulting byte array will look like this:
  // 0x01 x 100 bytes, 0x02 x 200 bytes
  
  var mem1 = new(array,100); // Allocate 100 bytes
  var mem2 = new(array,200); // Allocate 200 bytes
  
  mem1 = memset(mem1,0x01,0,100); // Fill mem1 with 1's
  mem2 = memset(mem2,0x02,0,200); // Fill mem2 with 2's
  
  var result = memadd(mem1,mem2);
  


Note: See also bytes, memins(), memset(), memmid(), memmem()

Return
bytes

memadd() returns a byte array containing all the passed byte arrays joined together in order.

Parameters
bytes mem

A byte array.

...

One or many byte arrays, separated by commas.

bytes memins(bytes mem1, bytes mem2, int pos)

Inserts a byte array at a given position in another.

Example:
  
  // See also the examples for strins().
  
  // The resulting byte array will look like this:
  // 0x01 x 100 bytes, 0x02 x 300 bytes, 0x01 x 100 bytes
  
  var mem1 = new(bytes,500); // Allocate 500 bytes
  var mem2 = new(bytes,300); // Allocate 300 bytes
  
  mem1 = memset(mem1,0x01,0,500); // Fill mem1 with 1's
  mem2 = memset(mem2,0x02,0,300); // Fill mem2 with 2's
  
  var result = memins(mem1,mem2,100);
  


Note: See also bytes, memset(), memmid(), memadd(), memmem()

Return
bytes

memins() returns a copy of the byte array mem1 where the byte array mem2 has been inserted at the position pos. The parts of mem1 that are covered by mem2 are replaced. The length of the result is the same as the length of mem1, so if mem2 is too long it will be truncated. The insertion position pos can be negative.

Parameters
bytes mem1

Tthe original byte array

bytes mem2

Tthe byte array that's inserted into mem1.

int pos

The insertion position within mem1.

int memmem(bytes mem, bytes phrase, int pos)

Locates the first occurrence of a phrase of bytes within another byte array, optionally beginning the search at a certain position.

Example:
  
  // See also the examples for strstr().
  
  // Locates and extracts an element in a data file.
  
  var file = loadDataFile();
  
  var signature = getElementSignature();
  var length = getElementLength();
  
  var pos = memmem(file,signature);
  var element = memmid(file,pos,length);
  


Note: See also bytes, memins(), memset(), memmid(), memadd()

Return
int

memmem() returns the position of the first occurence of phrase within the byte array mem. If the third parameter is passed, only the part of mem that is after the position pos is searched. If no match is found, the return value is -1.

Remember: The first element of a byte array is at position 0.

Parameters
bytes mem

The byte array.

bytes phrase

The search phrase.

int pos

The optional start position of the search.

bytes memmid(bytes mem, int pos, int len)

Creates a new byte array that contains an extract from another byte array, specified by the starting position within the original byte array and the length of the result.

Example:
  
  // See also the examples for strmid().
  
  // The resulting byte array will be 100 bytes long
  // and go from 0x2E to 0x91 (46 to 145).
  
  var i,mem = new(bytes,256);          // Allocates 256 bytes
  for (i=0x00;i<=0xFF;i++) mem[i] = i; // Fills the byte array from 0x00 to 0xFF
  
  var result = memmid(mem,0x2E,100);
  


(a better example is welcome)


Note: See also bytes, memins(), memset(), memadd(), memmem()

Return
bytes

memmid() returns a byte array containing an extract from mem, starting at position pos and with the length len. If the extract goes outside the original string, for example if len is bigger than the length of the byte array, it will be truncated. This means that the length of the returned byte array doesn't always equal len. The starting position pos can be negative.

Remember: The first element of a byte array is at position 0.

Parameters
bytes mem

The original byte array.

int pos

The starting position of the extract from mem.

int len

The length of the extract. (len >= 0)

bytes memset(bytes mem, int byte, int pos, int num)

Fills a specified number of bytes in a byte array from a given position with a certain byte.

Example:
  
  // See also the examples for strset().
  
  // The resulting byte array will be filled with FF's.
  
  var mem = new(bytes,512);
  
  var result = memset(mem,0xFF,0,512);
  


Note: See also bytes, memins(), memmid(), memadd(), memmem()

Return
bytes

memset() returns a copy of mem that is filled from position pos to position pos+num with the integer byte. The length of the return value is always the length of mem. If any position of the specified fill interval is outside of mem, for example if pos+num is greater than the length of mem, it is simply disregarded. The starting position pos can be negative.

Hexadecimal numbers are written like this: 0xEF = 239.

Remember: The first element of a byte array is at position 0.

Parameters
bytes mem

The original byte array.

int byte

The byte to fill with.

int pos

The starting position of the filling.

int num

The number of times that the byte is repeated. (num >= 0)

bool uword2mem(int value, bytes mem, int pos, int byteorder)

Converts an integer variable into a 16 bit unsigned short int word and inserts it at a certain position in a byte array.

uword2mem() converts value into a 16 bit unsigned short int word and inserts it at the position pos in the byte array mem. The 2 bytes that are at position pos are overwritten. The byte ordering is decided by the value of the byteorder parameter.

Remember: The first element of a byte array is at position 0.

Example:
  
  // Outputs "Motorola: 45524 => B1D4
  //          Intel:    45524 => D4B1".
  
  var mem = new(bytes,2);
  var x = 45524;
  
  // Motorola
  uword2mem(x,mem,0,GE_MOTOROLA);
  println("Motorola: 45524 => ",tostring(mem[0],"02X"),
                                tostring(mem[1],"02X"));
  
  // Intel
  uword2mem(x,mem,0,GE_INTEL);
  println("Intel:    45524 => ",tostring(mem[0],"02X"),
                                tostring(mem[1],"02X"));
  


Note: See also bytes, mem2word(), mem2uword(), mem2long(), mem2iee(), mem2liee(), word2mem(), long2mem(), iee2mem(), liee2mem()

Return
bool

The function returns TRUE if the operation was successful. Otherwise it returns FALSE.

Parameters
int value

An int value.

bytes mem

A byte array.

int pos

The position within mem.

int byteorder

Either Big Endian or Little Endian.

Constant Description

GE_MOTOROLA

big endian (Motorola)

GE_INTEL

little endian (Intel)


bool word2mem(int value, bytes mem, int pos, int byteorder)

Converts an integer variable into a 16 bit signed short int word and inserts it at a certain position in a byte array.

word2mem() converts value into a 16 bit signed short int word and inserts it at the position pos in the byte array mem. The 2 bytes that are at position pos are overwritten. The byte ordering is decided by the value of the byteorder parameter.

Remember: The first element of a byte array is at position 0.

Example:
  
  // Outputs "Motorola: 1524 => 05F4
  //          Intel:    1524 => F405".
  
  var mem = new(bytes,2);
  var x = 1524;
  
  // Motorola
  word2mem(x,mem,0,GE_MOTOROLA);
  println("Motorola: 1524 => ",tostring(mem[0],"02X"),
                               tostring(mem[1],"02X"));
  
  // Intel
  word2mem(x,mem,0,GE_INTEL);
  println("Intel:    1524 => ",tostring(mem[0],"02X"),
                               tostring(mem[1],"02X"));
  


Note: See also bytes, mem2word(), mem2uword(), mem2long(), mem2iee(), mem2liee(), uword2mem(), long2mem(), iee2mem(), liee2mem()

Return
bool

The function returns TRUE if the operation was successful. Otherwise it returns FALSE.

Parameters
int value

An int value.

bytes mem

A byte array.

int pos

The position within mem.

int byteorder

Either Big Endian or Little Endian.

Constant Description

GE_MOTOROLA

big endian (Motorola)

GE_INTEL

little endian (Intel)


bool iee2mem(float value, bytes mem, int pos, int byteorder)

Converts a float variable into a 32 bit IEE float and inserts it at a certain position in a byte array.

iee2mem() converts value into a 32 bit IEE float and inserts it at the position pos in the byte array mem. The 4 bytes that are at position pos are overwritten. The byte ordering is decided by the value of the byteorder parameter.

An IEE float consists of 1 sign bit (0 = positive and 1 = negative), 8 bits for the exponent (unsigned but biased with 127) and 23 bits for the mantissa (a binary fraction with an implied leading 1).

Remember: The first element of a byte array is at position 0.

Example:
  
  // Outputs "Motorola: 1826.5912 => 44E444EB
  //          Intel:    1826.5912 => EB52E444".
  
  var mem = new(bytes,4);
  var x = 1826.5912;
  
  // Motorola
  iee2mem(x,mem,0,GE_MOTOROLA);
  println("Motorola: 1826.5912 => ",tostring(mem[0],"02X"),
                                    tostring(mem[1],"02X"),
                                    tostring(mem[2],"02X"),
                                    tostring(mem[3],"02X"));
  
  // Intel
  iee2mem(x,mem,0,GE_INTEL);
  println("Intel:    1826.5912 => ",tostring(mem[0],"02X"),
                                    tostring(mem[1],"02X"),
                                    tostring(mem[2],"02X"),
                                    tostring(mem[3],"02X"));
  


Note: See also bytes, mem2word(), mem2uword(), mem2long(), mem2iee(), mem2liee(), word2mem(), uword2mem(), long2mem(), liee2mem()

Return
bool

The function returns TRUE if the operation was successful. Otherwise it returns FALSE.

Parameters
float value

A float value

bytes mem

A byte array

int pos

The position within mem

int byteorder

Either Big Endian or Little Endian.

Constant Description

GE_MOTOROLA

big endian (Motorola)

GE_INTEL

little endian (Intel)


bool liee2mem(float value, bytes mem, int pos, int byteorder)

Converts a float variable into a 64 bit IEE double float and inserts it at a certain position in a byte array.

liee2mem() converts value into a 64 bit IEE double float and inserts it at the position pos in the byte array mem. The 8 bytes that are at position pos are overwritten. The byte ordering is decided by the value of the byteorder parameter.

An IEE double float consists of 1 sign bit (0 = positive and 1 = negative), 11 bits for the exponent (unsigned but biased with 1023) and 52 bits for the mantissa (a binary fraction with an implied leading 1).

Remember: The first element of a byte array is at position 0.

Example:
  
  // Outputs "Motorola: 1421826.5912 => 4135B202A0000000
  //          Intel:    1421826.5912 => 000000A002B23541".
  
  var mem = new(bytes,8);
  var x = 1421826.5912;
  
  // Motorola
  liee2mem(x,mem,0,GE_MOTOROLA);
  println("Motorola: 1421826.5912 => ",tostring(mem[0],"02X"),
                                       tostring(mem[1],"02X"),
                                       tostring(mem[2],"02X"),
                                       tostring(mem[3],"02X"),
                                       tostring(mem[4],"02X"),
                                       tostring(mem[5],"02X"),
                                       tostring(mem[6],"02X"),
                                       tostring(mem[7],"02X"));
  
  // Intel
  liee2mem(x,mem,0,GE_INTEL);
  println("Intel:    1421826.5912 => ",tostring(mem[0],"02X"),
                                       tostring(mem[1],"02X"),
                                       tostring(mem[2],"02X"),
                                       tostring(mem[3],"02X"),
                                       tostring(mem[4],"02X"),
                                       tostring(mem[5],"02X"),
                                       tostring(mem[6],"02X"),
                                       tostring(mem[7],"02X"));
  


Note: See also bytes, mem2word(), mem2uword(), mem2long(), mem2iee(), mem2liee(), word2mem(), uword2mem(), long2mem(), iee2mem()

Return
bool

The function returns TRUE if the operation was successful. Otherwise it returns FALSE.

Parameters
float value

A float value

bytes mem

A byte array

int pos

The position within mem

int byteorder

Either Big Endian or Little Endian.

Constant Description

GE_MOTOROLA

big endian (Motorola)

GE_INTEL

little endian (Intel)


bool long2mem(float value, bytes mem, int pos, int byteorder)

Converts an integer variable into a 32 bit signed long int and inserts it at a certain position in a byte array.

long2mem() converts value into a 32 bit signed long int and inserts it at the position pos in the byte array mem. The 4 bytes that are at position pos are overwritten. The byte ordering is decided by the value of the byteorder parameter.

An IEE double float consists of 1 sign bit (0 = positive and 1 = negative), 11 bits for the exponent (unsigned but biased with 1023) and 52 bits for the mantissa (a binary fraction with an implied leading 1).

Remember: The first element of a byte array is at position 0.

Example:
  
  // Outputs "Motorola: 18265912 => 01160138
  //          Intel:    18265912 => 38B71601".
  
  var mem = new(bytes,4);
  var x = 18265912;
  
  // Motorola
  long2mem(x,mem,0,GE_MOTOROLA);
  println("Motorola: 18265912 => ",tostring(mem[0],"02X"),
                                   tostring(mem[1],"02X"),
                                   tostring(mem[2],"02X"),
                                   tostring(mem[3],"02X"));
  
  // Intel
  long2mem(x,mem,0,GE_INTEL);
  println("Intel:    18265912 => ",tostring(mem[0],"02X"),
                                   tostring(mem[1],"02X"),
                                   tostring(mem[2],"02X"),
                                   tostring(mem[3],"02X"));
  


Note: See also bytes, mem2word(), mem2uword(), mem2long(), mem2iee(), mem2liee(), word2mem(), uword2mem(), iee2mem(), liee2mem(),

Return
bool

The function returns TRUE if the operation was successful. Otherwise it returns FALSE.

Parameters
float value

A float value

bytes mem

A byte array

int pos

The position within mem

int byteorder

Either Big Endian or Little Endian.

Constant Description

GE_MOTOROLA

big endian (Motorola)

GE_INTEL

little endian (Intel)


bool isalnum(int char)

Tells if a character is alphanumeric or not.

Example:
  
  // Outputs "isalnum(5) = 1
  //          isalnum(a) = 1
  //          isalnum( ) = 0
  //          isalnum(!) = 0".
  
  println("isalnum(5) = ",isalnum("5"[0]));
  println("isalnum(a) = ",isalnum("a"[0]));
  println("isalnum( ) = ",isalnum(" "[0]));
  println("isalnum(!) = ",isalnum("!"[0]));
  


Note: See also isdigit(), isalpha(), isspace(), ispunct()

Return
bool

isalnum() returns TRUE if char is alphanumeric, that is either a letter or a digit. Otherwise it returns FALSE.

Parameters
int char

char is the character, given in 16 bit Unicode.

bool isalpha(int char)

Tells if a character is a letter or not.

Example:
  
  // Outputs "isalpha(5) = 0
  //          isalpha(a) = 1
  //          isalpha( ) = 0
  //          isalpha(!) = 0".
  
  println("isalpha(5) = ",isalpha("5"[0]));
  println("isalpha(a) = ",isalpha("a"[0]));
  println("isalpha( ) = ",isalpha(" "[0]));
  println("isalpha(!) = ",isalpha("!"[0]));
  


Note: See also isdigit(), isalnum(), isspace(), ispunct()

Return
bool

isalpha() returns TRUE if char is a letter. Otherwise it returns FALSE.

Parameters
int char

char is the character, given in 16 bit Unicode.

bool isdigit(int char)

Tells if a character is a digit or not.

Example:
  
  // Outputs "isdigit(5) = 1
  //          isdigit(a) = 0
  //          isdigit( ) = 0
  //          isdigit(!) = 0".
  
  println("isdigit(5) = ",isdigit("5"[0]));
  println("isdigit(a) = ",isdigit("a"[0]));
  println("isdigit( ) = ",isdigit(" "[0]));
  println("isdigit(!) = ",isdigit("!"[0]));
  


Note: See also isalpha(), isalnum(), isspace(), ispunct()

Return
bool

isdigit() returns TRUE if char is a digit. Otherwise it returns FALSE.

Parameters
int char

char is the character, given in 16 bit Unicode.

bool isdigit(int char)

Tells if a character is a punctuation mark or not.

Example:
  
  // Outputs "ispunct(5) = 0
  //          ispunct(a) = 0
  //          ispunct( ) = 0
  //          ispunct(!) = 1".
  
  println("ispunct(5) = ",ispunct("5"[0]));
  println("ispunct(a) = ",ispunct("a"[0]));
  println("ispunct( ) = ",ispunct(" "[0]));
  println("ispunct(!) = ",ispunct("!"[0]));
  


Note: See also isdigit(), isalpha(), isalnum(), isspace()

Return
bool

ispunct() returns TRUE if char is a punctuation mark. Otherwise it returns FALSE.

Parameters
int char

char is the character, given in 16 bit Unicode.

bool isspace(int char)

Tells if a character is a space or not.

Example:
  
  // Outputs "isspace(5) = 0
  //          isspace(a) = 0
  //          isspace( ) = 1
  //          isspace(!) = 0".
  
  println("isspace(5) = ",isspace("5"[0]));
  println("isspace(a) = ",isspace("a"[0]));
  println("isspace( ) = ",isspace(" "[0]));
  println("isspace(!) = ",isspace("!"[0]));
  


Note: See also isdigit(), isalpha(), isalnum(), ispunct()

Return
bool

isspace() returns TRUE if char is a space. Otherwise it returns FALSE.

Parameters
int char

char is the character, given in 16 bit Unicode.

bool ispunct(int char)

Tells if a character is a punctuation mark or not.

Example:
  
  // Outputs "ispunct(5) = 0
  //          ispunct(a) = 0
  //          ispunct( ) = 0
  //          ispunct(!) = 1".
  
  println("ispunct(5) = ",ispunct("5"[0]));
  println("ispunct(a) = ",ispunct("a"[0]));
  println("ispunct( ) = ",ispunct(" "[0]));
  println("ispunct(!) = ",ispunct("!"[0]));
  


Note: See also isdigit(), isalpha(), isalnum(), isspace()

Return
bool

ispunct() returns TRUE if char is a punctuation mark. Otherwise it returns FALSE.

Parameters
int char

char is the character, given in 16 bit Unicode.

string stradd(string str, ...)

Creates a new string that contains all the strings that are passed.

Example:
  
  // Outputs  "abcdefghj"
  
  var str1 = "abc";
  var str2 = "def";
  var str3 = "ghi";
  
  println(stradd(str1,str2,str3));
  
  
  // To add in other variable types one can use
  // the tostring() function.
  //
  // Outputs "The object has 437 polygons."
  
  var str1 = "The object has ";
  var num = 437;
  var str2 = " polygons.";
  
  println(stradd(str1,tostring(num),str2));
  


Note: See also string, strins(), strmid(), strset(), strstr(), strchr(), strcmp()

Return
string

stradd() returns a string containing all the passed strings joined together in order. The parameters must be strings.

Parameters
string str

A string.

...

One ore many additional strings, separated by commas.

string strchr(string str, int chr, int pos)

Locates the first occurrence of a character within a string, optionally beginning the search at a certain position.

Example:
  
  // Outputs "2". The first c is located at position 2.
  
  var str =  "abcdefghij";
  var char =   "c"[0];
  
  println(strchr(str,char));
  
  
  // Outputs "-1". No x was found.
  
  var str = "abcdefghij";
  var char = "x"[0];
  
  println(strchr(str,char));
  
  
  // Outputs "15". After position 8, the first e
  // is located at position 15.
  
  var str    = "abcdefghij abcdefghij";
  var char   =                "e"[0];
  var pos    = 8;
  
  println(strchr(str,char,pos));
  


Note: See also string, strins(), strmid(), strset(), strstr(), stradd(), strcmp()

Return
string

strchr() returns the position of the first occurence of the character chr within the string str. If the third parameter is passed, only the part of str that is after the position pos is searched. If no match is found, the return value is -1.

Remember: The first character of a string is at position 0.

The Unicode value of a character may be obtained by writing it like this: "a"[0]. One can also write a 16 bit hexadecimal Unicode value directly like this: 0x20AC

Parameters
string str

The string.

int chr

The character to search for, given in 16 bit Unicode.

int pos

The optional start position of the search.

string strcmp(string str1, string str2)

Compares two strings.

Example:
  
  // Outputs "0". The strings are identical.
  
  var str1 = "tree";
  var str2 = "tree";
  
  println(strcmp(str1,str2));
  
  
  // Outputs "9". The strings are not equal.
  // Since 9 > 0, tree is sorted after key.
  
  var str1 = "tree";
  var str2 = "key";
  
  println(strcmp(str1,str2));
  
  
  // Outputs "-17". The strings are not equal.
  // Since -17 < 0, car is sorted before key.
  
  var str1 = "car";
  var str2 = "key";
  
  println(strcmp(str1,str2));
  
  
  // Always remember that strcmp() works in the opposite way to the
  // normal == operator. Note the use of ! below.
  
  var password = "secret";
  var input = getPasswordInput();
  
  if (!strcmp(password,input))
    passwordAccepted();
  else
    accessDenied();
  


Note: See also string, strins(), strmid(), strset(), strstr(), stradd(), strchr()

Return
string

strcmp() compares str1 with str2. If the strings are equal, the return value is 0. (Please note that this is different from the normal == comparison, where 0 means not equal!) Otherwise the return value tells whether str1 would come before or after str2 if they were sorted. If the value is negative, str1 is less than str2, meaning that it would come before str2. If the value is positive, it's vice versa.

The sorting is strictly after the Unicode table, so for example upper-case letters come before lower-case letters.

Parameters
string str1

The first string.

string str2

The second phrase.

string strins(string str1, string str2, int pos)

Inserts a string at a given position in another.

Example:
  
  // Outputs "abtestghij"
  
  var str1 = "abcdefghij";
  var str2 =   "test";
  var pos = 2;
  
  println(strins(str1,str2,pos));
  
  
  // Outputs   "stingfghij"
  
  var str1 =   "abcdefghij";
  var str2 = "testing";
  var pos = -2;
  
  println(strins(str1,str2,pos));
  
  
  // Outputs "abcdeftest"
  
  var str1 = "abcdefghij";
  var str2 =       "testing";
  var pos = 6;
  
  println(strins(str1,str2,pos));
  


Note: See also string, strmid(), stradd(), strset(), strstr(), strchr(), strcmp()

Return
string

strins() returns a copy of the string str1 where the string str2 has been inserted at the position pos. The parts of str1 that are covered by str2 are replaced. The length of the result is the same as the length of str1, so if str2 is too long it will be truncated. The insertion position pos can be negative.

Remember: The first character of a string is at position 0.

Parameters
string str1

The original string.

string str2

The string that's inserted into str1.

int pos

The insertion position within str1.

string strmid(string str, int pos, int len)

Creates a new string that contains an extract from another string, specified by the starting position within the original string and the length of the result.

Example:
  
  // Outputs  "cde"
  
  var str = "abcdefghij";
  var pos = 2;
  var len = 3;
  
  println(strmid(str,pos,len));
  
  
  // Outputs "abcde"
  
  var str =  "abcdefghij";
  var pos = -3;
  var len = 8;
  
  println(strmid(str,pos,len));
  
  
  // Outputs      "ghij"
  
  var str = "abcdefghij";
  var pos = 6;
  var len = 7;
  
  println(strmid(str,pos,len));
  


Note: See also string, strins(), stradd(), strset(), strstr(), strchr(), strcmp()

Return
string

strmid() returns a string containing an extract from str, starting at position pos and with the length len. If the extract goes outside the original string, for example if len is bigger than the length of the string, it will be truncated. This means that the length of the returned string doesn't always equal len. The starting position pos can be negative.

Remember: The first character of a string is at position 0.

string strset(string str, int char, int pos, int num)

Fills a specified number of bytes in a string from a given position with a certain character.

Example:
  
  // Outputs "ab---fghij"
  
  var str  = "abcdefghij";
  var char = "-"[0]
  var pos  = 2;
  var len  = 3;
  
  println(strset(str,char,pos,len));
  
  
  // Outputs "----efghij"
  
  var str  = "abcdefghij";
  var char = "-"[0]
  var pos  = -2;
  var len  = 6;
  
  println(strset(str,char,pos,len));
  
  
  // Outputs "abcdefg---"
  
  var str  = "abcdefghij";
  var char = "-"[0]
  var pos  = 7;
  var len  = 6;
  
  println(strset(str,char,pos,len));
  


Note: See also string, strins(), strmid(), stradd(), strstr(), strchr(), strcmp()

Return
string

strset() returns a copy of str that is filled from position pos to position pos+num with the character char. The length of the return value is always the length of str. If any position of the specified fill interval is outside of str, for example if pos+num is greater than the length of str, it is simply disregarded. The starting position pos can be negative.

Remember: The first character of a string is at position 0.

The Unicode value of a character may be obtained by writing it like this: "a"[0]. One can also write a 16 bit hexadecimal Unicode value directly like this: 0x20AC

Parameters
string str

The original string.

int char

The character to fill with, given in 16 bit Unicode.

int pos

The starting position of the filling.

int num

The number of times that the character is repeated. (num >= 0)

int strstr(string str, string phrase, int pos)

Locates the first occurrence of a phrase within another string, optionally beginning the search at a certain position.

Example:
  
  // Outputs "2". The phrase is located at position 2.
  
  var str =  "abcdefghij";
  var phrase = "cde";
  
  println(strstr(str,phrase));
  
  
  // Outputs "-1". No occurrence was found.
  
  var str = "abcdefghij";
  var phrase = "xgj";
  
  println(strstr(str,phrase));
  
  
  // Outputs "15". After position 8, the first occurrence
  // of the phrase is located at position 15.
  
  var str    = "abcdefghij abcdefghij";
  var phrase =                "efg";
  var pos    = 8;
  
  println(strstr(str,phrase,pos));
  


Note: See also string, strins(), strmid(), stradd(), strset(), strchr(), strcmp()

Return
int

strstr() returns the position of the first occurence of the string phrase within the string str. If the third parameter is passed, only the part of str that is after the position pos is searched. If no match is found, the return value is -1.

Remember: The first character of a string is at position 0.

Parameters
string str

The string.

string phrase

The search phrase.

int pos

The optional start position of the search.

void print(anytype str, ...)

Outputs text to the Console window.

print() prints all the passed parameters in order to the Console window. Any non-string parameters are automatically converted to strings with tostring().

If one has several print() functions in a row, all their text will be output on one line. To insert a newline after each print-out, use the println() function instead. It is good practice to end each sequence of print() with at least one println(). Otherwise the next plug-in that prints to the Console will continue on the same line.

Note: See also println()

Parameters
anytype str

A string, bool or a numeric value.

...

One or more additional values (numerical, string, bool)

void println(anytype str, ...)

Outputs text to the Console window.

println() prints all the passed parameters in order to the Console window. Any non-string parameters are automatically converted to strings with tostring().

To print text without the automatic newline, use the print() function.

Example:
  
  // Outputs "Hello World!".
  println("Hello World!");
  
  // Outputs "There are 47 items.".
  var num = 47;
  println("There are ",num," items.");
  


Note: See also print()

Parameters
anytype str

A string, bool or a numeric value.

...

One or more additional values (numerical, string, bool)

void EventAdd(int flags)

Notifies CINEMA 4D of changes in the document.

This command is used to notify CINEMA 4D that something has changed somehow. It replaces the old GeEventAdd() function. You no longer have to specify exactly what happened.

Example:
  
  // Change the position and then refresh
  obj->SetPosition(vector(100.0, 0.0, 0.0));
  EventAdd();
  
  // Add a new object and refresh the OM
  var newObj = new(NullObject);
  doc->InserObject(newObj, NULL, NULL);
  EventAdd();
  


Note: See also SpecialEventAdd().

Parameters
int flags

These are the optional flags:

Constant Description

EVENT_FORCEREDRAW

Force a complete redraw.

EVENT_ANIMATE

Animate document.

EVENT_NOEXPRESSION

Don't execute expressions.

EVENT_CAMERAEXPRESSION

If this is set (and not EVENT_NOEXPRESSION), the event will only update camera dependant expressions (for faster speed).


bool SpecialEventAdd(int messageid, int p1, int p2)

This function sends a custom event with ID messageid. Use a plugin ID for messageid to make sure that there's no collision. Results in a CoreMessage() message. The optional parameters p1 and p2 are sent as parameters in the core message container.

Note: See also EventAdd()

Return
bool

TRUE if successful, otherwise FALSE.

Parameters
int messageid

A unique ID for your custom message.

int p1

An optional parameter

int p2

Another optional parameter

bool SendPluginMessage(BaseContainer msg)

Sends a plugin message. This version of the function only sends the message to C.O.F.F.E.E. message plugins.

bool SendPluginMessage(int id, BaseContainer msg)

Sends a plugin message. This version of the function only sends the message to all plugins (identical to the C++ function).

BaseObject object(int index)

Returns a selected object by index. This is used for example by the new "Create Script" function in CINEMA 4D.

Example:
  
  var i;
  for (i=0; object(i); i++)
  {
    doc->AddUndo(UNDO_CHANGE_SMALL,object(i));
    object(i)#PRIM_CUBE_DOFILLET=TRUE;
    object(i)->Message(MSG_UPDATE);
  }
  

Return
BaseObject

The selected object or class="silent">NULL if there is no selected object avaible for the index.

Parameters
int index

The index, must be >= 0.

BaseTag tag(int index)

Returns a selected tag by index. This is used for example by the new "Create Script" function in CINEMA 4D.

Example:
  
  var i;
  for (i=0; tag(i); i++)
  {
    doc->AddUndo(UNDO_CHANGE_SMALL,tag(i));
    tag(i)#PHONGTAG_PHONG_ANGLELIMIT=TRUE;
    tag(i)->Message(MSG_UPDATE);
  }
  

Return
BaseTag

The selected tag or class="silent">NULL if there is no selected tag avaible for the index.

Parameters
int index

The index, must be >= 0.

BaseList2D tool()

Returns the active tool.

Example:
  
  tool()#MDATA_SELECTLIVE_RADIUS=20;
  

Return
BaseList2D

The active tool data.

RenderData renderdata()

Returns the active render data (the one that is used for actual rendering).

Example:
  
  renderdata()#RDATA_ALPHACHANNEL=FALSE;
  

Return
RenderData

The active render data.


Copyright 2014 MAXON. See Plugin Cafe for the latest version. Last modified: 2014-10-03