All Classes Namespaces Functions Variables Groups Pages
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 | 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...
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...

## 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

bool Util::absolute_path | ( | string | path | ) |

returns True if the argument is an absolute path, False if not

Example:
  my bool $abs = absolute_path($path);

Parameters

  $path | the path to check

Returns
  True if the argument is an absolute path, False if not

bool Util::absolute_path_unix | ( | string | path | ) |

returns True if the argument is a UNIX absolute path, False if not

Example:
  my bool $abs = absolute_path_unix($path);

Parameters

  $path | the path to check

Returns
  True if the argument is a UNIX absolute path, False if not

bool Util::absolute_path_windows | ( | string | path | ) |

returns True if the argument is a Windows absolute path, False if not

Example:
  my bool $abs = absolute_path_windows($path);

Parameters

  $path | the path to check

Returns
  True if the argument is a Windows absolute path, False if not

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

compares complex versions by breaking down strings into component parts

Example:
  my 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:
  my 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:
  my 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:
  my 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::normalize_dir | ( | string | dir,
|  | string | cwd = `getcwd()`
| ) |  |

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

Example:
  my 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:
  my 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:
  my 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

Returns
  a normalized path name (eliminates `"."`, `".."`, and `"\\"`)

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 method 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

Parameters

  arg | a string to convert to a Qore value

Returns
  the Qore value corresponding to the input string