newton
Class Ref

java.lang.Object
  |
  +--newton.Ref

public class Ref

extends Object

A Ref is a pointer to an underlying NewtonScript object. The following objects are typically pointed to: nil, ints, chars, symbols, frames, arrays, floats, strings, binary objects, functions, and magic pointers.

Refs are generally immutable; they will not change to point to different NewtonScript objects. Of course, you can modify features of the underlying object as you please, changing its class or length or slots, etc. Just use the various set... methods.

The Ref class implements much of the NewtonScript language access facility, with some notable exceptions:

• Setting values at path expressions
• Testing for the existence of a slot
• Easily modifying NS strings
• Iterating
• Deep cloning

Most of these have been left out because they're not too common, and the class is getting too big as it is. Perhaps at some point some will be added in with popular demand. Let me know.

Field Summary

static int	ARRAY The Ref's type() is an array
static int	BINARY The Ref's type() is a binary object other than a string or a float
static int	CHAR The Ref's type() is a character
static int	FLOAT The Ref's type() is a float
static int	FRAME The Ref's type() is a frame
static int	FUNCTION The Ref's type() is a function
static int	INT The Ref's type() is a integer
static int	MAGIC The Ref's type() is a magic pointer of some kind
static int	NIL The Ref's type() is nil
static int	STRING The Ref's type() is a string
static int	SYMBOL The Ref's type() is a symbol
static int	UNKNOWN The Ref's type() is an unknown object

Constructor Summary

Ref()
Makes nil.

Ref(char val)
Makes a char.

Ref(float val)
Makes a float.

Ref(int val)
Makes an int.

Ref(String val)
Makes a string.

Method Summary

Ref	call(Ref[] args) Calls me (a function or symbol) as a function, passing in args.
static Ref	call(String name) Calls a global function named name of no arguments.
static Ref	call(String name, Ref arg1) Calls a global function named name, of one argument.
static Ref	call(String name, Ref[] args) Calls a global function named name, passing it args.
static Ref	call(String name, Ref arg1, Ref arg2) Calls a global function named name, of two arguments.
static Ref	call(String name, Ref arg1, Ref arg2, Ref arg3) Calls a global function named name, of three arguments.
char	charValue() Returns my char value.
float	floatValue() Returns my float value.
byte[]	getBytes(int refStart, int numBytesToGet) Gets numBytesToGet bytes out of a binary object, starting at refStart.
int	getBytes(int refStart, int putInStart, int numBytesToGet, byte[] putInHere) Gets numBytesToGet bytes out of a binary object, starting at position refstart in the binary object, and filling at position putInStart in the byte array, which is supplied with putInHere.
int	getLength() Returns the length of the binary object, string, or array.
Ref	getObjectClass() Returns my class.
Ref	getPath(String slotName) Looks up a slot in a frame, searching parent hierarchies if necessary (unlike getSlot).
Ref	getSlot(int slot) Returns the value of a slot in an array.
Ref	getSlot(String slotName) Returns the value of an immediate slot in a frame.
int	intValue() Returns my int value.
static Ref	newArray(int size) Makes an array of the given size, with all elements initialized to nil.
static Ref	newBinary(int size, Ref _class) Makes a binary object of the given size and class.
static Ref	newFrame() Makes an empty frame.
static Ref	newSymbol(String val) Makes a symbol.
Ref	push(Ref val) Adds val to the end of the array, and returns the array.
Ref	send(Ref methodName, Ref[] args) Sends a method call to me (a frame), passing in args.
Ref	send(String methodName) Sends a method call on me, named name, with no arguments.
Ref	send(String methodName, Ref arg1) Sends a method call on me, named name, with one argument.
Ref	send(String methodName, Ref[] args) Sends a method call on me, named name, with arguments.
Ref	send(String methodName, Ref arg1, Ref arg2) Sends a method call on me, named name, with two arguments.
Ref	send(String methodName, Ref arg1, Ref arg2, Ref arg3) Sends a method call on me, named name, with three arguments.
int	setBytes(int refStart, int getFromStart, int numBytesToSet, byte[] getFromHere) Sets up to numBytesToSet bytes in a binary object, increasing the size if necessary (and possible).
Ref	setClass(Ref thisClass) Sets the class of the object.
Ref	setClass(String thisClass) Sets the class of the object and returns the object.
int	setLength(int newLength) Tries to set the length of an array.
Ref	setSlot(int slot, Ref val) Sets a slot in an array and returns the array.
Ref	setSlot(Ref slotName, Ref slotVal) Sets an immediate slot in a frame and returns the frame.
Ref	setSlot(String slotName, Ref slotVal) Sets an immediate slot in a frame and returns the frame.
String	stringValue() Returns my string value.
String	symbolValue() Returns my symbol value.
int	type() Returns the type of the underlying NewtonScript object pointed to by this Ref.

Methods inherited from class java.lang.Object

equals, hashCode, toString

Field Detail

NIL

public static final int NIL

The Ref's type() is nil

INT

public static final int INT

The Ref's type() is a integer

CHAR

public static final int CHAR

The Ref's type() is a character

SYMBOL

public static final int SYMBOL

The Ref's type() is a symbol

FRAME

public static final int FRAME

The Ref's type() is a frame

ARRAY

public static final int ARRAY

The Ref's type() is an array

FLOAT

public static final int FLOAT

The Ref's type() is a float

STRING

public static final int STRING

The Ref's type() is a string

BINARY

public static final int BINARY

The Ref's type() is a binary object other than a string or a float

FUNCTION

public static final int FUNCTION

The Ref's type() is a function

MAGIC

public static final int MAGIC

The Ref's type() is a magic pointer of some kind

UNKNOWN

public static final int UNKNOWN

The Ref's type() is an unknown object

Constructor Detail

Ref

public Ref()

Makes nil. Example:

Java Code	new Ref()
NewtonScript Equivalent	nil

Ref

public Ref(int val)

Makes an int. Example:

Java Code	new Ref(4)
NewtonScript Equivalent	4

Ref

public Ref(char val)

Makes a char. Example:

Java Code	new Ref('f')
NewtonScript Equivalent	$f

Ref

public Ref(String val)

Makes a string. Example:

Java Code	new Ref("hello")
NewtonScript Equivalent	"hello"

Ref

public Ref(float val)

Makes a float. Example:

Java Code	new Ref("hello")
NewtonScript Equivalent	"hello"

Method Detail

type

public int type()

Returns the type of the underlying NewtonScript object pointed to by this Ref.

newSymbol

public static Ref newSymbol(String val)

Makes a symbol. Don't put the customary single quote in the front of your string. Example:

Java Code	Ref.newSymbol("name")
NewtonScript Equivalent	'name

newArray

public static Ref newArray(int size)

Makes an array of the given size, with all elements initialized to nil. Example:

Java Code	Ref.newArray(4)
NewtonScript Equivalent	Array(4,nil)

newBinary

public static Ref newBinary(int size,
                            Ref _class)

Makes a binary object of the given size and class. Class must be a symbol. Example:

Java Code	Ref.newBinary(4, Ref.newSymbol('foo))
NewtonScript Equivalent	MakeBinary(4,'foo)

newFrame

public static Ref newFrame()

Makes an empty frame. Example:

Java Code	Ref.newFrame()
NewtonScript Equivalent	{ }

intValue

public int intValue()

Returns my int value. Returns 0 if I'm not an int

charValue

public char charValue()

Returns my char value. Returns if I'm not a char

symbolValue

public String symbolValue()

Returns my symbol value. Returns null if I'm not a symbol

stringValue

public String stringValue()

Returns my string value. Returns null if I'm not a string

floatValue

public float floatValue()

Returns my float value. Returns 0.0 if I'm not a float

getObjectClass

public Ref getObjectClass()

Returns my class. Returns null if i have no class. Sorry for the inconvenience. Example:

Java Code	myobjRef.getClass()
NewtonScript Equivalent	ClassOf(myobj)

By the way, I'd call this "getClass()", except that there's already a java.lang.Object method of that name. :-(

getSlot

public Ref getSlot(int slot)

Returns the value of a slot in an array. Returns null if not an array or if there is no such slot. Example:

Java Code	myarrayRef.getSlot(4)
NewtonScript Equivalent	myarray[4]

getSlot

public Ref getSlot(String slotName)

Returns the value of an immediate slot in a frame. Returns null if not a frame or if there is no such slot. Example:

Java Code	myframeRef.getSlot("foo")
NewtonScript Equivalent	GetSlot(myframe,'foo)

getPath

public Ref getPath(String slotName)

Looks up a slot in a frame, searching parent hierarchies if necessary (unlike getSlot). Returns null if not a frame or if the slotName is invalid or doesn't exist. Example:

Java Code	myframeRef.getPath("foo")
NewtonScript Equivalent	myframe.foo

getBytes

public int getBytes(int refStart,
                    int putInStart,
                    int numBytesToGet,
                    byte[] putInHere)

Gets numBytesToGet bytes out of a binary object, starting at position refstart in the binary object, and filling at position putInStart in the byte array, which is supplied with putInHere. Returns -1 if not a binary object. Otherwise returns the number of bytes actually gotten.

getBytes

public byte[] getBytes(int refStart,
                       int numBytesToGet)

Gets numBytesToGet bytes out of a binary object, starting at refStart. Returns null if not a binary object. Array may be smaller than expected if there weren't enough bytes.

getLength

public int getLength()

Returns the length of the binary object, string, or array. Returns -1 if not binary or array (remember, strings and floats are binary). Remember that length for strings is byte length, not unichar length! This is identical to calling the NewtonScript Length(...) method.

setBytes

public int setBytes(int refStart,
                    int getFromStart,
                    int numBytesToSet,
                    byte[] getFromHere)

Sets up to numBytesToSet bytes in a binary object, increasing the size if necessary (and possible). The bytes are set starting at position refStart in the binary object, and are taken from the byte array getFromHere, position getFromStart. Returns the number of bytes legally settable.

setLength

public int setLength(int newLength)

Tries to set the length of an array. Returns the length it actually got set to. New slots are filled with nil. Returns -1 if not an array or an invalid (< 0) length. This is roughly the same as the NewtonScript SetLength(array,length), except that the NewtonScript version has no specified return value. Example:

Java Code	myarrayRef.setLength(100)
NewtonScript Equivalent	SetLength(myarray,100)

setClass

public Ref setClass(Ref thisClass)

Sets the class of the object. Returns null if thisClass is not a symbol or the class can't be set. Its faster to use this function instead of setClass(String) if you're going to set lots of objects to the same class in a tight loop. In this situation, create your own symbol and store it in a local variable, then pass it to this function repeatedly. This is roughly the same as the NewtonScript function SetClass(obj,newClass), except that the NewtonScript version has no specified return value. Example:

Java Code	Ref foo = Ref.newSymbol(foo); int len = myarrayRef.getLength(); for(int x=0;x<len;x++) myarrayRef.getSlot(x).setClass(foo);
NewtonScript Equivalent	local x; for x:= 0 to Length(myarray)-1 do SetClass(myarray[x],'foo);

setClass

public Ref setClass(String thisClass)

Sets the class of the object and returns the object. Returns null if the class can't be set. More convenient than setClass(Ref), but less efficient if many objects will be set to the same class in a tight loop. This is roughly the same as the NewtonScript function SetClass(obj,newClass), except that the NewtonScript version has no specified return value. Example:

Java Code	myobjRef.setClass("foo")
NewtonScript Equivalent	begin SetClass(myobj,'foo); myobj end

setSlot

public Ref setSlot(int slot,
                   Ref val)

Sets a slot in an array and returns the array. Returns null if no such slot. Example:

Java Code	myarrayRef.setSlot(4, myobjRef)
NewtonScript Equivalent	begin myarray[4]:=myobj; myarray end

push

public Ref push(Ref val)

Adds val to the end of the array, and returns the array. Returns null if this isn't an array. Example:

Java Code	myarrayRef.push(myobjRef)
NewtonScript Equivalent	begin AddArraySlot(myarray,myobj); myarray end

setSlot

public Ref setSlot(Ref slotName,
                   Ref slotVal)

Sets an immediate slot in a frame and returns the frame. Creates the slot if necessary. Returns null if the slot name is not a symbol. Its faster to use this function instead of setSlot(String, Ref) if you're going to set lots of objects to the same class in a tight loop. In this situation, create your own slot-name symbol and store it in a local variable, then pass it to this function repeatedly. Example:

Java Code	Ref foo = Ref.newSymbol(foo); int len = myarrayRef.getLength(); for(int x=0;x<len;x++) myarrayRef.getSlot(x).setSlot(foo, new Ref("Hi!"));
NewtonScript Equivalent	local x; for x:= 0 to Length(myarray)-1 do myarray[x].foo := "Hi!";

setSlot

public Ref setSlot(String slotName,
                   Ref slotVal)

Sets an immediate slot in a frame and returns the frame. Creates the slot if necessary. Returns null if the slot can't be set. More convenient than setSlot(Ref,Ref), but less efficient if the same slot will be set for many frames in a tight loop. Example:

Java Code	myobjRef.setSlot("foo", new Ref("Hi!"))
NewtonScript Equivalent	begin myobj.foo := "Hi"; myobj end

call

public Ref call(Ref[] args)

Calls me (a function or symbol) as a function, passing in args. If I am a symbol, I get called as a global function. If I am a function pointer, I just get called directly. If I am neither, null is returned. If a NewtonScript exception is raised by this call, then the symbol form of the exception will be returned instead of the expected return value. args may be null, this is considered to be an empty argument array. If you're calling a global function with fewer than 4 arguments, and won't repeatedly call this function in a tight loop, then use one of the other call... convenience functions. Example:

Java Code	Ref[] args = new Ref[4]; args[0] = new Ref(4); args[1] = new Ref("Yo"); args[2] = new Ref(0); args[3] = new Ref(); Ref returnval = myfuncRef.call(new Ref("Hi!"), args);
NewtonScript Equivalent	local returnval := Apply(myfunc, [4,"Yo",0,nil]);

call

public static Ref call(String name,
                       Ref[] args)

Calls a global function named name, passing it args. If a NewtonScript exception is raised by this call, then the symbol form of the exception will be returned instead of the expected return value. args may be null, this is considered to be an empty argument array. If you're calling a global function with fewer than 4 arguments, and won't repeatedly call this function in a tight loop, then use one of the other call... convenience functions. Example:

Java Code	Ref[] args = new Ref[4]; args[0] = new Ref(4); args[1] = new Ref("Yo"); args[2] = new Ref(0); args[3] = new Ref(); Ref returnval = Ref.call("Doit", args);
NewtonScript Equivalent	local returnval := Doit(4,"Yo",0,nil);

call

public static Ref call(String name)

Calls a global function named name of no arguments. If a NewtonScript exception is raised by this call, then the symbol form of the exception will be returned instead of the expected return value. Example:

Java Code	Ref returnval = Ref.call("Doit");
NewtonScript Equivalent	local returnval := Doit();

call

public static Ref call(String name,
                       Ref arg1)

Calls a global function named name, of one argument. If a NewtonScript exception is raised by this call, then the symbol form of the exception will be returned instead of the expected return value. Example:

Java Code	Ref returnval = Ref.call("Doit", new Ref(4));
NewtonScript Equivalent	local returnval := Doit(4);

call

public static Ref call(String name,
                       Ref arg1,
                       Ref arg2)

Calls a global function named name, of two arguments. If a NewtonScript exception is raised by this call, then the symbol form of the exception will be returned instead of the expected return value. Example:

Java Code	Ref returnval = Ref.call("Doit", new Ref(4), new Ref("Hey!"));
NewtonScript Equivalent	local returnval := Doit(4, "Hey!");

call

public static Ref call(String name,
                       Ref arg1,
                       Ref arg2,
                       Ref arg3)

Calls a global function named name, of three arguments. If a NewtonScript exception is raised by this call, then the symbol form of the exception will be returned instead of the expected return value. Example:

Java Code	Ref returnval = Ref.call("Doit", new Ref(4), new Ref("Hey!"), new Ref());
NewtonScript Equivalent	local returnval := Doit(4, "Hey!", nil);

send

public Ref send(Ref methodName,
                Ref[] args)

Sends a method call to me (a frame), passing in args. methodName must be a symbol. I must be a frame. If these conditions are not met, returns null. If a NewtonScript exception is raised by this call, then the symbol form of the exception will be returned instead of the expected return value. If you're sending a method call with fewer than 4 arguments, and won't repeatedly call this method in a tight loop, then use one of the other call... convenience functions. Example:

Java Code	Ref[] args = new Ref[4]; args[0] = new Ref(4); args[1] = new Ref("Yo"); args[2] = new Ref(0); args[3] = new Ref(); Ref methodname = Ref.newSymbol("Doit"); Ref returnval = myobjRef.send(methodname, args);
NewtonScript Equivalent	local returnval := myobj:Doit(4,"Yo",0,nil);

send

public Ref send(String methodName,
                Ref[] args)

Sends a method call on me, named name, with arguments. I must be a frame. If a NewtonScript exception is raised by this call, then the symbol form of the exception will be returned instead of the expected return value. args may be null, this is considered to be an empty argument array. If you're calling the same method repeatedly in a tight loop, consider using send(Ref, Ref[], Ref), it's a little faster because it doesn't have to create the symbol every time. If you're sending a method call with fewer than 4 arguments, and won't repeatedly call this method in a tight loop, then use one of the other call... convenience functions. Example:

Java Code	Ref[] args = new Ref[4]; args[0] = new Ref(4); args[1] = new Ref("Yo"); args[2] = new Ref(0); args[3] = new Ref(); Ref returnval = myobjRef.send("Doit", args);
NewtonScript Equivalent	local returnval := myobj:Doit(4,"Yo",0,nil);

send

public Ref send(String methodName)

Sends a method call on me, named name, with no arguments. I must be a frame. If a NewtonScript exception is raised by this call, then the symbol form of the exception will be returned instead of the expected return value. args may be null, this is considered to be an empty argument array. Example:

Java Code	Ref returnval = myframeRef.send("Doit");
NewtonScript Equivalent	local returnval := myframe:Doit();

send

public Ref send(String methodName,
                Ref arg1)

Sends a method call on me, named name, with one argument. I must be a frame. If a NewtonScript exception is raised by this call, then the symbol form of the exception will be returned instead of the expected return value. Example:

Java Code	Ref returnval = myframeRef.send("Doit", new Ref(4));
NewtonScript Equivalent	local returnval := myframe:Doit(4);

send

public Ref send(String methodName,
                Ref arg1,
                Ref arg2)

Sends a method call on me, named name, with two arguments. I must be a frame. If a NewtonScript exception is raised by this call, then the symbol form of the exception will be returned instead of the expected return value. Example:

Java Code	Ref returnval = myframeRef.send("Doit", new Ref(4), new Ref("Yo"));
NewtonScript Equivalent	local returnval := myframe:Doit(4, "Yo");

send

public Ref send(String methodName,
                Ref arg1,
                Ref arg2,
                Ref arg3)

Sends a method call on me, named name, with three arguments. I must be a frame. If a NewtonScript exception is raised by this call, then the symbol form of the exception will be returned instead of the expected return value. Example:

Java Code	Ref returnval = myframeRef.send("Doit", new Ref(4), new Ref("Yo"), new Ref(0));
NewtonScript Equivalent	local returnval := myframe:Doit(4, "Yo", 0);