Qore Programming Language Reference Manual  0.9.2
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...
 
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< stringQore::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< stringQore::split (string sep, string str, bool with_separator=False)
 Splits a string into a list of components based on a separator string. More...
 
list< stringQore::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< stringQore::split (binary 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< stringQore::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:

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 "%")

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.

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
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
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
strthe string to search in
substrthe substring to find in str
posthe 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

◆ 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
strthe string to search in
substrthe substring to find in str
posthe 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

◆ 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

◆ 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
strthe 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
stra 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
valthe byte value of the character; only the least-significant byte is used
encodingthe 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
strthe string to convert
encodingthe 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-ERRORthis 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
fmtthe 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

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

◆ 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
fmtthe format string
vargthe 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
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
fmtthe format string
vargthe 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
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:

◆ 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
strthe string to be returned
encodingthe 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
fmtthe 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
numthe 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
strthe 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
strthe string to search in
substrthe 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
posthe 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-ERRORthis exception could be thrown if the string arguments have different character encodings and an error occurs during encoding conversion
INVALID-ENCODINGthis 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

◆ 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
strthe 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-ERRORthis 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
strthe separator string
lthe 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-ERRORthis 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
strthe string to return the character length of
Returns
the length in characters for the string passed
Example:
int len = length(str);
Note
See also

◆ 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
binthe 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
strthe string to trim
charsthe 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
stra reference to an lvalue containing the string value to process; if the lvalue does not have a string value NOTHING is returned
charsthe 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
strthe string containing the byte to be retrieved
offsetthe 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
strcase-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
valthe 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
strthe string to parse
fmtthe 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
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
strthe string to parse
fmtthe 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
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
strthe string to parse
fmtthe 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
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
fmtthe 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

◆ 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
strthe string to test
regexthe regular expression pattern
optionsregular 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-ERRORThere was an error compiling the regular expression
REGEX-OPTION-ERRORthe option argument contains invalid option bits
ENCODING-CONVERSION-ERRORthis 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
strthe string to process
regexthe regular expression to use for matching, elements should be given in parentheses
optionsregular 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-ERRORThere was an error compiling the regular expression
REGEX-OPTION-ERRORthe option argument contains invalid option bits
ENCODING-CONVERSION-ERRORthis 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
strthe source string for substitution
regexthe regular expression pattern string
substthe pattern for substitution; use $1, $2, etc for patterns in parentheses in the regex argument
optionsregular 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-ERRORThere was an error compiling the regular expression
REGEX-OPTION-ERRORthe option argument contains invalid option bits
ENCODING-CONVERSION-ERRORthis exception could be thrown if an encoding error is encountered when converting the given strings to UTF-8
See also

◆ 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
strthe string to process
sourcethe substring to replace; if this string has a different character encoding than str, then it will be converted to str's character encoding
targetthe replacement value for source; if this string has a different character encoding than str, then it will be converted to str's character encoding
startthe 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
endthe 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-ERRORthis 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
strthe 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
strthe string to search in
substrthe 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
posthe 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-ERRORthis exception could be thrown if the string arguments have different character encodings and an error occurs during encoding conversion
INVALID-ENCODINGthis 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

◆ 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
strthe string to trim
charsthe 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
stra reference to an lvalue containing the string value to process; if the lvalue does not have a string value NOTHING is returned
charsthe 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
septhe 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
strthe string to split
with_separatorinclude 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-ERRORthis 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 preceded by a backquote character ("\"), then these quote characters are included as part of the field's text and not treated as quote characters

Code Flags:
RET_VALUE_ONLY
Parameters
septhe 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
strthe string to split
quotethe quote character
trim_unquotedremove 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-ERRORthis exception could be thrown if the string arguments have different character encodings and an error occurs during encoding conversion
SPLIT-ERRORfield 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

◆ split() [3/4]

list<string> Qore::split ( binary  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
datathe binary object to separate
septhe 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<string> l = split(sep, bin);
Note
equivalent to <binary>::split(binary)

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

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

◆ 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
strthe string element to repeat in the return value string
smulthe number of times the element should repeat
offsetthe 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-ERRORoffset 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
strThe string to process
startThe 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-ENCODINGthis 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
strThe string to process
startThe 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
lenThe 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-ENCODINGthis 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
bThe binary object to process
startThe 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
bThe binary object to process
startThe 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
lenThe 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
stra string to process
Returns
a string in all lower-case characters based on the argument passed
Note
  • equivalent to <string>::lwr(string)
See also
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
stra string to process
Returns
a string in all upper-case characters based on the argument passed
Note
  • equivalent to <string>::upr(string)
See also
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
strthe string to trim
charsthe 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
stra reference to an lvalue continaing the string value to process; if the lvalue does not have a string value NOTHING is returned
charsthe 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
strthe string to truncate
lenthe maximum byte length of the string
encodingif 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-ERRORthis 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
fmtthe format string
vargthe 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

◆ 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
fmtthe format string
vargthe 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

◆ 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