Qore Util Module Reference 1.11
|
the Util namespace contains all the objects in the Util module More...
Classes | |
hashdecl | AllowedValueInfo |
Allowed value hash. More... | |
hashdecl | UiMessageInfo |
Message information for display to the user. More... | |
hashdecl | UriQueryInfo |
the return value of the parse_uri_query() function More... | |
hashdecl | UrlRetrievalOptions |
URL retrieval options for get_file_from_url() More... | |
Functions | |
bool | absolute_path (string path) |
returns True if the argument is an absolute path, False if not | |
bool | absolute_path_unix (string path) |
returns True if the argument is a UNIX absolute path, False if not | |
bool | absolute_path_windows (string path) |
returns True if the argument is a Windows absolute path, False if not | |
hash< ExceptionInfo > | check_exception_serializable (hash< ExceptionInfo > ex) |
Recursively ensure that exception arguments are serializable. | |
bool | check_ip_address (string ip, bool exception=False) |
verifies if a string is an IPv4 or IPv6 address | |
int | compare_version (string lv, string rv) |
compares complex versions by breaking down strings into component parts | |
list< auto > | flatten (softlist< auto > arg) |
Flattens a nested list (the nesting can be to any depth). | |
string | get_byte_size (softnumber n, int decimals=2) |
returns a string giving a user-friendly real storage size (ie based on 1KiB = 1024 bytes) in KiB, MiB, GiB, TiB, etc for the given byte size | |
string | get_exception_string (hash< auto > ex) |
returns a multi-line string from the exception hash argument suitable for logging or output on the console | |
data | get_file_from_ftp (string url, string path, *hash< UrlRetrievalOptions > options) |
Retrieves file data from an FTP URL and a path. | |
data | get_file_from_http (string url, *string path, *hash< UrlRetrievalOptions > options) |
Retrieves file data from an HTTP URL. | |
data | get_file_from_sftp (string url, string path, *hash< UrlRetrievalOptions > options) |
Retrieves file data from an SFTP URL and a path. | |
data | get_file_from_url (string url, *hash< UrlRetrievalOptions > options) |
Retrieves file data from the given URL. | |
data | get_local_file (string path, *hash< UrlRetrievalOptions > options) |
Retrieves file data from a local file path. | |
string | get_marketing_byte_size (softnumber n, int decimals=2) |
returns a string giving a user-friendly "marketing storage" size (ie based on 1KB = 1000 bytes) in KB, MB, GB, TB, etc for the given byte size | |
string | get_random_string (softint len=15, int level=3) |
function that returns a random string | |
string | get_relative_path (string basedir, string path, string cwd=getcwd()) |
returns a path as a relative path from another directory | |
string | glob_to_regex (string pat) |
Translates a shell pattern to a regular expression. | |
bool | is_float (string text, bool pure=False) |
Checks whether string represents a (true) float value. | |
bool | is_int (string text, bool pure=False) |
Checks whether string represents a (true) integer value. | |
bool | is_number (string text, bool pure=False) |
Checks whether string represents a (true) number value. | |
string | lpad (softstring text, int length, string padding=' ') |
Returns a string left-padded to a specified length with the specified characters. | |
string | make_uri_query (hash< UriQueryInfo > h, string arg_separator=';') |
returns a serialized string for a UriQueryInfo hash | |
string | normalize_dir (string path, string cwd=getcwd()) |
returns a platform-specific normalized path name (starting from /, eliminates "." , ".." , and "//" ) | |
string | normalize_dir_unix (string path, string cwd=getcwd()) |
returns a normalized UNIX path name (starting from /, eliminates "." , ".." , and "//" ) | |
string | normalize_dir_windows (string path, string cwd=getcwd()) |
returns a normalized Windows path name (eliminates "." , ".." , and "//" ) | |
string | ordinal (int i) |
Returns string with partially textual representation of ordinal integer value. | |
int | parse_memory_size (string str, *bool use_binary) |
Returns a size in bytes from a string where "1M" = 1048576 and so forth. | |
list< int > | parse_ranges (string text) |
Parses a string and returns a list of integers. | |
auto | parse_to_qore_value (string arg) |
tries to convert a string (such as an argument given from the command-line) to a Qore value | |
hash< UriQueryInfo > | parse_uri_query (string path) |
parses a URI path for a arguments and a method; where the method is the part of the path before the first "?" character, and arguments are after | |
string | plural (int count, string base, string singular='', string plural='s') |
Returns string with number and proper singular/plural form of noun. | |
string | regex_escape (string text) |
Escapes (backslashes) all non-alphanumeric characters in a string. | |
string | rpad (softstring text, int length, string padding=' ') |
Returns a string right-padded to a specified length with the specified characters. | |
bool | same (list< auto > l) |
checks whether given list has only unique elements | |
string | serialize_to_string (auto val) |
Serializes the given value to a string that can be deserialized with parse_to_qore_value() | |
list< auto > | slice (list< auto > l, softlist< auto > indices) |
list slice implementation | |
bool | string_ends_with (string str, string substr) |
Verifies whether a string ends with specific substring. | |
bool | string_starts_with (string str, string substr) |
Verifies whether a string begins with specific substring. | |
string | substitute_env_vars (string str) |
Substitutes environment variables in a string and returns the string. | |
string | tmp_location () |
Returns a path for temporary files. | |
list< auto > | uniq (softlist< auto > arg) |
Returns a duplicate-free version of the list. | |
list< auto > | zip () |
Returns a list of lists, where the i-th list contains the i-th element from each of the argument lists. | |
bool Util::absolute_path | ( | string | path | ) |
returns True if the argument is an absolute path, False if not
path | the path to check |
bool Util::absolute_path_unix | ( | string | path | ) |
returns True if the argument is a UNIX absolute path, False if not
path | the path to check |
bool Util::absolute_path_windows | ( | string | path | ) |
returns True if the argument is a Windows absolute path, False if not
path | the path to check |
hash< ExceptionInfo > Util::check_exception_serializable | ( | hash< ExceptionInfo > | ex | ) |
Recursively ensure that exception arguments are serializable.
ex | the exception to check and remove any non-serializable attributes |
bool Util::check_ip_address | ( | string | ip, |
bool | exception = False |
||
) |
verifies if a string is an IPv4 or IPv6 address
ip | the string in dot-notation (for IPv4 addresses) or colon notation (for IPv6 addresses) to check; the string should not contain any network component which would cause the comparison to fail; note that IPv4 address components must be in the range of 0 - 255 and must not have leading zeros |
exception | if True an exception will be thrown if the string is not a valid IPv4 or IPv6 address, if False the return value of the function indicates the string's validation status |
exception
is True then an INVALID-IP-ADDRESS
exception is thrown if the string is invalid)INVALID-IP-ADDRESS | this exception is thrown if ip is not a valid IPv4 or IPv6 address and exception is True |
int Util::compare_version | ( | string | lv, |
string | rv | ||
) |
compares complex versions by breaking down strings into component parts
Each element is compared separately, so that compare_version("2.11.1", "2.2") returns 1 (a regular string comparison would give the opposite result)
lv | left-hand version |
rv | right-hand version |
list< auto > Util::flatten | ( | softlist< auto > | arg | ) |
Flattens a nested list (the nesting can be to any depth).
arg | a list to flatten |
string Util::get_byte_size | ( | softnumber | n, |
int | decimals = 2 |
||
) |
returns a string giving a user-friendly real storage size (ie based on 1KiB = 1024 bytes) in KiB, MiB, GiB, TiB, etc for the given byte size
n | the number to display |
decimals | the number of digits after the decimal point |
string Util::get_exception_string | ( | hash< auto > | ex | ) |
returns a multi-line string from the exception hash argument suitable for logging or output on the console
ex | the exception hash to process |
data Util::get_file_from_ftp | ( | string | url, |
string | path, | ||
*hash< UrlRetrievalOptions > | options | ||
) |
Retrieves file data from an FTP URL and a path.
url | the FTP URL |
path | the path to the file on the FTP server |
options | connection options |
GET-FILE-FROM-URL-ERROR | empty path string |
data Util::get_file_from_http | ( | string | url, |
*string | path, | ||
*hash< UrlRetrievalOptions > | options | ||
) |
Retrieves file data from an HTTP URL.
url | the HTTP URL including the path to the resource to retrieve |
path | an optional path to append to the URL |
options | connection options |
data Util::get_file_from_sftp | ( | string | url, |
string | path, | ||
*hash< UrlRetrievalOptions > | options | ||
) |
Retrieves file data from an SFTP URL and a path.
url | the SFTP URL |
path | the path to the file on the SFTP server |
options | connection options |
GET-FILE-FROM-URL-ERROR | empty path string |
data Util::get_file_from_url | ( | string | url, |
*hash< UrlRetrievalOptions > | options | ||
) |
Retrieves file data from the given URL.
url | the URL for the file |
options | retrieval options |
GET-FILE-FROM-URL-ERROR | unknown or unsupported scheme in URL or other error retrieving the file |
data Util::get_local_file | ( | string | path, |
*hash< UrlRetrievalOptions > | options | ||
) |
Retrieves file data from a local file path.
path | the path to the file data on the local filesystem |
options | connection options |
string Util::get_marketing_byte_size | ( | softnumber | n, |
int | decimals = 2 |
||
) |
returns a string giving a user-friendly "marketing storage" size (ie based on 1KB = 1000 bytes) in KB, MB, GB, TB, etc for the given byte size
n | the number to display |
decimals | the number of digits after the decimal point |
string Util::get_random_string | ( | softint | len = 15 , |
int | level = 3 |
||
) |
function that returns a random string
len | the length fo the string returned |
level | a value from 1 - 4 inclusive giving the range of printable ASCII characters included in the output (values out of the range result in the nearest value in the range being used):
|
string Util::get_relative_path | ( | string | basedir, |
string | path, | ||
string | cwd = getcwd() |
||
) |
returns a path as a relative path from another directory
basedir | the directory that the result will be relative to |
path | the path to return as a relative path from base |
cwd | the current working directory, used in case base or path are relative paths |
string Util::glob_to_regex | ( | string | pat | ) |
Translates a shell pattern to a regular expression.
Returns the shell-style pattern converted to a regular expression.
pat | the pattern to convert |
bool Util::is_float | ( | string | text, |
bool | pure = False |
||
) |
Checks whether string represents a (true) float value.
text | a string to check |
pure | if True then only floats match, otherwise include integers. |
bool Util::is_int | ( | string | text, |
bool | pure = False |
||
) |
Checks whether string represents a (true) integer value.
text | a string to check |
pure | if True then only integers match, otherwise check floats too. |
bool Util::is_number | ( | string | text, |
bool | pure = False |
||
) |
Checks whether string represents a (true) number value.
text | a string to check |
pure | if True then only numbers match, otherwise include floats and integers. |
string Util::lpad | ( | softstring | text, |
int | length, | ||
string | padding = ' ' |
||
) |
Returns a string left-padded to a specified length with the specified characters.
Returns a string, left-padded to a specified length with the specified characters; or, when the string to be padded is longer than the length specified after padding, only that portion of the string that fits into the specified length.
text | input string that you want to pad |
length | total length of output string (in characters) |
padding | padding character(s); default value is a single blank |
string Util::make_uri_query | ( | hash< UriQueryInfo > | h, |
string | arg_separator = ';' |
||
) |
returns a serialized string for a UriQueryInfo hash
h | the UriQueryInfo hash to serialize |
arg_separator | the character to use to separate URI query arguments |
string Util::normalize_dir | ( | string | path, |
string | cwd = getcwd() |
||
) |
returns a platform-specific normalized path name (starting from /, eliminates "."
, ".."
, and "//"
)
Currently only Windows and UNIX-style directories are supported; this function calls either:
path | the path to normalize |
cwd | the current working directory for normalizing relative paths |
string Util::normalize_dir_unix | ( | string | path, |
string | cwd = getcwd() |
||
) |
returns a normalized UNIX path name (starting from /, eliminates "."
, ".."
, and "//"
)
For example, calling:
from current directory "/opt/qorus/sub/dir"
returns:
path | the path to normalize |
cwd | the current working directory |
"."
, ".."
, and "//"
) string Util::normalize_dir_windows | ( | string | path, |
string | cwd = getcwd() |
||
) |
returns a normalized Windows path name (eliminates "."
, ".."
, and "//"
)
For example, calling:
from current directory "c:\\lang\\qore\\prog1"
returns:
path | the path to normalize |
cwd | the current working directory |
"."
, ".."
, and "\\"
(except at the beginning of a UNC path) string Util::ordinal | ( | int | i | ) |
Returns string with partially textual representation of ordinal integer value.
i | integer value to convert to textual representation |
int Util::parse_memory_size | ( | string | str, |
*bool | use_binary | ||
) |
Returns a size in bytes from a string where "1M" = 1048576 and so forth.
str | the input string to parse |
use_binary | if True then base-2-based values are always assumed (i.e. "1 KB" = 1024 bytes and so forth) |
Known suffixes:
K
, KiB = one Kibibyte (1024 bytes)M
, MiB = one Mebibyte (1024 * 1024 bytes)G
, GiB = one Gibibyte (1024 * 1024 * 1024 bytes)KB
= 1,000 bytes (i.e. a "marketing kilobyte")MB
= 1,000,000 bytes (i.e. a "marketing megabyte")GB
= 1,000,000,000 bytes (i.e. a "marketing gigabyte") . and so onMEMORY-SIZE-ERROR | cannot parse string |
list< int > Util::parse_ranges | ( | string | text | ) |
Parses a string and returns a list of integers.
text | the string to parse |
auto Util::parse_to_qore_value | ( | string | arg | ) |
tries to convert a string (such as an argument given from the command-line) to a Qore value
This function recognizes two special prefixes in the string:
STR=
this prefix indicates that the rest of the string should be passed literally and not parsedEVAL=
this prefix indicates that the rest of the string should be taken as a Qore expression and executed and the value returnedStrings are interpreted as in the following table.
String Parsing
Format | Description |
key_string = value[, ...] | a hash |
value, [...] | a list |
integers | an integer |
floats | a float |
arbitrary-numeric value | a number |
True , true , False , false | a bool |
YYYY-MM-DD[[-T ]HH:mm[:SS[.uu]]] | a date |
a Qore expression | the value evaluated |
a quoted string | a string |
prompt% qore -l Util -X 'parse_to_qore_value("(a=(b=(c=x, 2, 3)))")' hash: (1 member) a : hash: (1 member) b : list: (3 elements) [0]=hash: (1 member) c : "x" [1]=2 [2]=3
arg | a string to convert to a Qore value according to the rules documented above |
PARSE-ERROR | cannot parse the string given |
hash< UriQueryInfo > Util::parse_uri_query | ( | string | path | ) |
parses a URI path for a arguments and a method; where the method is the part of the path before the first "?"
character, and arguments are after
path | the URI path to parse |
string Util::plural | ( | int | count, |
string | base, | ||
string | singular = '' , |
||
string | plural = 's' |
||
) |
Returns string with number and proper singular/plural form of noun.
count | integer value to convert |
base | base word or possibly nothing |
singular | singular form suffix or whole word |
plural | plural form suffix or whole word |
string Util::regex_escape | ( | string | text | ) |
Escapes (backslashes) all non-alphanumeric characters in a string.
Returns string with all non-alphanumerics backslashed; this is useful if you want to match an arbitrary literal string that may have regular expression metacharacters in it.
text | string to escape / backslash |
string Util::rpad | ( | softstring | text, |
int | length, | ||
string | padding = ' ' |
||
) |
Returns a string right-padded to a specified length with the specified characters.
Returns a string, right-padded to a specified length with the specified characters; or, when the string to be padded is longer than the length specified after padding, only that portion of the string that fits into the specified length.
text | input string that you want to pad |
length | total length of output string (in characters) |
padding | padding character(s); default value is a single blank |
bool Util::same | ( | list< auto > | l | ) |
checks whether given list has only unique elements
l | some list |
string Util::serialize_to_string | ( | auto | val | ) |
Serializes the given value to a string that can be deserialized with parse_to_qore_value()
val | the value to serialize to a string |
string
, int
, float
, bool
, date
(absolute), list
, and hash
values are supportedSERIALIZATION-ERROR | cannot serialize data type |
list< auto > Util::slice | ( | list< auto > | l, |
softlist< auto > | indices | ||
) |
list slice implementation
l | some list |
indices | indices that should be sliced from the original list |
bool Util::string_ends_with | ( | string | str, |
string | substr | ||
) |
Verifies whether a string ends with specific substring.
str | string to be checked |
substr | substring to look for at str's end |
bool Util::string_starts_with | ( | string | str, |
string | substr | ||
) |
Verifies whether a string begins with specific substring.
str | string to be checked |
substr | substring to look for at str's start |
string Util::substitute_env_vars | ( | string | str | ) |
Substitutes environment variables in a string and returns the string.
str | the string to process |
string Util::tmp_location | ( | ) |
Returns a path for temporary files.
Environment variables are searched in the following order (the first with a value is used):
TMPDIR
TMP
TEMP
TEMPDIR
If none of these are present, then "/tmp"
(UNIX) or "c:\temp"
(Windows) is checked.
TMP-ERROR | unable to find the location of the temporary directory; temporary directory is not writable |
list< auto > Util::uniq | ( | softlist< auto > | arg | ) |
Returns a duplicate-free version of the list.
arg | a list of values to filter out |
UNIQ-ERROR | if two different values from the list share the same implicit string representation |
list< auto > Util::zip | ( | ) |
Returns a list of lists, where the i-th list contains the i-th element from each of the argument lists.
... | lists to 'zip' |