QoreStringNode Class Reference

Qore's string value type, reference counted, dynamically-allocated only. More...

#include <QoreStringNode.h>

Inheritance diagram for QoreStringNode:

SimpleValueQoreNode QoreString SimpleQoreNode AbstractQoreNode QoreReferenceCounter

List of all members.

Public Member Functions

DLLEXPORT QoreStringNode ()
 creates an empty string and assigns the default encoding QCS_DEFAULT
DLLEXPORT QoreStringNode (const char *str, const QoreEncoding *enc=QCS_DEFAULT)
 creates a new object from a string and sets the character encoding
DLLEXPORT QoreStringNode (const QoreString &str)
 creates a new QoreStringNode from an existing QoreString reference
DLLEXPORT QoreStringNode (const QoreStringNode &str)
 creates a new QoreStringNode from an existing QoreStringNode reference
DLLEXPORT QoreStringNode (const std::string &str, const QoreEncoding *enc=QCS_DEFAULT)
 creates a new object from a std::string and sets the character encoding
DLLEXPORT QoreStringNode (char *nbuf, qore_size_t nlen, qore_size_t nallocated, const QoreEncoding *enc)
 creates a new object; takes ownership of the char pointer passed, all parameters are mandatory
DLLEXPORT int getAsString (QoreString &str, int format_offset, ExceptionSink *xsink) const
 concatenates the string data in double quotes to an existing QoreString
DLLEXPORT QoreStringgetAsString (bool &del, int format_offset, ExceptionSink *xsink) const
 returns a QoreString giving the string data in double quotes
virtual DLLEXPORT QoreStringgetStringRepresentation (bool &del) const
 returns the current string and sets del to false
virtual DLLEXPORT void getStringRepresentation (QoreString &str) const
 concatentates the value of the type to an existing QoreString reference
virtual DLLEXPORT DateTimegetDateTimeRepresentation (bool &del) const
 returns the DateTime representation of this string
virtual DLLEXPORT void getDateTimeRepresentation (DateTime &dt) const
 assigns the date representation of this string to the DateTime reference passed
virtual DLLEXPORT
AbstractQoreNode
realCopy () const
 returns a copy of the object, the caller owns the reference count
virtual DLLEXPORT bool is_equal_soft (const AbstractQoreNode *v, ExceptionSink *xsink) const
 tests for equality ("deep compare" including all contained values for container types) with possible type and character encoding conversion (soft compare)
virtual DLLEXPORT bool is_equal_hard (const AbstractQoreNode *v, ExceptionSink *xsink) const
 tests for equality ("deep compare" including all contained values for container types) without type or character encoding conversions (hard compare)
virtual DLLEXPORT const char * getTypeName () const
 returns the type name as a c string
DLLEXPORT QoreStringNodeconvertEncoding (const QoreEncoding *nccs, ExceptionSink *xsink) const
 converts the encoding of the string to the specified encoding, returns 0 if an error occurs, the caller owns the pointer returned
DLLEXPORT QoreStringNodesubstr (qore_offset_t offset, ExceptionSink *xsink) const
 returns a new string consisting of all the characters from the current string starting with character position "offset"
DLLEXPORT QoreStringNodesubstr (qore_offset_t offset, qore_offset_t length, ExceptionSink *xsink) const
 returns a new string consisting of "length" characters from the current string starting with character position "offset"
DLLEXPORT QoreStringNodereverse () const
 return a QoreStringNode with the characters reversed
DLLEXPORT QoreStringNodecopy () const
 returns an exact copy of the string
DLLEXPORT QoreStringNodeparseBase64ToString (ExceptionSink *xsink) const
 parses the string as a base64-encoded binary and returns the decoded value as a QoreStringNode
DLLEXPORT QoreStringNodestringRefSelf () const
 references the object and returns a non-const pointer to "this"
DLLLOCAL QoreStringNode (const char *str, const QoreEncoding *from, const QoreEncoding *to, ExceptionSink *xsink)
 constructor supporting createAndConvertEncoding(), not exported in the library
DLLLOCAL QoreStringNode (struct qore_string_private *p)
 constructor using the private implementation of QoreString; not exported in the library

Static Public Member Functions

static DLLEXPORT QoreStringNodecreateAndConvertEncoding (const char *str, const QoreEncoding *from, const QoreEncoding *to, ExceptionSink *xsink)
 creates a new QoreStringNode from a string and converts its encoding

Protected Member Functions

virtual DLLEXPORT ~QoreStringNode ()
 destructor only called when references = 0, use deref() instead


Detailed Description

Qore's string value type, reference counted, dynamically-allocated only.

for a version that can be used on the stack, use QoreString Each QoreStringNode is tagged with a specific encoding implemented by QoreEncoding. Character encodings can be converted with QoreStringNode::convertEncoding()

See also:
QoreString

QoreEncoding


Constructor & Destructor Documentation

DLLEXPORT QoreStringNode::QoreStringNode ( const char *  str,
const QoreEncoding enc = QCS_DEFAULT 
)

creates a new object from a string and sets the character encoding

Parameters:
str the string data is copied to the new QoreStringNode object
enc the encoding for the string

DLLEXPORT QoreStringNode::QoreStringNode ( const QoreString str  ) 

creates a new QoreStringNode from an existing QoreString reference

Parameters:
str copies the data into the new QoreStringNode

DLLEXPORT QoreStringNode::QoreStringNode ( const QoreStringNode str  ) 

creates a new QoreStringNode from an existing QoreStringNode reference

Parameters:
str copies the data into the new QoreStringNode

DLLEXPORT QoreStringNode::QoreStringNode ( const std::string &  str,
const QoreEncoding enc = QCS_DEFAULT 
)

creates a new object from a std::string and sets the character encoding

Parameters:
str the string data is copied to the new QoreStringNode object
enc the encoding for the string

DLLEXPORT QoreStringNode::QoreStringNode ( char *  nbuf,
qore_size_t  nlen,
qore_size_t  nallocated,
const QoreEncoding enc 
)

creates a new object; takes ownership of the char pointer passed, all parameters are mandatory

Parameters:
nbuf the pointer for the character data
nlen the length of the string in bytes (not including the trailing '\0')
nallocated the number of bytes allocated for this buffer (if unknown, set to nlen + 1)
enc the encoding for the string


Member Function Documentation

DLLEXPORT QoreStringNode* QoreStringNode::convertEncoding ( const QoreEncoding nccs,
ExceptionSink xsink 
) const

converts the encoding of the string to the specified encoding, returns 0 if an error occurs, the caller owns the pointer returned

if the encoding is the same as the current encoding, a copy of the string is returned

Parameters:
nccs the encoding for the new string
xsink if an error occurs, the Qore-language exception information will be added here
Returns:
the new string with the desired encoding or 0 if an error occured

Reimplemented from QoreString.

DLLEXPORT QoreString* QoreStringNode::getAsString ( bool &  del,
int  format_offset,
ExceptionSink xsink 
) const [virtual]

returns a QoreString giving the string data in double quotes

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
format_offset 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.

DLLEXPORT int QoreStringNode::getAsString ( QoreString str,
int  format_offset,
ExceptionSink xsink 
) const [virtual]

concatenates the string data in double quotes to an existing QoreString

used for n and N printf formatting. An exception may be thrown if there is an encoding conversion error

Parameters:
str the string representation of the type will be concatenated to this QoreString reference
format_offset 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.

virtual DLLEXPORT void QoreStringNode::getDateTimeRepresentation ( DateTime dt  )  const [virtual]

assigns the date representation of this string to the DateTime reference passed

Parameters:
dt the DateTime reference to be assigned

Reimplemented from AbstractQoreNode.

virtual DLLEXPORT DateTime* QoreStringNode::getDateTimeRepresentation ( bool &  del  )  const [virtual]

returns the DateTime representation of this string

NOTE: Use the DateTimeValueHelper class instead of using this function directly

Parameters:
del output parameter: if del is true, then the returned DateTime pointer belongs to the caller (and must be deleted manually), if false, then it must not be
See also:
DateTimeValueHelper

Reimplemented from AbstractQoreNode.

virtual DLLEXPORT void QoreStringNode::getStringRepresentation ( QoreString str  )  const [virtual]

concatentates the value of the type to an existing QoreString reference

Parameters:
str a reference to a QoreString where the value of the type will be concatenated

Reimplemented from AbstractQoreNode.

virtual DLLEXPORT QoreString* QoreStringNode::getStringRepresentation ( bool &  del  )  const [virtual]

returns the current string and sets del to false

NOTE: do not call this function directly, use QoreStringValueHelper instead

Parameters:
del output parameter: always sets del to false
See also:
QoreStringValueHelper

Reimplemented from AbstractQoreNode.

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

tests for equality ("deep compare" including all contained values for container types) without type or character encoding conversions (hard compare)

if the character encodings of the two strings differ, the comparison fails immediately this function does not throw any Qore-language exceptions as no character set encoding conversions are made

Parameters:
v the value to compare
xsink is not used in this implementation of the function

Implements AbstractQoreNode.

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

tests for equality ("deep compare" including all contained values for container types) with possible type and character encoding conversion (soft compare)

An exception could be raised if character set encoding is required to do the compare the the conversion fails

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

Implements AbstractQoreNode.

DLLEXPORT QoreStringNode* QoreStringNode::substr ( qore_offset_t  offset,
qore_offset_t  length,
ExceptionSink xsink 
) const

returns a new string consisting of "length" characters from the current string starting with character position "offset"

offset and length spoecify characters, not bytes

Parameters:
offset the offset in characters from the beginning of the string (starting with 0), can be negative
length the number of characters to take for the new substring, can be negative
xsink an invalid multibyte character encoding can cause an exception to be thrown
Returns:
the new string

Reimplemented from QoreString.

DLLEXPORT QoreStringNode* QoreStringNode::substr ( qore_offset_t  offset,
ExceptionSink xsink 
) const

returns a new string consisting of all the characters from the current string starting with character position "offset"

offset is a character offset and not a byte offset

Parameters:
offset the offset in characters from the beginning of the string (starting with 0), can be negative
xsink an invalid multibyte character encoding can cause an exception to be thrown
Returns:
the new string

Reimplemented from QoreString.


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

doxygen