String Functions

Collaboration diagram for String Functions:

Modules
	Regular Expression Constants

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

(

)

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

bindex() [2/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)

brindex() [1/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

brindex() [2/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)

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]

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

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]

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

chr() [1/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

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]

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

convert_encoding() [1/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

convert_encoding() [2/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

f_printf() [1/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_printf() [2/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_sprintf() [1/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_sprintf() [2/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_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]

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

force_encoding() [2/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");

format_number() [1/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

format_number() [2/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()

get_encoding() [1/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

get_encoding() [2/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()

index() [1/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

index() [2/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)

join() [1/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

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]

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

length() [1/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() [2/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

length() [3/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() [4/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()

ltrim() [1/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);

ltrim() [2/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 "

ord() [1/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

ord() [2/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

parse_boolean() [1/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_boolean() [2/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_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

(

)

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

printf() [2/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

regex() [1/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() [2/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_extract() [1/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_extract() [2/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_subst() [1/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

regex_subst() [2/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

replace() [1/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

replace() [2/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()

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

(

)

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

rindex() [2/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)

rtrim() [1/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.

rtrim() [2/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.

split() [1/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

split() [2/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() [3/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() [4/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

sprintf() [1/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

sprintf() [2/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

strlen() [1/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() [2/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

strlen() [3/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()

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]

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

substr() [2/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() [3/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() [4/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() [5/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)

tolower() [1/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

tolower() [2/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

toupper() [1/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

toupper() [2/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

trim() [1/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

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]

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

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

(

)

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

vprintf() [2/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

vsprintf() [1/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

vsprintf() [2/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