Qore Programming Language  1.7.0
QoreString Class Reference

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 and ensures the maximum line length for the base64-encoded output
 
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 and ensures the maximum line length for the base64-encoded output
 
DLLEXPORT void concatBase64 (const QoreString *str)
 concatenates the base64-encoded version of the binary data passed (does not make any character encoding conversions)
 
DLLEXPORT void concatBase64 (const QoreString *str, size_t maxlinelen)
 concatenates the base64-encoded version of the binary data passed (does not make any character encoding conversions) and ensures the maximum line length for the base64-encoded output
 
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 QoreStringconvertEncoding (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 QoreStringcopy () 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 QoreStringextract (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 QoreStringextract (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 QoreStringextract (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 QoreEncodinggetEncoding () 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 QoreStringoperator+= (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 QoreStringoperator+= (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 QoreStringoperator= (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 QoreStringoperator= (const QoreString &other)
 assigns the value of one string to another
 
DLLEXPORT QoreStringoperator= (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 BinaryNodeparseBase64 (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 QoreStringparseBase64ToString (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 QoreStringparseBase64ToString (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 BinaryNodeparseHex (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 QoreStringregexSubst (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 QoreStringreverse () 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 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 QoreStringsubstr (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 QoreStringsubstr (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
strthe 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
strthe 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
strthe string to compare
xsinkif 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
strthe string to concatenate to the current string (this)
posthe starting character position (not byte) for concatenation (negative values are from the end)
xsinkif 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
strthe string to concatenate to the current string (this)
posthe starting character (not byte) position for concatenation (negative values are from the end)
lenthe number of characters (not bytes) to concatenate from the starting position (negative values indicate all except that many characters from the end)
xsinkif 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
strthe QoreString to concatenate
sizethe number of characters to copy (not bytes)
xsinkif 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

◆ 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
xsinkQore-language exceptions (in this case character encoding conversion errors) are raised here
strthe string to concentenate; it is converted to the target character encoding (of 'this') unless CD_NUM_REF is given in the code argument
codea 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
xsinkQore-language exceptions (in this case character encoding conversion errors) are raised here
strthe source string for the concatenation; it is converted to the target character encoding (of 'this') unless CE_NONASCII is given in the code argument
codean 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
xsinkQore-language exceptions (in this case character encoding conversion errors) are raised here
urlthe 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
xsinkQore-language exceptions (in this case character encoding conversion errors) are raised here
urlthe url to encode and concatentate to the current string
encode_allif 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
codethe 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
codethe Unicode code point to append to the string
xsinkif 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
codethe 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
nccsthe encoding for the new string
xsinkif 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
strthe string to compare
xsinkif 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
strthe string to compare
xsinkif 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
strthe string to compare
xsinkif 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
offsetcharacter 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)
xsinkis 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
offsetcharacter 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)
lengththe number of characters (not bytes) to remove (negative length means all but that many characters from the end of the string)
xsinkinvalid 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
offsetcharacter 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)
lengththe number of characters (not bytes) to remove (negative length means all but that many characters from the end of the string)
strnthe string to insert at character position "offset" after "length" characters are removed
xsinkinvalid 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
ithe character offset to find the byte offset for
xsinkif 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
xsinkif 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
offsetthe offset in characters (not bytes) in the string; may be negative giving an offset from the end of the string
xsinkif 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
offsetthe offset in bytes in the string
lenthe length of the character in bytes in the source string in the original encoding
xsinkif 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
offsetthe 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)

◆ insert()

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

inserts a character string at a certain position in the string

Parameters
strthe string to insert
posthe 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
cthe character to insert
posthe position to insert the character(s) (first position is 0)
timesthe 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
posbyte 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
xsinkif 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
encthe encoding to tag the decoded string with
xsinkif 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
xsinkif 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

◆ 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
xsinkif 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
matchthe pattern to match
substthe substitution string
optsregex options combined with binary or; see String Regular Expression Options for options
xsinkinvalid 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
outputthe string where the output will be written
matchthe pattern to match
substthe substitution string
optsregex options combined with binary or; see String Regular Expression Options for options
xsinkinvalid 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
matchthe pattern to match
substthe substitution string
optsregex options combined with binary or; see String Regular Expression Options for options
xsinkinvalid 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
needlethe string to find
posthe character position to start the search; if pos is < 0 then it gives an offset from the end of the string (-1 = last character)
xsinkif 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
offsetcharacter 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)
xsinkis 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
offsetcharacter 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)
lengththe number of characters (not bytes) to remove (negative length means all but that many characters from the end of the string)
strthe string to insert at character position "offset" after "length" characters are removed
xsinkinvalid 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
offsetcharacter 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)
lengththe number of characters (not bytes) to remove (negative length means all but that many characters from the end of the string)
xsinkinvalid 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
offsetcharacter 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)
lengththe number of characters (not bytes) to remove (negative length means all but that many characters from the end of the string)
strnthe string to insert at character position "offset" after "length" characters are removed
xsinkinvalid multi-byte encodings can cause an exception to be thrown

◆ 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
offsetthe offset in characters from the beginning of the string (starting with 0)
xsinkinvalid 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
offsetthe offset in characters from the beginning of the string (starting with 0)
lengththe number of characters for the substring
xsinkinvalid 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: