To-do
Methods will be moved up to the new method list as their details are released.
Revisit list:
- isRatio
- hasUnit
- canNum, canInt
- to... equivalents
- toBytes, toBytesOr
- asList/asListOr and getParams/getParamsOr return types for C++
- putNum, putList, putRef
- getNumFigures (getNumSig?), getNumPrec, getNumRes
- setNumFigures (setNumSig?), setNumPrec, setNumRes
- setIncludes, setGlobalIncludes
Design
The primary methods for traversing an article and fetching content will throw exceptions if the structure or data types are not exactly as requested by the caller. The purpose is to make implicit assertions that such structure exists and that the contents are of the expected data type, all as required by the software interface being implemented.
For example, calling getItemAt(2).asDouble() on an element will assert implicitly that it has list content with at least three items available, and that the third item has numeric content.
This way, if getItemAt returns normally then its return value is guaranteed to be a valid element pointer.
Similarly, asDouble can only return a genuine number derived from the article, as opposed to the corresponding value of a string which looks numeric (see toDouble ) or a sentinel value for some non-numeric content (see asDoubleOr ).
Such methods each have a secondary equivalent which returns a default value instead of throwing an exception. These can be used where some aspect of the article is optional, or to satisfy a compiler which tracks exception prospects at compile-time (as with Java).
Method groups
Most method names use a prefix which identifies the general category of that method:
| Prefix | Category | ||
| in | Markup input | ||
| out | Markup output | ||
| link | Element adjacency | ||
| obj | Object codec interface | ||
| copy | Copy between elements | ||
| eq | Compare elements | ||
| is | has | num | Test element state |
| can | Test cast compatibility | ||
| as | Get content (strict) | ||
| to | Cast content (lenient) | ||
| put | Put content | ||
| get | with | Get other | |
| set | clear | Set other | |
| add | new | Add parameter/item | |
| rem | un | Remove parameter/item | |
Additional methods with prefix tx or rx exist for methods which assist the markup encode/decode process, but otherwise are not useful in normal operation.
The only methods without a prefix are validate , walk and reset .
Method list
Input | |
| inStream | Read from stream/handle |
| inString | Read text string |
| inBytes | Read byte array |
| inFile | Read file contents |
Output | |
| outStream outPrint | Write to stream/handle |
| outString | Create text string |
| outBytes | Create byte array |
| outFile | Write/overwrite file |
Adjacency | |
| link | Set both adjacent elements |
| linkNext linkPrev | Set adjacent element |
Codec | |
| objEncode objDecode | Convert object to/from article |
| objCapture objRestore | Top-level encode/decode |
Cloning | |
| copy copyTo | Clone element |
| copyName | Copy name only |
| copyParams | Copy parameters only |
| copyContent | Copy content only |
| copyOptions | Transfer I/O settings |
Comparison | |
| eq | Full comparison |
| eqName | Compare names |
| eqParams | Compare parameters |
| eqContent | Compare contents |
State | |
| hasName isAnon | Test element name |
| isName | Match element name |
| isFirst hasPrev | Test preceding elements |
| isLast hasNext | Test following elements |
| hasParams numParams | Parameters exist |
| hasParam | Parameter name exists |
| isNull hasContent | Content exists |
| isBool | Boolean content |
| isTrue isFalse | Specific boolean content |
| isStr | String content |
| isNum | Numeric content |
| isList numItems | List content |
| hasItem | List item name exists |
| isRef | Element reference content |
| hasRefName hasRefTarget | Reference matches exist |
Cast check | |
| canBool | Boolean interpretation exists |
| canStr | String interpretation exists |
Get content | |
| asBool asBoolOr | Get boolean |
| asStr asStrOr | Get string |
| asInt asIntOr | Get 32-bit integer |
| asLong asLongOr | Get 64-bit integer |
| asFloat asFloatOr | Get 32-bit floating-point |
| asDouble asDoubleOr | Get 64-bit floating-point |
| asList asListOr | Get element list |
| asRef asRefOr | Get element reference |
Cast content | |
| toBool toBoolOr | Cast to boolean |
| toStr toStrOr | Cast to string See note 1 |
Put content | |
| putNull | Erase content |
| putBool | Put boolean |
| putTrue putFalse | Put specific boolean |
| putStr | Put string |
| putNum | Put numeric string |
| putInt putLong | Put integer |
| putFloat putDouble | Put floating-point |
| putList | Put element list |
| putRef | Put element reference |
Get other | |
| getName getNameOr | Get element name |
| getPrev getPrevOr | Get adjacent element before |
| getNext getNextOr | Get adjacent element after |
| getParamFirst getParamFirstOr | Get first parameter |
| getParamLast getParamLastOr | Get last parameter |
| getParamAt getParamAtOr | Get parameter by index |
| getParam getParamOr | Get parameter by name |
| getParamStr getParamStrOr | Cast parameter by name |
| getParams getParamsOr | Get all parameters |
| getItemFirst getItemFirstOr | Get first list item |
| getItemLast getItemLastOr | Get last list item |
| getItemAt getItemAtOr | Get list item by index |
| getItem getItemOr | Get list item by name |
| getItemStr getItemStrOr | Cast list item by name |
| getNumN getNumD | Get numerator/denominator |
| getNumUnit | Get number unit string |
| getRefName getRefTarget | Get reference match strings |
| getRefObj withRefObj | Retrieve reference objects |
| getOpts | Get I/O settings |
Set other | |
| setName clearName | Set/erase element name |
| setParam | Set/overwrite parameter |
| setParamNull clearParam | Erase parameter content |
| setParamBool | Set boolean parameter |
| setParamStr | Set string parameter |
| setParamInt setParamLong | Set integer parameter |
| setParamFloat setParamDouble | Set floating-point parameter |
| setParamRef | Set element reference parameter |
| setParams clearParams | Set/erase parameters |
| setNumUnit | Set number unit string |
| setRefName setRefTarget | Set reference match strings |
| setRefObj | Set reference directly |
| clearContent | Erase content |
| setIncludes setGlobalIncludes | Enable/disable file inclusion |
Add | |
| addParam | Insert parameter |
| addParamAt | Insert parameter at index |
| newParam | Create parameter with name |
| addItem | Insert list item |
| addItemAt | Insert list item at index |
| newItem | Create list item |
Remove | |
| remParam | Remove parameter |
| remParamAt | Remove parameter at index |
| unParam | Remove parameter by name |
| remItem | Remove list item |
| remItemAt | Remove list item at index |
| unItem | Remove list item by name |
Other | |
| validate | Check article integrity |
| walk | Call function recursively |
| reset | Erase all |
Note 1: toStr refers specifically to element content.
It is not a default method for producing a string representation of an object, such as ToString in C#, toString in Java and __str__ in Python.
Input/deserialisation
All methods of the form in... are for calling from a blank element and providing article markup for decoding, with that element becoming the top-level storage for the result.
Officially, each platform is free to provide different input utilities as appropriate, using that name prefix.
In practice, coverage for most platforms is achieved well enough using inStream to read from an input handle, inFile to wrap it for reading files, with inString and inBytes for data already in memory.
Note that file includes are disabled by default.
Use setIncludes to enable that for one element, or the static method setGlobalIncludes to enable it for all future elements (prior to construction).
After the parser is done, this element will become the top-level entry element from the markup stream.
After the parser is done, this element will become the top-level entry element from the markup stream.
After the parser is done, this element will become the top-level entry element from the markup stream.
After the parser is done, this element will become the top-level entry element from the markup stream.
Output/serialisation
All methods of the form out... are for calling on a completed top-level element to obtain encoded markup.
As with inputs, platform-specific methods for markup output are acceptable, using that name prefix.
Due to code style differences, there are two methods for writing to an output handle, outStream which throws if a problem occurs and outPrint which returns false instead.
This is designed to maintain the concept that most platforms have a failure mechanism (or at least an error register) for writing to a file handle in general, but also a safe means to write to standard output.
By design decision, the only cause for an output method to throw an exception is when an underlying I/O error occurs.
Consequently, the process for encoding article markup has to resort to default behaviour if any structural problems are encountered, such that reparsing the output will not recover the original article fully.
To test for this in advance, call validate first before producing article output.
At present, the only possible structural problem is an element reference which is not self-contained within the article. These are known as foreign references, and will output as nulls instead. To avoid this, the structure with the reference and the structure containing the target element should be placed within a wider article which contains both.
If adjacents is true, all preceding and following elements will also be encoded.
If a preceding element was encoded that way, the markup will contain an entry instruction.
Any write errors will be sent back to the caller.
If adjacents is true, all preceding and following elements will also be encoded.
If a preceding element was encoded that way, the markup will contain an entry instruction.
If adjacents is true, all preceding and following elements will also be encoded.
If a preceding element was encoded that way, the markup will contain an entry instruction.
If adjacents is true, all preceding and following elements will also be encoded.
If a preceding element was encoded that way, the markup will contain an entry instruction.
If adjacents is true, all preceding and following elements will also be encoded.
If a preceding element was encoded that way, the markup will contain an entry instruction.
Any write errors will be sent back to the caller.
Adjacent elements
The link... methods make or break the pointers to the previous/next adjacent elements.
These pointers form doubly-linked lists, where each linkage call maintains the pointers on both ends of each link.
These methods exist mainly for the benefit of the markup decoder.
Outside of that, they are intended for building an article with multiple top-level elements.
List items and parameters should be managed from the parent element instead, using add... and rem... for simple changes or putList and setParams after preparing complex changes.
C++ users must be very careful; linking two segments will also share deletion, and breaking a link will prevent deletion. To truncate a segment safely, deleting only the tail elements:
- Test
hasNext()first, proceed if true. - Use
getNext()to fetch the tail pointer. - Break the link with
linkNext(nullptr). deletethe tail pointer.
Avoid delete el->getNext(); , which will fail dramatically.
Places the provided elements adjacent to this one, on either side.
If an element is null, this one will become the first/last in sequence.
Before this operation occurs, any existing links will be cross-connected to remove this element from the chain.
Places the provided element adjacent to this one, next in sequence.
If the element is null, this one will become last in sequence.
Any existing forward link will be undone before this operation.
Places the provided element adjacent to this one, previous in sequence.
If the element is null, this one will become first in sequence.
Any existing reverse link will be undone before this operation.
Object codec interface
By implementing the IDAObj interface, the obj... methods become available for encoding and decoding user objects.
One such object should represent the full state to be captured, containing or referring to others which also implement IDAObj.
Capturing or restoring that object transfers it to or from a top-level article element.
The IDAObj interface specifies three methods to be overridden as needed:
idaName– Return a default name for elements which represent objects of this class.idaEncode– Store the object into a provided element.idaDecode– Use a provided element to recall/rebuild the object.
By default, idaName returns null, and idaEncode and idaDecode throw an exception.
A class should implement idaEncode to enable storage, idaDecode to enable rebuilding, or both for the full store/recall functionality.
Within idaEncode , further/deeper objects can be stored easily if they also implement IDAObj .
For each of these objects, create a new element and pass the object to objEncode , then join the element to the article as a list item or parameter (the top-level object could also use adjacency).
If pointers between objects are required, create elements for them and call setRefObj .
This way, they will be converted into element references after all other encoding is complete.
The idaDecode method should work similarly for rebuilding an object from an element formed by idaEncode .
If a parameter or list item represents a further/deeper object, create the appropriate type then pass it to objDecode .
Pointers are recalled using getRefObj or withRefObj :
getRefObjreturns the object reference immediately, but will throw an exception if the object has yet to be created. Obtaining a pointer during the decode process is only possible if the article is designed so that the target object is created prior to fetching the pointer.withRefObjaccepts a callback function, which will be provided with the target object when it becomes available. Assuming the decode process can proceed now and receive the object later, this is preferable because it avoids imposing that article design dependency.
With that in place, call objCapture or objRestore to begin the full top-level encode/decode process.
These are the same as calling objEncode or objDecode structurally, but they will also perform the proper conversions between object references and element references.
Encode one member object via idaEncode, with automatic element name via idaName. This element will become "representative" of the object, which is used to encode references via setRefObj.
This method should be called from within idaEncode itself, to record members which also implement the IDAObj codec interface. For the top-level operation, user code should call idaCapture instead to ensure that all object references are recorded.
Decode one member object via idaDecode. This element will become "representative" of the object, which is used to decode references via getRefObj or withRefObj.
This method should be called from within idaDecode itself, to create members which also implement the IDAObj codec interface. For the top-level operation, user code should call idaRestore instead to verify that all object reference requests were resolved.
Top-level article encode operation for a full object tree. This method calls objEncode, so the top-level object must implement idaEncode.
After all encoding is complete, any object references declared via setRefObj will be established as element references in the article.
Top-level article decode operation for a full object tree. This method calls objDecode, so the top-level object must implement idaDecode.
After all decoding is complete, the integrity will be checked to ensure that all object reference requests were resolved. If any calls to withRefObj did not receive the deferred result, an exception is thrown. This occurs if the article contained an element reference for which no object was constructed via objDecode.
Element cloning
The copy... methods are used for making one element become the same as another in various ways, either in the context of a single feature or of the entire element recursively.
Following a copy operation, it should be the case that the two elements test equal with the corresponding eq... method.
A copy of a full article element should output the same markup as the original.
A cloned element is independent of the original used to create it, and can be modified as needed without affecting that original. If element references are involved, the targets within the cloned context will be the cloned elements which correspond to the targets within the original context.
C++ users should consider that calling copy will create a new element object, which should be freed explicitly unless joined to become part of a larger article (use copyTo to supply your own object instead).
Note also that cloning parameters and list content will create new element objects; these will be freed implicitly unless detached.
Create a new element as a copy of all aspects of this element. Any parameters or list content will be cloned recursively.
Modify the provided element to become a copy of all aspects of this element. Any parameters or list content will be cloned recursively.
Set the name of this element to match the name of the provided element.
Set the parameters of this element to be clones of the parameters of the provided element.
Set the content of this element to match the content of the provided element. If the content in question is a list, its inner elements will be cloned.
Set the input/output options of this element to match those of the provided element.
Comparison tests
The eq... methods test various aspects of whether an element is equal to another element, with eq providing a combined call which depends on each of the others.
Two elements are equal if they have the same name with eqName, parameters with eqParams and content with eqContent.
The arrays for parameters and list content are equal if their elements are equal as defined by eq itself, providing full depth recursion.
Non-list contents are equal if they have the same inherent type, and their values match in a type-dependent way (generally, if they represent the same information). Booleans must match, and strings must contain the same Unicode characters in sequence.
Beyond matching numerically, numbers must also have the same precision. Additional decimal places in the representation inform a user that the number was measurable with greater precision, and this difference of information makes the elements non-equal regardless of their numeric values. Existing platform means should be used to test whether two numeric values are equal, keeping in mind to use some small tolerance when comparing results of floating-point arithmetic.
References are more complicated, and are not simply equal if their referenced elements are equal.
This would ignore the intended concept; for example, references to any in a list of identical elements would then be considered equal despite pointing to different positions within the list.
It also causes logic problems, such as eqContent entering infinite recursion.
Instead, when testing whether two elements are equal, temporary scopes are created in which those elements are assumed to be top-level articles. References are then tested as follows:
- If a reference target is an element within the same scope, it is called a scope reference. To be equal, the other also must be a scope reference, and must target the corresponding element within its article structure.
- Otherwise, both are foreign references with targets outside of their respective scopes. All foreign references are considered equal regardless of their targets.
The reason for considering foreign references equal by default is that they exist relative to a scope/context in which they cannot be proven to represent different information. It is at least allowable that two elements are equal when viewed narrowly but may be non-equal in a wider context, whereas it is not acceptable for two high-level elements to be equal despite some inner elements being non-equal. Moreover, foreign references have no place in an article which is properly self-contained, and will output as null (thus becoming explicitly equal).
Use validate to ensure that this will not occur, and consider designing the article structure to have a higher level which spans all of the needed references.
The higher-level elements can then be compared with eq more meaningfully.
Perform a top-level comparison of this element and the provided element.
To be equal, both elements must match when interpreted as full articles. The element names, parameters and content must all match recursively.
Note that content matches consider whether the information is the same. See eqContent for details.
Compare the contents of this element and the provided element.
The content type must match, and the contents must match in a type-dependent way such that each element contains the same information. Numbers must have the same precision, and scope references must target the same element relative to each scope. Foreign references are equal by default.
Element state
The methods beginning is... , has... and num... all provide different forms of information about an element.
These span all element aspects; its name, parameters, content type, content value and whether adjacent elements are present.
Several of these methods provide alternative options for obtaining the same information about an element. In most cases, these additional methods are intended for convenience with lambdas. For example:
isTrueandisFalseare specialised versions of callingisBoolthenasBool.isFirstandisLastrefer to adjacenct elements, and are the opposites ofhasPrevandhasNext.isAnonis the opposite ofhasName.
For parameters and for list content, numParams and numItems will provide a respective element count.
Note that elements distinguish between having an empty list (numParams/numItems are zero) and having no list (hasParams/isList are false).
The sentinel value −1 is returned for the number of items of a non-existent list.
These methods also include some which report whether reference identifiers have been assigned. This is a form of meta-data which may be fresh or stale depending on what article-related actions have occurred. The identifiers will be stale if any references are created or updated at runtime.
Immediately after decoding a markup document, the identifiers will be fresh (and equal to those used in the document). Otherwise, the following actions will generate fresh identifiers:
- Encoding an article.
- Copying a top-level article element.
- Testing whether two top-level article elements are equal.
- Calling
txRefLabelat top-level to generate identifiers manually.
Test whether this element has a name. The name can be any non-null string, including the empty string.
Test whether this element has no name. The name must be null, not merely the empty string.
This is the opposite of hasName, intended as a convenience for function references.
Test whether this element has a specific name. Providing null will perform the same test as with isAnon.
Test whether no element is adjacent to this element in the reverse direction.
This is the opposite of hasPrev, intended as a convenience for function references.
Test whether an element is adjacent to this element in the reverse direction.
Test whether no element is adjacent to this element in the forward direction.
This is the opposite of hasNext, intended as a convenience for function references.
Test whether an element is adjacent to this element in the forward direction.
Test whether this element contains a parameters list.
This reports whether a parameters list object exists at all, as opposed to whether at least one parameter is present. The primary purpose is to ensure the list exists before calling getParams and/or iterating over its elements.
Use numParams to test for an empty list (0) or at least one parameter present (greater than 0).
Fetch the number of parameters within this element.
If no parameters list is present, the sentinel value -1 is returned. If 0 is returned, the list is present but empty.
Test whether this element contains a parameter with the provided name. If it does, an equivalent call to getParam will return an element.
If false is returned, this can be either due to having no parameter of that name or due to having no parameters list. Use hasParams to separate those two cases.
Test whether this element contains no content.
This is the opposite of hasContent, intended as a convenience for function references.
Test whether this element contains some type of content.
This is the opposite of isNull, intended as a convenience for function references.
Test whether the content type of this element is a boolean value.
Test whether the content of this element is boolean-true.
If false is returned, this can be either due to being boolean-false or not being a boolean value. Use isBool and asBool for methods with those effects.
This is intended as a convenience for function references.
Test whether the content of this element is boolean-false.
If false is returned, this can be either due to being boolean-true or not being a boolean value. Use isBool and (not-)asBool for methods with those effects.
This is intended as a convenience for function references.
Test whether the content type of this element is a string value.
Test whether the content type of this element is a numeric value.
Test whether the content type of this element is a list.
This reports whether the content is a list or non-list, as opposed to whether at least one list item is present. The primary purpose is to ensure the list exists before calling asList and/or iterating over its elements.
Use numItems to test for an empty list (0) or at least one item present (greater than 0).
Fetch the number of content list items within this element.
If no content list is present, the sentinel value -1 is returned. If 0 is returned, the list is present but empty.
Test whether this element contains a list item with the provided name. If it does, an equivalent call to getItem will return an element.
If false is returned, this can be either due to having no list item of that name or due to being a non-list. Use isList to separate those two cases.
Test whether the content type of this element is a reference to another element.
Test whether this element has been assigned a transient identifier for encoding/decoding inbound references. The returned value may be stale.
If an article has been decoded from markup, any reference target elements will have fresh identifiers from the markup document. Encoding, copying or testing equal a top-level article element will generate fresh identifiers.
Call txRefLabel at top-level to generate fresh identifiers manually.
Test whether this element has been assigned a transient target for encoding/decoding an outbound reference. The returned value may be stale.
If an article has been decoded from markup, any reference target elements will have fresh identifiers from the markup document. Encoding, copying or testing equal a top-level article element will generate fresh identifiers.
Call txRefLabel at top-level to generate fresh identifiers manually.
Cast check
Test whether this element content can be interpreted as a boolean value (see toBool). This will always be the case for natural boolean content (see isBool).
All numeric content can be cast to boolean, which is true if non-zero. String content can be "true" or "false".
Test whether this element content can be interpreted as a string value (see toStr). This will always be the case for natural string content (see isStr).
Most content can be cast to string. Types which cannot be cast are lists, references and nulls.
Get content
Fetch this element content as a boolean value.
If this element content is not a boolean value, an exception is thrown. To avoid that possibility, use asBoolOr to provide a default value. One may also use isTrue for false by default, or not-isFalse for true by default.
Use toBool/toBoolOr for casting other content types to be a boolean value.
Fetch this element content as a boolean value.
If this element content is not a boolean value, the provided default value is returned.
Fetch this element content as a string value.
If this element content is not a string value, an exception is thrown. To avoid that possibility, use asStrOr to provide a default value.
Use toStr/toStrOr for casting other content types to be a string value.
Fetch this element content as a string value.
If this element content is not a string value, null is returned.
This method exists for platform compatibility where strings are not nullable/optional, such as with C++. The purpose is for this return type to be a nullable string container, while asStrOr(other) returns a string directly. On platforms where string values can be null, asStrOr() is equivalent to asStrOr(null), but only the former is fully portable.
Fetch this element content as a string value.
If this element content is not a string value, the provided default value is returned.
On platforms where strings are nullable/optional, the return value is guaranteed to be non-null if the default value is non-null. The purpose is for this return type to be a guaranteed string, such that code will not be fully portable if null is provided. If possible, always call asStrOr() rather than asStrOr(null).
Fetch this element content as a 32-bit integer value.
If this element content is not numeric, an exception is thrown. To avoid that possibility, use asIntOr to provide a default value.
Use toInt/toIntOr for casting other content types to be a 32-bit integer value.
Fetch this element content as a 32-bit integer value.
If this element content is not numeric, the provided default value is returned.
Fetch this element content as a 64-bit integer value.
If this element content is not numeric, an exception is thrown. To avoid that possibility, use asLongOr to provide a default value.
Use toLong/toLongOr for casting other content types to be a 64-bit integer value.
Fetch this element content as a 64-bit integer value.
If this element content is not numeric, the provided default value is returned.
Fetch this element content as a 32-bit floating-point value.
If this element content is not numeric, an exception is thrown. To avoid that possibility, use asFloatOr to provide a default value.
Use toFloat/toFloatOr for casting other content types to be a 32-bit floating-point value.
Fetch this element content as a 32-bit floating-point value.
If this element content is not numeric, the provided default value is returned.
Fetch this element content as a 64-bit floating-point value.
If this element content is not numeric, an exception is thrown. To avoid that possibility, use asDoubleOr to provide a default value.
Use toDouble/toDoubleOr for casting other content types to be a 64-bit floating-point value.
Fetch this element content as a 64-bit floating-point value.
If this element content is not numeric, the provided default value is returned.
Fetch this element content as a list (containing other elements).
If this element content is not a list, an exception is thrown. To avoid that possibility, use asListOr to provide a default value.
Fetch this element content as a list (containing other elements).
If this element content is not a list, null is returned.
This method exists for platform compatibility where lists/vectors are not nullable/optional, such as with C++. The purpose is for this return type to be a nullable list container, while asListOr(other) returns a list directly. On platforms where lists can be null, asListOr() is equivalent to asListOr(null), but only the former is fully portable.
Fetch this element content as a list (containing other elements).
If this element content is not a list, the provided default value is returned.
On platforms where lists/vectors are nullable/optional, the return value is guaranteed to be non-null if the default value is non-null. The purpose is for this return type to be a guaranteed list, such that code will not be fully portable if null is provided. If possible, always call asListOr() rather than asListOr(null).
Fetch this element content as a reference (to another element).
If this element content is not a reference, an exception is thrown. To avoid that possibility, use asRefOr to provide a default value.
Fetch this element content as a reference (to another element).
If this element content is not a reference, null is returned.
Fetch this element content as a reference (to another element).
If this element content is not a reference, the provided default value is returned.
Cast content
Cast this element content to a boolean value.
If this element content can not be interpreted as a boolean value, an exception is thrown. To avoid that possibility, use toBoolOr to provide a default value.
Cast this element content to a boolean value.
If this element content can not be interpreted as a boolean value, the provided default value is returned.
Cast this element content to a string value.
If this element content can not be interpreted as a string value, an exception is thrown. To avoid that possibility, use toStrOr to provide a default value.
Cast this element content to a string value.
If this element content can not be interpreted as a string value, null is returned.
This method exists for platform compatibility where strings are not nullable/optional, such as with C++. The purpose is for this return type to be a nullable string container, while toStrOr(other) returns a string directly. On platforms where string values can be null, toStrOr() is equivalent to toStrOr(null), but only the former is fully portable.
Cast this element content to a string value.
If this element content can not be interpreted as a string value, the provided default value is returned.
On platforms where strings are nullable/optional, the return value is guaranteed to be non-null if the default value is non-null. The purpose is for this return type to be a guaranteed string, such that code will not be fully portable if null is provided. If possible, always call toStrOr() rather than toStrOr(null).
Put content
Erase any existing content from this element.
This is the same as calling clearContent.
Place boolean content into this element with the provided value, replacing any existing content.
Place boolean content into this element with value true, replacing any existing content.
Place boolean content into this element with value false, replacing any existing content.
Place string content into this element with the provided value, replacing any existing content.
Place 32-bit integer content into this element with the provided value, replacing any existing content.
If the provided unit string is non-null, also updates the unit string for this number (see setNumUnit).
Place 64-bit integer content into this element with the provided value, replacing any existing content.
If the provided unit string is non-null, also updates the unit string for this number (see setNumUnit).
Place 32-bit floating-point content into this element with the provided value, replacing any existing content.
If the provided unit string is non-null, also updates the unit string for this number (see setNumUnit).
Place 64-bit floating-point content into this element with the provided value, replacing any existing content.
If the provided unit string is non-null, also updates the unit string for this number (see setNumUnit).
Get other
Fetch this element name string.
If this element content is anonymous, an exception is thrown. To avoid that possibility, use getNameOr to provide a default value.
Fetch this element name string.
If this element content is anonymous, null is returned.
This method exists for platform compatibility where strings are not nullable/optional, such as with C++. The purpose is for this return type to be a nullable string container, while getNameOr(other) returns a string directly. On platforms where string values can be null, getNameOr() is equivalent to getNameOr(null), but only the former is fully portable.
Fetch this element name string.
If this element content is anonymous, the provided default value is returned.
On platforms where strings are nullable/optional, the return value is guaranteed to be non-null if the default value is non-null. The purpose is for this return type to be a guaranteed string, such that code will not be fully portable if null is provided. If possible, always call getNameOr() rather than getNameOr(null).
Fetch the adjacent element before this one.
If this element is first, an exception is thrown. To avoid that possibility, use getPrevOr to provide a default value.
Fetch the adjacent element before this one.
If this element is first, null is returned.
Fetch the adjacent element before this one.
If this element is first, the provided default value is returned.
Fetch the adjacent element after this one.
If this element is last, an exception is thrown. To avoid that possibility, use getNextOr to provide a default value.
Fetch the adjacent element after this one.
If this element is last, null is returned.
Fetch the adjacent element after this one.
If this element is last, the provided default value is returned.
Fetch the first parameter element in this element's parameters list.
If this element has no parameters list or has an empty parameters list, an exception is thrown. To avoid that possibility, use getParamFirstOr to provide a default value.
Fetch the first parameter element in this element's parameters list.
If this element has no parameters list or has an empty parameters list, null is returned.
Fetch the first parameter element in this element's parameters list.
If this element has no parameters list or has an empty parameters list, the provided default value is returned.
Fetch the last parameter element in this element's parameters list.
If this element has no parameters list or has an empty parameters list, an exception is thrown. To avoid that possibility, use getParamLastOr to provide a default value.
Fetch the last parameter element in this element's parameters list.
If this element has no parameters list or has an empty parameters list, null is returned.
Fetch the last parameter element in this element's parameters list.
If this element has no parameters list or has an empty parameters list, the provided default value is returned.
Fetch the parameter element at the provided index in this element's parameters list.
If this element has no parameters list or has too few parameters in the list, an exception is thrown. To avoid that possibility, use getParamAtOr to provide a default value.
Fetch the parameter element at the provided index in this element's parameters list.
If this element has no parameters list or has too few parameters in the list, null is returned.
Fetch the parameter element at the provided index in this element's parameters list.
If this element has no parameters list or has too few parameters in the list, the provided default value is returned.
Fetch the first parameter element with the provided name in this element's parameters list.
If this element has no parameters list or has no parameter of that name, an exception is thrown. To avoid that possibility, use getParamOr to provide a default value.
Fetch the first parameter element with the provided name in this element's parameters list.
If this element has no parameters list or has no parameter of that name, null is returned.
Fetch the first parameter element with the provided name in this element's parameters list.
If this element has no parameters list or has no parameter of that name, the provided default value is returned.
Cast to a string value the first parameter element with the provided name in this element's parameters list.
If this element has no parameters list, has no parameter of that name or can not be interpreted as a string value, an exception is thrown. To avoid that possibility, use getParamStrOr to provide a default value.
Cast to a string value the first parameter element with the provided name in this element's parameters list.
If this element has no parameters list, has no parameter of that name or can not be interpreted as a string value, null is returned.
This method exists for platform compatibility where strings are not nullable/optional, such as with C++. The purpose is for this return type to be a nullable string container, while getParamStrOr(key, other) returns a string directly. On platforms where string values can be null, getParamStrOr(key) is equivalent to getParamStrOr(key, null), but only the former is fully portable.
Cast to a string value the first parameter element with the provided name in this element's parameters list.
If this element has no parameters list, has no parameter of that name or can not be interpreted as a string value, the provided default value is returned.
On platforms where strings are nullable/optional, the return value is guaranteed to be non-null if the default value is non-null. The purpose is for this return type to be a guaranteed string, such that code will not be fully portable if null is provided. If possible, always call getParamStrOr(key) rather than getParamStrOr(key, null).
Fetch this element's parameters list.
If this element has no parameters list, an exception is thrown. To avoid that possibility, use getParamsOr to provide a default value.
Fetch this element's parameters list.
If this element has no parameters list, null is returned.
This method exists for platform compatibility where lists/vectors are not nullable/optional, such as with C++. The purpose is for this return type to be a nullable list container, while getParamsOr(other) returns a list directly. On platforms where lists can be null, getParamsOr() is equivalent to getParamsOr(null), but only the former is fully portable.
Fetch this element's parameters list.
If this element has no parameters list, the provided default value is returned.
On platforms where lists/vectors are nullable/optional, the return value is guaranteed to be non-null if the default value is non-null. The purpose is for this return type to be a guaranteed list, such that code will not be fully portable if null is provided. If possible, always call getParamsOr() rather than getParamsOr(null).
Fetch the first item element in this element's content list.
If this element content is not a list or is an empty list, an exception is thrown. To avoid that possibility, use getItemFirstOr to provide a default value.
Fetch the first item element in this element's content list.
If this element content is not a list or is an empty list, null is returned.
Fetch the first item element in this element's content list.
If this element content is not a list or is an empty list, the provided default value is returned.
Fetch the last item element in this element's content list.
If this element content is not a list or is an empty list, an exception is thrown. To avoid that possibility, use getItemLastOr to provide a default value.
Fetch the last item element in this element's content list.
If this element content is not a list or is an empty list, null is returned.
Fetch the last item element in this element's content list.
If this element content is not a list or is an empty list, the provided default value is returned.
Fetch the item element at the provided index in this element's content list.
If this element content is not a list or has too few items in the list, an exception is thrown. To avoid that possibility, use getItemAtOr to provide a default value.
Fetch the item element at the provided index in this element's content list.
If this element content is not a list or has too few items in the list, null is returned.
Fetch the item element at the provided index in this element's content list.
If this element content is not a list or has too few items in the list, the provided default value is returned.
Fetch the first item element with the provided name in this element's content list.
If this element content is not a list or has no item of that name, an exception is thrown. To avoid that possibility, use getItemOr to provide a default value.
Fetch the first item element with the provided name in this element's content list.
If this element content is not a list or has no item of that name, null is returned.
Fetch the first item element with the provided name in this element's content list.
If this element content is not a list or has no item of that name, the provided default value is returned.
Cast to a string value the first item element with the provided name in this element's content list.
If this element content is not a list, has no item of that name or can not be interpreted as a string value, an exception is thrown. To avoid that possibility, use getItemStrOr to provide a default value.
Cast to a string value the first item element with the provided name in this element's content list.
If this element content is not a list, has no item of that name or can not be interpreted as a string value, null is returned.
This method exists for platform compatibility where strings are not nullable/optional, such as with C++. The purpose is for this return type to be a nullable string container, while getItemStrOr(key, other) returns a string directly. On platforms where string values can be null, getItemStrOr(key) is equivalent to getItemStrOr(key, null), but only the former is fully portable.
Cast to a string value the first item element with the provided name in this element's content list.
If this element content is not a list, has no item of that name or can not be interpreted as a string value, the provided default value is returned.
On platforms where strings are nullable/optional, the return value is guaranteed to be non-null if the default value is non-null. The purpose is for this return type to be a guaranteed string, such that code will not be fully portable if null is provided. If possible, always call getItemStrOr(key) rather than getItemStrOr(key, null).
Fetch the numerator string for the number represented by this element content.
If this element content is not numeric, an exception is thrown. If the number was not a quotient, calling getNumN will return the same result as calling toStr.
Fetch the denominator string for the number represented by this element content.
If this element content is not numeric, an exception is thrown. If the number was not a quotient, calling getNumD will return "1".
Fetch the unit string appended to the number represented by this element content.
If this element content is not numeric, an exception is thrown. If numeric content had no unit specified, an empty string is returned.
Fetch the transient identifier for this element. The returned value may be stale.
Identifiers are set automatically when encoding/decoding markup, testing equal, or calling txRefLabel directly. Encoding, copying or testing equal a top-level article element will generate fresh identifiers.
These names are used only for capturing and restoring element pointer information. The string content itself is not information, insofar as it need not survive a loop test.
Fetch the transient target for this element. The returned value may be stale.
The targets match the identifiers assigned via setRefName, and are used only for capturing and restoring element pointer information. The string content itself is not information, insofar as it need not survive a loop test.
Fetches the object corresponding with the referenced element, after it has been encoded or decoded. During a restore/decode process, an exception is thrown if the object is not yet available.
To retrieve the object this way during a restore/decode process, the article structure must be designed such that the referenced object element is decoded in advance of this call. Use withRefObj instead if that design is not the case.
Calling code should use article information to establish the correct object type.
During a restore/decode process, the object corresponding with the referenced element will be sent to the callback when it becomes available. If that object is already available, the callback will be resolved before this call returns.
If the object is needed immediately, the article structure must be designed such that the referenced object element is decoded in advance of this call. Use getRefObj instead if that design should be enforced.
To ensure consistency, a top-level call to objRestore will throw an exception if any unresolved callbacks remain after decoding is complete.
Calling code should use article information to establish the correct object type.
Fetch the input/output options for this element.
Set other
Set the name of this element to be the provided string.
If the provided string is null, this element will become anonymous as with calling clearName.
Clear the name of this element, leaving it anonymous.
If this element has no parameters list, a new list will be created.
Replace the first matching parameter name, or insert a new parameter.
If this element has no parameters list, a new list will be created.
This is the same as calling clearParam.
Replace the first matching parameter name, or insert a new parameter.
If this element has no parameters list, a new list will be created.
This is the same as calling setParamNull.
If this element has no parameters list, a new list will be created.
If this element has no parameters list, a new list will be created.
If this element has no parameters list, a new list will be created.
If this element has no parameters list, a new list will be created.
If this element has no parameters list, a new list will be created.
If this element has no parameters list, a new list will be created.
If this element has no parameters list, a new list will be created.
Set this element's parameters to be an empty list.
Any existing parameter elements will be deleted.
Delete this element's parameters list.
If this element has no parameters list, calling clearParams has no effect.
Set the unit string appended to the number represented by this element content.
Passing null to setNumUnit has no effect. To clear the unit, call setNumUnit with an empty string.
If this element content is not numeric, an exception is thrown.
Set a transient identifier for this element.
Identifiers are set automatically when encoding/decoding markup, testing equal, or calling txRefLabel directly. Encoding, copying or testing equal a top-level article element will generate fresh identifiers.
These names are used only for capturing and restoring element pointer information. The string content itself is not information, insofar as it need not survive a loop test.
Set a transient target for this element.
The targets match the identifiers assigned via setRefName, and are used only for capturing and restoring element pointer information. The string content itself is not information, insofar as it need not survive a loop test.
Sets an object for which this element should reference the corresponding element as it is encoded.
During a restore/decode process, the rebuilt object can be retrieved using getRefObj or withRefObj. The IDAObj codec interface implementation should ensure that any required type information is captured.
Erase any existing content from this element.
This is the same as calling putNull.
The provided working dir is used for resolving relative paths.
Set null to disable includes.
The present runtime working dir is used for resolving relative paths.
The provided working dir is used for resolving relative paths.
Set null to disable includes by default.
The present runtime working dir is used for resolving relative paths.
Add parameter/item
If this element has no parameters list, a new list will be created.
If this element has no parameters list, a new list will be created.
If this element has no parameters list, a new list will be created.
If this element does not have list content, a new list will be created.
If this element does not have list content, a new list will be created if the makeList flag is set, otherwise an exception is thrown.
If this element does not have list content, an exception is thrown.
If this element does not have list content, a new list will be created, overwriting existing content.
If this element does not have list content, a new list will be created if the makeList flag is set, otherwise an exception is thrown.
Remove parameter/item
If the parameter is absent or this element has no parameters list, the call has no effect.
If this element has no parameters list, an exception is thrown.
If no such parameter exists or this element has no parameters list, the call has no effect.
If the item is absent or this element does not have list content, the call has no effect.
If this element does not have list content, an exception is thrown.
If no such item exists or this element does not have list content, the call has no effect.
Other operations
Check the integrity of article element. If a problem is detected which would lead to errors or corrupted output, an exception is thrown with details in the exception text.
The tests can be performed with adjacent elements enabled or disabled, matching the markup output modes. Note that disabling adjacents may avoid some problems (such as with linkage), but may also induce others (such as with references).
The top-level element linkage is tested to ensure that there are no loops, and that adjacent elements are doubly-linked correctly. A bad double-link can disrupt the output flow, and a loop can cause infinite iteration.
Any elements with reference content are tested for foreign references, which become lost/null during output.
Call the provided function once for each element within this article.
This element is passed first, then its parameters (if any), then its list content items (if any). Parameters and list items are treated recursively until the full article has been traversed.
Optionally, the walk may also traverse adjacent elements recursively, requested via the reverse and forward flags.
Initialisate this element anew.
All existing information comprising this element will be discarded. The result will be an anonymous, null-content element with no parameters list, no adjacent elements and default input/output options.