Index Object

Index objects are created by the index Lambda and are persistent objects residing in object repositories. Index objects are similar to directory objects with extensions for unique and non-unique key insertion and retreival. An index object contains an arbitrary number of bindings. An index object can manage a unique index or non-unique index. Values can be referenced by key, a single index or two indices.Like a directory object, keys in an index object can be of any type. Values can also be of any type unless the user specifies that values will always be numeric.

Non-unique indices keep a vector of values for each unique key. When you reference a key in a non-unqiue index you get back a vector of values. Each of the values in the returned vector is a value that was previously associated with the key in the index.When you reference a key in a unique index you get back a single value. Remember that vlaues may themselves be of any type (including a vector).

Index objects are instances of the index Lambda. Include the index.sl Lambda in a cabinet to use index objects. Use the (index.new ...) function to create new index objects or open existing index objects. All other index object functions are performed on the index object returned from a call to new.

Using the Index Object

To use index objects you must first have an open repository object in which to store the index. See the documentation on object repositories to learn more about creating and managing object repositories. Consider the code below:

;;Create a new unique index object
		(setq myIndex (index.new myIndex:  myrepo create: unique:))
		(setq myIndex["teddy"] 10)
		(writeln myIndex["teddy"]); >> 10
		(setq myIndex["teddybear"] 20)
		(writeln (myIndex.Pv.refValues)); >> #(10 20)
		(writeln myIndex[0 1]); >> 10
		(writeln myIndex[0 0]); >> "teddy"
		(writlen (myIndex.Pv.refAttributes)); >> #(teddy teddybear)
		(writeln (myIndex.Pv.member "teddy")); >> 0
		(writeln (myIndex.Pv.refValues "teddy")); >> #(10 20)
		(writeln (myIndex.Pv.length)); >> 2
		(writeln (myIndex.Pv.length); > 1
		
		(myIndex.close); close the index
		

;;Create a new non-unique index object
		(setq myIndex (index.new myIndex: myrepo create:))
		(setq myIndex["teddy"] 10)
		(writeln myIndex["teddy"]); >> #(10)
		(setq myIndex["teddy"] 20)
		(writeln myIndex["teddy"] ; #(10 20)
		(setq myIndex["teddybear"] 30)
		(writeln (myIndex.Pv.refValues)); >> #(10 20 30)
		(writeln myIndex[0 1]); >> #(10 20)
		(writeln myIndex[0 0](; >> "teddy"
		(writlen (myIndex.Pv.refAttributes)); >> #(teddy teddybear)
		(writeln (myIndex.Pv.member "teddy")); >> 0
		(writeln (myIndex.Pv.length)); >> 2
		
		(myIndex.close); close the index
		
		;;Create a new unique composite key index object
		(setq myIndex (index.new myIndex: myrepo create: 2))
		(setq myIndex[#("teddy" 1)] 10)
		(writeln myIndex[#("teddy" 1)]); >> #(10)
		(setq myIndex[#("teddy" 2)] 20)
		(writeln myIndex[#("teddy")] ; #(10 20)
		(setq myIndex[#("teddybear" 1)] 30)
		(writeln (myIndex.Pv.refValues)); >> #(10 20 30)
		(writeln myIndex[0 1]); >> #(10 20)
		(writeln myIndex[0 0](; >> #("teddy" 1)
		(writlen (myIndex.Pv.refAttributes)); >> #(#("teddy" 1) #("teddy" 2) #("teddybear" 1))
		(writeln (myIndex.Pv.length)); >> 3		
		(myIndex.close); close the index
		   

Use the indexobject.Pv.clear method to delete all keys from the index.
Syntax: (indexobject.Pv.close )

Returns

True

close

Use the indexobject.Pv.close method to close the index object.
Syntax: (indexobject.Pv.close nosave:)

nosave:	An optional symbol argument spcifying that the index not be saved on close. This option is only meaningful and valid if the index was opened with the memory: options.
Returns	FrameID of saved index

Use the indexobject.Pv.delete method to delete keys and their associated values from an index. Pass the optional value argument to delete a seleced value from a non-unique index. Calling delete on a non-unique index with only a key argument will delete all values associated with that key from the index. Keys with no values associated with them are removed from non-unique indices. The optional value argument should not be passed when delete is called on a unique index.
Syntax: (indexobject.Pv.delete key oldvalue

key	An argument containing a key value for a single key index or a vector of key component values for a composite key index. Keys can be of any type.
oldvalue	An optional argument of any type that contains a value to make selection possible in non-unique indicies. This argument may not be passed when using a unique index.
Returns	Reference to Index object

Use the indexobject.Pv.drop method to remove an open index from the repository.
Syntax: (indexobject.Pv.drop )

Returns

True

Use the indexobject.Pv.isMember method to determine if a supplied key is in the index.
Syntax: (indexobject.Pv.isMember key )

key	An argument containing a key value for a single key index or a vector of key component values for a composite key index. Keys can be of any type. Partial composite keys may be passed and will cause key selection that match the partial key specification.
Returns	True if key found, false if key not found.

Use the indexobject.Pv.length method to find the number of entries in the index.
Syntax: (indexobject.Pv.length)

Returns

Number of key entries in index.

Use the indexobject.Pv.member method to get the index of the first entry having the supplied key.
Syntax: (indexobject.Pv.member key)

key	An argument containing a key value for a single key index or a vector of key component values for a composite key index. Keys can be of any type. Partial composite keys may be passed and will cause key selection that match the partial key specification.
Returns	Returns the index of the first key matching the supplied key. False is returned if no match is found.

Use the indexobject.Pv.members method to get a vector of indices for entries having the supplied key or partial key.
Syntax: (indexobject.Pv.members key)

key	An argument containing a key value for a single key index or a vector of key component values for a composite key index. Keys can be of any type. Partial composite keys may be passed and will cause key selection that match the partial key specification.
Returns	Vector of indicies to entries matching supplied key. Empty vector is returned if no matches found.

Use the index.new function to create a new index object. If the specified index already exists in the object repository it will be opened. Pass the create: argument to create a new index.
Syntax: (index.new indexName repository create: numComponents unique: snapshot: memory: numvalues:)
Syntax: (index.new indexFrameID repository create: numComponents unique:snapshot: memory:numvalues:)
Returns: Index Object

indexName	A string or symbol containing the name of the index.
indexFrameID	A number containing the frameID of the index header record. Pass #void if creating a new index. Your application should store the frameID returned from the indexobject.close method so that you can reopen the index in the future.
repository	Object reference to object repository in which index is stored.
create:	Use when you are creating a new index or when you want to clear the current index and create it anew. Note that you must supply the numComponents value when you supply the create: flag.
numComponents	A number specifying the number of components supplied for each key. Pass this value when you have specified create:. The numComponents value allows the index object to distinguish among a key that is a vector and a composite key supplied as a vector of components. This is useful for optimizing various query operations.
transLambdas	An optional structure containing transaction Lambdas to use instead of defaults. ie: #{beginTrans: someLambda commitTrans: someLambda rollbackTrans: someLambda}
unique:	An optional symbol argument specifying that the index is to be a unique key index. Provide this argument on when first creating an index. It will be stored in the index header record and need not be supplied again. Passing this argument when opening an existing index will yield an error.
snapshot:	An optional symbol argument specifying that an existing index should be copied on open. The original index will not be modified.
memory:	An optional symbol argument specifying that the entire index should be loaded and processed in memory.
numvalues:	An optional symbol argument specifying that only numeric values will be allowed. This option has no effect on the index keys - which can be of any type. This option allows the index Lambda to optimize it's storage structures and run faster. Do not use this option if you want to store values of any type in the index.
Returns	True

Use the indexobject.Pv.refAttributes method to get a vector containing keys from the index. The optional keys argument allows composite keys partially matching the optional keys argument to be returned.
Syntax: (indexobject.Pv.refAttributes key:)

key:	An optional argument containing a vector of key component values for a composite key index. Keys can be of any type. Partial composite keys may be passed and will return all composite keys that match the partial key specification.
Returns	A vector containing the index keys.

Use the indexobject.Pv.refValues method to get a vector containing the index values. Pass an optional key value to restrict the range of values returned.
Syntax: (indexobject.Pv.refValues key )

key	An optional argument containing a key value for a single key index or a vector of key component values for a composite key index. Keys can be of any type. Partial composite keys may be passed and will return all values that match the partial key specification.
Returns	Vector containing values from index that match the key supplied or all values in index if no key argument was supplied. An empty vector is returned if no matches are found.

Use the indexobject.Pv.update method update a key/value pair in non-unqiue indicies.
Syntax: (indexobject.Pv.update key oldvalue newvalue)

key	An argument containing a key value for a single key index or a vector of key component values for a composite key index.
oldvalue	A value currently associated with the key in the index.
newvalue	A value to replace the old value in the index.
Returns	A reference to the index Lambda.