Objects, Buffers, References and the Dot Syntax

Primary and Secondary (cache) Buffers
Each object utilizes two internal buffers. The primary, that holds the string's data, and a secondary, that is used during SDS<>DDS conversions. E.g., for strD objects, the secondary buffer will be holding SDS data. This can significantly increase performance when working with different types of objects (strDs and strSs), since after the first conversion, subsequent requests won't require converting the data again. The secondary buffer is cleared automatically as required (e.g. when modifying the original string, or changing its codepage). The secondary buffer is used only when required - if you don't mix strDs with strSs, there will be nothing to cache.
The only case (except when changing the NMC) when the cache has to be cleared explicitly is when performing binary, or digit level modifications. Usually, when you go binary, you need speed. Checking if the cache needs to be cleared is a very fast internal procedure, but, for maximum speed, it has been disabled when directly setting bytes/digits - no matter how fast, in lengthy repeat loops the delay would be measurable.

Lazy Developer's note:
To be always on the safe side, instead of:
put _s("my data").char[10..20].word[1]
you should use:
s=_s("my data")
put s.char[10..20].word[1]
Both of the above lines are safe, but with the second approach, the data source object is always locked since it is assigned to a variable. So, you can safely create lines of code that include multiple property selection and regular commands on objects.
If you follow this method, and you don't care that much about speed and string optimizations, you can skip reading all reference / data source / top object stuff below.

Or, you can forget all about combining miltiple commands in a single line all together, and work with the traditional Director's method.

Reference Objects
When an <str> object is created using the _s, _d, or other command, its buffer is filled with the appropriate value. E.g. the command _s("abc") will create a new object, copy "abc" to the object's buffer, and return the object. To be more exact, a reference to the object is returned, but we'll be using the term 'object' to refer to the values returned to the command line, to avoid confusion with the 'reference objects' described below.
So far, everything works as with regular Director strings. However, Xtrema also supports the creation of objects that instead of using their own primary buffer for data retrieval, they pool data from another object's buffer (data source object).
Such dependant objects will be called 'reference objects', or references. Using references can significantly increase performance, but they must be used with caution, since their improper use can even crash Director.

There is just one rule for working safely with reference objects:
Never release/modify the data source object, till your work on all references to it is finished.
A reference to an object can be created with the .ref command.

Definitions
solid object: an object that is keeping its data in its own buffer.
reference object: an object that is pooling its data from another object's buffer.
data source of a reference object: the solid object from which the reference object pools data from.
parent object : the object from which a reference object (offspring) was created. May be a solid object or a reference.

offspring : the reference object created from a parent object. Soon as the reference is returned, no parent-child relation between the parent and the offspring exists.
The offspringwill depend only on its data source (which inherits from its parent). Offsprings are always references, but, they are often converted to solid objects before returned to the command line - see 'top object' below.

top object: the first object in a dot sequence. A top object will not be released until the final property of the dot syntax is returned. All objects created during property accessing will be references to the top object. Soon as property accessing is finished, and if the last property returns an offspring (e.g. myStr.word[2].char[1]), the top object will be examined. If the top object is a solid object, the final offspring will be dereferenced to a solid object as well - unless the dot syntax is terminated with the .ref command. Otherwise, if the top object is a reference, the final offspring won't be dereferenced - it will be a reference, whose data source will be the top object's data source. In this case, the final offspring can be converted to a solid object, if the dot syntax is terminated with the .deref() command.

s=_s("data source object") --solid object, will be the data source of the objects created below.
x=s.char[1..2] --solid. 's' is solid, so the result of the dot syntax will be dereferenced before returned to the command line.
x=s.char[1..2].ref --reference. By using .ref, we instruct the Xtra to not dereference the result.
x=s.char[1..2].word[1] --solid object, created from the parent object s.char[1..2] (internal reference, temporary object since more dots follow)
x=s.char[1..2].word[1].char[1] --solid. The result of s.char[1..2] is the parent of .word[1] , the result of which is the parent of the final object rC.
x=s.ref.char[1..2] --reference. the top object is the result of s.ref (reference object). Since the top object is a ref, the final object will be a ref - its data source will be s, which is the data source of the (temporary) s.ref top object.

The term 'parent object' is an abstract definition referring to the object other objects are created from.
A reference object is created from a parent, but, right after creation, depends only on the data source.
According to the above, even if an itermediate reference object from which offsprings have been created is discarded, working with its offsprings is safe.

s=_s("abcd")
p=s.char[2..3].ref --reference, offspring of s - solid.
r=p.char[1]          --reference, offspring of p - reference.
p=0   --resetting p is safe. 'r' is still usable, since its data source is s, not p.
s=0   --unsafe!! s is r's data source. r is now unusable - its fixed properties are still accessible, but an attempt to access its data, or properties that rely on data access may even crash your application.


Dot Syntax
One of the primary concerns of all of the Xtra's classes is ease of use. Creating smart commands that can evaluate arguments and act accordingly instead of creating multiple strict commands, and allowing a sequence of commands to be executed in just one line of code, are parts of this approach.
This object's dot syntax was not only designed with that philosophy, but goes even further:
By adding support for references / parent objects / offsprings, it is possible to create code lines like this:

s=_s("One and two and three and four!")
put s.idl["and"].item[-1].upper.exp.iSel["two"].insAft("...")
-- One and two... and three and FOUR!

Dot Syntax & Top Object
When accessing a <str> object's selection property, e.g. str.word[1], a new object is created, and <str> becomes the 'top object' of the dot queue.

At that point, the new object will be a reference, or a 'selection', in the top object - no data is being copied to the new object's buffers, just the memory address and length of the target area in the top object's buffer.
Further property accessing, e.g. str.word[1].char[2], return new objects, as above.

The range in the top object of each offspring depends on it's immediate parent - in the last example, str.word[1].char[2], the char command will select the 2nd character of the 1st word of str.
If no further properties are requested, the result is being dereferenced (data is being copied) and str (the top object) is being released, far as the queue is concearned.
If however, str (the top object) is itself a reference, the result won't be dereferenced - it will be dependant to the object the str was dependant to.

Caution to commands that return a reference to the object they were used on:
It is safe to call:
put _s("abcd").toClip().char[1]
but calling
put _s("abcd").char[1].toClip().char[1] -- *invalid data*
is not, and may even crash Director .
The reason:
The .toClip() command of the _s("abcd").char[1].toClip() sequence is performed on the result of _s("abcd").char[1] , which is a reference at this point. Soon as the .toClip() command is finished, the top object will be released. But the .toClip() will return a reference to the object it was called on  (the result of s("abcd").char[1]) , which will be, right after the completion of the command, an orphaned object (a reference whose top object has been disposed). It is safe to request from an orphaned object properties like .err, to check if the command was successful, but ANYTHING that has to do with data access/manipulation, will return invalid data, and may even lead to a chrash.
If you need to continue working with objects that are results of property accessing and finalized with commands that return references, you need to use the .deref() command right after accessing the last property.
This sequence is safe:
put _s("abcd").char[1].deref().toClip().char[1]

Still, if you prefer to work with references in order to avoid data copying, you could use:
s=_s("abcd")
put s.char[1].toClip().char[1]
In the above example, s will become a top object for the .char[1] command, but the actual data won't be disposed at it's release: s is a local variable, and, though the Xtra does not need it any more after property accessing is done, it is being kept alive by Director (until e.g. some other value is assigned to s).

DevNote: When designing string objects, there is always a speed vs security vs flexibility issue. Director's string objects are built for security, sacrificing both speed and flexibility. This class's strings were designed to offer a rich feature set and flexibility, plus extended multilanguage support, with the minimal speed penalty possible. Director's strings will never crash the program. xStrs may cause a crash if not used with caution.
In practice, though objects created with Xtras are slower than native Director objects, you'll find many commands to be from significant to several times faster than Director's equivalents, especially when working with large strings.

As for the command set and dot syntax.. Well, hope you enjoy them.

---