Util Namespace Reference

the Util namespace contains all the objects in the Util module 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...
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...
string | lpad (softstring text, int length, string padding= ' ')
| Returns a string left-padded to a specified length with the specified characters. 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...
any | 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...
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 | 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

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

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

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

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

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

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

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

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

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 `"//"`)

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)

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

any 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.qm -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

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

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

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

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

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

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

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 s = zip ((1, 2, 3), (4, 5)); # returns ((1,4), (2,5), (3,NOTHING))

Since
  Util 1.2