<string> Class Reference

Methods in this pseudo-class can be executed on strings. More...

Inheritance diagram for Qore::<string>:
[legend]

## Public Member Functions

int | comparePartial (string ostr)
| Compares the beginning of the current string with a shorter string passed as an argument, returns -1, 0, or 1 if the argument string is less than, equal, or greater than the beginning of the current string; returns also -1 if the argument string is equal to the beginning of the current string but the argument string is longer than the current string. More...
bool | empty ()
| Returns True if the string is empty, False if not. More...
string | encoding ()
| Returns the name of the string's character encoding. More...
bool | equalPartial (string ostr)
| Compares the beginning of the current string with a shorter string passed as an argument for equality only, returns True if the string argument matches the beginning of the string, False if not. More...
bool | equalPartialPath (string ostr)
| Compares the beginning of the current string assumed to be a path with a shorter string passed as an argument for equality only, returns True if the string argument matches the beginning of the 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. More...
int | find (softstring substr, softint pos=0)
| Retrieves the character position of a substring within a string. More...
string | getDecoded (int code=CD_ALL)
| returns a string based on the string value, decoded as per the code argument More...
string | getEncoded (int code=CE_XHTML)
| returns a string based on the string value with encodings as per the code argument More...
*string | getLine (int offset=0, *string eol, bool trim=True, *reference< int > size)
| returns a string for the next line in the string buffer starting at the given offset (or at the beginning if no offset is given) More...
int | getUnicode (int offset=0)
| returns the Unicode code for the given character offset in the string More...
bool | intp ()
| Returns True if the string can be converted to an integer, False if not, this depends on the first (or possibly second) character of the string, if it's 0 - 9 (possibly preceded by `"-"`), then the method returns True. More...
bool | isDataAscii ()
| returns True if the string is empty or has no characters with the high bit set (ie all characters < 128) More...
bool | isDataPrintableAscii ()
| returns True if the string is empty or only contains printable non-control ASCII characters (ie all characters > 31 && < 127) More...
int | length ()
| Returns the number of characters in the string; may not be equal to the byte length (returned by <string>::strlen() and <string>::size()) for multi-byte character encodings. More...
string | lwr ()
| Returns the string in lower case. More...
bool | regex (string regex, int options=0)
| Returns True if the regular expression matches the string passed, otherwise returns False. More...
*list< *string > | regexExtract (string regex, int options=0)
| Returns a list of substrings in a string based on matching patterns defined by a regular expression. More...
int | rfind (softstring substr, softint pos=-1)
| Retrieves the character position of a substring within a string, starting the search from the end of the string. More...
int | size ()
| Returns the number of bytes in the string (not including the terminating null character (`'\0'`) More...
bool | sizep ()
| Returns True since strings can return a non-zero size. More...
list< string > | split (string sep, bool with_separator=False)
| Splits a string into a list of components based on a separator string. More...
list< string > | split (string sep, string quote, bool trim_unquoted=False)
| Splits a string into a list of components based on a separator string and a quote character. More...
list< string > | splitRegex (string regex_sep, int options=0, bool with_separator=False)
| Splits a string into a list of components based on a separator regular expression. More...
list< string > | splitRegex (string regex_sep, bool with_separator=False)
| Splits a string into a list of components based on a separator regular expression. More...
int | strlen ()
| Returns the number of bytes in the string (not including the terminating null character (`'\0'`) More...
bool | strp ()
| Returns True by default. More...
string | substr (softint start)
| Returns a portion of a string starting from an integer offset. More...
string | substr (softint start, softint len)
| Returns a portion of a string starting from an integer offset, with a length parameter. More...
string | toBase64 (softint maxlinelen=-1)
| Returns the base64-encoded representation of the string. More...
binary | toBinary ()
| Returns a binary value with the string's data. More...
string | toHex ()
| returns a string of hexadecimal digits corresponding to the contents of the string More...
int | toInt (int base=10)
| Converts the string to an integer value with respect to the base. More...
string | toMD5 ()
| Returns the MD5 message digest of the string as a hex string. More...
string | toSHA1 ()
| Returns the SHA1 message digest of the string as a hex string. More...
string | toSHA224 ()
| Returns the SHA-224 message digest (a variant of SHA-2) of the string as a hex string. More...
string | toSHA256 ()
| Returns the SHA-256 message digest (a variant of SHA-2) of the string as a hex string. More...
string | toSHA384 ()
| Returns the SHA-384 message digest (a variant of SHA-2) of the string as a hex string. More...
string | toSHA512 ()
| Returns the SHA-512 message digest (a variant of SHA-2) of the string as a hex string. More...
int | typeCode ()
| Returns Qore::NT_STRING. More...
string | unaccent ()
| Returns a string with all accented characters removed. More...
string | upr ()
| Returns the string in upper case. More...
bool | val ()
| Returns False if the string is empty, True if not. More...
int | width ()
| Returns the width of characters in the string; some unicode characters take up multiple spaces on output. More...
Public Member Functions inherited from <value>
bool | callp ()
| Returns False; this method is reimplemented in other types and will return True if the given expression is a callable value (ie closures or call references) More...
bool | complexType ()
| returns True if the value has a complex type, False if not More...
bool | empty ()
| Returns True; this method will be reimplemented in container types where it may return False. More...
string | fullType (*bool with_namespaces)
| returns the full type name which differs from the simple type name in case of complex types and objects More...
bool | intp ()
| Returns False; this method is reimplemented in other types and will return True if the given expression can be converted to an integer. More...
AbstractIterator | iterator ()
| Returns an iterator object for the value; the default iterator object returned is SingleValueIterator. More...
int | lsize ()
| Returns 1; the return value of this method should give the list size of the value, which is normally 1 for non-lists (except for NOTHING where the size will be 0) and the number of the elements in the list for lists; this method will be reimplemented in other types where it may return other values. More...
int | size ()
| Returns zero; this method will be reimplemented in container types where it may return a non-zero value. More...
bool | sizep ()
| Returns True if the type can return a non-zero size (True for containers including binary objects and strings, False for everything else) More...
bool | strp ()
| Returns False; this method is reimplemented in other types and will return True if the given expression can be converted to a string. More...
bool | toBool ()
| Returns the boolean representation of the value; the default is False. More...
float | toFloat ()
| Returns the floating-point representation of the value; the default is 0.0. More...
int | toInt ()
| Returns the integer representation of the value; the default is 0. More...
number | toNumber ()
| Returns the arbitrary-precision numeric representation of the value; the default is 0. More...
string | toString ()
| Returns the string representation of the value; the default is an empty string. More...
string | type ()
| Returns the string type for the value. More...
int | typeCode ()
| Returns the type code for the value. More...
bool | val ()
| Returns False; this method is reimplemented in other types and will return True if the given expression has a non-empty value. More...

## Detailed Description

Methods in this pseudo-class can be executed on strings.

## Member Function Documentation

## comparePartial()

int <string>::comparePartial | ( | string | ostr | ) |

Compares the beginning of the current string with a shorter string passed as an argument, returns -1, 0, or 1 if the argument string is less than, equal, or greater than the beginning of the current string; returns also -1 if the argument string is equal to the beginning of the current string but the argument string is longer than the current string.

Code Flags:
  RET_VALUE_ONLY

Example:
  int i = str.comparePartial(ostr);

Parameters

  ostr | the partial string to compare the current string to

Returns
  -1, 0, or 1 if the argument string is less than, equal, or greater than the beginning of the current string; returns also -1 if the argument string is equal to the beginning of the current string but the argument string is longer than the current string

Since
  Qore 0.8.8

## empty()

bool <string>::empty | ( |  | ) |

Returns True if the string is empty, False if not.

The opposite of <string>::val()

Returns
  True if the string is empty, False if not

Code Flags:
  CONSTANT

Example:
  bool b = str.empty();

## encoding()

string <string>::encoding | ( |  | ) |

Returns the name of the string's character encoding.

Returns
  the name of the string's character encoding

Code Flags:
  CONSTANT

Example:
  string enc = str.encoding();

Note
  equivalent to Qore::get_encoding(string)

## equalPartial()

bool <string>::equalPartial | ( | string | ostr | ) |

Compares the beginning of the current string with a shorter string passed as an argument for equality only, returns True if the string argument matches the beginning of the string, False if not.

Code Flags:
  RET_VALUE_ONLY

Example:
  bool b = str.equalPartial(ostr);

This pseudo-method is slightly faster than comparePartial() since the length of the substring can be used to determine if the strings can match or not.

Parameters

  ostr | the partial string to compare the current string to

Returns
  True if the string argument matches the beginning of the string, False if not

Since
  Qore 0.8.8

## equalPartialPath()

bool <string>::equalPartialPath | ( | string | ostr | ) |

Compares the beginning of the current string assumed to be a path with a shorter string passed as an argument for equality only, returns True if the string argument matches the beginning of the 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.

Code Flags:
  RET_VALUE_ONLY

Example:
  bool b = str.equalPartialPath(ostr);

Parameters

  ostr | the partial string to compare the current string to

Returns
  True if the string argument matches the beginning of the 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

## find()

int <string>::find | ( | softstring | substr,
|  | softint | pos = `0`
| ) |  |

Retrieves the character position of a substring within a string.

The pos argument and the return value are in character positions; byte offsets may differ from the character offsets with multi-byte character encodings.

Code Flags:
  RET_VALUE_ONLY

Parameters

  substr | the substring to find in the string; if the character encoding of this string does not match str, then it will be converted to str's character encoding before processing
  pos | the starting character position for the search

Returns
  the character position of a substring within a string, -1 is returned if the substring is not found

Example:
  int i = str.find(substr);
  if (i == -1)
  printf("could not find %y in %y\n", substr, str);

Exceptions

  ENCODING-CONVERSION-ERROR | this exception could be thrown if the string arguments have different character encodings and an error occurs during encoding conversion
  INVALID-ENCODING | this exception could be thrown if a character offset calculation fails due to invalid encoding of multi-byte character data

Note
  equivalent to Qore::index(softstring, softstring, softint)

See also
  - <string>::rfind(softstring, softint)
  - rindex(softstring, softstring, softint)
  - bindex(softstring, softstring, softint)
  - brindex(softstring, softstring, softint)

## getDecoded()

string <string>::getDecoded | ( | int | code = `CD_ALL` | ) |

returns a string based on the string value, decoded as per the code argument

  string ns = string.getDecoded(CE_XML);

Parameters

  code | a decoding bitfield argument; see String Concatenation Decoding Codes for more information

See also
  <string>::getEncoded()

Since
  Qore 0.8.12

## getEncoded()

string <string>::getEncoded | ( | int | code = `CE_XHTML` | ) |

returns a string based on the string value with encodings as per the code argument

  string ns = string.getEncoded(CE_XML);

Parameters

  code | an encoding bitfield argument; see String Concatenation Encoding Codes for more information

See also
  <string>::getDecoded()

Since
  Qore 0.8.12

## getLine()

*string <string>::getLine | ( | int | offset = `0`,
|  | *string | eol,
|  | bool | trim = `True`,
|  | *reference< int > | size
| ) |  |

returns a string for the next line in the string buffer starting at the given offset (or at the beginning if no offset is given)

Code Flags:
  CONSTANT

Example:
  *string line = string.getLine(pos);

Parameters

  offset | the offset in bytes from the beginning of the string; negative numbers give an offset from the end of the string

  eol

  the optional end of line character(s) to use to detect lines in the buffer; if this string is not passed, then the end of line character(s) are detected automatically, and can be either `"\n"`, `"\r"`, or `"\r\n"`; if this string is passed and has a different character encoding from this object's (as determined by the `encoding` parameter), then it will be converted to the string's character encoding

  trim | if True the string return values for the lines iterated will be trimmed of the eol bytes
  size | an optional reference to an integer that returns the number of bytes in the line including the end of line characters

Returns
  the line found or NOTHING if no end of line character(s) were found or no data was found after the offset

Since
  Qore 0.8.9

## getUnicode()

int <string>::getUnicode | ( | int | offset = `0` | ) |

returns the Unicode code for the given character offset in the string

Code Flags:
  RET_VALUE_ONLY

Example:
  int uc = str.getUnicode(0);

Parameters

  offset | the offset in characters in the string; negative numbers give offsets from the end of the string

Returns
  the Unicode code for the given character offset in the string

Since
  Qore 0.8.8

## intp()

bool <string>::intp | ( |  | ) |

Returns True if the string can be converted to an integer, False if not, this depends on the first (or possibly second) character of the string, if it's 0 - 9 (possibly preceded by `"-"`), then the method returns True.

Returns
  True if the string can be converted to an integer, False if not, this depends on the first (or possibly second) character of the string, if it's 0 - 9 (possibly preceded by `"-"`), then the method returns True

Code Flags:
  CONSTANT

Example:
  if (n.intp())
  printf("%y: can be converted to an integer: %d\n", n, int(n));

## isDataAscii()

bool <string>::isDataAscii | ( |  | ) |

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

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

Code Flags:
  CONSTANT

Example:
  bool b = str.isDataAscii();

Since
  Qore 0.8.6

## isDataPrintableAscii()

bool <string>::isDataPrintableAscii | ( |  | ) |

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

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

Code Flags:
  CONSTANT

Example:
  bool b = str.isDataPrintableAscii();

Since
  Qore 0.8.6

## length()

int <string>::length | ( |  | ) |

Returns the number of characters in the string; may not be equal to the byte length (returned by <string>::strlen() and <string>::size()) for multi-byte character encodings.

Returns
  the number of characters in the string; may not be equal to the byte length (returned by <string>::strlen() and <string>::size()) for multi-byte character encodings

Code Flags:
  CONSTANT

Example:
  int len = str.length();

Note
  - this operation has O(n) complexity if the string has a multi-byte character encoding, otherwise it is O(1)
  - equivalent to Qore::length(softstring)

See also
  - <string>::strlen()
  - <string>::size()
  - <string>::width()

## lwr()

string <string>::lwr | ( |  | ) |

Returns the string in lower case.

Code Flags:
  CONSTANT

Example:
  printf("%y", "PŘÍLIŠ ŽLUŤOUČKÝ KŮŇ ÚPĚL ĎÁBELSKÉ ÓDY".lwr());
  # outputs: "příliš žluťoučký kůň úpěl ďábelské ódy"

This pseudo-method operates on a very wide range of non-ASCII characters using a Unicode lookup table for mapping Latin, Cyrillic, Greek, Armenian, Georgian, etc characters.

Returns
  the string in lower case

Note
  - equivalent to Qore::tolower(string)

See also
  - <string>::upr()
  - tolower()
  - toupper()

Since
  Qore 0.8.8 this pseudo-method operates on a wide range of characters and is no longer limited to ASCII characters

## regex()

bool <string>::regex | ( | string | regex,
|  | int | options = `0`
| ) |  |

Returns True if the regular expression matches the string passed, otherwise returns False.

Strings are converted to UTF-8 for pattern-matching; if any invalid encodings are encountered, an `ENCODING-CONVERSION-ERROR` is raised

Code Flags:
  RET_VALUE_ONLY

Parameters

  regex | the regular expression pattern
  options | regular expression options; see Regular Expression Constants for possible values

Returns
  True if the regular expression matches the string passed, otherwise returns False

Example:
  bool b = "hello".regex("^hel"); # returns True

Exceptions

  REGEX-COMPILATION-ERROR | There was an error compiling the regular expression
  REGEX-OPTION-ERROR | the option argument contains invalid option bits
  ENCODING-CONVERSION-ERROR | this exception could be thrown if an encoding error is encountered when converting the given strings to UTF-8

Note
  equivalent to Qore::regex(string, string, int)

See also
  Regular Expressions for more information about regular expression support in Qore

Since
  Qore 0.8.5

## regexExtract()

*list<*string> <string>::regexExtract | ( | string | regex,
|  | int | options = `0`
| ) |  |

Returns a list of substrings in a string based on matching patterns defined by a regular expression.

Strings are converted to UTF-8 for pattern-matching; if any invalid encodings are encountered, an `ENCODING-CONVERSION-ERROR` is raised

Code Flags:
  RET_VALUE_ONLY

Parameters

  regex | the regular expression to use for matching, elements should be given in parentheses
  options | regular expression options; see Regular Expression Constants for possible values

Returns
  a list of substrings in a string based on matching patterns defined by a regular expression or NOTHING if no match was made

Example:
  string str = "ns:element";
  *list<*string> rv = str.regexExtract("(\\w+):(\\w+)");

Exceptions

  REGEX-COMPILATION-ERROR | There was an error compiling the regular expression
  REGEX-OPTION-ERROR | the option argument contains invalid option bits
  ENCODING-CONVERSION-ERROR | this exception could be thrown if an encoding error is encountered when converting the given strings to UTF-8

Note
  equivalent Qore::regex_extract(string, string, int)

See also
  Regular Expressions for more information about regular expression support in Qore

Since
  Qore 0.8.5
  Qore 0.8.8 this function accepts the Qore::RE_Global option to extract all occurrences of the pattern(s) in a string

## rfind()

int <string>::rfind | ( | softstring | substr,
|  | softint | pos = `-1`
| ) |  |

Retrieves the character position of a substring within a string, starting the search from the end of the string.

The pos argument and the return value are in character positions; byte offsets may differ from the character offsets with multi-byte character encodings.

Code Flags:
  RET_VALUE_ONLY

Parameters

  substr | the substring to find in str; if the character encoding of this string does not match str, then it will be converted to str's character encoding before processing
  pos | the starting character position for the search, -1 means start from the end of the string

Returns
  the character position of a substring within a string, -1 is returned if the substring is not found

Example:
  int i = str.rfind(substr);
  if (i == -1)
  printf("could not find %y in %y\n", substr, str);

Exceptions

  ENCODING-CONVERSION-ERROR | this exception could be thrown if the string arguments have different character encodings and an error occurs during encoding conversion
  INVALID-ENCODING | this exception could be thrown if a character offset calculation fails due to invalid encoding of multi-byte character data

Note
  equivalent to Qore::rindex(softstring, softstring, softint)

See also
  - <string>::find(softstring, softint)
  - index(softstring, softstring, softint)
  - bindex(softstring, softstring, softint)
  - brindex(softstring, softstring, softint)

## size()

int <string>::size | ( |  | ) |

Returns the number of bytes in the string (not including the terminating null character (`'\0'`)

Returns
  the number of bytes in the string (not including the terminating null character (`'\0'`)

Code Flags:
  CONSTANT

Example:
  int len = str.size();

Note
  - this operation is always executed in constant time (ie O(1)) because the string's byte length is always stored with the string
  - equivalent to <string>::strlen() and Qore::strlen(softstring)

See also
  - <string>::sizep()
  - <string>::length()
  - <string>::width()

## sizep()

bool <string>::sizep | ( |  | ) |

Returns True since strings can return a non-zero size.

Code Flags:
  CONSTANT

Returns
  True since strings can return a non-zero size

See also
  <string>::size()

Since
  Qore 0.8.9

## split() [1/2]

list<string> <string>::split | ( | string | sep,
|  | bool | with_separator = `False`
| ) |  |

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

Code Flags:
  RET_VALUE_ONLY

Parameters

  sep | the separator string; if the separator string is not found in the string to split, then a list with only one element containing the entire string argument is returned'; if this string has a different character encoding than str, then it will be converted to str's character encoding
  with_separator | include the separator string in every element

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

Example:
  string str = "some:text:here";
  list<string> list = str.split(":"); # returns ("some", "text", "here")

Exceptions

  ENCODING-CONVERSION-ERROR | this exception could be thrown if the string arguments have different character encodings and an error occurs during encoding conversion

Note
  equivalent to Qore::split(string, string, bool)

Since
  Qore 0.8.5

## split() [2/2]

list<string> <string>::split | ( | string | sep,
|  | string | quote,
|  | bool | trim_unquoted = `False`
| ) |  |

Splits a string into a list of components based on a separator string and a quote character.

The quote character can appear as the first part of a field, in which case it is assumed to designate the entire field. If instances of the quote character are found in the field preceded by a backquote character (`"\"`), then these quote characters are included as part of the field's text and not treated as quote characters. Also the separator character can appear as a part of a field with this variant. This variant is useful for parsing CSV files, for example.

Code Flags:
  RET_VALUE_ONLY

Parameters

  sep | the separator string; if the separator string is not found in the string to split, then a list with only one element containing the entire string argument is returned'; if this string has a different character encoding than str, then it will be converted to str's character encoding
  quote | the quote character
  trim_unquoted | remove leading and trailing whitespace from unquoted fields

Returns
  a list of each component of a string separated by a separator string, with the separator and any enclosing quote characters removed

Example:
  list<string> list = "some,'text with spaces, and commas, here is another one! ,',here".split(",", "'"); # returns ("some", ", and commas, here is another one! ,", "here")

Exceptions

  ENCODING-CONVERSION-ERROR | this exception could be thrown if the string arguments have different character encodings and an error occurs during encoding conversion return split_with_quote(xsink, sep, str, quote, trim_unquoted);
  SPLIT-ERROR | field missing closing quote character; extra text following quoted field

Note
  equivalent to Qore::split(string, string, string, bool)

Since
  - Qore 0.8.5 added this pseudo-method
  - Qore 0.8.6 added the `trim_unquoted` parameter

## splitRegex() [1/2]

list<string> <string>::splitRegex | ( | string | regex_sep,
|  | int | options = `0`,
|  | bool | with_separator = `False`
| ) |  |

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

Code Flags:
  RET_VALUE_ONLY

Example:
  string str = "some\\:text:here";
  list<string> list = str.splitRegex("(?<!\\\\)\\:"); # returns ("some\\:text", "here")

Parameters

  regex_sep | the separator regular expression; if the separator regular expression is not matched in the string to split, then a list with only one element containing the entire string argument is returned'; if this string has a different character encoding than str, then it will be converted to str's character encoding
  options | regular expression options; see Regular Expression Constants for possible values
  with_separator | include the separator string in every element

Returns
  a list of each component of a string separated by a separator regular expression, with the separator removed; the separator pattern will not be included in the elements of the list returned unless the with_separator argument is True; the strings in the return value are always returned in UTF-8 encoding

Exceptions

  ENCODING-CONVERSION-ERROR | this exception could be thrown if the string arguments have different character encodings and an error occurs during encoding conversion

Since
  Qore 1.0.7

## splitRegex() [2/2]

list<string> <string>::splitRegex | ( | string | regex_sep,
|  | bool | with_separator = `False`
| ) |  |

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

Code Flags:
  RET_VALUE_ONLY

Example:
  string str = "some\\:text:here";
  list<string> list = str.splitRegex("(?<!\\\\)\\:"); # returns ("some\\:text", "here")

Parameters

  regex_sep | the separator regular expression; if the separator regular expression is not matched in the string to split, then a list with only one element containing the entire string argument is returned'; if this string has a different character encoding than str, then it will be converted to str's character encoding
  with_separator | include the separator string in every element

Returns
  a list of each component of a string separated by a separator regular expression, with the separator removed; the separator pattern will not be included in the elements of the list returned unless the with_separator argument is True; the strings in the return value are always returned in UTF-8 encoding

Exceptions

  ENCODING-CONVERSION-ERROR | this exception could be thrown if the string arguments have different character encodings and an error occurs during encoding conversion

Since
  Qore 1.0.7

## strlen()

int <string>::strlen | ( |  | ) |

Returns the number of bytes in the string (not including the terminating null character (`'\0'`)

Returns
  the number of bytes in the string (not including the terminating null character (`'\0'`)

Code Flags:
  CONSTANT

Example:
  int len = str.strlen();

Note
  - this operation is always executed in constant time (ie O(1)) because the string's byte length is always stored with the string
  - equivalent to <string>::size() and Qore::strlen(softstring)

See also
  - <string>::size()
  - <string>::length()
  - <string>::width()

## strp()

bool <string>::strp | ( |  | ) |

Returns True by default.

Returns
  True by default

Code Flags:
  CONSTANT

Example:
  if (n.strp())
  printf("%y: can be converted to a string: '%s'\n", n, string(n));

## substr() [1/2]

string <string>::substr | ( | softint | start | ) |

Returns a portion of a string starting from an integer offset.

Arguments can be negative, giving offsets from the end of the string. All offsets are character positions, not byte positions.

Code Flags:
  RET_VALUE_ONLY

Parameters

  start | The starting character for the substring where the first character is at offset 0; if the offset is negative, it designates the number of characters from the end of the string. If the offset is 0, then the entire string is returned.

Returns
  the substring of the string starting from an integer character offset; the rest of the string is returned after this offset; an emtpy string is returned if the argument cannot be satisfied

Example:
  # get the last 10 characters of a string
  string substr = str.substr(-10);

Exceptions

  INVALID-ENCODING | this exception could be thrown if a character offset calculation fails due to invalid encoding of multi-byte character data

Note
  equivalent to Qore::substr(softstring, softint)

## substr() [2/2]

string <string>::substr | ( | softint | start,
|  | softint | len
| ) |  |

Returns a portion of a string starting from an integer offset, with a length parameter.

Arguments can be negative, giving offsets from the end of the string. All offsets are character positions, not byte positions.

Code Flags:
  RET_VALUE_ONLY

Parameters

  start | The starting character for the substring where the first character is at offset 0; if the offset is negative, it designates the number of characters from the end of the string
  len | The maximum number of characters to copy; if this value is negative, the rest of the string from start will be copied to the substring, except without - len characters from the end of the string

Returns
  the substring of the string according to the arguments passed; an emtpy string is returned if the argument cannot be satisfied

Example:
  # get a substring 10 characters into the string except omitting the last 2 characters of the string
  string substr = str.substr(10, -2);

Exceptions

  INVALID-ENCODING | this exception could be thrown if a character offset calculation fails due to invalid encoding of multi-byte character data

Note
  equivalent to Qore::substr(softstring, softint, softint)

Since
  Qore 0.8.5

## toBase64()

string <string>::toBase64 | ( | softint | maxlinelen = `-1` | ) |

Returns the base64-encoded representation of the string.

Code Flags:
  CONSTANT

Example:
  string base64 = str.toBase64(64);

Implementation based on RFC-1421 and RFC-2045

Parameters

  maxlinelen | the maximum length of a line in the resulting output string in bytes; if this value is > 0 then output lines will be separated by CRLF characters

Returns
  the base64-encoded string of the data passed

Since
  Qore 0.8.8

See also
  - <binary>::toBase64()
  - make_base64_string(string, softint)

## toBinary()

binary <string>::toBinary | ( |  | ) |

Returns a binary value with the string's data.

Code Flags:
  CONSTANT

Example:
  binary bin = str.toBinary();

Returns
  a binary value with the string's data

See also
  Qore::binary(softstring) "binary(softstring)"

Since
  Qore 0.9.3

## toHex()

string <string>::toHex | ( |  | ) |

returns a string of hexadecimal digits corresponding to the contents of the string

Code Flags:
  CONSTANT

Example:
  string str = str.toHex();

Returns
  a string of hexadecimal digits corresponding to the contents of the string

Since
  Qore 0.8.8

See also
  - <binary>::toHex()
  - make_hex_string(string)

## toInt()

int <string>::toInt | ( | int | base = `10` | ) |

Converts the string to an integer value with respect to the base.

If a character is out of range of the corresponding base only the substring preceeding the character is taken into account.
Base 0 means to interpret as a code literal, so that the actual base is 8, 10, or 16.
(Does the same as Qore::int(string str, int base)).

Code Flags:
  RET_VALUE_ONLY

Parameters

  base | the base of the integer in the string; this value must be 0 or 2 - 36 inclusive or an `INVALID-BASE` exception will be thrown

Returns
  the integer value corresponding to the arguments

Example:
  "fe".toInt(16); // returns 254
  "34".toInt(5); // returns 19
  "2p".toInt(25); // returns 2 (p means 25, which is out of range)
  "2p".toInt(26); // returns 77
  "2z".toInt(36); // returns 107
  "21".toInt(); // returns 21 (base = 10)
  "21".toInt(0); // returns 21 (base = 10)
  "021".toInt(0); // returns 17 (base = 8)
  "0x21".toInt(0); // returns 33 (base = 16)

Exceptions

  INVALID-BASE | the base is invalid; must be 0 or 2 - 36 inclusive
  UNSUPPORTED-ENCODING | only ASCII-compatible encodings are currently supported

See also
  <value>::toInt()
  Qore::int(string str, int base = 10)

Since
  Qore 0.8.13; in previous versions the <value>::toInt() function (without the base argument) applied also to strings

## toMD5()

string <string>::toMD5 | ( |  | ) |

Returns the MD5 message digest of the string as a hex string.

The trailing null character is not included in the digest returned.

Returns
  a hex string of the digest (ex: `"5d41402abc4b2a76b9719d911017c592"`)

Code Flags:
  RET_VALUE_ONLY

Example:
  string str = "hello".toMD5(); # returns "5d41402abc4b2a76b9719d911017c592"

Exceptions

  MD5-DIGEST-ERROR | error calculating digest (should not normally happen)

Note
  - equivalent to Qore::MD5()
  - the MD5 algorithm is not collision-resistant; it's recommended to use another hash algorithm (like SHA-256) if cryptographic security is important

See also
  - MD5_bin()
  - <binary>::toMD5()

Since
  Qore 0.8.5

## toSHA1()

string <string>::toSHA1 | ( |  | ) |

Returns the SHA1 message digest of the string as a hex string.

The trailing null character is not included in the digest returned.

Returns
  a hex string of the digest (ex: `"aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"`)

Code Flags:
  RET_VALUE_ONLY

Example:
  string str = "hello".toSHA1(); # returns "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"

Exceptions

  SHA1-DIGEST-ERROR | error calculating digest (should not normally happen)

Note
  equivalent to Qore::SHA1()

See also
  - SHA1_bin()
  - <binary>::toSHA1()

Since
  Qore 0.8.5

## toSHA224()

string <string>::toSHA224 | ( |  | ) |

Returns the SHA-224 message digest (a variant of SHA-2) of the string as a hex string.

The trailing null character is not included in the digest returned.

Platform Availability:
  Qore::Option::HAVE_SHA224

Code Flags:
  RET_VALUE_ONLY

Returns
  a hex string of the digest (ex: `"ea09ae9cc6768c50fcee903ed054556e5bfc8347907f12598aa24193"`)

Example:
  string str = "hello".toSHA224("hello"); # returns "ea09ae9cc6768c50fcee903ed054556e5bfc8347907f12598aa24193"

Exceptions

  SHA224-DIGEST-ERROR | error calculating digest (should not normally happen)

Note
  equivalent to Qore::SHA224()

See also
  - SHA224_bin()
  - <binary>::toSHA224()

Since
  Qore 0.8.5

## toSHA256()

string <string>::toSHA256 | ( |  | ) |

Returns the SHA-256 message digest (a variant of SHA-2) of the string as a hex string.

The trailing null character is not included in the digest returned.

Platform Availability:
  Qore::Option::HAVE_SHA256

Code Flags:
  RET_VALUE_ONLY

Returns
  a hex string of the digest (ex: `"2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"`)

Example:
  string str = "hello".toSHA256(); # returns "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

Exceptions

  SHA256-DIGEST-ERROR | error calculating digest (should not normally happen)

Note
  equivalent to Qore::SHA256()

See also
  - SHA256_bin()
  - <binary>::toSHA256()

Since
  Qore 0.8.5

## toSHA384()

string <string>::toSHA384 | ( |  | ) |

Returns the SHA-384 message digest (a variant of SHA-2) of the string as a hex string.

The trailing null character is not included in the digest returned.

Platform Availability:
  Qore::Option::HAVE_SHA384

Code Flags:
  RET_VALUE_ONLY

Returns
  a hex string of the digest (ex: `"59e1748777448c69de6b800d7a33bbfb9ff1b463e44354c3553bcdb9c666fa90125a3c79f90397bdf5f6a13de828684f"`)

Example:
  string str = "hello".toSHA384(); # returns "59e1748777448c69de6b800d7a33bbfb9ff1b463e44354c3553bcdb9c666fa90125a3c79f90397bdf5f6a13de828684f"

Exceptions

  SHA384-DIGEST-ERROR | error calculating digest (should not normally happen)

Note
  equivalent to Qore::SHA384()

See also
  - SHA384_bin()
  - <binary>::toSHA224()

Since
  Qore 0.8.5

## toSHA512()

string <string>::toSHA512 | ( |  | ) |

Returns the SHA-512 message digest (a variant of SHA-2) of the string as a hex string.

The trailing null character is not included in the digest returned.

Platform Availability:
  Qore::Option::HAVE_SHA512

Code Flags:
  RET_VALUE_ONLY

Returns
  a hex string of the digest (ex: `"9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043"`)

Example:
  string str = "hello".toSHA512(); # returns "9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043"

Exceptions

  SHA512-DIGEST-ERROR | error calculating digest (should not normally happen)

Note
  equivalent to Qore::SHA512()

See also
  - SHA512_bin()
  - <binary>::toSHA512()

Since
  Qore 0.8.5

## typeCode()

int <string>::typeCode | ( |  | ) |

Returns Qore::NT_STRING.

Returns
  Qore::NT_STRING

Code Flags:
  CONSTANT

Example:
  switch (str.typeCode()) {
  case NT_STRING:
  printf("%y: is a string\n", str);
  break;
  }

## unaccent()

string <string>::unaccent | ( |  | ) |

Returns a string with all accented characters removed.

Code Flags:
  RET_VALUE_ONLY

Example:
  string s = "příliš žluťoučký kůň úpěl ďábelské ódy";
  printf("%y\n", s.unaccent()); # result: "prilis zlutoucky kun upel dabelske ody"

The returned string has the same encoding as the original input.

Returns
  the string with accents replaced

Since
  Qore 0.8.8

## upr()

string <string>::upr | ( |  | ) |

Returns the string in upper case.

Code Flags:
  CONSTANT

Example:
  printf("%y", "příliš žluťoučký kůň úpěl ďábelské ódy".upr());
  # outputs: "PŘÍLIŠ ŽLUŤOUČKÝ KŮŇ ÚPĚL ĎÁBELSKÉ ÓDY"

This pseudo-method operates on a very wide range of non-ASCII characters using a Unicode lookup table for mapping Latin, Cyrillic, Greek, Armenian, Georgian, etc characters.

Returns
  the string in upper case

Note
  - equivalent to Qore::toupper(string)

See also
  - <string>::lwr()
  - tolower()
  - toupper()

Since
  Qore 0.8.8 this pseudo-method operates on a wide range of characters and is no longer limited to ASCII characters

## val()

bool <string>::val | ( |  | ) |

Returns False if the string is empty, True if not.

Returns
  False if the string is empty, True if not

Code Flags:
  CONSTANT

Example:
  bool b = str.val();

## width()

int <string>::width | ( |  | ) |

Returns the width of characters in the string; some unicode characters take up multiple spaces on output.

Returns
  the width of characters in the string; some unicode characters take up multiple spaces on output; for example the string "ステップの例" is made up of 6 double-wide characters, so the width is 12, while the length in characters is 6, and the size (string byte length) is 18

Code Flags:
  RET_VALUE_ONLY

Example:
  int width = str.width();

Note
  - this operation has O(n) complexity if the string has a multi-byte character encoding, otherwise it is O(1)
  - equivalent to Qore::char_width(softstring)

See also
  - <string>::length()
  - <string>::strlen()
  - <string>::size()

Since
  Qore 0.9.4