Qore Programming Language: QoreString Class Reference

Qore Programming Language 0.8.11

- Main Page
- Related Pages
- Modules
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Public Member Functions | Protected Attributes | List of all members
QoreString Class Reference

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

`#include <QoreString.h>`

Inheritance diagram for QoreString:
[legend]

## Public Member Functions
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 (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 QoreEncoding *new_qorecharset)
| creates an empty string and assigns the encoding passed
DLLEXPORT | QoreString (const char *str, qore_size_t len, const QoreEncoding *new_qorecharset=QCS_DEFAULT)
| copies the c-string passed and assigns the length and encoding passed
DLLEXPORT | QoreString (const std::string &str, const QoreEncoding *new_encoding=QCS_DEFAULT)
| copies the std::string passed and assigns the encoding passed
DLLEXPORT | QoreString (char c)
| creates a single-character string from the argument and assigns the default encoding QCS_DEFAULT
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, qore_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 (int64 i)
| creates a new string with the string representation of the integer passed and assigns the default encoding QCS_DEFAULT
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 (const DateTime *date)
| creates a new string from the DateTime value passed in the format YYYYMMDDHHmmSS
DLLEXPORT | QoreString (const BinaryNode *bin)
| creates a new string as the base64-encoded value of the binary object passed
DLLEXPORT | QoreString (const BinaryNode *bin, qore_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 (char *nbuf, qore_size_t nlen, qore_size_t nallocated, const QoreEncoding *enc)
| takes ownership of the char* passed
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 QoreString &needle, qore_offset_t pos) const
| returns the byte position of a substring within the string or -1 if not found
DLLEXPORT qore_offset_t | bindex (const char *needle, qore_offset_t pos) 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) const
| returns the byte position of a substring within the string or -1 if not found
DLLEXPORT qore_offset_t | brindex (const QoreString &needle, qore_offset_t pos) 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 char *needle, qore_offset_t pos) 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) 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_size_t | capacity () const
| returns number of bytes allocated for the string's buffer, capacity is always >= size
DLLEXPORT qore_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 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 | 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 | 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 QoreString *str, ExceptionSink *xsink)
| concatenates a string and converts encodings if necessary
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, qore_size_t size, ExceptionSink *xsink)
| concatenates a QoreString up to character "len" More...
DLLEXPORT void | concat (const DateTime *d)
| concatenates a DateTime value to a string in the format YYYYMMDDHHmmSS
DLLEXPORT void | concat (const char *str)
| concatenates a c-string to the existing string
DLLEXPORT void | concat (const std::string &str)
| concatenates an stl string to the existing string
DLLEXPORT void | concat (const char *str, qore_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 | concatAndHTMLDecode (const QoreString *str)
| concatenates HTML-decoded version of the c-string passed
DLLEXPORT void | concatAndHTMLDecode (const char *str, size_t slen)
| concatenates HTML-decoded version of the c-string passed with the given length
DLLEXPORT void | concatAndHTMLDecode (const char *str)
| concatenates HTML-decoded version of the c-string passed
DLLEXPORT void | concatAndHTMLEncode (const char *str)
| concatenates HTML-encoded version of the c-string passed
DLLEXPORT void | concatAndHTMLEncode (const QoreString *, ExceptionSink *xsink)
| concatenation with character set conversion
DLLEXPORT void | concatBase64 (const char *buf, qore_size_t size)
| concatenates the base64-encoded version of the binary data passed
DLLEXPORT void | concatBase64 (const BinaryNode *bin)
| concatenates the base64-encoded version of the binary data passed
DLLEXPORT void | concatBase64 (const QoreString *str)
| concatenates the base64-encoded version of the binary data passed (does not make any character encoding conversions)
DLLEXPORT void | concatBase64 (const char *buf, qore_size_t size, qore_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 BinaryNode *bin, qore_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, qore_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 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 | 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 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 | concatEscape (const char *str, char c, char esc_char= '\\')
| concatenates a string and escapes character c with esc_char
DLLEXPORT void | concatHex (const char *buf, qore_size_t size)
| concatenates hexidecimal digits corresponding to the binary data passed up to byte "len"
DLLEXPORT void | concatHex (const BinaryNode *bin)
| concatenates hexidecimal digits corresponding to the binary data passed
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, ExceptionSink *xsink)
| append a character sequence from a unicode code point (returns 0 for OK, -1 for exception) More...
DLLEXPORT int | concatUnicode (unsigned code)
| append a character sequence from a unicode code point (returns 0 for OK, -1 for error) 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 | 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 | equal (const char *str) const
| returns true if the strings are equal, 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 | 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 | 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, const AbstractQoreNode *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 const char * | getBuffer () const
| returns the string's buffer; this data should not be changed
DLLEXPORT qore_offset_t | getByteOffset (qore_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 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 (qore_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, qore_size_t pos)
| inserts a character string at a certain position in the string More...
DLLEXPORT int | insertch (char c, qore_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 qore_size_t | length () const
| returns the number of characters (not bytes) in the string More...
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 QoreString &other)
| assigns the value of one string to another
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 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 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 bool | operator== (const char *other) const
| returns true if the other string is equal to this string (encodings also must be equal)
DLLEXPORT char | operator[] (qore_offset_t pos) const
| returns the byte (not character) at the given location; if the location is invalid, returns 0 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 (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 (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 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, qore_size_t size)
| prepends the string given to the string, assumes character encoding is the same as the string's
DLLEXPORT void | replace (qore_size_t offset, qore_size_t len, const char *str)
| replaces bytes with the string passed More...
DLLEXPORT void | replace (qore_size_t offset, qore_size_t len, const QoreString *str)
| replaces bytes with the string passed More...
DLLEXPORT void | replace (qore_size_t offset, qore_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 (qore_size_t offset, char c)
| replaces a byte with the byte passed More...
DLLEXPORT void | reserve (qore_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 | 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 (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 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 | 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 | 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 qore_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, ExceptionSink *xsink)
| removes "length" characters from the string starting at position "offset" More...
DLLEXPORT void | splice (qore_offset_t offset, qore_offset_t length, const AbstractQoreNode *strn, 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, const QoreString &str, 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 qore_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, qore_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, qore_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, qore_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, qore_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 (qore_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 (const char *chars=0)
| remove leading and trailing whitespace or other characters
DLLEXPORT void | trim (char c)
| remove leading and trailing characters if present
DLLEXPORT void | trim_leading (const char *chars=0)
| remove leading whitespace or other characters
DLLEXPORT void | trim_leading (char c)
| remove leading characters if present
DLLEXPORT void | trim_single_leading (char c)
| remove a single leading character if present
DLLEXPORT void | trim_single_trailing (char c)
| remove a single trailing character if present
DLLEXPORT void | trim_trailing (const char *chars=0)
| remove trailing whitespace or other characters
DLLEXPORT void | trim_trailing (char c)
| remove trailing characters if present
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...

## Protected Attributes
struct qore_string_private * | priv
| 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

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

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

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

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

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

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

DLLEXPORT void QoreString::concat | ( | const QoreString * | str,
|  | qore_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

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

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

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

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

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

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)

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

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

Referenced by QoreStringValueHelper::QoreStringValueHelper().

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

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

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

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

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

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

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

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

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

DLLEXPORT QoreString* QoreString::extract | ( | qore_offset_t | offset,
|  | qore_offset_t | length,
|  | const AbstractQoreNode * | 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

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

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

if the string is not in UTF-8 encoding, only a single character is converted to make the unicode code point calculation

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

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

return Unicode code point for the given byte offset

if the string is not in UTF-8 encoding, only a single character is converted to make the unicode code point calculation

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

Returns
  the unicode code for the character at the given byte offset

Since
  Qore 0.8.8

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

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

DLLEXPORT int QoreString::insert | ( | const char * | str,
|  | qore_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)

DLLEXPORT int QoreString::insertch | ( | char | c,
|  | qore_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)

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

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

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

DLLEXPORT char QoreString::operator[] | ( | qore_offset_t | pos | ) | const

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

Parameters

  pos | offset in string, negative offsets are form the end of the string

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

FIXME: return value should be int and should return -1 if location is invalid

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)

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

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

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)

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

replaces bytes with the string passed

offsets and size are in bytes, not characters

DLLEXPORT void QoreString::replace | ( | qore_size_t | offset,
|  | qore_size_t | len,
|  | const QoreString * | str
| ) |  |

replaces bytes with the string passed

offsets and size are in bytes, not characters does nothing if the encodings are different DEPRECATED: do not use FIXME: this function should take an ExceptionSink argument and convert encodings

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

replaces bytes with the string passed

offsets and size are in bytes, not characters

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

DLLEXPORT void QoreString::replaceChar | ( | qore_size_t | offset,
|  | char | c
| ) |  |

replaces a byte with the byte passed

offsets and size are in bytes, not characters

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

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

DLLEXPORT QoreString* QoreString::reverse | ( |  | ) | const

return a Qorestring with the characters reversed

Returns
  a Qorestring with the characters reversed

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

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

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

DLLEXPORT void QoreString::splice | ( | qore_offset_t | offset,
|  | qore_offset_t | length,
|  | const AbstractQoreNode * | 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

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

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!

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

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; 0 is returned only if a Qore-language exception is thrown due to character encoding conversion errors

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

DLLEXPORT void QoreString::tolwr | ( |  | ) |

converts the string to lower-case in place

WARNING: only works with ASCII characters!

DLLEXPORT void QoreString::toupr | ( |  | ) |

converts the string to upper-case in place

WARNING: only works with ASCII characters!

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:

- include/qore/QoreString.h (6585)