Util Namespace Reference

the Util namespace contains all the objects in the Util module More...

## Classes

struct | UriQueryInfo
| the return value of the parse_uri_query() function More...

## Functions

bool | absolute_path (string path)
| returns True if the argument is an absolute path, False if not More...
bool | absolute_path_unix (string path)
| returns True if the argument is a UNIX absolute path, False if not More...
bool | absolute_path_windows (string path)
| returns True if the argument is a Windows absolute path, False if not More...
int | compare_version (string lv, string rv)
| compares complex versions by breaking down strings into component parts More...
list | flatten (softlist arg)
| Flattens a nested list (the nesting can be to any depth). More...
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 More...
string | get_exception_string (hash ex)
| returns a multi-line string from the exception hash argument suitable for logging or output on the console More...
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 More...
string | get_random_string (softint len=15, int level=3)
| function that returns a random string More...
string | glob_to_regex (string pat)
| Translates a shell pattern to a regular expression. More...
bool | is_float (string text, bool pure=False)
| Checks whether string represents a (true) float value. More...
bool | is_int (string text, bool pure=False)
| Checks whether string represents a (true) integer value. More...
bool | is_number (string text, bool pure=False)
| Checks whether string represents a (true) number value. More...
string | lpad (softstring text, int length, string padding=' ')
| Returns a string left-padded to a specified length with the specified characters. More...
string | make_uri_query (hash< UriQueryInfo > h, string arg_separator=";")
| returns a serialized string for a UriQueryInfo hash More...
string | normalize_dir (string dir, string cwd=getcwd())
| returns a platform-specific normalized path name (starting from /, eliminates `"."`, `".."`, and `"//"`) More...
string | normalize_dir_unix (string dir, string cwd=getcwd())
| returns a normalized UNIX path name (starting from /, eliminates `"."`, `".."`, and `"//"`) More...
string | normalize_dir_windows (string dir, string cwd=getcwd())
| returns a normalized Windows path name (eliminates `"."`, `".."`, and `"//"`) More...
string | ordinal (int i)
| Returns string with partially textual representation of ordinal integer value. More...
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 More...
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 More...
string | plural (int count, string base, string singular="", string plural="s")
| Returns string with number and proper singular/plural form of noun. More...
string | regex_escape (string text)
| Escapes (backslashes) all non-alphanumeric characters in a string. More...
string | rpad (softstring text, int length, string padding=' ')
| Returns a string right-padded to a specified length with the specified characters. More...
bool | same (list l)
| checks whether given list has only uniq element More...
list | slice (list l, softlist indices)
| list slice implementation More...
string | tmp_location ()
| Returns a path for temporary files. More...
list | uniq (softlist arg)
| Returns a duplicate-free version of the list. More...
list | zip ()
| Returns a list of lists, where the i-th list contains the i-th element from each of the argument lists. More...

## Variables

const | StorageNames = ("Kilo", "Mega", "Giga", "Tera", "Peta", "Exa", "Zetta", "Yotta", "Bronto")
| storage names (Geop, which would normally follow Bronto, is excluded as the abbreviation would be GB/GiB)

## Detailed Description

the Util namespace contains all the objects in the Util module

## Function Documentation

## compare_version()

int Util::compare_version | ( | string | lv,
|  | string | rv
| ) |  |

compares complex versions by breaking down strings into component parts

Example:
  int result = compare_version("2.11.1", "2.2");

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)

Parameters

  lv | left-hand version
  rv | right-hand version

Returns
  -1 if lv < rv, 0 if equal, and 1 if lv > rv

## flatten()

list Util::flatten | ( | softlist | arg | ) |

Flattens a nested list (the nesting can be to any depth).

Parameters

  arg | a list to flatten

Returns
  a flattened list

Example:
  list f = flatten (((1, 2), (3, 4), 5)); # returns (1, 2, 3, 4, 5)

Since
  Util 1.3

## get_byte_size()

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

Example:
  string str = get_byte_size(n);

Parameters

  n | the number to display
  decimals | the number of digits after the decimal point

## get_exception_string()

string Util::get_exception_string | ( | hash | ex | ) |

returns a multi-line string from the exception hash argument suitable for logging or output on the console

Parameters

  ex | the exception hash to process

Returns
  a multi-line string from the exception hash argument suitable for logging or output on the console

## get_marketing_byte_size()

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

Example:
  string str = get_marketing_byte_size(n);

Parameters

  n | the number to display
  decimals | the number of digits after the decimal point

## get_random_string()

string Util::get_random_string | ( | softint | len = `15`,
|  | int | level = `3`
| ) |  |

function that returns a random string

Example:
  string pass = get_random_string();

Parameters

  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):
  - 1: only upper case
  - 2: +lower case
  - 3: +numbers
  - 4: +symbols but not including any quote characters

Returns
  a random string of the given length containing only printable ASCII characters according to the level argument

See also
  Qore::get_random_bytes()

## glob_to_regex()

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.

Parameters

  pat | the pattern to convert

Returns
  a converted pattern

Example:
  string s = glob_to_regex ("*.*"); # returns ".*\\..*"

Since
  Util 1.2

## is_float()

bool Util::is_float | ( | string | text,
|  | bool | pure = `False`
| ) |  |

Checks whether string represents a (true) float value.

Parameters

  text | a string to check
  pure | if True then only floats match, otherwise include integers.

Returns
  True if input represents a float value, False otherwise.

Example:
  bool match = is_float("1.2");
  # returns True, while any of the following returns False:
  match = is_float("12", True);
  match = is_float("1.2x");

Note
  The function only checks whether a string represents a float value, but it does not validate size / precision restrictions (whether it would fit Qore's native float type).

Since
  Util 1.2

## is_int()

bool Util::is_int | ( | string | text,
|  | bool | pure = `False`
| ) |  |

Checks whether string represents a (true) integer value.

Parameters

  text | a string to check
  pure | if True then only integers match, otherwise check floats too.

Returns
  True if input represents an integer value, False otherwise.

Example:
  bool match = is_int("123");
  # returns True, while any of the following returns False:
  match = is_int("1.0", True);
  match = is_int("12x");

Note
  The function only checks whether a string represents an integer value, but it does not validate size restrictions (that is whether it would fit Qore's native int type) etc.

Since
  Util 1.2

## is_number()

bool Util::is_number | ( | string | text,
|  | bool | pure = `False`
| ) |  |

Checks whether string represents a (true) number value.

Parameters

  text | a string to check
  pure | if True then only numbers match, otherwise include floats and integers.

Returns
  True if input represents a number value, False otherwise.

Example:
  bool match = is_number("1.2n");
  # returns True, while any of the following returns False:
  match = is_number("12", True);
  match = is_number("1.2", True);
  match = is_number("1.2x");

Note
  The function only checks whether a string represents an arbitrary precision number value, but it does not validate any restrictions (whether it would fit Qore's native number type).

Since
  Util 1.2

## lpad()

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.

Parameters

  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

Returns
  a string left-padded to the specified length

Example:
  string s = lpad ("123", 5); # returns " 123"
  string s = lpad ("ABC", 9, "-"); # returns "------ABC"

Since
  Util 1.2

## make_uri_query()

string Util::make_uri_query | ( | hash< UriQueryInfo > | h,
|  | string | arg_separator = `";"`
| ) |  |

returns a serialized string for a UriQueryInfo hash

Parameters

  h | the UriQueryInfo hash to serialize
  arg_separator | the character to use to separate URI query arguments

Since
  Util 1.3

## normalize_dir()

string Util::normalize_dir | ( | string | dir,
|  | string | cwd = `getcwd()`
| ) |  |

returns a platform-specific normalized path name (starting from /, eliminates `"."`, `".."`, and `"//"`)

Example:
  string dir = normalize_dir(dir);

Currently only Windows and UNIX-style directories are supported; this function calls either:

- Util::normalize_dir_unix() or
- Util::normalize_dir_windows()

Parameters

  dir | the directory name to normalize
  cwd | the current working directory for normalizing relative paths

Returns
  a normalized path name for the current platform

See also
  - Util::normalize_dir_unix() or
  - Util::normalize_dir_windows()

## normalize_dir_unix()

string Util::normalize_dir_unix | ( | string | dir,
|  | string | cwd = `getcwd()`
| ) |  |

returns a normalized UNIX path name (starting from /, eliminates `"."`, `".."`, and `"//"`)

Example:
  string dir = normalize_dir_unix(dir, "/var/tmp");

For example, calling:

normalize_dir("../../test/.//dir");

from current directory `"/opt/qorus/sub/dir"` returns:

"/opt/qorus/test/dir"

Parameters

  dir | the directory name to normalize
  cwd | the current working directory

Returns
  a normalized path name (starting from /, eliminates `"."`, `".."`, and `"//"`)

## normalize_dir_windows()

string Util::normalize_dir_windows | ( | string | dir,
|  | string | cwd = `getcwd()`
| ) |  |

returns a normalized Windows path name (eliminates `"."`, `".."`, and `"//"`)

Example:
  string dir = normalize_dir_windows(dir, "c:\\qore"));

For example, calling:

normalize_dir("..\..\test\.\\dir");

from current directory `"c:\\lang\\qore\\prog1"` returns:

"c:\\lang\\test\\dir"

Parameters

  dir | the directory name to normalize
  cwd | the current working directory

Returns
  a normalized path name; eliminates `"."`, `".."`, and `"\\"` (except at the beginning of a UNC path)

## ordinal()

string Util::ordinal | ( | int | i | ) |

Returns string with partially textual representation of ordinal integer value.

Example:
  printf ("%s grade", ordinal(1));
  # would print "1st grade"

Parameters

  i | integer value to convert to textual representation

Returns
  a string representation of ordinal value of the argument

Since
  Util 1.2

## parse_to_qore_value()

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 parsed
- `EVAL=` this prefix indicates that the rest of the string should be taken as a Qore expression and executed and the value returned

Strings 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

Examples:

      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

Parameters

  arg | a string to convert to a Qore value according to the rules documented above

Returns
  the Qore value corresponding to the input string

Exceptions

  PARSE-ERROR | cannot parse the string given

## parse_uri_query()

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

Parameters

  path | the URI path to parse

Returns
  a UriQueryInfo hash

Note
  the params output key value is always returned as a hash

Since
  Util 1.3

## plural()

string Util::plural | ( | int | count,
|  | string | base,
|  | string | singular = `""`,
|  | string | plural = `"s"`
| ) |  |

Returns string with number and proper singular/plural form of noun.

Parameters

  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

Returns
  a string representation of number plus noun

Example:
  printf (plural(1, "beer"));
  # would print "1 beer"
  printf (plural(1, "lad", "y", "ies"));
  # would print "1 lady"
  printf (plural(32, "", "tooth", "teeth"));
  # would print "32 teeth"

Since
  Util 1.2

## regex_escape()

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.

Parameters

  text | string to escape / backslash

Returns
  a string escaped / backslashed

Example:
  string s = regex_escape ("Gain: $100"); # returns "Gain\\:\\ \\$100"

Since
  Util 1.2

## rpad()

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.

Parameters

  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

Returns
  a string right-padded to the specified length

Example:
  string s = rpad ("123", 5); # returns "123 "
  string s = rpad ("ABC", 9, "-"); # returns "ABC------"

Since
  Util 1.2

## same()

bool Util::same | ( | list | l | ) |

checks whether given list has only uniq element

Example:
  if (same((1, 1, 1)) {
  printf("only uniq element");
  };

Parameters

  l | some list

Since
  Util 1.2

## slice()

list Util::slice | ( | list | l,
|  | softlist | indices
| ) |  |

list slice implementation

Example:
  list_slice(("a", "b", "c", "d"), (1, 3)); # returns ("b", "d")

Parameters

  l | some list
  indices | indices that should be sliced from the original list

Since
  Util 1.2

## tmp_location()

string Util::tmp_location | ( |  | ) |

Returns a path for temporary files.

Example:
  string testfile = tmp_location() + '/test.txt';
  # some processing
  unlink(testfile);

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.

Exceptions

  TMP-ERROR | unable to find the location of the temporary directory; temporary directory is not writable

Since
  Util 1.2

## uniq()

list Util::uniq | ( | softlist | arg | ) |

Returns a duplicate-free version of the list.

Parameters

  arg | a list of values to filter out

Returns
  a list of unique values

Example:
  list u = uniq ((1,2,1,3,2,1)); # returns (1,2,3)

Note
  Since implementation of this function uses hash to keep track of the list values, it cannot safely process values which implicit string representation collide (e.g. float values that differ outside implicit toString() precision).

Exceptions

  UNIQ-ERROR | if two different values from the list share the same implicit string representation

Since
  Util 1.3

## zip()

list Util::zip | ( |  | ) |

Returns a list of lists, where the i-th list contains the i-th element from each of the argument lists.

Parameters

  ... | lists to 'zip'

Returns
  a list of lists

Example:
  list z = zip ((1, 2, 3), (4, 5)); # returns ((1,4), (2,5), (3,NOTHING))

Since
  Util 1.2