| Qore Programming Language Reference Manual 1.0.8

Functions
String Functions

## Functions
int | Qore::bindex (softstring str, softstring substr, softint pos=0)
| Retrieves the byte position of a substring within a string. More...
int | Qore::bindex ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
int | Qore::brindex (softstring str, softstring substr, softint pos=-1)
| Retrieves the byte position of a substring within a string, starting the search from the end of the string. More...
int | Qore::brindex ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
int | Qore::char_width (softstring str)
| Returns the width of characters in the string; some unicode characters take up multiple spaces on output. More...
string | Qore::chomp (string str)
| Removes the trailing end-of-line indicator (`"\n"` or `"\r\n"`) from a string and returns the new string (also see the chomp operator) More...
*string | Qore::chomp (reference< string > str)
| Removes the trailing end-of-line indicator (`"\n"` or `"\r\n"`) from a reference to a string and returns the new string (also see the chomp operator) More...
nothing | Qore::chomp ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::chr (softint val, *string encoding)
| Returns a string containing a single ASCII character represented by the numeric value passed. More...
string | Qore::chr (auto arg)
| This function variant returns a string with a single ASCII NULL ('\0'); it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
nothing | Qore::chr ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::convert_encoding (string str, string encoding)
| Performs explicit string character encoding conversions. More...
nothing | Qore::convert_encoding ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::f_printf (string fmt,...)
| Outputs the string passed to standard output, using the first argument as a format string; enforces field widths on arguments larger than the given field width. More...
string | Qore::f_printf ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::f_sprintf (string fmt,...)
| Returns a formatted string based on a format string and other arguments; enforces field widths on arguments larger than the given field width. More...
string | Qore::f_sprintf ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::f_vprintf (string fmt, auto varg)
| Outputs the string passed to standard output, using the first argument as a format string and a second argument giving a list or a single argument to the format string; enforces field widths on arguments larger than the given field width. More...
string | Qore::f_vsprintf (string fmt, auto varg)
| Returns a formatted string based on a format string and other arguments given as a list after the format string; enforces field widths on arguments larger than the given field width. More...
nothing | Qore::flush ()
| Flushes output to the console output with print(), printf(), etc. More...
string | Qore::force_encoding (string str, string encoding)
| Returns the first string argument tagged with the character encoding given as the second argument; does not actually change the string data. More...
nothing | Qore::force_encoding ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::format_number (string fmt, softfloat num)
| Returns a string of a formatted number according to a number argument and a format string. More...
nothing | Qore::format_number ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::get_encoding (string str)
| Returns a string describing the character encoding of the string argument passed. More...
nothing | Qore::get_encoding ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
int | Qore::index (softstring str, softstring substr, softint pos=0)
| Retrieves the character position of a substring within a string. More...
int | Qore::index ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::join (string str,...)
| Creates a string from separator string and a list of arguments. More...
string | Qore::join (string str, list< auto > l)
| Creates a string from separator string and a list of arguments. More...
nothing | Qore::join ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
int | Qore::length (softstring str)
| Returns the length in characters for the string passed. More...
int | Qore::length (binary bin)
| Returns the number of bytes in the binary object passed as an argument. More...
nothing | Qore::length ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
int | Qore::length (auto arg)
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::ltrim (string str, *string chars)
| Removes byte characters from the start of a string and returns the new string. More...
*string | Qore::ltrim (reference< string > str, *string chars)
| Removes byte characters from the start of a reference to an lvalue containing a string and returns string after processing. More...
int | Qore::ord (softstring str, softint offset=0)
| Gives the positive numeric value of the given byte in the string passed; if no string is passed or the offset is after the end of the string, -1 is returned. More...
int | Qore::ord ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
bool | Qore::parse_boolean (string str)
| tries to parse a string value as a boolean More...
bool | Qore::parse_boolean (any val)
| returns the first value passed as a boolean More...
float | Qore::parse_float (string str, string fmt)
| returns a floating-point value corresponding to a string representing the number and an argument giving the format More...
int | Qore::parse_int (string str, string fmt)
| returns an integer corresponding to a string representing the number and an argument giving the format More...
number | Qore::parse_number (string str, string fmt)
| returns a number corresponding to the string and the argument, giving the format More...
nothing | Qore::print (...)
| Outputs a string to standard output with no formatting. More...
string | Qore::printf (string fmt,...)
| Outputs the string passed to standard output, using the first argument as a format string; does not enforce field widths on arguments larger than the given field width. More...
string | Qore::printf ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
bool | Qore::regex (string str, string regex, int options=0)
| Returns True if the regular expression matches the string passed, otherwise returns False. More...
nothing | Qore::regex ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
*list< *string > | Qore::regex_extract (string str, string regex, int options=0)
| Returns a list of substrings in a string based on matching patterns defined by a regular expression. More...
nothing | Qore::regex_extract ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::regex_subst (string str, string regex, string subst, int options=0)
| Returns a string with patterns substituted according to the arguments passed. More...
nothing | Qore::regex_subst ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::replace (string str, string source, string target, int start=0, int end=-1)
| Replaces all occurrences of a substring in a string with another string. More...
nothing | Qore::replace ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::reverse (softstring str)
| Reverses a string and returns the new string. More...
int | Qore::rindex (softstring str, 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 | Qore::rindex ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::rtrim (string str, *string chars)
| Removes byte characters from the end of a string and returns the new string. More...
*string | Qore::rtrim (reference< string > str, *string chars)
| Removes byte characters from the end of a reference to an lvalue containing a string and returns string after processing. More...
list< string > | Qore::split (string sep, string str, bool with_separator=False)
| Splits a string into a list of components based on a separator string. More...
list< string > | Qore::split (string sep, string str, 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< binary > | Qore::split (data sep, binary data)
| Returns a list of binary objects representing each component of the binary object separated by the bytes identified by the separator argument, with the separator removed. More...
list< string > | Qore::split ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::sprintf (string fmt,...)
| Returns a formatted string based on a format string and other arguments; does not enforce field widths on arguments larger than the given field width. More...
string | Qore::sprintf ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
int | Qore::strlen (softstring str)
| Returns the length in bytes of the string argument. More...
nothing | Qore::strlen ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
int | Qore::strlen (auto arg)
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::strmul (softstring str, softint smul, *softint offset)
| Returns a new string with a repeated string element and optionally removing trailing characters. More...
string | Qore::substr (softstring str, softint start)
| Returns a portion of a string starting from an integer offset. More...
string | Qore::substr (softstring str, softint start, softint len)
| Returns a portion of a string starting from an integer offset, with a length parameter. More...
binary | Qore::substr (binary b, softint start)
| Returns a portion of a binary object starting from an integer offset. More...
binary | Qore::substr (binary b, softint start, softint len)
| Returns a portion of a binary object starting from an integer offset, with a length parameter. More...
nothing | Qore::substr ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::tolower (string str)
| Returns a string in all lower-case characters based on the argument passed. More...
nothing | Qore::tolower ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::toupper (string str)
| Returns a string in all upper-case characters based on the argument passed. More...
nothing | Qore::toupper ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::trim (string str, *string chars)
| Removes byte characters from the start and end of a string and returns the new string (also see the trim operator) More...
*string | Qore::trim (reference< string > str, *string chars)
| Removes byte characters from the start and end of a reference to an lvalue containing a string and returns string after processing (also see the trim operator) More...
nothing | Qore::trim ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::trunc_str (softstring str, softint len, *string encoding)
| Returns a truncated string with no more than the given number of bytes and optionally converted to a specific character encoding. More...
string | Qore::vprintf (string fmt, auto varg)
| Outputs the string passed to standard output, using the first argument as a format string and a second argument giving a list or a single argument to the format string; does not enforce field widths on arguments larger than the given field width. More...
string | Qore::vprintf ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
string | Qore::vsprintf (string fmt, auto varg)
| Returns a formatted string based on a format string and other arguments given as a list after the format string; does not enforce field widths on arguments larger than the given field width. More...
string | Qore::vsprintf ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...

## Detailed Description

# String Formatting

String formatting in Qore is based on c-style "printf" string formatting.

There are three types of objects in the format string:

- Plain characters, which are copied as-is to the output string
- Escape characters, which are converted and copied to the output string
- Format specifications for arguments to be included in the output string, which are preceded by the percent sign `"%"`

Note
  The percent sign `"%"` always starts a format specification unless it is followed by another `"%"` sign, in this case only one `"%"` is output (ie `"%%"` in the format string is output as a single `"%"`)

## String Format Specification

After the `"%"` sign, there can be zero or more formatting flags as in the following table:

Printf Formatting Flags

Flag | Description
`-` | left-justify the field
`+` | include the sign for the number (+ or -)
`0` | use zero left padding rather than space padding
space | use space padding

Then a field width specifier can optionally be given as a string of digits specifying the length of the field. With "field" functions (function names preceded by `"f_"`), these width specifiers are hard limits; that is; arguments longer than the width specified are truncated to the specified width.

Note
  String fields are padded based on the byte length of characters by default; to do string padding based on character width; use the `"%w"` specifier instead of `"%s"` (ex: `"%10w"`); for "field" functions, if a multi-position character cannot fit in the space left in the field, the field is padded with `"."` characters; ex:
  f_sprintf("%-5w", str) == "ステ."

For floating-point arguments, a precision specifier may be given by including a period "." and another digit string, which indicates the number of digits to appear after the decimal point.

Then the format character is given as follows:

Printf Formatting Characters

Character | Description
`s` | String where field width specify the number of characters regardless of their width
`d` | Integer, output in base 10 format
`o` | Integer, output in base 8 (octal) format
`f` | Literal floating point value
`F` | Literat floating point value
`a` | Hexadecimal floating-point output with lower-case `"0x"` and `"abcdef"`
`A` | Hexadecimal floating-point output with upper-case `"0X"` and `"ABCDEF"`
`g` | Compact floating-point output using a lower-case `"e"` for exponential output when necessary
`G` | Compact floating-point output using an upper-case `"E"` for exponential output when necessary
`n` | Any Qore value, formatted as a string, without any line breaks
`N` | Any Qore value, formatted as a string, with line breaks and whitespace formatting for complex objects
`w` | String where field widths specify actual character widths instead of the number of characters (ex: the character width of `"ス"` is 2)
`x` | Integer, output in base 16 (hexadecimal) format with lower-case a-f
`X` | Integer, output in base 16 (hexadecimal) format with upper-case A-F
`y` | Any Qore value, formatted as a pseudo-YAML string, without any line breaks; this format option is similar to `"%n"`, but uses a YAML-like format. Note that the output is not guaranteed to be parsed by the yaml module's parseYAML() function; it is for display purposes only; to get real YAML functionality, use the yaml module.

String Escape Characters

Escape Characters | Description
`\b` | a backspace character
`\f` | a form-feed character
`\n` | a newline character
`\r` | a carriage-return character
`\t` | a tab character
`\v` | a vertical tab character
`\num` | an 8-bit character whose value is the 1, 2, or 3 digit octal number num
`\"` | a double-quote character (`"`)
`\\` | a backslash character

Warning
  Trying to escape a 3-digit octal number in the range 400-777 will result in a `PARSE-EXCEPTION` being thrown. Trying to parse a number starting with 8 or 9 will result in that number being reproduced literally.
  string abc = "Number: \455"; # will throw a parse error
  string abc = "Number: \820";
  printf(abc); # will print out "Number: 820"

Note
  Trying to escape any other character will result in that character being reproduced literally:
  string abc = "He\llo\, worl\d!";
  printf(abc); # will print out "Hello, world!"

## Function Documentation

## ◆ bindex() [1/2]

int Qore::bindex | ( | softstring | str,
|  | softstring | substr,
|  | softint | pos = `0`
| ) |  |

Retrieves the byte position of a substring within a string.

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

Code Flags:
  CONSTANT

Parameters

  str | the string to search in
  substr | the substring to find in str
  pos | the starting character position for the search

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

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

Note
  no character encoding conversions are made by this function even if the string arguments have different character encodings

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

## ◆ bindex() [2/2]

int Qore::bindex | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ brindex() [1/2]

int Qore::brindex | ( | softstring | str,
|  | softstring | substr,
|  | softint | pos = `-1`
| ) |  |

Retrieves the byte 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 byte positions; byte offsets may differ from the character offsets with multi-byte character encodings.

Code Flags:
  CONSTANT

Parameters

  str | the string to search in
  substr | the substring to find in str
  pos | the starting character position for the search, -1 means start from the end of the string

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

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

Note
  no character encoding conversions are made by this function even if the string arguments have different character encodings

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

## ◆ brindex() [2/2]

int Qore::brindex | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ char_width()

int Qore::char_width | ( | softstring | str | ) |

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 = char_width(str);

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

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

Since
  Qore 0.9.4

## ◆ chomp() [1/3]

string Qore::chomp | ( | string | str | ) |

Removes the trailing end-of-line indicator (`"\n"` or `"\r\n"`) from a string and returns the new string (also see the chomp operator)

If no EOL indicator is present in the string, this function simply returns the original string unmodified.

Code Flags:
  CONSTANT

Parameters

  str | the string to process

Returns
  the new string with any end-of-line character(s) removed

Example:
  string line = chomp("hello\n"); # returns "hello"

See also
  the chomp operator

## ◆ chomp() [2/3]

*string Qore::chomp | ( | reference< string > | str | ) |

Removes the trailing end-of-line indicator (`"\n"` or `"\r\n"`) from a reference to a string and returns the new string (also see the chomp operator)

This variant accepts variable references, in which case it will modify the string in place and also return the modified string

Parameters

  str | a reference to an lvalue continaing the string value to process; if the lvalue does not have a string value NOTHING is returned

Returns
  the string as modified

Example:
  chomp(\str);

## ◆ chomp() [3/3]

nothing Qore::chomp | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ chr() [1/3]

string Qore::chr | ( | softint | val,
|  | *string | encoding
| ) |  |

Returns a string containing a single ASCII character represented by the numeric value passed.

Code Flags:
  CONSTANT

Parameters

  val | the byte value of the character; only the least-significant byte is used
  encoding | the character encoding tag for the string return value; if not present, the default character encoding is assumed

Returns
  a string containing a single ASCII character represented by the numeric value passed

Example:
  string char = chr(13);

Since
  Qore 0.8.5 the encoding argument is supported

## ◆ chr() [2/3]

string Qore::chr | ( | auto | arg | ) |

This function variant returns a string with a single ASCII NULL ('\0'); it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  NOOP

Returns
  a string with a single ASCII NULL ('\0')

## ◆ chr() [3/3]

nothing Qore::chr | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ convert_encoding() [1/2]

string Qore::convert_encoding | ( | string | str,
|  | string | encoding
| ) |  |

Performs explicit string character encoding conversions.

Code Flags:
  RET_VALUE_ONLY

Parameters

  str | the string to convert
  encoding | the encoding for the return value

Returns
  a string corresponding to the string argument converted to the encoding given

Example:
  string enc = convert_encoding(str, "iso-8859-1");

Exceptions

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

## ◆ convert_encoding() [2/2]

nothing Qore::convert_encoding | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ f_printf() [1/2]

string Qore::f_printf | ( | string | fmt,
|  |  | ...
| ) |  |

Outputs the string passed to standard output, using the first argument as a format string; enforces field widths on arguments larger than the given field width.

This function will truncate output longer than any field width given in the format string

Restrictions:
  Qore::PO_NO_TERMINAL_IO

Parameters

  fmt | the format string
  ... | the argument(s) corresponding to format specifiers in the format string

Returns
  the formatted string output corresponding to the arguments given

Example:
  f_printf("%5s", "a long string"); # will print out "a lon"

See also
  - String Formatting for information on the formatting string
  - printf() for a similar function that does not enforce field widths

## ◆ f_printf() [2/2]

string Qore::f_printf | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  NOOP

## ◆ f_sprintf() [1/2]

string Qore::f_sprintf | ( | string | fmt,
|  |  | ...
| ) |  |

Returns a formatted string based on a format string and other arguments; enforces field widths on arguments larger than the given field width.

This function will truncate output longer than any field width given in the format string

Code Flags:
  CONSTANT

Parameters

  fmt | the format string
  ... | the argument(s) corresponding to format specifiers in the format string

Returns
  a formatted string corresponding to the arguments given

Example:
  string str = f_sprintf("%5s", "a long string"); # will return "a lon"

See also
  - String Formatting for information on the formatting string
  - sprintf() for a similar function that does not enforce field widths

## ◆ f_sprintf() [2/2]

string Qore::f_sprintf | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  NOOP

## ◆ f_vprintf()

string Qore::f_vprintf | ( | string | fmt,
|  | auto | varg
| ) |  |

Outputs the string passed to standard output, using the first argument as a format string and a second argument giving a list or a single argument to the format string; enforces field widths on arguments larger than the given field width.

This function will truncate output longer than any field width given in the format string

Restrictions:
  Qore::PO_NO_TERMINAL_IO

Parameters

  fmt | the format string
  varg | the argument(s) corresponding to format specifiers in the format string

Returns
  the formatted string output corresponding to the arguments given

Example:
  f_vprintf("%5s %3d", ("a long string", 5000)); # will print out "a lon 500"

See also
  - String Formatting for information on the formatting string
  - vprintf() for a similar function that does not enforce field widths

Since
  Qore 0.8.4

## ◆ f_vsprintf()

string Qore::f_vsprintf | ( | string | fmt,
|  | auto | varg
| ) |  |

Returns a formatted string based on a format string and other arguments given as a list after the format string; enforces field widths on arguments larger than the given field width.

This function will truncate output longer than any field width given in the format string

Code Flags:
  CONSTANT

Parameters

  fmt | the format string
  varg | the argument(s) corresponding to format specifiers in the format string

Returns
  a formatted string corresponding to the arguments given

Example:
  string str = f_vsprintf("%5s %3d\n", ("a lon", 500)); # will return "a lon 500"

See also
  - String Formatting for information on the formatting string
  - vsprintf() for a similar function that does not enforce field widths

Since
  Qore 0.8.4

## ◆ flush()

nothing Qore::flush | ( |  | ) |

Flushes output to the console output with print(), printf(), etc.

Restrictions:
  Qore::PO_NO_TERMINAL_IO

Example:
  flush();

## ◆ force_encoding() [1/2]

string Qore::force_encoding | ( | string | str,
|  | string | encoding
| ) |  |

Returns the first string argument tagged with the character encoding given as the second argument; does not actually change the string data.

Use only in the case that a string is tagged with the wrong encoding, for example, if a string from a File object has a different encoding than the File object.

Code Flags:
  CONSTANT

Parameters

  str | the string to be returned
  encoding | the encoding to tag the return value with

Returns
  the first string argument tagged with the character encoding given as the second argument; does not actually change the string data

Example:
  string nstr = force_encoding(str, "iso-8859-1");

## ◆ force_encoding() [2/2]

nothing Qore::force_encoding | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ format_number() [1/2]

string Qore::format_number | ( | string | fmt,
|  | softfloat | num
| ) |  |

Returns a string of a formatted number according to a number argument and a format string.

Code Flags:
  CONSTANT

Parameters

  fmt | the format string has the following format: <thousands_separator>`[`<decimal_separator>[<decimals>]`]` where: thousands_separator and decimal_separator are single characters defining the thousands and decimal separator characters respectively, and decimals is one or more digits defining how may decimals should appear after the decimal point
  num | the number to format

Returns
  a string of a formatted number according to a number argument and a format string; if the format string does not follow the given format, then the number without formatting is returned

Example:
  string nstr = format_number(".,3", -48392093894.2349); # returns "-48.392.093.894,235"

See also
  <float>::format()

## ◆ format_number() [2/2]

nothing Qore::format_number | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ get_encoding() [1/2]

string Qore::get_encoding | ( | string | str | ) |

Returns a string describing the character encoding of the string argument passed.

Code Flags:
  CONSTANT

Parameters

  str | the string to get the encoding for

Returns
  a string describing the character encoding of the string argument passed

Example:
  string enc = get_encoding(str);

Note
  equivalent to <string>::encoding()

## ◆ get_encoding() [2/2]

nothing Qore::get_encoding | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ index() [1/2]

int Qore::index | ( | softstring | str,
|  | 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

  str | the string to search in
  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

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

Example:
  int i = index(str, 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 <string>::find(softstring, softint)

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

## ◆ index() [2/2]

int Qore::index | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ join() [1/3]

string Qore::join | ( | string | str,
|  |  | ...
| ) |  |

Creates a string from separator string and a list of arguments.

Code Flags:
  RET_VALUE_ONLY

Parameters

  str | the separator string
  ... | the list of arguments to join; each argument will be converted to a string if necessary to be concatenated to the return value string; additionally if any string argument has a different character encoding than str, then it will be converted to str's character encoding before concatentation to the return value string

Returns
  a string created from a list and a seperator string, each element in the list will be present in the return value separated by the separator string

Example:
  string str = join(":", "a", "b", "c"); # returns "a:b:c"

Exceptions

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

## ◆ join() [2/3]

string Qore::join | ( | string | str,
|  | list< auto > | l
| ) |  |

Creates a string from separator string and a list of arguments.

Code Flags:
  RET_VALUE_ONLY

Parameters

  str | the separator string
  l | the list of arguments to join; each argument will be converted to a string if necessary to be concatenated to the return value string; additionally if any string argument has a different character encoding than str, then it will be converted to str's character encoding before concatentation to the return value string

Returns
  a string created from a list and a separator string, each element in the list will be present in the return value separated by the separator string; the string returned with have the same character encoding as str

Example:
  string str = join(":", ("a", "b", "c")); # returns "a:b:c"

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 <list>::join(string)

## ◆ join() [3/3]

nothing Qore::join | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ length() [1/4]

int Qore::length | ( | softstring | str | ) |

Returns the length in characters for the string passed.

Note that the byte length may differ from the character length with multi-byte character encodings. To get the byte length of a string, see strlen().

Code Flags:
  CONSTANT

Parameters

  str | the string to return the character length of

Returns
  the length in characters for the string passed

Example:
  int len = length(str);

Note
  - this operation has O(n) complexity if called on a string with a multi-byte character encoding, otherwise it is O(1)
  - equivalent to <string>::length()

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

## ◆ length() [2/4]

int Qore::length | ( | binary | bin | ) |

Returns the number of bytes in the binary object passed as an argument.

This variant of the function accepting a binary object as an argument works identically to the elements operator

Code Flags:
  CONSTANT

Parameters

  bin | the binary object to return the size of

Returns
  the number of bytes in the binary object

Example:
  int nbytes = length(bin);

## ◆ length() [3/4]

nothing Qore::length | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ length() [4/4]

int Qore::length | ( | auto | arg | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  NOOP

## ◆ ltrim() [1/2]

string Qore::ltrim | ( | string | str,
|  | *string | chars
| ) |  |

Removes byte characters from the start of a string and returns the new string.

By default (if the second argument is omitted or passed as an empty string) the following whitespace byte characters are removed: `" "`, `"\n"`, `"\r"`, `"\t"`, `"\v"` (vertical tab, ASCII 11), and `"\0"` (null character). To trim other characters, pass a string as the second argument specifying the byte characters to be removed.

Code Flags:
  CONSTANT

Parameters

  str | the string to trim
  chars | the characters to trim from the start of the string (default: `" "`, `"\n"`, `"\r"`, `"\t"`, `"\v"` (vertical tab, ASCII 11), and `"\0"` (null character))

Returns
  the trimmed string

Example:
  string tstr = ltrim(" ABC ");
  # returns string "ABC "

## ◆ ltrim() [2/2]

*string Qore::ltrim | ( | reference< string > | str,
|  | *string | chars
| ) |  |

Removes byte characters from the start of a reference to an lvalue containing a string and returns string after processing.

By default (if the second argument is omitted or passed as an empty string) the following whitespace byte characters are removed: `" "`, `"\n"`, `"\r"`, `"\t"`, `"\v"` (vertical tab, ASCII 11), and `"\0"` (null character). To trim other characters, pass a string as the second argument specifying the byte characters to be removed.

This variant accepts variable references, in which case it will modify the string in place and also return the modified string.

Parameters

  str | a reference to an lvalue containing the string value to process; if the lvalue does not have a string value NOTHING is returned
  chars | the characters to trim from the start of the string (default: `" "`, `"\n"`, `"\r"`, `"\t"`, `"\v"` (vertical tab, ASCII 11), and `"\0"` (null character))

Returns
  the trimmed string

Example:
  ltrim(\str);

## ◆ ord() [1/2]

int Qore::ord | ( | softstring | str,
|  | softint | offset = `0`
| ) |  |

Gives the positive numeric value of the given byte in the string passed; if no string is passed or the offset is after the end of the string, -1 is returned.

Code Flags:
  CONSTANT

Parameters

  str | the string containing the byte to be retrieved
  offset | the byte offset of the byte to be retrieved

Returns
  the positive numeric value of the given byte in the string passed; if the offset is after the end of the string or negative, -1 is returned

Example:
  int i = ord(str);

Note
  ord() only works on byte offsets and returns byte values

## ◆ ord() [2/2]

int Qore::ord | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ parse_boolean() [1/2]

bool Qore::parse_boolean | ( | string | str | ) |

tries to parse a string value as a boolean

Code Flags:
  CONSTANT

Example:
  bool b = parse_boolean(str);

Parameters

  str | case-insensitive `"on"`, `"true"`, `"enable*"`, `"yes"`, `"y"` are True, the rest is interpreted as a number where 0 is False, everything else is True

Returns
  a boolean value according to the parsed argument

Since
  Qore 0.8.12 `"y"` is also parsed as True

## ◆ parse_boolean() [2/2]

bool Qore::parse_boolean | ( | any | val | ) |

returns the first value passed as a boolean

Code Flags:
  CONSTANT

Example:
  bool b = parse_boolean(i);

Parameters

  val | the value to convert to a boolean

Returns
  the first value passed as a boolean

## ◆ parse_float()

float Qore::parse_float | ( | string | str,
|  | string | fmt
| ) |  |

returns a floating-point value corresponding to a string representing the number and an argument giving the format

Code Flags:
  RET_VALUE_ONLY

Example:
  float f = parse_float("1.150.200,55", ".,");

Parameters

  str | the string to parse
  fmt | the format of the number in the string, consisting of two characters, the first for the thousands separator, the second for the decimal point (ex: `".,"` for many European locales)

Returns
  the floating-point value represented by the string

See also
  - parse_number()
  - parse_int()

Since
  Qore 0.8.11.1

## ◆ parse_int()

int Qore::parse_int | ( | string | str,
|  | string | fmt
| ) |  |

returns an integer corresponding to a string representing the number and an argument giving the format

Code Flags:
  RET_VALUE_ONLY

Example:
  int i = parse_int("1.150.200,55", ".,");

Parameters

  str | the string to parse
  fmt | the format of the number in the string, consisting of two characters, the first for the thousands separator, the second for the decimal point (ex: `".,"` for many European locales)

Returns
  the number value represented by the string

See also
  - parse_number()
  - parse_float()

Since
  Qore 0.8.13

## ◆ parse_number()

number Qore::parse_number | ( | string | str,
|  | string | fmt
| ) |  |

returns a number corresponding to the string and the argument, giving the format

Code Flags:
  RET_VALUE_ONLY

Example:
  number n = parse_number("1.150.200,55", ".,");

Parameters

  str | the string to parse
  fmt | the format of the number in the string, consisting of two characters, the first for the thousands separator, the second for the decimal point (ex: `".,"` for many European locales)

Returns
  the number value represented by the string

See also
  - parse_int()
  - parse_float()

Since
  Qore 0.8.11.1

## ◆ print()

nothing Qore::print | ( |  | ... | ) |

Outputs a string to standard output with no formatting.

Restrictions:
  Qore::PO_NO_TERMINAL_IO

Parameters

  ... | each of the arguments passed to this function will be output literally with no output formatting

Example:
  print("hello\n");

See also
  printf() for a function that allows for formatted output

## ◆ printf() [1/2]

string Qore::printf | ( | string | fmt,
|  |  | ...
| ) |  |

Outputs the string passed to standard output, using the first argument as a format string; does not enforce field widths on arguments larger than the given field width.

This function will not truncate output longer than any field width given in the format string

Restrictions:
  Qore::PO_NO_TERMINAL_IO

Parameters

  fmt | the format string
  ... | the argument(s) corresponding to format specifiers in the format string

Returns
  the formatted string output corresponding to the arguments given

Example:
  printf("%5s", "a long string"); # will print out "a long string"

See also
  - String Formatting for information on the formatting string
  - f_printf() for a similar function that enforces field widths

## ◆ printf() [2/2]

string Qore::printf | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Restrictions:
  Qore::PO_NO_TERMINAL_IO

Code Flags:
  NOOP

## ◆ regex() [1/2]

bool Qore::regex | ( | string | str,
|  | 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

  str | the string to test
  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 = regex("hello", "^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 <string>::regex(string, int)

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

## ◆ regex() [2/2]

nothing Qore::regex | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ regex_extract() [1/2]

*list<*string> Qore::regex_extract | ( | string | str,
|  | 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

  str | the string to process
  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:
  *list<*string> rv = regex_extract("ns:element", "(\\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 <string>::regexExtract(string, int)

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

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

## ◆ regex_extract() [2/2]

nothing Qore::regex_extract | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ regex_subst() [1/2]

string Qore::regex_subst | ( | string | str,
|  | string | regex,
|  | string | subst,
|  | int | options = `0`
| ) |  |

Returns a string with patterns substituted according to the arguments passed.

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

  str | the source string for substitution
  regex | the regular expression pattern string
  subst | the pattern for substitution; use `$1`, `$2`, etc for patterns in parentheses in the regex argument
  options | regular expression options; see Regular Expression Constants for possible values

Returns
  a string with patterns substituted according to the arguments passed

Example:
  regex_subst("hello there", "^(.*) there$", "you $1"); #returns "you hello"

Example of global replacement:
  string content = "123
  123
  123";
  printf("%s\n", regex_subst(content, "123", "456", Qore::RE_Global));
  resulting in:
  456
  456
  456

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

See also
  - replace()
  - Regular Expressions for more information about regular expression support in Qore

## ◆ regex_subst() [2/2]

nothing Qore::regex_subst | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ replace() [1/2]

string Qore::replace | ( | string | str,
|  | string | source,
|  | string | target,
|  | int | start = `0`,
|  | int | end = `-1`
| ) |  |

Replaces all occurrences of a substring in a string with another string.

Code Flags:
  RET_VALUE_ONLY

Parameters

  str | the string to process
  source | the substring to replace; if this string has a different character encoding than str, then it will be converted to str's character encoding
  target | the replacement value for source; if this string has a different character encoding than str, then it will be converted to str's character encoding
  start | the starting character position in the source for the replacement where the first character is at position 0 (may not be the same as the byte position for multibyte character encodings); negative numbers give character offsets from the end of the string
  end | the ending character position in the source for the replacement where the first character is at position 0 (may not be the same as the byte position for multibyte character encodings; negative numbers give offsets from the end of the string)

Returns
  a string with all occurrences of source replaced with target

Example:
  string str = replace("hello there", "there", "you"); # returns "hello you"

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
  no regular expressions are used in this function, only direct replacements

See also
  regex_subst()

## ◆ replace() [2/2]

nothing Qore::replace | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ reverse()

string Qore::reverse | ( | softstring | str | ) |

Reverses a string and returns the new string.

Works properly on strings with multi-byte character encodings as well (such as UTF-8)

Code Flags:
  CONSTANT

Parameters

  str | the string to reverse

Returns
  a string with all characters in reverse order

Example:
  string ns = reverse(str);

See also
  reverse(list)

## ◆ rindex() [1/2]

int Qore::rindex | ( | softstring | str,
|  | 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

  str | the string to search in
  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 = rindex(str, 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 <string>::rfind(softstring, softint)

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

## ◆ rindex() [2/2]

int Qore::rindex | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ rtrim() [1/2]

string Qore::rtrim | ( | string | str,
|  | *string | chars
| ) |  |

Removes byte characters from the end of a string and returns the new string.

By default (if the second argument is omitted or passed as an empty string) the following whitespace byte characters are removed: `" "`, `"\n"`, `"\r"`, `"\t"`, `"\v"` (vertical tab, ASCII 11), and `"\0"` (null character). To trim other characters, pass a string as the second argument specifying the byte characters to be removed.

Code Flags:
  CONSTANT

Parameters

  str | the string to trim
  chars | the characters to trim from the end of the string (default: `" "`, `"\n"`, `"\r"`, `"\t"`, `"\v"` (vertical tab, ASCII 11), and `"\0"` (null character))

Returns
  the trimmed string

Example:
  string tstr = rtrim(str);
  # returns string " ABC"

Bug:
  it is not possible to trim multi-byte characters from strings using this function; each byte is treated as a character. No encoding conversions are done even if the chars argument has a different character encoding than the str argument.

## ◆ rtrim() [2/2]

*string Qore::rtrim | ( | reference< string > | str,
|  | *string | chars
| ) |  |

Removes byte characters from the end of a reference to an lvalue containing a string and returns string after processing.

By default (if the second argument is omitted or passed as an empty string) the following whitespace byte characters are removed: `" "`, `"\n"`, `"\r"`, `"\t"`, `"\v"` (vertical tab, ASCII 11), and `"\0"` (null character). To trim other characters, pass a string as the second argument specifying the byte characters to be removed.

This variant accepts variable references, in which case it will modify the string in place and also return the modified string.

Parameters

  str | a reference to an lvalue containing the string value to process; if the lvalue does not have a string value NOTHING is returned
  chars | the characters to trim from the end of the string (default: `" "`, `"\n"`, `"\r"`, `"\t"`, `"\v"` (vertical tab, ASCII 11), and `"\0"` (null character))

Returns
  the trimmed string

Example:
  rtrim(\str);

Bug:
  it is not possible to trim multi-byte characters from strings using this function; each byte is treated as a character. No encoding conversions are done even if the chars argument has a different character encoding than the str argument.

## ◆ split() [1/4]

list<string> Qore::split | ( | string | sep,
|  | string | str,
|  | 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
  str | the string to split
  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:
  list<string> l = split(":", "some:text:here"); # 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 <string>::split(string, bool)

## ◆ split() [2/4]

list<string> Qore::split | ( | string | sep,
|  | string | str,
|  | 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 doubled or preceded by a backquote character (`"\"`), then these quote characters are included as part of the field's text and not treated as quote characters (in quoted fields only).

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
  str | the string to split
  quote | the quote character; quotes may be escaped (in quoted fields only) by doubling the quote character or by preceding it with a backslash (`"\"`)
  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> l = split(",", "some,'text with spaces',here", "'"); # returns ("some", "text with spaces", "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
  SPLIT-ERROR | field missing closing quote character; extra text following quoted field

Note
  equivalent to <string>::split(string, string)

Since
  - Qore 0.8.6 the `trim_unquoted` parameter was added
  - Qore 0.9.4 processes doubled quote characters as an escaped quote within a quoted field

## ◆ split() [3/4]

list<binary> Qore::split | ( | data | sep,
|  | binary | data
| ) |  |

Returns a list of binary objects representing each component of the binary object separated by the bytes identified by the separator argument, with the separator removed.

Code Flags:
  CONSTANT

Parameters

  data | the binary object to separate
  sep | the bytes that separate the fields

Returns
  a list of binary objects representing each component of the binary object separated by the bytes identified by the separator argument, with the separator removed

Example:
  list<binary> l = split(sep, bin);

Note
  equivalent to <binary>::split(data)

## ◆ split() [4/4]

list<string> Qore::split | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ sprintf() [1/2]

string Qore::sprintf | ( | string | fmt,
|  |  | ...
| ) |  |

Returns a formatted string based on a format string and other arguments; does not enforce field widths on arguments larger than the given field width.

This function will not truncate output longer than any field width given in the format string

Code Flags:
  CONSTANT

Parameters

  fmt | the format string
  ... | the argument(s) corresponding to format specifiers in the format string

Returns
  a formatted string corresponding to the arguments given

Example:
  string str = sprintf("%5s", "a long string"); # will return "a long string"

See also
  - String Formatting for information on the formatting string
  - f_sprintf() for a similar function that enforces field widths

## ◆ sprintf() [2/2]

string Qore::sprintf | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  NOOP

## ◆ strlen() [1/3]

int Qore::strlen | ( | softstring | str | ) |

Returns the length in bytes of the string argument.

Note that the byte length may differ from the character length with multi-byte character encodings. For the character length of a string, see length().

Code Flags:
  CONSTANT

Parameters

  str | the string to return the byte length of

Returns
  the length in bytes for the string passed

Example:
  int size = strlen(str);

Note
  equivalent to <string>::strlen() and <string>::size()

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

## ◆ strlen() [2/3]

nothing Qore::strlen | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ strlen() [3/3]

int Qore::strlen | ( | auto | arg | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  NOOP

## ◆ strmul()

string Qore::strmul | ( | softstring | str,
|  | softint | smul,
|  | *softint | offset
| ) |  |

Returns a new string with a repeated string element and optionally removing trailing characters.

Code Flags:
  RET_VALUE_ONLY

Parameters

  str | the string element to repeat in the return value string
  smul | the number of times the element should repeat
  offset | the number of characters that should be removed from the end of the string after processing

Example:
  string ret = strmul("%s,", 3, 1); # returns "%s,%s,%s"

Exceptions

  STRMUL-ERROR | offset is < 0 or smul < 0

## ◆ substr() [1/5]

string Qore::substr | ( | softstring | str,
|  | 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

  str | The string to process
  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 empty string is returned if the argument cannot be satisfied

Example:
  # get the last 10 characters of a string
  string substr = substr(str, -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 <string>::substr(softint)

## ◆ substr() [2/5]

string Qore::substr | ( | softstring | str,
|  | 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

  str | The string to process
  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 empty 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 = substr(str, 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 <string>::substr(softint, softint)

## ◆ substr() [3/5]

binary Qore::substr | ( | binary | b,
|  | softint | start
| ) |  |

Returns a portion of a binary object starting from an integer offset.

Arguments can be negative, giving offsets from the end of the data.

Code Flags:
  CONSTANT

Parameters

  b | The binary object to process
  start | The starting byte for the portion of the binary object where the first byte is at offset 0; if the offset is negative, it designates the number of bytes from the end of the data

Returns
  the portion of the binary data argument starting from an integer byte offset; the rest of the data is returned after this offset

Example:
  # get the last 10 bytes
  binary b1 = substr(b, -10);

Note
  equivalent to <binary>::substr(softint)

Since
  Qore 0.8.8

## ◆ substr() [4/5]

binary Qore::substr | ( | binary | b,
|  | softint | start,
|  | softint | len
| ) |  |

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

Arguments can be negative, giving offsets from the end of the data.

Code Flags:
  CONSTANT

Parameters

  b | The binary object to process
  start | The starting byte for the portion of the binary object where the first byte is at offset 0; if the offset is negative, it designates the number of bytes from the end of the data
  len | The maximum number of bytes to copy; if this value is negative, the rest of the data from start will be copied to the return value, except without - len bytes from the end of the data

Returns
  the portion of the binary data argument according to the arguments passed

Example:
  # get a binary object 10 characters into the data except omitting the last 2 bytes
  binary b1 = substr(b, 10, -2);

Note
  equivalent to <binary>::substr(softint, softint)

Since
  Qore 0.8.8

## ◆ substr() [5/5]

nothing Qore::substr | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  NOOP

## ◆ tolower() [1/2]

string Qore::tolower | ( | string | str | ) |

Returns a string in all lower-case characters based on the argument passed.

Code Flags:
  CONSTANT

Example:
  string lwr = tolower(str);

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

Parameters

  str | a string to process

Returns
  a string in all lower-case characters based on the argument passed

Note
  - equivalent to <string>::lwr(string)

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

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

## ◆ tolower() [2/2]

nothing Qore::tolower | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ toupper() [1/2]

string Qore::toupper | ( | string | str | ) |

Returns a string in all upper-case characters based on the argument passed.

Code Flags:
  CONSTANT

Example:
  string upr = toupper(str);

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

Parameters

  str | a string to process

Returns
  a string in all upper-case characters based on the argument passed

Note
  - equivalent to <string>::upr(string)

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

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

## ◆ toupper() [2/2]

nothing Qore::toupper | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ trim() [1/3]

string Qore::trim | ( | string | str,
|  | *string | chars
| ) |  |

Removes byte characters from the start and end of a string and returns the new string (also see the trim operator)

By default (if the second argument is omitted or passed as an empty string) the following whitespace byte characters are removed: `" "`, `"\n"`, `"\r"`, `"\t"`, `"\v"` (vertical tab, ASCII 11), and `"\0"` (null character). To trim other characters, pass a string as the second argument specifying the byte characters to be removed.

Code Flags:
  CONSTANT

Parameters

  str | the string to trim
  chars | the characters to trim from the start and end of the string (default: `" "`, `"\n"`, `"\r"`, `"\t"`, `"\v"` (vertical tab, ASCII 11), and `"\0"` (null character))

Returns
  the trimmed string

Example:
  string tstr = trim(str);

## ◆ trim() [2/3]

*string Qore::trim | ( | reference< string > | str,
|  | *string | chars
| ) |  |

Removes byte characters from the start and end of a reference to an lvalue containing a string and returns string after processing (also see the trim operator)

By default (if the second argument is omitted or passed as an empty string) the following whitespace byte characters are removed: `" "`, `"\n"`, `"\r"`, `"\t"`, `"\v"` (vertical tab, ASCII 11), and `"\0"` (null character). To trim other characters, pass a string as the second argument specifying the byte characters to be removed.

This variant accepts variable references, in which case it will modify the string in place and also return the modified string.

Parameters

  str | a reference to an lvalue continaing the string value to process; if the lvalue does not have a string value NOTHING is returned
  chars | the characters to trim from the start and end of the string (default: `" "`, `"\n"`, `"\r"`, `"\t"`, `"\v"` (vertical tab, ASCII 11), and `"\0"` (null character))

Returns
  the trimmed string

Example:
  trim(\str);

## ◆ trim() [3/3]

nothing Qore::trim | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  RUNTIME_NOOP

## ◆ trunc_str()

string Qore::trunc_str | ( | softstring | str,
|  | softint | len,
|  | *string | encoding
| ) |  |

Returns a truncated string with no more than the given number of bytes and optionally converted to a specific character encoding.

Code Flags:
  RET_VALUE_ONLY

Parameters

  str | the string to truncate
  len | the maximum byte length of the string
  encoding | if given, the string returned will be returned in the given encoding, otherwise the encoding of \ str is used for the return value

Returns
  the string truncated to be no longer than the given byte length in the character encoding given (or in the original string's character encoding if no encoding argument was passed to the function); if the string has a multi-byte character encoding, this function will guarantee that the returned string ends on a valid character (in this case the byte length of the string could be less than the limit given)

Example:
  string column = trunc_str(str, 80, dsp.getOSEncoding());

Exceptions

  ENCODING-CONVERSION-ERROR | this exception could be thrown if an explicit character encoding was given and an error occurs during encoding conversion

## ◆ vprintf() [1/2]

string Qore::vprintf | ( | string | fmt,
|  | auto | varg
| ) |  |

Outputs the string passed to standard output, using the first argument as a format string and a second argument giving a list or a single argument to the format string; does not enforce field widths on arguments larger than the given field width.

This function will not truncate output longer than any field width given in the format string

Restrictions:
  Qore::PO_NO_TERMINAL_IO

Parameters

  fmt | the format string
  varg | the argument(s) corresponding to format specifiers in the format string

Returns
  the formatted string output corresponding to the arguments given

Example:
  vprintf("%5s %3d", ("a long string", 5000)); # will print out "a long string 5000"

See also
  - String Formatting for information on the formatting string
  - f_vprintf() for a similar function that enforces field widths

## ◆ vprintf() [2/2]

string Qore::vprintf | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  NOOP

## ◆ vsprintf() [1/2]

string Qore::vsprintf | ( | string | fmt,
|  | auto | varg
| ) |  |

Returns a formatted string based on a format string and other arguments given as a list after the format string; does not enforce field widths on arguments larger than the given field width.

This function will not truncate output longer than any field width given in the format string

Code Flags:
  CONSTANT

Parameters

  fmt | the format string
  varg | the argument(s) corresponding to format specifiers in the format string

Returns
  a formatted string corresponding to the arguments given

Example:
  string str = vsprintf("%5s %3d\n", ("a long string", 5000)); # will return "a long string 5000"

See also
  - String Formatting for information on the formatting string
  - f_vsprintf() for a similar function that enforces field widths

## ◆ vsprintf() [2/2]

string Qore::vsprintf | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:
  NOOP