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

#include <QoreStringNode.h>

Inheritance diagram for QoreStringNode:

Collaboration diagram for QoreStringNode:

Public Member Functions
DLLEXPORT	QoreStringNode ()
	creates an empty string and assigns the default encoding QCS_DEFAULT

DLLEXPORT	QoreStringNode (char nbuf, size_t nlen, size_t nallocated, const QoreEncoding enc)
	creates a new object; takes ownership of the char pointer passed, all parameters are mandatory

DLLEXPORT	QoreStringNode (const BinaryNode *bin, size_t maxlinelen)
	creates a new string as the base64-encoded value of the binary object passed and ensures the maximum line length for the base64-encoded output

DLLEXPORT	QoreStringNode (const char str, const QoreEncoding enc=QCS_DEFAULT)
	creates a new object from a string and sets the character encoding

DLLLOCAL	QoreStringNode (const char str, const QoreEncoding from, const QoreEncoding to, ExceptionSink xsink)
	constructor supporting createAndConvertEncoding(), not exported in the library

DLLEXPORT	QoreStringNode (const char str, size_t len, const QoreEncoding new_qorecharset=QCS_DEFAULT)
	copies the c-string passed (up to len) and assigns the encoding passed

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

DLLLOCAL	QoreStringNode (struct qore_string_private *p)
	constructor using the private implementation of QoreString; not exported in the library

DLLEXPORT 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

DLLEXPORT QoreStringNode *	extract (qore_offset_t offset, ExceptionSink *xsink)
	removes characters from the string starting at position "offset" and returns a string of the characters removed

DLLEXPORT QoreStringNode *	extract (qore_offset_t offset, qore_offset_t length, ExceptionSink *xsink)
	removes "length" characters from the string starting at position "offset" and returns a string of the characters removed

DLLEXPORT QoreStringNode *	extract (qore_offset_t offset, qore_offset_t length, QoreValue strn, ExceptionSink *xsink)
	removes "length" characters from the string starting at position "offset" and replaces them with the string passed, then returns a string of the characters removed

DLLEXPORT QoreString *	getAsString (bool &del, int format_offset, ExceptionSink *xsink) const
	returns a QoreString giving the string data in double quotes

DLLEXPORT int	getAsString (QoreString &str, int format_offset, ExceptionSink *xsink) const
	concatenates the string data in double quotes to an existing QoreString

virtual DLLEXPORT DateTime *	getDateTimeRepresentation (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 QoreString *	getStringRepresentation (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 const char *	getTypeName () const
	returns the type name as a c string

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 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)

DLLEXPORT QoreStringNode *	parseBase64ToString (const QoreEncoding enc, ExceptionSink xsink) const
	parses the current string data as base64-encoded data and returns it as a QoreStringNode pointer owned by the caller

DLLEXPORT QoreStringNode *	parseBase64ToString (ExceptionSink *xsink) const
	parses the string as a base64-encoded binary and returns the decoded value as a QoreStringNode

DLLEXPORT QoreStringNode *	parseBase64UrlToString (const QoreEncoding enc, ExceptionSink xsink) const
	parses the current string data as base64-url-encoded data and returns it as a QoreStringNode pointer owned by the caller

DLLEXPORT QoreStringNode *	parseBase64UrlToString (ExceptionSink *xsink) const
	parses the string as a base64-url-encoded binary and returns the decoded value as a QoreStringNode

virtual DLLLOCAL int	parseInit (QoreValue &val, QoreParseContext &parse_context)
	returns the type information

virtual DLLEXPORT AbstractQoreNode *	realCopy () const
	returns a copy of the object, the caller owns the reference count

DLLEXPORT QoreStringNode *	regexSubst (QoreString &match, QoreString &subst, int opts, ExceptionSink *xsink) const
	performs perl5-compatible regular expression substitution

DLLEXPORT QoreStringNode *	reverse () const
	return a QoreStringNode with the characters reversed

DLLEXPORT QoreStringNode *	stringRefSelf () const
	references the object and returns a non-const pointer to "this"

DLLEXPORT 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"

DLLEXPORT 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"

Public Member Functions inherited from SimpleValueQoreNode
DLLLOCAL	SimpleValueQoreNode (qore_type_t t, bool n_there_can_be_only_one=false)
	creates the object by assigning the type code and setting the "value" flag, unsetting the "needs_eval" flag, and setting "there_can_be_only_one"

Public Member Functions inherited from SimpleQoreNode
DLLLOCAL	SimpleQoreNode (const SimpleQoreNode &v)
	copy constructor

DLLLOCAL	SimpleQoreNode (qore_type_t t, bool n_value, bool n_needs_eval, bool n_there_can_be_only_one=false)
	constructor takes the type and value arguments

DLLEXPORT void	deref (ExceptionSink *xsink)
	decrements the reference count and deletes the object when references = 0

SimpleQoreNode &	operator= (const SimpleQoreNode &)=delete
	this function is not implemented

Public Member Functions inherited from AbstractQoreNode
DLLEXPORT	AbstractQoreNode (const AbstractQoreNode &v)
	copy constructor

DLLEXPORT	AbstractQoreNode (qore_type_t t, bool n_value, bool n_needs_eval, bool n_there_can_be_only_one=false, bool n_custom_reference_handlers=false)
	constructor takes the type

virtual DLLEXPORT void	customDeref (ExceptionSink *xsink)

virtual DLLEXPORT void	customRef () const
	special processing when the object's reference count transitions from 0-1

DLLEXPORT void	deref (ExceptionSink *xsink)
	decrements the reference count and calls derefImpl() if there_can_be_only_one is false, otherwise does nothing

virtual DLLEXPORT bool	derefImpl (ExceptionSink *xsink)
	decrements the reference count

DLLEXPORT QoreValue	eval (bool &needs_deref, ExceptionSink *xsink) const
	optionally evaluates the argument

DLLEXPORT QoreValue	eval (ExceptionSink *xsink) const
	evaluates the object and returns a value (or 0)

DLLEXPORT int64	getAsBigInt () const
	returns the 64-bit integer value of the object

DLLEXPORT bool	getAsBool () const
	returns the boolean value of the object

DLLEXPORT double	getAsFloat () const
	returns the float value of the object

DLLEXPORT int	getAsInt () const
	returns the integer value of the object

DLLLOCAL qore_type_t	getType () const
	returns the data type

DLLLOCAL bool	is_value () const
	returns true if the node represents a value

DLLLOCAL bool	isReferenceCounted () const
	returns true if the object is reference-counted

DLLLOCAL bool	needs_eval () const
	returns true if the object needs evaluation to return a value, false if not

DLLLOCAL AbstractQoreNode &	operator= (const AbstractQoreNode &)
	this function is not implemented; it is here as a private function in order to prohibit it from being used

DLLEXPORT void	ref () const
	increments the reference count

DLLEXPORT AbstractQoreNode *	refSelf () const
	returns "this" with an incremented reference count

Public Member Functions inherited from QoreReferenceCounter
DLLEXPORT	QoreReferenceCounter ()
	Creates the reference counter object.

DLLEXPORT	QoreReferenceCounter (const QoreReferenceCounter &old)
	Creates a new object with a reference count of 1.

DLLEXPORT	~QoreReferenceCounter ()
	destroys the reference counter object

DLLEXPORT bool	is_unique () const
	Returns true if the reference count is 1.

DLLEXPORT bool	optRef ()
	Make a strong reference only if the object is valid.

DLLEXPORT int	reference_count () const
	Gets the reference count.

DLLEXPORT bool	ROdereference () const
	Atomically decrements the reference count.

DLLEXPORT void	ROreference () const
	Atomically increments the reference count.

Public Member Functions inherited from QoreString
DLLEXPORT	QoreString ()
	creates an empty string and assigns the default encoding QCS_DEFAULT

DLLEXPORT	QoreString (bool b)
	creates a single-character string (either '0' or '1') and assigns the default encoding QCS_DEFAULT

DLLEXPORT	QoreString (char nbuf, size_t nlen, size_t nallocated, const QoreEncoding enc)
	takes ownership of the char* passed

DLLEXPORT	QoreString (char c)
	creates a single-character string from the argument and assigns the default encoding QCS_DEFAULT

DLLEXPORT	QoreString (const BinaryNode *bin)
	creates a new string as the base64-encoded value of the binary object passed

DLLEXPORT	QoreString (const BinaryNode *bin, size_t maxlinelen)
	creates a new string as the base64-encoded value of the binary object passed and ensures the maximum line length for the base64-encoded output

DLLEXPORT	QoreString (const char *str)
	copies the c-string passed and assigns the default encoding QCS_DEFAULT

DLLEXPORT	QoreString (const char str, const QoreEncoding new_qorecharset)
	copies the c-string passed and assigns the encoding passed

DLLEXPORT	QoreString (const char str, size_t len, const QoreEncoding new_qorecharset=QCS_DEFAULT)
	copies the c-string passed and assigns the length and encoding passed

DLLEXPORT	QoreString (const DateTime *date)
	creates a new string from the DateTime value passed in the format YYYYMMDDHHmmSS

DLLEXPORT	QoreString (const QoreEncoding *new_qorecharset)
	creates an empty string and assigns the encoding passed

DLLEXPORT	QoreString (const QoreString &str)
	creates a copy of the QoreString argument passed

DLLEXPORT	QoreString (const QoreString *str)
	creates a copy of the QoreString argument passed

DLLEXPORT	QoreString (const QoreString *str, size_t len)
	creates a copy of the QoreString argument passed up to byte "len" and assigns "len" as the byte length of the new string

DLLEXPORT	QoreString (const std::string &str, const QoreEncoding *new_encoding=QCS_DEFAULT)
	copies the std::string passed and assigns the encoding passed

DLLEXPORT	QoreString (double f)
	creates a new string with the string representation of the floating-point value passed and assigns the default encoding QCS_DEFAULT

DLLEXPORT	QoreString (int64 i)
	creates a new string with the string representation of the integer passed and assigns the default encoding QCS_DEFAULT

DLLEXPORT	~QoreString ()
	frees any memory allocated by the string

DLLEXPORT void	addch (char c, unsigned times)
	append a character to the string a number of times

DLLEXPORT void	allocate (unsigned requested_size)
	Ensure the internal buffer has at least expected size in bytes.

DLLEXPORT qore_offset_t	bindex (const char *needle, qore_offset_t pos=0) const
	returns the byte position of a substring within the string or -1 if not found

DLLEXPORT qore_offset_t	bindex (const QoreString &needle, qore_offset_t pos=0) const
	returns the byte position of a substring within the string or -1 if not found

DLLEXPORT qore_offset_t	bindex (const std::string &needle, qore_offset_t pos=0) const
	returns the byte position of a substring within the string or -1 if not found

DLLEXPORT qore_offset_t	brindex (const char *needle, qore_offset_t pos=-1) const
	returns the byte position of a substring within the string searching in reverse from a given position or -1 if not found

DLLEXPORT qore_offset_t	brindex (const QoreString &needle, qore_offset_t pos=-1) const
	returns the byte position of a substring within the string searching in reverse from a given position or -1 if not found

DLLEXPORT qore_offset_t	brindex (const std::string &needle, qore_offset_t pos=-1) const
	returns the byte position of a substring within the string searching in reverse from a given position or -1 if not found

DLLEXPORT const char *	c_str () const
	returns the string's buffer; this data should not be changed

DLLEXPORT size_t	capacity () const
	returns number of bytes allocated for the string's buffer, capacity is always >= size

DLLEXPORT size_t	chomp ()
	removes a single \n\r or \n from the end of the string and returns the number of characters removed

DLLEXPORT void	clear ()
	reset string to zero length; memory is not deallocated; string encoding does not change

DLLEXPORT int	compare (const char *str) const
	compares the string with a c-string, which is assumed to be in the same encoding as the string

DLLEXPORT int	compare (const QoreString *str) const
	compares two strings without converting encodings (if the encodings do not match then "this" is deemed automatically less than the argument)

DLLEXPORT int	compareSoft (const QoreString str, ExceptionSink xsink) const
	compares the string with another string, performing character set encoding conversion if necessary

DLLEXPORT void	concat (const char *str)
	concatenates a c-string to the existing string

DLLEXPORT void	concat (const char *str, size_t size)
	concatenates a c-string to the existing string, up to byte "size"

DLLEXPORT void	concat (const char c)
	concatenates a single character to the string

DLLEXPORT void	concat (const DateTime *d)
	concatenates a DateTime value to a string in the format YYYYMMDDHHmmSS

DLLEXPORT int	concat (const QoreString &str, qore_offset_t pos, ExceptionSink *xsink)
	concatenates a string and converts encodings if necessary

DLLEXPORT int	concat (const QoreString &str, qore_offset_t pos, qore_offset_t len, ExceptionSink *xsink)
	concatenates a string and converts encodings if necessary

DLLEXPORT void	concat (const QoreString str, ExceptionSink xsink)
	concatenates a string and converts encodings if necessary

DLLEXPORT void	concat (const QoreString str, size_t size, ExceptionSink xsink)
	concatenates a QoreString up to character "len"

DLLEXPORT void	concat (const std::string &str)
	concatenates an stl string to the existing string

DLLEXPORT void	concatAndHTMLDecode (const char *str)
	concatenates HTML-decoded version of the c-string passed

DLLEXPORT void	concatAndHTMLDecode (const char *str, size_t slen)
	concatenates HTML-decoded version of the c-string passed with the given length

DLLEXPORT void	concatAndHTMLDecode (const QoreString *str)
	concatenates HTML-decoded version of the c-string passed

DLLEXPORT void	concatAndHTMLEncode (const char *str)
	concatenates HTML-encoded version of the c-string passed

DLLEXPORT void	concatAndHTMLEncode (const QoreString str, ExceptionSink xsink)
	concatenation with HTML special character encoding

DLLEXPORT void	concatBase64 (const BinaryNode *bin)
	concatenates the base64-encoded version of the binary data passed

DLLEXPORT void	concatBase64 (const BinaryNode *bin, size_t maxlinelen)
	concatenates the base64-encoded version of the binary data passed

DLLEXPORT void	concatBase64 (const char *buf, size_t size)
	concatenates the base64-encoded version of the binary data passed

DLLEXPORT void	concatBase64 (const char *buf, size_t size, size_t maxlinelen)
	concatenates the base64-encoded version of the binary data passed

DLLEXPORT void	concatBase64 (const QoreString *str)
	concatenates the base64-encoded version of the binary data passed

DLLEXPORT void	concatBase64 (const QoreString *str, size_t maxlinelen)
	concatenates the base64-encoded version of the binary data passed

DLLEXPORT void	concatBase64Url (const BinaryNode &bin)
	concatenates the base64-url-encoded version of the binary data passed

DLLEXPORT void	concatBase64Url (const QoreString &str)
	concatenates the base64-url-encoded version of the binary data passed

DLLEXPORT int	concatDecode (ExceptionSink *xsink, const QoreString &str, unsigned code=CD_ALL)
	concatenates a string and decodes HTML, XML, and numeric character references as per the supplied arguments

DLLEXPORT int	concatDecodeUriRequest (const QoreString &url, ExceptionSink *xsink)
	concatenates a URI-decoded version of the c-string passed

DLLEXPORT void	concatDecodeUrl (const char *url)
	concatenates a URL-decoded version of the c-string passed

DLLEXPORT int	concatDecodeUrl (const QoreString &url, ExceptionSink *xsink)
	concatenates a URL-decoded version of the c-string passed (RFC 3986 compliant: http://tools.ietf.org/html/rfc3986)

DLLEXPORT int	concatEncode (ExceptionSink *xsink, const QoreString &str, unsigned code=CE_XHTML)
	concatenates a string and encodes it according to the encoding argument passed

DLLEXPORT int	concatEncodeUriRequest (ExceptionSink *xsink, const QoreString &url)
	concatenates a URI-encoded version of the c-string passed

DLLEXPORT int	concatEncodeUrl (ExceptionSink *xsink, const QoreString &url, bool encode_all=false)
	concatenates a URL-encoded version of the c-string passed

DLLEXPORT void	concatEscape (const char *str, char c, char esc_char='\\')
	concatenates a string and escapes character c with esc_char

DLLEXPORT void	concatEscape (const QoreString str, char c, char esc_char, ExceptionSink xsink)
	concatenates a string and escapes character c with esc_char (converts encodings if necessary)

DLLEXPORT void	concatHex (const BinaryNode *bin)
	concatenates hexidecimal digits corresponding to the binary data passed

DLLEXPORT void	concatHex (const char *buf, size_t size)
	concatenates hexidecimal digits corresponding to the binary data passed up to byte "len"

DLLEXPORT void	concatHex (const QoreString *str)
	concatenates hexidecimal digits corresponding to the QoreString data passed interpreted as binary data

DLLEXPORT void	concatISO8601DateTime (const DateTime *d)
	concatenates a DateTime value to a string in the format YYYYMMDDTHH:mm:SS <- where the "T" is a literal "T"

DLLEXPORT int	concatUnicode (unsigned code)
	append a character sequence from a unicode code point (returns 0 for OK, -1 for error)

DLLEXPORT int	concatUnicode (unsigned code, ExceptionSink *xsink)
	append a character sequence from a unicode code point (returns 0 for OK, -1 for exception)

DLLEXPORT void	concatUTF8FromUnicode (unsigned code)
	append a UTF-8 character sequence from a unicode code point, assumes the string is tagged with QCS_UTF8 encoding

DLLEXPORT QoreString *	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

DLLEXPORT QoreString *	copy () const
	returns an exact copy of the string

DLLEXPORT bool	empty () const
	returns true if the string is empty, false if not

DLLEXPORT bool	endsWith (const char *str) const
	returns true if the current string ends with the argument string (bytes)

DLLEXPORT bool	endsWith (const std::string &str) const
	returns true if the current string ends with the argument string (bytes)

DLLEXPORT bool	equal (const char *str) const
	returns true if the strings are equal, false if not (encodings are assumed to be equal)

DLLEXPORT bool	equal (const QoreString &str) const
	returns true if the strings are equal, false if not, if the character encodings are different, then the strings are not equal

DLLEXPORT bool	equalPartial (const char *str) const
	returns true if the beginning of the current string matches the argument string, false if not (encodings are assumed to be equal)

DLLEXPORT bool	equalPartial (const QoreString &str) const
	returns true if the beginning of the current string matches the argument string, false if not, if the character encodings are different, then the strings are not equal

DLLEXPORT bool	equalPartialPath (const QoreString &str, ExceptionSink *xsink) const
	returns true if the begining of the current string matches the argument string where either both strings are the same size or the current string has a '/' or '?' character after the point where the argument string stops, false if not, if the character encodings are different, then the encoding of the argument string is temporarily converted to the encoding of the current string to do the comparison

DLLEXPORT bool	equalPartialSoft (const QoreString &str, ExceptionSink *xsink) const
	returns true if the beginning of the current string matches the argument string, false if not, if the character encodings are different, then the encoding of the argument string is temporarily converted to the encoding of the current string to do the comparison

DLLEXPORT bool	equalSoft (const QoreString &str, ExceptionSink *xsink) const
	returns true if the strings are equal, false if not, if the character encodings are different, then the encoding of the argument string is temporarily converted to the encoding of the current string to do the comparison

DLLEXPORT QoreString *	extract (qore_offset_t offset, ExceptionSink *xsink)
	removes characters from the string starting at position "offset" and returns a string of the characters removed

DLLEXPORT QoreString *	extract (qore_offset_t offset, qore_offset_t length, ExceptionSink *xsink)
	removes "length" characters from the string starting at position "offset" and returns a string of the characters removed

DLLEXPORT QoreString *	extract (qore_offset_t offset, qore_offset_t length, QoreValue strn, ExceptionSink *xsink)
	removes "length" characters from the string starting at position "offset" and replaces them with the string passed, then returns a string of the characters removed

DLLEXPORT qore_offset_t	find (char c, qore_offset_t pos=0) const
	returns the byte position of a character (byte) within the string or -1 if not found

DLLEXPORT qore_offset_t	find (const char *str, qore_offset_t pos=0) const
	returns the byte position of a string byte sequence) within the string or -1 if not found

DLLEXPORT qore_offset_t	find (const std::string &str, qore_offset_t pos=0) const
	returns the byte position of a string byte sequence) within the string or -1 if not found

DLLEXPORT qore_offset_t	findAny (const char *str, qore_offset_t pos=0) const
	returns the byte position of any of the given characters (bytes) within the string or -1 if not found

DLLEXPORT const char *	getBuffer () const
	returns the string's buffer; this data should not be changed

DLLEXPORT qore_offset_t	getByteOffset (size_t i, ExceptionSink *xsink) const
	returns the byte position of the given character position in the string or -1 if the string does not have that many characters (or if an invalid encoding exception is raised); may be different than the byte number for multi-byte character encodings such as UTF-8

DLLEXPORT size_t	getCharWidth (ExceptionSink *xsink) const
	returns the character width of the string

DLLEXPORT const QoreEncoding *	getEncoding () const
	returns the encoding for the string

DLLEXPORT unsigned int	getUnicodePoint (qore_offset_t offset, ExceptionSink *xsink) const
	return Unicode code point for the single character at the given character (not byte) offset in the string

DLLEXPORT unsigned int	getUnicodePointFromBytePos (size_t offset, unsigned &len, ExceptionSink *xsink) const
	return Unicode code point for the given byte offset

DLLEXPORT unsigned int	getUnicodePointFromUTF8 (qore_offset_t offset=0) const
	return Unicode code point for character offset, string must be UTF-8

DLLEXPORT char *	giveBuffer ()
	returns the character buffer and leaves the QoreString empty, the caller owns the memory returned (must be manually freed)

DLLEXPORT qore_offset_t	index (const QoreString &needle, qore_offset_t pos, ExceptionSink *xsink) const
	returns the character position of a substring within the string or -1 if not found

DLLEXPORT int	insert (const char *str, size_t pos)
	inserts a character string at a certain position in the string

DLLEXPORT int	insertch (char c, size_t pos, unsigned times)
	insert a character at a certain position in the string a number of times

DLLEXPORT bool	isDataAscii () const
	returns true if the string is empty or has no characters with the high bit set (ie all characters < 128)

DLLEXPORT bool	isDataPrintableAscii () const
	returns true if the string is empty or only contains printable non-control ASCII characters (ie all characters > 31 && < 127)

DLLEXPORT size_t	length () const
	returns the number of characters (not bytes) in the string

DLLLOCAL bool	operator!= (const char *other) const
	returns true if the other string is not equal to this string (encodings also must be equal)

DLLLOCAL bool	operator!= (const QoreString &other) const
	returns true if the other string is not equal to this string (encodings also must be equal)

DLLLOCAL bool	operator!= (const std::string &other) const
	returns true if the other string is not equal to this string (encodings also must be equal)

DLLEXPORT QoreString &	operator+= (const char *str)
	concatenates the characters to the string; assumes the string to be concatenated is already in the character encoding of the "this" string

DLLEXPORT QoreString &	operator+= (const std::string &str)
	concatenates the characters to the string; assumes the string to be concatenated is already in the character encoding of the "this" string

DLLEXPORT QoreString &	operator= (const char *other)
	assigns the value of one string to another; note that in this case the string is assigned the default encoding (QCS_DEFAULT)

DLLEXPORT QoreString &	operator= (const QoreString &other)
	assigns the value of one string to another

DLLEXPORT QoreString &	operator= (const std::string &other)
	assigns the value of one string to another; note that in this case the string is assigned the default encoding (QCS_DEFAULT)

DLLEXPORT bool	operator== (const char *other) const
	returns true if the other string is equal to this string (encodings also must be equal)

DLLEXPORT bool	operator== (const QoreString &other) const
	returns true if the other string is equal to this string (encodings also must be equal)

DLLEXPORT bool	operator== (const std::string &other) const
	returns true if the other string is equal to this string (encodings also must be equal)

DLLEXPORT int	operator[] (qore_offset_t pos) const
	returns the byte (not character) at the given location; if the location is invalid, returns -1

DLLEXPORT BinaryNode *	parseBase64 (ExceptionSink *xsink) const
	parses the current string data as base64-encoded data and returns it as a BinaryNode pointer (caller owns the reference count), throws a qore-language exception if any errors are encountered

DLLEXPORT QoreString *	parseBase64ToString (const QoreEncoding enc, ExceptionSink xsink) const
	parses the current string data as base64-encoded data and returns it as a QoreString pointer owned by the caller

DLLEXPORT QoreString *	parseBase64ToString (ExceptionSink *xsink) const
	parses the current string data as base64-encoded data and returns it as a QoreString pointer owned by the caller

DLLEXPORT BinaryNode *	parseBase64Url (ExceptionSink *xsink) const
	Parses the current string data as base64-URL-encoded data and returns a BinaryNode pointer.

DLLEXPORT QoreString *	parseBase64UrlToString (const QoreEncoding enc, ExceptionSink xsink) const
	Parses the current string data as base64-URL-encoded data and returns a QoreString pointer owned by the caller.

DLLEXPORT QoreString *	parseBase64UrlToString (ExceptionSink *xsink) const
	Parses the current string data as base64-URL-encoded data and returns a QoreString pointer owned by the caller.

DLLEXPORT BinaryNode *	parseHex (ExceptionSink *xsink) const
	parses the current string data as hexadecimal-encoded data and returns it as a BinaryNode pointer (caller owns the reference count), throws a qore-language exception if any errors are encountered

DLLEXPORT void	prepend (const char *str)
	prepends the string given to the string, assumes character encoding is the same as the string's

DLLEXPORT void	prepend (const char *str, size_t size)
	prepends the string given to the string, assumes character encoding is the same as the string's

DLLEXPORT QoreString *	regexSubst (QoreString &match, QoreString &subst, int opts, ExceptionSink *xsink) const
	performs perl5-compatible regular expression substitution

DLLEXPORT int	regexSubst (QoreString &output, QoreString &match, QoreString &subst, int opts, ExceptionSink *xsink) const
	performs perl5-compatible regular expression substitution

DLLEXPORT int	regexSubstInPlace (QoreString &match, QoreString &subst, int opts, ExceptionSink *xsink) const
	performs perl5-compatible regular expression substitution to the current string

DLLEXPORT size_t	removeBytes (size_t len)

DLLEXPORT void	replace (size_t offset, size_t len, const char *str)
	replaces bytes with the string passed

DLLEXPORT void	replace (size_t offset, size_t len, const QoreString str, ExceptionSink xsink)
	replaces bytes with the string passed

DLLEXPORT void	replaceAll (const char old_str, const char new_str)
	replaces all occurences of the first string with the second string

DLLEXPORT void	replaceChar (size_t offset, char c)
	replaces a byte with the byte passed

DLLEXPORT void	reserve (size_t size)
	ensures that at least the given size is available in the string; the string's contents are not affected

DLLEXPORT void	reset ()
	reset string to zero length; memory is deallocated; string encoding is reset to QCS_DEFAULT

DLLEXPORT QoreString *	reverse () const
	return a Qorestring with the characters reversed

DLLEXPORT qore_offset_t	rfind (char c, qore_offset_t pos=-1) const
	returns the last byte position of a character (byte) within the string or -1 if not found

DLLEXPORT qore_offset_t	rfind (const char *str, qore_offset_t pos=-1) const
	returns the last byte position of a string (byte sequence) within the string or -1 if not found

DLLEXPORT qore_offset_t	rfind (const std::string &str, qore_offset_t pos=-1) const
	returns the last byte position of a string (byte sequence) within the string or -1 if not found

DLLEXPORT qore_offset_t	rfindAny (const char *str, qore_offset_t pos=-1) const
	returns the last byte position of any of the given characters (bytes) within the string or -1 if not found

DLLEXPORT qore_offset_t	rindex (const QoreString &needle, qore_offset_t pos, ExceptionSink *xsink) const
	returns the character position of a substring searching in reverse from a given position or -1 if not found

DLLEXPORT void	set (char nbuf, size_t nlen, size_t nallocated, const QoreEncoding enc)
	takes ownership of the char* passed; discards current state

DLLEXPORT void	set (const char str, const QoreEncoding new_qorecharset=QCS_DEFAULT)
	copies the c-string passed and sets the value of the string and its encoding

DLLEXPORT void	set (const char *str, size_t len)
	copies the c-string passed and sets the value of the string up to the byte position given

DLLEXPORT void	set (const QoreString &str)
	sets the value to the copy of the QoreString passed

DLLEXPORT void	set (const QoreString *str)
	sets the value to the copy of the QoreString passed

DLLEXPORT void	set (const std::string &str, const QoreEncoding *new_qorecharset=QCS_DEFAULT)
	copies the string passed and sets the value of the string and its encoding

DLLEXPORT void	setEncoding (const QoreEncoding *new_encoding)
	changes the tagged encoding to the given encoding; does not affect the actual string buffer, only changes the tagged encoding value

DLLEXPORT size_t	size () const
	returns number of bytes in the string (not including the null pointer)

DLLEXPORT void	splice (qore_offset_t offset, ExceptionSink *xsink)
	removes characters from the string starting at position "offset"

DLLEXPORT void	splice (qore_offset_t offset, qore_offset_t length, const QoreString &str, ExceptionSink *xsink)
	removes "length" characters from the string starting at position "offset" and replaces them with the string passed

DLLEXPORT void	splice (qore_offset_t offset, qore_offset_t length, ExceptionSink *xsink)
	removes "length" characters from the string starting at position "offset"

DLLEXPORT void	splice (qore_offset_t offset, qore_offset_t length, QoreValue strn, ExceptionSink *xsink)
	removes "length" characters from the string starting at position "offset" and replaces them with the string passed

DLLEXPORT QoreListNode *	split (const char *sep, bool with_separator=false)
	Splits a string into a list of components based on a separator string.

DLLEXPORT QoreListNode *	split (ExceptionSink xsink, const char sep, const char *quote, bool trim_unquoted=false)
	Splits a string into a list of components based on a separator string.

DLLEXPORT int	sprintf (const char *fmt,...)
	this will concatentate a formatted string to the existing string according to the format string and the arguments

DLLEXPORT bool	startsWith (const char *str) const
	returns true if the current string starts with the argument string (bytes)

DLLEXPORT bool	startsWith (const std::string &str) const
	returns true if the current string starts with the argument string (bytes)

DLLEXPORT size_t	strlen () const
	returns number of bytes in the string (not including the null pointer)

DLLEXPORT QoreString *	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"

DLLEXPORT QoreString *	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"

DLLEXPORT void	take (char *str)
	takes ownership of the character pointer passed and assigns it to the string (frees memory previously allocated)

DLLEXPORT void	take (char str, const QoreEncoding enc)
	takes ownership of the character pointer passed and assigns it to the string (frees memory previously allocated), sets the encoding to the encoding passed

DLLEXPORT void	take (char *str, size_t size)
	takes ownership of the character pointer passed and assigns it to the string (frees memory previously allocated) and sets the string byte lentgh to "size"

DLLEXPORT void	take (char str, size_t size, const QoreEncoding enc)
	takes ownership of the character pointer passed and assigns it to the string (frees memory previously allocated), sets the string byte lentgh to "size", and sets the encoding to the encoding passed

DLLEXPORT void	takeAndTerminate (char *str, size_t size)
	takes ownership of the character pointer passed and assigns it to the string (frees memory previously allocated), sets the string byte length to "size", and sets the amount of member allocated to size + 1

DLLEXPORT void	takeAndTerminate (char str, size_t size, const QoreEncoding enc)
	takes ownership of the character pointer passed and assigns it to the string (frees memory previously allocated), sets the string byte length to "size", and sets the amount of member allocated to size + 1, and sets the new encoding

DLLEXPORT void	terminate (size_t size)
	terminates the string at byte position "size", the string is reallocated if necessary

DLLEXPORT int64	toBigInt () const
	returns the value of the string as an int64

DLLEXPORT void	tolwr ()
	converts the string to lower-case in place

DLLEXPORT void	toupr ()
	converts the string to upper-case in place

DLLEXPORT void	trim (char c)
	remove leading and trailing characters if present

DLLEXPORT void	trim (const char *chars=0)
	remove leading and trailing whitespace or other characters

DLLEXPORT int	trim (ExceptionSink xsink, const QoreString chars=nullptr)
	removes leading and trailing whitespace or other characters

DLLEXPORT void	trim_leading (char c)
	remove leading characters if present

DLLEXPORT void	trim_leading (const char *chars=0)
	remove leading whitespace or other characters

DLLEXPORT void	trim_single_leading (char c)
	remove a single leading character if present

DLLEXPORT void	trim_single_trailing (char c)
	remove a single trailing character if present

DLLEXPORT void	trim_trailing (char c)
	remove trailing characters if present

DLLEXPORT void	trim_trailing (const char *chars=0)
	remove trailing whitespace or other characters

DLLEXPORT int	trimLeading (ExceptionSink xsink, const QoreString chars=nullptr)
	removes leading whitespace or other characters

DLLEXPORT int	trimTrailing (ExceptionSink xsink, const QoreString chars=nullptr)
	removes trailing whitespace or other characters

DLLEXPORT int	vsprintf (const char *fmt, va_list args)
	this will concatentate a formatted string to the existing string according to the format string and the arguments

Static Public Member Functions
static DLLEXPORT QoreStringNode *	createAndConvertEncoding (const char str, const QoreEncoding from, const QoreEncoding to, ExceptionSink xsink)
	creates a new QoreStringNode from a string and converts its encoding

static DLLLOCAL qore_type_t	getStaticTypeCode ()
	returns the type code (useful in templates)

static DLLLOCAL const char *	getStaticTypeName ()
	returns the type name (useful in templates)

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

Protected Member Functions inherited from SimpleValueQoreNode
virtual DLLEXPORT QoreValue	evalImpl (bool &needs_deref, ExceptionSink *xsink) const
	should never be called for value types

Protected Member Functions inherited from AbstractQoreNode
virtual DLLEXPORT	~AbstractQoreNode ()
	default destructor does nothing

Additional Inherited Members
Protected Attributes inherited from AbstractQoreNode
bool	custom_reference_handlers: 1
	set to one for objects that need custom reference handlers

bool	needs_eval_flag: 1
	if this is true then the type can be evaluated

bool	there_can_be_only_one: 1
	if this is set to true, then reference counting is turned off for objects of this class

qore_type_t	type: 11
	the type of the object

bool	value: 1
	this is true for values, if false then either the type needs evaluation to produce a value or is a parse expression

Protected Attributes inherited from QoreString
struct qore_string_private *	priv = nullptr
	the private implementation of QoreString

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

◆ QoreStringNode() [1/5]

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

References QCS_DEFAULT.

◆ QoreStringNode() [2/5]

DLLEXPORT QoreStringNode::QoreStringNode ( const QoreString & str )

creates a new QoreStringNode from an existing QoreString reference

Parameters

str	copies the data into the new QoreStringNode

References QoreString::QoreString().

◆ QoreStringNode() [3/5]

DLLEXPORT QoreStringNode::QoreStringNode ( const QoreStringNode & str )

creates a new QoreStringNode from an existing QoreStringNode reference

Parameters

str	copies the data into the new QoreStringNode

◆ QoreStringNode() [4/5]

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

References QCS_DEFAULT.

◆ QoreStringNode() [5/5]

DLLEXPORT QoreStringNode::QoreStringNode	(	char *	nbuf,
		size_t	nlen,
		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

◆ convertEncoding()

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

◆ extract() [1/3]

DLLEXPORT QoreStringNode * QoreStringNode::extract	(	qore_offset_t	offset,
		ExceptionSink *	xsink )

removes characters from the string starting at position "offset" and returns a string of the characters removed

values are for characters, not bytes. If no characters a removed, an empty string is returned

Parameters

offset	character position to start (rest of the string is removed) (offset starts with 0, negative offset means that many positions from the end of the string)
xsink	is ignored

Returns: a string of the characters removed; if no characters a removed, an empty string is returned

◆ extract() [2/3]

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

removes "length" characters from the string starting at position "offset" and returns a string of the characters removed

values are for characters, not bytes. If no characters a removed, an empty string is returned

Parameters

offset	character position to start (rest of the string is removed) (offset starts with 0, negative offset means that many positions from the end of the string)
length	the number of characters (not bytes) to remove (negative length means all but that many characters from the end of the string)
xsink	invalid multi-byte encodings can cause an exception to be thrown

Returns: a string of the characters removed; if no characters a removed, an empty string is returned, however if an exception is raised converting encodings, then 0 is returned

References QoreString::length().

◆ extract() [3/3]

DLLEXPORT QoreStringNode * QoreStringNode::extract	(	qore_offset_t	offset,
		qore_offset_t	length,
		QoreValue	strn,
		ExceptionSink *	xsink )

removes "length" characters from the string starting at position "offset" and replaces them with the string passed, then returns a string of the characters removed

values are for characters, not bytes. If no characters a removed, an empty string is returned

Parameters

offset	character position to start (rest of the string is removed) (offset starts with 0, negative offset means that many positions from the end of the string)
length	the number of characters (not bytes) to remove (negative length means all but that many characters from the end of the string)
strn	the string to insert at character position "offset" after "length" characters are removed
xsink	invalid multi-byte encodings can cause an exception to be thrown

Returns: a string of the characters removed; if no characters a removed, an empty string is returned, however if an exception is raised converting encodings, then 0 is returned

References QoreString::length().

◆ getAsString() [1/2]

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.

References QoreString::QoreString().

◆ getAsString() [2/2]

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.

References QoreString::QoreString().

◆ getDateTimeRepresentation() [1/2]

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.

◆ getDateTimeRepresentation() [2/2]

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.

◆ getStringRepresentation() [1/2]

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.

References QoreString::QoreString().

◆ getStringRepresentation() [2/2]

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.

References QoreString::QoreString().

◆ is_equal_hard()

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.

References AbstractQoreNode::AbstractQoreNode().

◆ is_equal_soft()

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.

References AbstractQoreNode::AbstractQoreNode().

◆ parseBase64ToString()

DLLEXPORT QoreStringNode * QoreStringNode::parseBase64ToString	(	const QoreEncoding *	enc,
		ExceptionSink *	xsink ) const

parses the current string data as base64-encoded data and returns it as a QoreStringNode pointer owned by the caller

Parameters

enc	the encoding to tag the decoded string with
xsink	if an error occurs, the Qore-language exception information will be added here

Returns: a QoreStringNode of the decoded data (0 if an exception occurs), the QoreStringNode pointer is owned by the caller

◆ parseBase64UrlToString()

DLLEXPORT QoreStringNode * QoreStringNode::parseBase64UrlToString	(	const QoreEncoding *	enc,
		ExceptionSink *	xsink ) const

parses the current string data as base64-url-encoded data and returns it as a QoreStringNode pointer owned by the caller

Parameters

enc	the encoding to tag the decoded string with
xsink	if an error occurs, the Qore-language exception information will be added here

Returns: a QoreStringNode of the decoded data (0 if an exception occurs), the QoreStringNode pointer is owned by the caller

◆ regexSubst()

DLLEXPORT QoreStringNode * QoreStringNode::regexSubst	(	QoreString &	match,
		QoreString &	subst,
		int	opts,
		ExceptionSink *	xsink ) const

performs perl5-compatible regular expression substitution

Parameters

match	the pattern to match
subst	the substitution string
opts	regex options
xsink	invalid multi-byte encodings can cause an exception to be thrown

Returns: the new string if the operation was successful

Since: Qore 1.1.0

References QoreString::QoreString().

◆ substr() [1/2]

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

◆ substr() [2/2]

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

References QoreString::length().

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

include/qore/QoreStringNode.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QoreStringNode() [1/5]

◆ QoreStringNode() [2/5]

◆ QoreStringNode() [3/5]

◆ QoreStringNode() [4/5]

◆ QoreStringNode() [5/5]

Member Function Documentation

◆ convertEncoding()

◆ extract() [1/3]

◆ extract() [2/3]

◆ extract() [3/3]

◆ getAsString() [1/2]

◆ getAsString() [2/2]

◆ getDateTimeRepresentation() [1/2]

◆ getDateTimeRepresentation() [2/2]

◆ getStringRepresentation() [1/2]

◆ getStringRepresentation() [2/2]

◆ is_equal_hard()

◆ is_equal_soft()

◆ parseBase64ToString()

◆ parseBase64UrlToString()

◆ regexSubst()

◆ substr() [1/2]

◆ substr() [2/2]