Qore's string type supported by the QoreEncoding class. More...

#include <QoreString.h>

Inheritance diagram for QoreString:

Public Member Methods
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. More...

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

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

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

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

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

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" More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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" More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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" More...

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

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

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

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

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

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

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

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

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" More...

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" More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Private Attributes
struct qore_string_private *	priv = nullptr
	the private implementation of QoreString

Detailed Description

Qore's string type supported by the QoreEncoding class.

A QoreString is implemented by a char pointer, a byte length, and a QoreEncoding pointer. For the equivalent Qore parse tree/value type, see QoreStringNode

See also: QoreStringNode

Member Function Documentation

◆ allocate()

DLLEXPORT void QoreString::allocate ( unsigned requested_size )

Ensure the internal buffer has at least expected size in bytes.

Useful to eliminate repeated buffer reallocations when data are appended in a loop

◆ compare() [1/2]

DLLEXPORT int QoreString::compare ( const char * str ) const

compares the string with a c-string, which is assumed to be in the same encoding as the string

Parameters

str	the string to compare

Returns: -1, 0, or 1 if "this" is less than, equal to, or greater than "str" respectively

◆ compare() [2/2]

DLLEXPORT int QoreString::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)

Parameters

str	the string to compare

Returns: -1, 0, or 1 if "this" is less than, equal to, or greater than "str" respectively

◆ compareSoft()

DLLEXPORT int QoreString::compareSoft	(	const QoreString *	str,
		ExceptionSink *	xsink
	)		const

compares the string with another string, performing character set encoding conversion if necessary

Parameters

str	the string to compare
xsink	if an error occurs, the Qore-language exception information will be added here

Returns: -1, 0, or 1 if "this" is less than, equal to, or greater than "str" respectively

◆ concat() [1/3]

DLLEXPORT int QoreString::concat	(	const QoreString &	str,
		qore_offset_t	pos,
		ExceptionSink *	xsink
	)

concatenates a string and converts encodings if necessary

Parameters

str	the string to concatenate to the current string (this)
pos	the starting character position (not byte) for concatenation (negative values are from the end)
xsink	if an error occurs converting character encodings, it will be raised here

Returns: 0 for OK, -1 for exception raised

◆ concat() [2/3]

DLLEXPORT int QoreString::concat	(	const QoreString &	str,
		qore_offset_t	pos,
		qore_offset_t	len,
		ExceptionSink *	xsink
	)

concatenates a string and converts encodings if necessary

Parameters

str	the string to concatenate to the current string (this)
pos	the starting character (not byte) position for concatenation (negative values are from the end)
len	the number of characters (not bytes) to concatenate from the starting position (negative values indicate all except that many characters from the end)
xsink	if an error occurs converting character encodings, it will be raised here

Returns: 0 for OK, -1 for exception raised

◆ concat() [3/3]

DLLEXPORT void QoreString::concat	(	const QoreString *	str,
		size_t	size,
		ExceptionSink *	xsink
	)

concatenates a QoreString up to character "len"

An exception could be thrown if the string to concatenate requires character set encoding conversion and the conversion fails

Parameters

str	the QoreString to concatenate
size	the number of characters to copy (not bytes)
xsink	if an error occurs, the Qore-language exception information will be added here

◆ concatAndHTMLDecode() [1/3]

DLLEXPORT void QoreString::concatAndHTMLDecode ( const char * str )

concatenates HTML-decoded version of the c-string passed

Deprecated:: does not do any character encoding conversions; use concatDecode() instead

◆ concatAndHTMLDecode() [2/3]

DLLEXPORT void QoreString::concatAndHTMLDecode	(	const char *	str,
		size_t	slen
	)

concatenates HTML-decoded version of the c-string passed with the given length

Deprecated:: does not do any character encoding conversions; use concatDecode() instead

◆ concatAndHTMLDecode() [3/3]

DLLEXPORT void QoreString::concatAndHTMLDecode ( const QoreString * str )

concatenates HTML-decoded version of the c-string passed

Deprecated:: does not do any character encoding conversions; use concatDecode() instead

◆ concatAndHTMLEncode() [1/2]

DLLEXPORT void QoreString::concatAndHTMLEncode ( const char * str )

concatenates HTML-encoded version of the c-string passed

Deprecated:: does not do any character encoding conversions; use concatEncode() instead

◆ concatAndHTMLEncode() [2/2]

DLLEXPORT void QoreString::concatAndHTMLEncode	(	const QoreString *	str,
		ExceptionSink *	xsink
	)

concatenation with HTML special character encoding

equivalent to concatEncode() with code = CE_HTML

See also: concatEncode()

Deprecated:: use concatEncode() instead

◆ concatBase64() [1/4]

DLLEXPORT void QoreString::concatBase64	(	const BinaryNode *	bin,
		size_t	maxlinelen
	)

concatenates the base64-encoded version of the binary data passed

ensures the maximum line length for the base64-encoded output

◆ concatBase64() [2/4]

DLLEXPORT void QoreString::concatBase64	(	const char *	buf,
		size_t	size,
		size_t	maxlinelen
	)

concatenates the base64-encoded version of the binary data passed

ensures the maximum line length for the base64-encoded output

◆ concatBase64() [3/4]

DLLEXPORT void QoreString::concatBase64 ( const QoreString * str )

concatenates the base64-encoded version of the binary data passed

does not make any character encoding conversions

◆ concatBase64() [4/4]

DLLEXPORT void QoreString::concatBase64	(	const QoreString *	str,
		size_t	maxlinelen
	)

concatenates the base64-encoded version of the binary data passed

does not make any character encoding conversions; ensures the maximum line length for the base64-encoded output

◆ concatBase64Url() [1/2]

DLLEXPORT void QoreString::concatBase64Url ( const BinaryNode & bin )

concatenates the base64-url-encoded version of the binary data passed

Since: Qore 1.19.0

◆ concatBase64Url() [2/2]

DLLEXPORT void QoreString::concatBase64Url ( const QoreString & str )

concatenates the base64-url-encoded version of the binary data passed

does not make any character encoding conversions

Since: Qore 1.19.0

◆ concatDecode()

DLLEXPORT int QoreString::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

Parameters

xsink	Qore-language exceptions (in this case character encoding conversion errors) are raised here
str	the string to concentenate; it is converted to the target character encoding (of 'this') unless CD_NUM_REF is given in the code argument
code	a decoding bitfield arguments; see String Concatenation Decoding Codes for more information

Returns: -1 if a Qore-language exception was thrown, 0 if not

Note: if the target character encoding of 'this' cannot support the decoded symbol, the character reference is not decoded but rather concatenated as-is

See also: concatEncode()

Since: Qore 0.8.12

◆ concatDecodeUriRequest()

DLLEXPORT int QoreString::concatDecodeUriRequest	(	const QoreString &	url,
		ExceptionSink *	xsink
	)

concatenates a URI-decoded version of the c-string passed

Since: Qore 0.8.12

◆ concatDecodeUrl()

DLLEXPORT void QoreString::concatDecodeUrl ( const char * url )

concatenates a URL-decoded version of the c-string passed

Deprecated:: does not support RFC 3986, use concatDecodeUrl(const QoreString&, ExceptionSink*) instead

◆ concatEncode()

DLLEXPORT int QoreString::concatEncode	(	ExceptionSink *	xsink,
		const QoreString &	str,
		unsigned	code = `CE_XHTML`
	)

concatenates a string and encodes it according to the encoding argument passed

Parameters

xsink	Qore-language exceptions (in this case character encoding conversion errors) are raised here
str	the source string for the concatenation; it is converted to the target character encoding (of 'this') unless CE_NONASCII is given in the code argument
code	an encoding bitfield argument; see String Concatenation Encoding Codes for more information

Returns: -1 if a Qore-language exception was thrown, 0 if not

See also: concatDecode()

Since: Qore 0.8.12

◆ concatEncodeUriRequest()

DLLEXPORT int QoreString::concatEncodeUriRequest	(	ExceptionSink *	xsink,
		const QoreString &	url
	)

concatenates a URI-encoded version of the c-string passed

Parameters

xsink	Qore-language exceptions (in this case character encoding conversion errors) are raised here
url	the url to encode and concatentate to the current string

Since: Qore 0.8.12

◆ concatEncodeUrl()

DLLEXPORT int QoreString::concatEncodeUrl	(	ExceptionSink *	xsink,
		const QoreString &	url,
		bool	encode_all = `false`
	)

concatenates a URL-encoded version of the c-string passed

Parameters

xsink	Qore-language exceptions (in this case character encoding conversion errors) are raised here
url	the url to encode and concatentate to the current string
encode_all	if true then all reserved characters are percent encoded (!*'();:&=+$,/?#[]), otherwise only non-ascii characters, '' and ' ' are percent-encoded

◆ concatHex()

DLLEXPORT void QoreString::concatHex	(	const char *	buf,
		size_t	size
	)

concatenates hexidecimal digits corresponding to the binary data passed up to byte "len"

hex characters are always in lwoer case

◆ concatUnicode() [1/2]

DLLEXPORT int QoreString::concatUnicode ( unsigned code )

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

Parameters

code	the Unicode code point to append to the string

Returns: returns 0 for OK, -1 for error (current encoding does not support this unicode character)

◆ concatUnicode() [2/2]

DLLEXPORT int QoreString::concatUnicode	(	unsigned	code,
		ExceptionSink *	xsink
	)

append a character sequence from a unicode code point (returns 0 for OK, -1 for exception)

tries to convert the unicode data to the string's character encoding, if an error occurs an exception will be thrown

Parameters

code	the Unicode code point to append to the string
xsink	if an error occurs, the Qore-language exception information will be added here

◆ concatUTF8FromUnicode()

DLLEXPORT void QoreString::concatUTF8FromUnicode ( unsigned code )

append a UTF-8 character sequence from a unicode code point, assumes the string is tagged with QCS_UTF8 encoding

WARNING! Does not check the encoding before appending data to the string; if the string was not created as a UTF-8 string, then this function will append invalid data to the string.

Parameters

code	the Unicode code point to append to the string as UTF-8 data

See also: QoreString::concatUnicode()

◆ convertEncoding()

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

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

◆ endsWith() [1/2]

DLLEXPORT bool QoreString::endsWith ( const char * str ) const

returns true if the current string ends with the argument string (bytes)

Since: Qore 1.0

◆ endsWith() [2/2]

DLLEXPORT bool QoreString::endsWith ( const std::string & str ) const

returns true if the current string ends with the argument string (bytes)

Since: Qore 1.0

◆ equal() [1/2]

DLLEXPORT bool QoreString::equal ( const char * str ) const

returns true if the strings are equal, false if not (encodings are assumed to be equal)

Since: Qore 0.8.8

◆ equal() [2/2]

DLLEXPORT bool QoreString::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

Since: Qore 0.8.8

◆ equalPartial() [1/2]

DLLEXPORT bool QoreString::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)

Since: Qore 0.8.8

◆ equalPartial() [2/2]

DLLEXPORT bool QoreString::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

Since: Qore 0.8.8

◆ equalPartialPath()

DLLEXPORT bool QoreString::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

Parameters

str	the string to compare
xsink	if an error occurs, the Qore-language exception information will be added here

Returns: true if the beginning 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

Since: Qore 0.8.8

◆ equalPartialSoft()

DLLEXPORT bool QoreString::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

Parameters

str	the string to compare
xsink	if an error occurs, the Qore-language exception information will be added here

Returns: true if the beginning of the current string matches the argument string, false if not

Since: Qore 0.8.8

◆ equalSoft()

DLLEXPORT bool QoreString::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

Parameters

str	the string to compare
xsink	if an error occurs, the Qore-language exception information will be added here

Returns: true if the strings are equal, false if not

Since: Qore 0.8.8

◆ extract() [1/3]

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

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

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

◆ extract() [3/3]

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

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

◆ find() [1/2]

DLLEXPORT qore_offset_t QoreString::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

Since: Qore 1.0

◆ find() [2/2]

DLLEXPORT qore_offset_t QoreString::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

Since: Qore 1.0

◆ getByteOffset()

DLLEXPORT qore_offset_t QoreString::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

Parameters

i	the character offset to find the byte offset for
xsink	if invalid encoded data is found the error is raised here

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

◆ getCharWidth()

DLLEXPORT size_t QoreString::getCharWidth ( ExceptionSink * xsink ) const

returns the character width of the string

Parameters

xsink if invalid encoded data is found the error is raised here

Returns: the character width of the string

unicode characters may be wider than one space

Since: Qore 0.9.4

◆ getUnicodePoint()

DLLEXPORT unsigned int QoreString::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

Parameters

offset	the offset in characters (not bytes) in the string; may be negative giving an offset from the end of the string
xsink	if an error occurs, the Qore-language exception information will be added here

Returns: the unicode code for the character or -1 in case of an error

◆ getUnicodePointFromBytePos()

DLLEXPORT unsigned int QoreString::getUnicodePointFromBytePos	(	size_t	offset,
		unsigned &	len,
		ExceptionSink *	xsink
	)		const

return Unicode code point for the given byte offset

Parameters

offset	the offset in bytes in the string
len	the length of the character in bytes in the source string in the original encoding
xsink	if an error occurs, the Qore-language exception information will be added here

Returns: the unicode code for the character at the given byte offset or -1 in case of an error

Since: Qore 0.8.8

◆ getUnicodePointFromUTF8()

DLLEXPORT unsigned int QoreString::getUnicodePointFromUTF8 ( qore_offset_t offset = 0 ) const

return Unicode code point for character offset, string must be UTF-8

if the string is not in UTF-8 encoding (tagged with QCS_UTF8), an unpredictable value will be returned

Parameters

offset the offset in characters (not bytes) in the string (negative offset means that many characters from the end of the string)

Returns: the unicode code for the character or -1 in case of an error

◆ giveBuffer()

DLLEXPORT char * QoreString::giveBuffer ( )

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

note that after this call the string buffer memory is 0 (i.e. QoreString::getBuffer() will return NULL)

Returns: the character buffer for the string, the caller owns the memory returned (must be manually freed)

Referenced by TempEncodingHelper::giveBuffer().

◆ insert()

DLLEXPORT int QoreString::insert	(	const char *	str,
		size_t	pos
	)

inserts a character string at a certain position in the string

Parameters

str	the string to insert
pos	the position to insert the string (first position is 0)

Returns: 0 = OK, -1 = error (pos is greater than the string's length)

◆ insertch()

DLLEXPORT int QoreString::insertch	(	char	c,
		size_t	pos,
		unsigned	times
	)

insert a character at a certain position in the string a number of times

Parameters

c	the character to insert
pos	the position to insert the character(s) (first position is 0)
times	the number of times the character should be inserted

Returns: 0 = OK, -1 = error (pos is greater than the string's length)

◆ isDataAscii()

DLLEXPORT bool QoreString::isDataAscii ( ) const

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

Note: the string's encoding is ignored and the data itself is scanned for the return value

◆ isDataPrintableAscii()

DLLEXPORT bool QoreString::isDataPrintableAscii ( ) const

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

Note: the string's encoding is ignored and the data itself is scanned for the return value

◆ length()

DLLEXPORT size_t QoreString::length ( ) const

returns the number of characters (not bytes) in the string

an invalid character length may be returned if invalid character encodings are found in a multi-byte character encoding

◆ operator[]()

DLLEXPORT int QoreString::operator[] ( qore_offset_t pos ) const

returns the byte (not character) at the given location; if the location is invalid, returns -1

Parameters

pos	byte offset in string, negative offsets are from the end of the string

Returns: the byte (not character) at the given location; if the location is invalid, returns -1

◆ parseBase64()

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

Parameters

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

Returns: a pointer to a BinaryNode object of the decoded data, the caller owns the reference count of the object returned (0 if an exception occurs)

◆ parseBase64ToString() [1/2]

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

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 QoreString of the decoded data (0 if an exception occurs), the QoreString pointer is owned by the caller

◆ parseBase64ToString() [2/2]

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

Parameters

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

Returns: a QoreString of the decoded data tagged with the default encoding (0 if an exception occurs), the QoreString pointer is owned by the caller

◆ parseBase64Url()

DLLEXPORT BinaryNode * QoreString::parseBase64Url ( ExceptionSink * xsink ) const

Parses the current string data as base64-URL-encoded data and returns a BinaryNode pointer.

Caller owns the reference count returned; throws a qore-language exception if any errors are encountered

Parameters

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

Returns: a pointer to a BinaryNode object of the decoded data, the caller owns the reference count of the object returned (0 if an exception occurs)

Since: Qore 2.0

◆ parseBase64UrlToString() [1/2]

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

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 QoreString of the decoded data (0 if an exception occurs), the QoreString pointer is owned by the caller

Since: Qore 2.0

◆ parseBase64UrlToString() [2/2]

DLLEXPORT QoreString * QoreString::parseBase64UrlToString ( ExceptionSink * xsink ) const

Parses the current string data as base64-URL-encoded data and returns a QoreString pointer owned by the caller.

Parameters

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

Returns: a QoreString of the decoded data tagged with the default encoding (0 if an exception occurs), the QoreString pointer is owned by the caller

Since: Qore 2.0

◆ parseHex()

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

Parameters

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

Returns: a pointer to a BinaryNode object of the decoded data, the caller owns the reference count of the object returned (0 if an exception occurs)

◆ regexSubst() [1/2]

DLLEXPORT QoreString * QoreString::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 combined with binary or; see String Regular Expression Options for 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

◆ regexSubst() [2/2]

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

performs perl5-compatible regular expression substitution

Parameters

output	the string where the output will be written
match	the pattern to match
subst	the substitution string
opts	regex options combined with binary or; see String Regular Expression Options for options
xsink	invalid multi-byte encodings can cause an exception to be thrown

Returns: 0 = OK, -1 = error raised

Since: Qore 1.1.0

◆ regexSubstInPlace()

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

performs perl5-compatible regular expression substitution to the current string

Parameters

match	the pattern to match
subst	the substitution string
opts	regex options combined with binary or; see String Regular Expression Options for options
xsink	invalid multi-byte encodings can cause an exception to be thrown

Returns: 0 = OK, -1 = error raised

Since: Qore 1.1.0

◆ replace() [1/2]

DLLEXPORT void QoreString::replace	(	size_t	offset,
		size_t	len,
		const char *	str
	)

replaces bytes with the string passed

offsets and size are in bytes, not characters

◆ replace() [2/2]

DLLEXPORT void QoreString::replace	(	size_t	offset,
		size_t	len,
		const QoreString *	str,
		ExceptionSink *	xsink
	)

replaces bytes with the string passed

offsets and size are in bytes, not characters

◆ replaceAll()

DLLEXPORT void QoreString::replaceAll	(	const char *	old_str,
		const char *	new_str
	)

replaces all occurences of the first string with the second string

both of the new strings must be in the same encoding as the QoreString

◆ replaceChar()

DLLEXPORT void QoreString::replaceChar	(	size_t	offset,
		char	c
	)

replaces a byte with the byte passed

offsets and size are in bytes, not characters

◆ reserve()

DLLEXPORT void QoreString::reserve ( size_t size )

ensures that at least the given size is available in the string; the string's contents are not affected

actually reserves size + 1 bytes to accommodate the terminating '\0' character

◆ reset()

DLLEXPORT void QoreString::reset ( )

reset string to zero length; memory is deallocated; string encoding is reset to QCS_DEFAULT

a new string buffer is allocated with a '\0' in the first location

◆ reverse()

DLLEXPORT QoreString * QoreString::reverse ( ) const

return a Qorestring with the characters reversed

Returns: a Qorestring with the characters reversed

◆ rfind() [1/2]

DLLEXPORT qore_offset_t QoreString::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

Since: Qore 1.0

◆ rfind() [2/2]

DLLEXPORT qore_offset_t QoreString::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

Since: Qore 1.0

◆ rindex()

DLLEXPORT qore_offset_t QoreString::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

Parameters

needle	the string to find
pos	the character position to start the search; if pos is < 0 then it gives an offset from the end of the string (-1 = last character)
xsink	if an error occurs, the Qore-language exception information will be added here

Returns: -1 for not found otherwise the character position of the last occurrence of the search string

◆ set()

DLLEXPORT void QoreString::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

Since: Qore 1.0

◆ splice() [1/4]

DLLEXPORT void QoreString::splice	(	qore_offset_t	offset,
		ExceptionSink *	xsink
	)

removes characters from the string starting at position "offset"

values are for characters, not bytes

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

◆ splice() [2/4]

DLLEXPORT void QoreString::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

values are for characters, not bytes

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

◆ splice() [3/4]

DLLEXPORT void QoreString::splice	(	qore_offset_t	offset,
		qore_offset_t	length,
		ExceptionSink *	xsink
	)

removes "length" characters from the string starting at position "offset"

values are for characters, not bytes

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

◆ splice() [4/4]

DLLEXPORT void QoreString::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

values are for characters, not bytes

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

◆ split() [1/2]

DLLEXPORT QoreListNode * QoreString::split	(	const char *	sep,
		bool	with_separator = `false`
	)

Splits a string into a list of components based on a separator string.

Parameters

xsink	invalid multi-byte encodings can cause an exception to be thrown
sep	the separator string; if the separator string is not found in the string to split, then a list with only one element containing the entire string argument is returned'
with_separator	include the separator string in every element

Returns: a list of each component of a string separated by a separator string, with the separator removed; the separator pattern will not be included in the elements of the list returned unless the with_separator argument is True

Since: Qore 2.0

◆ split() [2/2]

DLLEXPORT QoreListNode * QoreString::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.

Parameters

xsink	invalid multi-byte encodings can cause an exception to be thrown
sep	the separator string; if the separator string is not found in the string to split, then a list with only one element containing the entire string argument is returned'
quote	the quote character
trim_unquoted	remove leading and trailing whitespace from unquoted fields

Returns: a list of each component of a string separated by a separator string, with the separator removed; the separator pattern will not be included in the elements of the list returned unless the with_separator argument is True

Since: Qore 2.0

◆ sprintf()

DLLEXPORT int QoreString::sprintf	(	const char *	fmt,
			...
	)

this will concatentate a formatted string to the existing string according to the format string and the arguments

NOTE that the formatted string is concatenated to the end of the current string!

◆ startsWith() [1/2]

DLLEXPORT bool QoreString::startsWith ( const char * str ) const

returns true if the current string starts with the argument string (bytes)

Since: Qore 1.0

◆ startsWith() [2/2]

DLLEXPORT bool QoreString::startsWith ( const std::string & str ) const

returns true if the current string starts with the argument string (bytes)

Since: Qore 1.0

◆ substr() [1/2]

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

offset is a character offset (not a byte offset)

Parameters

offset	the offset in characters from the beginning of the string (starting with 0)
xsink	invalid multi-byte encodings can cause an exception to be thrown

Returns: the new string; an empty string is returned if the arguments cannot be satisfied; 0 is returned only if a Qore-language exception is thrown due to character encoding conversion errors

◆ substr() [2/2]

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

offset and length spoecify characters, not bytes

Parameters

offset	the offset in characters from the beginning of the string (starting with 0)
length	the number of characters for the substring
xsink	invalid multi-byte encodings can cause an exception to be thrown

Returns: the new string; an empty string is returned if the arguments cannot be satisfied; nullptr is returned only if a Qore-language exception is thrown due to character encoding conversion errors

◆ take()

DLLEXPORT void QoreString::take ( char * str )

takes ownership of the character pointer passed and assigns it to the string (frees memory previously allocated)

the encoding marker is not changed by this call, it remains the same as the previous encoding

◆ tolwr()

DLLEXPORT void QoreString::tolwr ( )

converts the string to lower-case in place

WARNING: only works with ASCII characters!

◆ toupr()

DLLEXPORT void QoreString::toupr ( )

converts the string to upper-case in place

WARNING: only works with ASCII characters!

◆ trim() [1/3]

DLLEXPORT void QoreString::trim ( char c )

remove leading and trailing characters if present

does not work with multi-byte encodings

◆ trim() [2/3]

DLLEXPORT void QoreString::trim ( const char * chars = 0 )

remove leading and trailing whitespace or other characters

does not work with multi-byte encodings

◆ trim() [3/3]

DLLEXPORT int QoreString::trim	(	ExceptionSink *	xsink,
		const QoreString *	chars = `nullptr`
	)

removes leading and trailing whitespace or other characters

performs character conversions, works with multi-byte encodings

Returns: 0 = OK, -1 = exception raised

Since: Qore 0.8.13

◆ trim_leading() [1/2]

DLLEXPORT void QoreString::trim_leading ( char c )

remove leading characters if present

does not work with multi-byte encodings

◆ trim_leading() [2/2]

DLLEXPORT void QoreString::trim_leading ( const char * chars = 0 )

remove leading whitespace or other characters

does not work with multi-byte encodings

◆ trim_single_leading()

DLLEXPORT void QoreString::trim_single_leading ( char c )

remove a single leading character if present

does not work with multi-byte encodings

◆ trim_single_trailing()

DLLEXPORT void QoreString::trim_single_trailing ( char c )

remove a single trailing character if present

does not work with multi-byte encodings

◆ trim_trailing() [1/2]

DLLEXPORT void QoreString::trim_trailing ( char c )

remove trailing characters if present

does not work with multi-byte encodings

◆ trim_trailing() [2/2]

DLLEXPORT void QoreString::trim_trailing ( const char * chars = 0 )

remove trailing whitespace or other characters

does not work with multi-byte encodings

◆ trimLeading()

DLLEXPORT int QoreString::trimLeading	(	ExceptionSink *	xsink,
		const QoreString *	chars = `nullptr`
	)

removes leading whitespace or other characters

performs character conversions, works with multi-byte encodings

Returns: 0 = OK, -1 = exception raised

Since: Qore 0.8.13

◆ trimTrailing()

DLLEXPORT int QoreString::trimTrailing	(	ExceptionSink *	xsink,
		const QoreString *	chars = `nullptr`
	)

removes trailing whitespace or other characters

performs character conversions, works with multi-byte encodings

Returns: 0 = OK, -1 = exception raised

Since: Qore 0.8.13

◆ vsprintf()

DLLEXPORT int QoreString::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

NOTE that the formatted string is concatenated to the end of the current string!

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

/tmp/qore/include/qore/QoreString.h

Public Member Methods

Private Attributes

Detailed Description

Member Function Documentation

◆ allocate()

◆ compare() [1/2]

◆ compare() [2/2]

◆ compareSoft()

◆ concat() [1/3]

◆ concat() [2/3]

◆ concat() [3/3]

◆ concatAndHTMLDecode() [1/3]

◆ concatAndHTMLDecode() [2/3]

◆ concatAndHTMLDecode() [3/3]

◆ concatAndHTMLEncode() [1/2]

◆ concatAndHTMLEncode() [2/2]

◆ concatBase64() [1/4]

◆ concatBase64() [2/4]

◆ concatBase64() [3/4]

◆ concatBase64() [4/4]

◆ concatBase64Url() [1/2]

◆ concatBase64Url() [2/2]

◆ concatDecode()

◆ concatDecodeUriRequest()

◆ concatDecodeUrl()

◆ concatEncode()

◆ concatEncodeUriRequest()

◆ concatEncodeUrl()

◆ concatHex()

◆ concatUnicode() [1/2]

◆ concatUnicode() [2/2]

◆ concatUTF8FromUnicode()

◆ convertEncoding()

◆ endsWith() [1/2]

◆ endsWith() [2/2]

◆ equal() [1/2]

◆ equal() [2/2]

◆ equalPartial() [1/2]

◆ equalPartial() [2/2]

◆ equalPartialPath()

◆ equalPartialSoft()

◆ equalSoft()

◆ extract() [1/3]

◆ extract() [2/3]

◆ extract() [3/3]

◆ find() [1/2]

◆ find() [2/2]

◆ getByteOffset()

◆ getCharWidth()

◆ getUnicodePoint()

◆ getUnicodePointFromBytePos()

◆ getUnicodePointFromUTF8()

◆ giveBuffer()

◆ insert()

◆ insertch()

◆ isDataAscii()

◆ isDataPrintableAscii()

◆ length()

◆ operator[]()

◆ parseBase64()

◆ parseBase64ToString() [1/2]

◆ parseBase64ToString() [2/2]

◆ parseBase64Url()

◆ parseBase64UrlToString() [1/2]

◆ parseBase64UrlToString() [2/2]

◆ parseHex()

◆ regexSubst() [1/2]

◆ regexSubst() [2/2]

◆ regexSubstInPlace()

◆ replace() [1/2]

◆ replace() [2/2]

◆ replaceAll()

◆ replaceChar()

◆ reserve()

◆ reset()

◆ reverse()

◆ rfind() [1/2]

◆ rfind() [2/2]

◆ rindex()

◆ set()