QoreString Class Reference

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

#include <QoreString.h>

Inheritance diagram for QoreString:

QoreStringNode

List of all members.

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 (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 qore_size_t length () const
 returns the number of characters (not bytes) in the string
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 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 concatAndHTMLEncode (const char *str)
 concatenates HTML-encoded version of the c-string passed
DLLEXPORT void concatAndHTMLDecode (const QoreString *str)
 concatenates HTML-decoded version of the c-string passed
DLLEXPORT void concatEscape (const QoreString *, 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 *, char c, char esc_char= '\\')
 concatenates a string and escapes character c with esc_char
DLLEXPORT void concatAndHTMLEncode (const QoreString *, ExceptionSink *xsink)
 concatenation with character set conversion
DLLEXPORT void concat (const QoreString *str, ExceptionSink *xsink)
 concatenates a string and converts encodings if necessary
DLLEXPORT void concat (const QoreString *str, qore_size_t size, ExceptionSink *xsink)
 concatenates a QoreString up to character "len"
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
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
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
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 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
DLLEXPORT void concat (const DateTime *d)
 concatenates a DateTime value to a string in the format YYYYMMDDHHmmSS
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 void concat (const char *str)
 concatenates a c-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 int compareSoft (const QoreString *str, ExceptionSink *xsink) const
 compares the string with another string, performing character set encoding conversion if necessary
DLLEXPORT int compare (const QoreString *str) const
 compares two strings without converting encodings (if the encodings do not match then "this" is deemed automatically less than the argument)
DLLEXPORT int compare (const char *str) const
 compares the string with a c-string, which is assumed to be in the same encoding as the string
DLLEXPORT void terminate (qore_size_t size)
 terminates the string at byte position "size", the string is reallocated if necessary
DLLEXPORT int sprintf (const char *fmt,...)
 this will concatentate a formatted string to the existing string according to the format string and the arguments
DLLEXPORT 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
DLLEXPORT void take (char *str)
 takes ownership of the character pointer passed and assigns it to the string (frees memory previously allocated)
DLLEXPORT void take (char *str, const QoreEncoding *enc)
 takes ownership of the character pointer passed and assigns it to the string (frees memory previously allocated), sets the encoding to the encoding passed
DLLEXPORT void take (char *str, 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 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
DLLEXPORT char * giveBuffer ()
 returns the character buffer and leaves the QoreString empty, the caller owns the memory returned (must be manually freed)
DLLEXPORT void clear ()
 reset string to zero length. Memory is not deallocated.
DLLEXPORT void replace (qore_size_t offset, qore_size_t len, const char *str)
 replaces bytes with the string passed
DLLEXPORT void replace (qore_size_t offset, qore_size_t len, const QoreString *str)
 replaces bytes with the string passed
DLLEXPORT void replace (qore_size_t offset, qore_size_t len, const QoreString *str, ExceptionSink *xsink)
 replaces bytes with the string passed
DLLEXPORT void splice (qore_offset_t offset, ExceptionSink *xsink)
 removes characters from the string starting at position "offset"
DLLEXPORT void splice (qore_offset_t offset, qore_offset_t length, ExceptionSink *xsink)
 removes "length" characters from the string starting at position "offset"
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
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"
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"
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 const QoreEncodinggetEncoding () const
 returns the encoding for the string
DLLEXPORT QoreStringcopy () const
 returns an exact copy of the string
DLLEXPORT void tolwr ()
 converts the string to lower-case in place
DLLEXPORT void toupr ()
 converts the string to upper-case in place
DLLEXPORT qore_size_t strlen () const
 returns number of bytes in the string
DLLEXPORT const char * getBuffer () const
 returns the string's buffer; this data should not be changed
DLLEXPORT void addch (char c, unsigned times)
 append a character to the string a number of times
DLLEXPORT void concatUTF8FromUnicode (unsigned code)
 append a UTF-8 character sequence from a unicode code point, assumes the string is tagged with QCS_UTF8 encoding
DLLEXPORT int concatUnicode (unsigned code, ExceptionSink *xsink)
 append a character sequence from a unicode code point (returns 0 for OK, -1 for exception)
DLLEXPORT int concatUnicode (unsigned code)
 append a character sequence from a unicode code point (returns 0 for OK, -1 for error)
DLLEXPORT QoreStringreverse () const
 return a Qorestring with the characters reversed
DLLEXPORT void trim_trailing (const char *chars=0)
 remove trailing whitespace or other characters
DLLEXPORT void trim_leading (const char *chars=0)
 remove leading whitespace or other characters
DLLEXPORT void trim (const char *chars=0)
 remove leading and trailing whitespace or other characters
DLLEXPORT void trim_trailing (char c)
 remove trailing character
DLLEXPORT void trim_leading (char c)
 remove leading characters
DLLEXPORT void trim (char c)
 remove leading and trailing single char
DLLEXPORT unsigned int getUnicodePointFromUTF8 (qore_offset_t offset=0) const
 return Unicode code point for character offset, string must be UTF-8
DLLEXPORT unsigned int getUnicodePoint (qore_offset_t offset, ExceptionSink *xsink) const
 return Unicode code point for character offset

Protected Member Functions

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

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

Reimplemented in QoreStringNode.

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 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::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::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 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!

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

Reimplemented in QoreStringNode.

Referenced by QoreStringValueHelper::QoreStringValueHelper().

DLLEXPORT char* QoreString::giveBuffer (  ) 

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

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

Referenced by TempEncodingHelper::giveBuffer().

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

Reimplemented in QoreStringNode.

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

Reimplemented in QoreStringNode.

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 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 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 QoreString* QoreString::reverse (  )  const

return a Qorestring with the characters reversed

Returns:
a Qorestring with the characters reversed

Reimplemented in QoreStringNode.

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 unsigned int QoreString::getUnicodePoint ( qore_offset_t  offset,
ExceptionSink xsink 
) const

return Unicode code point for character offset

if the string is not in UTF-8 encoding (tagged with QCS_UTF8), a temporary string will be created in UTF-8 encoding

Parameters:
offset the offset in characters (not bytes) in the string
xsink if an error occurs, the Qore-language exception information will be added here
Returns:
the unicode code for the character


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

Generated on Mon Oct 26 09:09:50 2009 for Qore Programming Language by  doxygen 1.5.6