QoreListNode Class Reference

This is the list container type in Qore, dynamically allocated only, reference counted. More...

#include <QoreListNode.h>

Inheritance diagram for QoreListNode:

AbstractQoreNode QoreReferenceCounter

List of all members.

Public Member Functions

DLLEXPORT int getAsString (QoreString &str, int foff, class ExceptionSink *xsink) const
 concatenate the verbose string representation of the list (including all contained values) to an existing QoreString
DLLEXPORT QoreStringgetAsString (bool &del, int foff, class ExceptionSink *xsink) const
 returns a QoreString giving the verbose string representation of the List (including all contained values)
virtual DLLEXPORT class
AbstractQoreNode
realCopy () const
 returns true if the list contains parse expressions and therefore needs evaluation to return a value, false if not
virtual DLLEXPORT bool is_equal_soft (const AbstractQoreNode *v, ExceptionSink *xsink) const
 tests for equality ("deep compare" including all contained values) with possible type conversion (soft compare)
virtual DLLEXPORT bool is_equal_hard (const AbstractQoreNode *v, ExceptionSink *xsink) const
 tests for equality ("deep compare" including all contained values) without type conversions (hard compare)
virtual DLLEXPORT const char * getTypeName () const
 returns the type name as a c string
DLLEXPORT AbstractQoreNoderetrieve_entry (qore_size_t index)
 returns the element at "index" (first element is index 0)
DLLEXPORT const AbstractQoreNoderetrieve_entry (qore_size_t index) const
 returns the element at "index" (first element is index 0)
DLLEXPORT AbstractQoreNodeget_referenced_entry (qore_size_t index) const
 returns the element at "index" (first element is index 0), the caller owns the reference
DLLEXPORT int getEntryAsInt (qore_size_t index) const
 returns the value of element at "index" as an integer (first element is index 0)
DLLEXPORT AbstractQoreNode ** get_entry_ptr (qore_size_t index)
DLLEXPORT AbstractQoreNode ** getExistingEntryPtr (qore_size_t index)
DLLEXPORT void set_entry (qore_size_t index, AbstractQoreNode *val, class ExceptionSink *xsink)
 sets the value of a list element
DLLEXPORT AbstractQoreNodepop ()
 returns the last element of the list, the length is decremented by one, caller owns the reference
DLLEXPORT AbstractQoreNodeshift ()
 returns the first element of the list, all other entries are moved down to fill up the first position, caller owns the reference
DLLEXPORT void merge (const QoreListNode *list)
 appends the elements of "list" to this list
DLLEXPORT int delete_entry (qore_size_t index, class ExceptionSink *xsink)
DLLEXPORT void pop_entry (qore_size_t index, class ExceptionSink *xsink)
DLLEXPORT QoreListNodeevalList (class ExceptionSink *xsink) const
 evaluates the list and returns a value (or 0)
DLLEXPORT QoreListNodeevalList (bool &needs_deref, class ExceptionSink *xsink) const
 optionally evaluates the list
DLLEXPORT QoreListNodecopy () const
 performs a deep copy of the list and returns the new list
DLLEXPORT QoreListNodecopyListFrom (qore_size_t index) const
 performs a deep copy of the list starting from element "offset" and returns the new list
DLLEXPORT QoreListNodesort () const
 returns a new list based on quicksorting the source list ("this")
DLLEXPORT QoreListNodesort (const class ResolvedCallReferenceNode *fr, class ExceptionSink *xsink) const
 returns a new list based on quicksorting the source list ("this") using the passed function reference to determine lexical order
DLLEXPORT QoreListNodesortStable () const
 returns a new list based on executing mergesort on the source list ("this")
DLLEXPORT QoreListNodesortStable (const class ResolvedCallReferenceNode *fr, class ExceptionSink *xsink) const
 returns a new list based on executing mergesort on the source list ("this") using the passed function reference to determine lexical order
DLLEXPORT QoreListNodesortDescending () const
 returns a new list based on quicksorting the source list ("this") in descending order
DLLEXPORT QoreListNodesortDescending (const class ResolvedCallReferenceNode *fr, class ExceptionSink *xsink) const
 returns a new list based on quicksorting the source list ("this") in descending order, using the passed function reference to determine lexical order
DLLEXPORT QoreListNodesortDescendingStable () const
 returns a new list based on executing mergesort on the source list ("this") in descending order
DLLEXPORT QoreListNodesortDescendingStable (const class ResolvedCallReferenceNode *fr, class ExceptionSink *xsink) const
 returns a new list based on executing mergesort on the source list ("this") in descending order, using the passed function reference to determine lexical order
DLLEXPORT AbstractQoreNodemin () const
 returns the element having the lowest value (determined by calling OP_LOG_LT - the less-than "<" operator)
DLLEXPORT AbstractQoreNodemax () const
 returns the element having the highest value (determined by calling OP_LOG_GT - the greater-than ">" operator)
DLLEXPORT AbstractQoreNodemin (const class ResolvedCallReferenceNode *fr, class ExceptionSink *xsink) const
 returns the element having the lowest value (determined by calling the function reference passed to give lexical order)
DLLEXPORT AbstractQoreNodemax (const class ResolvedCallReferenceNode *fr, class ExceptionSink *xsink) const
 returns the element having the highest value (determined by calling the function reference passed to give lexical order)
DLLEXPORT void splice (qore_offset_t offset, class ExceptionSink *xsink)
 truncates the list at position "offset" (first element is offset 0)
DLLEXPORT void splice (qore_offset_t offset, qore_offset_t length, class ExceptionSink *xsink)
 removes "length" elements at position "offset" (first element is offset 0)
DLLEXPORT void splice (qore_offset_t offset, qore_offset_t length, const AbstractQoreNode *l, class ExceptionSink *xsink)
 adds a single value or a list of values ("l") to list possition "offset", while removing "length" elements
DLLEXPORT qore_size_t size () const
 returns the number of elements in the list
DLLEXPORT bool empty () const
 returns true if the list is empty
DLLEXPORT QoreListNodereverse () const
 returns a list with the order of the elements reversed
DLLEXPORT QoreListNodelistRefSelf () const
 returns "this" with an incremented reference count
DLLLOCAL QoreListNode (bool i)
 this function is not exported in the qore library
DLLLOCAL bool isFinalized () const
 this function is not exported in the qore library
DLLLOCAL void setFinalized ()
 this function is not exported in the qore library
DLLLOCAL bool isVariableList () const
 this function is not exported in the qore library
DLLLOCAL void setVariableList ()
 this function is not exported in the qore library
DLLLOCAL void clearNeedsEval ()
 this function is not exported in the qore library
DLLLOCAL void setNeedsEval ()
 this function is not exported in the qore library
DLLLOCAL void clear ()
 this function is not exported in the qore library
DLLLOCAL AbstractQoreNodeeval_entry (qore_size_t num, class ExceptionSink *xsink) const
 this function is not exported in the qore library

Static Public Member Functions

static DLLLOCAL const char * getStaticTypeName ()
 returns true if the list does not contain any parse expressions, otherwise returns false

Protected Member Functions

DLLLOCAL int qsort (const class ResolvedCallReferenceNode *fr, qore_size_t left, qore_size_t right, bool ascending, class ExceptionSink *xsink)
 qsort sorts the list in-place (unstable)
DLLLOCAL int mergesort (const class ResolvedCallReferenceNode *fr, bool ascending, class ExceptionSink *xsink)
 mergesort sorts the list in-place (stable)
DLLLOCAL QoreListNodeeval_intern (class ExceptionSink *xsink) const
 does an unconditional evaluation of the list and returns the new list, 0 if there is a qore-language exception
virtual DLLEXPORT ~QoreListNode ()
 the destructor is protected so it cannot be called directly
virtual DLLEXPORT bool derefImpl (class ExceptionSink *xsink)
 dereferences all elements of the list
virtual DLLEXPORT class
AbstractQoreNode
evalImpl (class ExceptionSink *xsink) const
 evaluates the list and returns a value (or 0)
virtual DLLLOCAL AbstractQoreNodeevalImpl (bool &needs_deref, ExceptionSink *xsink) const
 optionally evaluates the argument
virtual DLLLOCAL int64 bigIntEvalImpl (ExceptionSink *xsink) const
 always returns 0
virtual DLLLOCAL int integerEvalImpl (ExceptionSink *xsink) const
 always returns 0
virtual DLLLOCAL bool boolEvalImpl (ExceptionSink *xsink) const
 always returns false
virtual DLLLOCAL double floatEvalImpl (ExceptionSink *xsink) const
 always returns 0.0

Protected Attributes

struct qore_list_private * priv
 this structure holds the private implementation for the type


Detailed Description

This is the list container type in Qore, dynamically allocated only, reference counted.

it is both a value type and can hold parse expressions as well (in which case it needs to be evaluated) the first element in the list is element 0


Constructor & Destructor Documentation

virtual DLLEXPORT QoreListNode::~QoreListNode (  )  [protected, virtual]

the destructor is protected so it cannot be called directly

use the deref(ExceptionSink) function to release the reference count

See also:
AbstractQoreNode::deref()

QoreListNode::derefImpl()


Member Function Documentation

DLLLOCAL int QoreListNode::qsort ( const class ResolvedCallReferenceNode fr,
qore_size_t  left,
qore_size_t  right,
bool  ascending,
class ExceptionSink xsink 
) [protected]

qsort sorts the list in-place (unstable)

Returns:
0 for OK, -1 for exception raised

DLLLOCAL int QoreListNode::mergesort ( const class ResolvedCallReferenceNode fr,
bool  ascending,
class ExceptionSink xsink 
) [protected]

mergesort sorts the list in-place (stable)

Returns:
0 for OK, -1 for exception raised

virtual DLLEXPORT bool QoreListNode::derefImpl ( class ExceptionSink xsink  )  [protected, virtual]

dereferences all elements of the list

The ExceptionSink argument is needed for those types that could throw an exception when they are deleted (ex: QoreObject) - which could be contained in the list

Parameters:
xsink if an error occurs, the Qore-language exception information will be added here
Returns:
true if the object can be deleted, false if not (externally-managed)

Reimplemented from AbstractQoreNode.

virtual DLLEXPORT class AbstractQoreNode* QoreListNode::evalImpl ( class ExceptionSink xsink  )  const [protected, virtual]

evaluates the list and returns a value (or 0)

return value requires a deref(xsink) NOTE: if there is an exception, 0 will be returned

Parameters:
xsink if an error occurs, the Qore-language exception information will be added here

Implements AbstractQoreNode.

virtual DLLLOCAL AbstractQoreNode* QoreListNode::evalImpl ( bool &  needs_deref,
ExceptionSink xsink 
) const [protected, virtual]

optionally evaluates the argument

return value requires a deref(xsink) if needs_deref is true

See also:
AbstractQoreNode::eval()

Implements AbstractQoreNode.

DLLEXPORT int QoreListNode::getAsString ( QoreString str,
int  foff,
class ExceptionSink xsink 
) const [virtual]

concatenate the verbose string representation of the list (including all contained values) to an existing QoreString

used for n and N printf formatting

Parameters:
str the string representation of the type will be concatenated to this QoreString reference
foff for multi-line formatting offset, -1 = no line breaks
xsink if an error occurs, the Qore-language exception information will be added here
Returns:
-1 for exception raised, 0 = OK

Implements AbstractQoreNode.

DLLEXPORT QoreString* QoreListNode::getAsString ( bool &  del,
int  foff,
class ExceptionSink xsink 
) const [virtual]

returns a QoreString giving the verbose string representation of the List (including all contained values)

used for n and N printf formatting

Parameters:
del if this is true when the function returns, then the returned QoreString pointer should be deleted, if false, then it must not be
foff for multi-line formatting offset, -1 = no line breaks
xsink if an error occurs, the Qore-language exception information will be added here NOTE: Use the QoreNodeAsStringHelper class (defined in QoreStringNode.h) instead of using this function directly
See also:
QoreNodeAsStringHelper

Implements AbstractQoreNode.

virtual DLLEXPORT class AbstractQoreNode* QoreListNode::realCopy (  )  const [virtual]

returns true if the list contains parse expressions and therefore needs evaluation to return a value, false if not

performs a deep copy of the list and returns the new list

Implements AbstractQoreNode.

virtual DLLEXPORT bool QoreListNode::is_equal_soft ( const AbstractQoreNode v,
ExceptionSink xsink 
) const [virtual]

tests for equality ("deep compare" including all contained values) with possible type conversion (soft compare)

Parameters:
v the value to compare
xsink if an error occurs, the Qore-language exception information will be added here

Implements AbstractQoreNode.

virtual DLLEXPORT bool QoreListNode::is_equal_hard ( const AbstractQoreNode v,
ExceptionSink xsink 
) const [virtual]

tests for equality ("deep compare" including all contained values) without type conversions (hard compare)

Parameters:
v the value to compare
xsink if an error occurs, the Qore-language exception information will be added here

Implements AbstractQoreNode.

DLLEXPORT AbstractQoreNode* QoreListNode::retrieve_entry ( qore_size_t  index  ) 

returns the element at "index" (first element is index 0)

the value is not referenced for the caller

Parameters:
index the index of the element (first element is index 0)
Returns:
the value of the element at "index", not referenced for the caller

Referenced by get_bigint_param(), get_bool_param(), get_int_param(), get_param(), get_param_type(), test_binary_param(), test_callref_param(), test_date_param(), test_hash_param(), test_list_param(), test_nothing_param(), test_object_param(), test_reference_param(), and test_string_param().

DLLEXPORT const AbstractQoreNode* QoreListNode::retrieve_entry ( qore_size_t  index  )  const

returns the element at "index" (first element is index 0)

the value is not referenced for the caller

Parameters:
index the index of the element (first element is index 0)
Returns:
the value of the element at "index", not referenced for the caller

DLLEXPORT AbstractQoreNode* QoreListNode::get_referenced_entry ( qore_size_t  index  )  const

returns the element at "index" (first element is index 0), the caller owns the reference

Parameters:
index the index of the element (first element is index 0)
Returns:
the value of the element at "index" with an incremented reference count for the caller

DLLEXPORT int QoreListNode::getEntryAsInt ( qore_size_t  index  )  const

returns the value of element at "index" as an integer (first element is index 0)

Parameters:
index the index of the element (first element is index 0)

DLLEXPORT AbstractQoreNode** QoreListNode::get_entry_ptr ( qore_size_t  index  ) 

Parameters:
index the index of the element (first element is index 0)

DLLEXPORT AbstractQoreNode** QoreListNode::getExistingEntryPtr ( qore_size_t  index  ) 

Parameters:
index the index of the element (first element is index 0)

DLLEXPORT void QoreListNode::set_entry ( qore_size_t  index,
AbstractQoreNode val,
class ExceptionSink xsink 
)

sets the value of a list element

if there is a value there already, it is dereferenced (hence "xsink" is needed to catch any exceptions)

Parameters:
index the index of the element (first element is index 0)
val the value to set, must be already referenced for the assignment (or 0)
xsink if an error occurs, the Qore-language exception information will be added here

DLLEXPORT AbstractQoreNode* QoreListNode::pop (  ) 

returns the last element of the list, the length is decremented by one, caller owns the reference

if the list is empty the 0 is returned (NOTE: the last entry could also be 0 as well)

DLLEXPORT AbstractQoreNode* QoreListNode::shift (  ) 

returns the first element of the list, all other entries are moved down to fill up the first position, caller owns the reference

if the list is empty the 0 is returned (NOTE: the first entry could also be 0 as well) with the current implementation the execution time for this function is O(n) where n is the length of the list

DLLEXPORT int QoreListNode::delete_entry ( qore_size_t  index,
class ExceptionSink xsink 
)

Parameters:
index the index of the element (first element is index 0)
xsink if an error occurs, the Qore-language exception information will be added here
Returns:
-1 if the index was invalid, 0 if the index was valid

DLLEXPORT void QoreListNode::pop_entry ( qore_size_t  index,
class ExceptionSink xsink 
)

Parameters:
index the index of the element (first element is index 0)
xsink if an error occurs, the Qore-language exception information will be added here

DLLEXPORT QoreListNode* QoreListNode::evalList ( class ExceptionSink xsink  )  const

evaluates the list and returns a value (or 0)

return value requires a deref(xsink) if the list does not require evaluation then "refSelf()" is used to return the same object with an incremented reference count NOTE: if the object requires evaluation and there is an exception, 0 will be returned

Parameters:
xsink if an error occurs, the Qore-language exception information will be added here

Referenced by QoreListNodeEvalOptionalRefHolder::QoreListNodeEvalOptionalRefHolder().

DLLEXPORT QoreListNode* QoreListNode::evalList ( bool &  needs_deref,
class ExceptionSink xsink 
) const

optionally evaluates the list

return value requires a deref(xsink) if needs_deref is true NOTE: if the list requires evaluation and there is an exception, 0 will be returned NOTE: do not use this function directly, use the QoreListEvalOptionalRefHolder class instead

Parameters:
needs_deref this is an output parameter, if needs_deref is true then the value returned must be dereferenced
xsink if an error occurs, the Qore-language exception information will be added here
See also:
QoreListEvalOptionalRefHolder

DLLEXPORT QoreListNode* QoreListNode::copyListFrom ( qore_size_t  index  )  const

performs a deep copy of the list starting from element "offset" and returns the new list

therefore element 0 of the new list is element "offset" in the source list

Parameters:
index the index of the element (first element is index 0)

DLLEXPORT QoreListNode* QoreListNode::sort (  )  const

returns a new list based on quicksorting the source list ("this")

"soft" comparisons are made using OP_LOG_LT, meaning that the list can be made up of different data types and still be sorted

DLLEXPORT QoreListNode* QoreListNode::sort ( const class ResolvedCallReferenceNode fr,
class ExceptionSink xsink 
) const

returns a new list based on quicksorting the source list ("this") using the passed function reference to determine lexical order

Parameters:
fr the function reference to be executed for each comparison to give lexical order to the elements
xsink if an error occurs, the Qore-language exception information will be added here

DLLEXPORT QoreListNode* QoreListNode::sortStable (  )  const

returns a new list based on executing mergesort on the source list ("this")

"soft" comparisons are made using OP_LOG_LT, meaning that the list can be made up of different data types and still be sorted

DLLEXPORT QoreListNode* QoreListNode::sortStable ( const class ResolvedCallReferenceNode fr,
class ExceptionSink xsink 
) const

returns a new list based on executing mergesort on the source list ("this") using the passed function reference to determine lexical order

Parameters:
fr the function reference to be executed for each comparison to give lexical order to the elements
xsink if an error occurs, the Qore-language exception information will be added here

DLLEXPORT QoreListNode* QoreListNode::sortDescending (  )  const

returns a new list based on quicksorting the source list ("this") in descending order

"soft" comparisons are made using OP_LOG_LT, meaning that the list can be made up of different data types and still be sorted

DLLEXPORT QoreListNode* QoreListNode::sortDescending ( const class ResolvedCallReferenceNode fr,
class ExceptionSink xsink 
) const

returns a new list based on quicksorting the source list ("this") in descending order, using the passed function reference to determine lexical order

Parameters:
fr the function reference to be executed for each comparison to give lexical order to the elements
xsink if an error occurs, the Qore-language exception information will be added here

DLLEXPORT QoreListNode* QoreListNode::sortDescendingStable (  )  const

returns a new list based on executing mergesort on the source list ("this") in descending order

"soft" comparisons are made using OP_LOG_LT, meaning that the list can be made up of different data types and still be sorted

DLLEXPORT QoreListNode* QoreListNode::sortDescendingStable ( const class ResolvedCallReferenceNode fr,
class ExceptionSink xsink 
) const

returns a new list based on executing mergesort on the source list ("this") in descending order, using the passed function reference to determine lexical order

Parameters:
fr the function reference to be executed for each comparison to give lexical order to the elements
xsink if an error occurs, the Qore-language exception information will be added here

DLLEXPORT AbstractQoreNode* QoreListNode::min (  )  const

returns the element having the lowest value (determined by calling OP_LOG_LT - the less-than "<" operator)

so "soft" comparisons are made, meaning that the list can be made up of different types, and, as long as the comparisons are meaningful, the minimum value can be returned

DLLEXPORT AbstractQoreNode* QoreListNode::max (  )  const

returns the element having the highest value (determined by calling OP_LOG_GT - the greater-than ">" operator)

so "soft" comparisons are made, meaning that the list can be made up of different types, and, as long as the comparisons are meaningful, the maximum value can be returned

DLLEXPORT AbstractQoreNode* QoreListNode::min ( const class ResolvedCallReferenceNode fr,
class ExceptionSink xsink 
) const

returns the element having the lowest value (determined by calling the function reference passed to give lexical order)

Parameters:
fr the function reference to be executed for each comparison to give lexical order to the elements
xsink if an error occurs, the Qore-language exception information will be added here

DLLEXPORT AbstractQoreNode* QoreListNode::max ( const class ResolvedCallReferenceNode fr,
class ExceptionSink xsink 
) const

returns the element having the highest value (determined by calling the function reference passed to give lexical order)

Parameters:
fr the function reference to be executed for each comparison to give lexical order to the elements
xsink if an error occurs, the Qore-language exception information will be added here

DLLEXPORT void QoreListNode::splice ( qore_offset_t  offset,
class ExceptionSink xsink 
)

truncates the list at position "offset" (first element is offset 0)

Parameters:
offset the index of the element (first element is offset 0, negative offsets are offsets from the end of the list)
xsink if an error occurs, the Qore-language exception information will be added here

DLLEXPORT void QoreListNode::splice ( qore_offset_t  offset,
qore_offset_t  length,
class ExceptionSink xsink 
)

removes "length" elements at position "offset" (first element is offset 0)

Parameters:
offset the index of the element (first element is offset 0, negative offsets are offsets from the end of the list)
length the number of elements to remove (negative numbers mean all except that many elements from the end)
xsink if an error occurs, the Qore-language exception information will be added here

DLLEXPORT void QoreListNode::splice ( qore_offset_t  offset,
qore_offset_t  length,
const AbstractQoreNode l,
class ExceptionSink xsink 
)

adds a single value or a list of values ("l") to list possition "offset", while removing "length" elements

the "l" AbstractQoreNode (or each element if it is a QoreListNode) will be referenced for the assignment in the QoreListNode

Parameters:
offset the index of the element (first element is offset 0, negative offsets are offsets from the end of the list)
length the number of elements to remove (negative numbers mean all except that many elements from the end)
l the value or list of values to insert
xsink if an error occurs, the Qore-language exception information will be added here

DLLEXPORT qore_size_t QoreListNode::size (  )  const

returns the number of elements in the list

return the number of elements in the list

Referenced by num_params().

DLLEXPORT bool QoreListNode::empty (  )  const

returns true if the list is empty

return true if the list is empty

DLLLOCAL AbstractQoreNode* QoreListNode::eval_entry ( qore_size_t  num,
class ExceptionSink xsink 
) const

this function is not exported in the qore library

Parameters:
num the offset of the entry to evaluate (starting with 0)
xsink if an error occurs, the Qore-language exception information will be added here


Member Data Documentation

struct qore_list_private* QoreListNode::priv [read, protected]

this structure holds the private implementation for the type

therefore changes to the implementation will not affect the C++ ABI


The documentation for this class was generated from the following file:

Generated on Mon Oct 26 09:09:50 2009 for Qore Programming Language by  doxygen 1.5.6