Qore Programming Language Reference Manual: <binary> Class Reference

Qore Programming Language Reference Manual 0.8.11

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | List of all members
<binary> Class Reference

Methods in this pseudo-class can be executed on binary values. More...

Inheritance diagram for Qore::<binary>:
[legend]

## Public Member Functions
bool | empty ()
| Returns True if the binary object is empty (size = 0), False if not. More...
int | size ()
| Returns the number of bytes in the binary object. More...
bool | sizep ()
| Returns True since binary objects can return a non-zero size. More...
list | split (binary sep)
| 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...
binary | substr (softint start)
| Returns a portion of the binary data starting from an integer offset. More...
binary | substr (softint start, softint len)
| Returns a portion of the binary data starting from an integer offset. More...
string | toBase64 (softint maxlinelen=-1)
| Returns the base64-encoded representation of the binary object. More...
string | toHex ()
| returns a string of hexadecimal digits corresponding to the contents of the binary object More...
string | toMD5 ()
| Returns the MD5 message digest of the binary data as a hex string. More...
string | toSHA1 ()
| Returns the SHA1 message digest of the binary data as a hex string. More...
string | toSHA224 ()
| Returns the SHA-224 message digest (a variant of SHA-2) of the binary data as a hex string. More...
string | toSHA256 ()
| Returns the SHA-256 message digest (a variant of SHA-2) of the binary data as a hex string. More...
string | toSHA384 ()
| Returns the SHA-384 message digest (a variant of SHA-2) of the binary data as a hex string. More...
string | toSHA512 ()
| Returns the SHA-512 message digest (a variant of SHA-2) of the binary data as a hex string. More...
string | toString (*string encoding)
| Returns a string created from the binary data, taking an optional second argument giving the string encoding; if no second argument is passed then the default character encoding is assumed. More...
int | typeCode ()
| Returns Qore::NT_BINARY. More...
bool | val ()
| Returns False if the binary object is empty (size = 0), True if not. More...
Public Member Functions inherited from <value>
bool | callp ()
| Returns False; this method is reimplemented in other types and will return True if the given expression is a callable value (ie closures or call references) More...
bool | empty ()
| Returns True; this method will be reimplemented in container types where it may return False. More...
bool | intp ()
| Returns False; this method is reimplemented in other types and will return True if the given expression can be converted to an integer. More...
AbstractIterator | iterator ()
| Returns an iterator object for the value; the default iterator object returned is SingleValueIterator. More...
int | lsize ()
| Returns 1; the return value of this method should give the list size of the value, which is normally 1 for non-lists (except for NOTHING where the size will be 0) and the number of the elements in the list for lists; this method will be reimplemented in other types where it may return other values. More...
int | size ()
| Returns zero; this method will be reimplemented in container types where it may return a non-zero value. More...
bool | sizep ()
| Returns True if the type can return a non-zero size (True for containers including binary objects and strings, False for everything else) More...
bool | strp ()
| Returns False; this method is reimplemented in other types and will return True if the given expression can be converted to a string. More...
bool | toBool ()
| Returns the boolean representation of the value; the default is False. More...
float | toFloat ()
| Returns the floating-point representation of the value; the default is 0.0. More...
int | toInt ()
| Returns the integer representation of the value; the default is 0. More...
number | toNumber ()
| Returns the arbitrary-precision numeric representation of the value; the default is 0. More...
string | toString ()
| Returns the string representation of the value; the default is an empty string. More...
string | type ()
| Returns the string type for the value. More...
int | typeCode ()
| Returns the type code for the value. More...
bool | val ()
| Returns False; this method is reimplemented in other types and will return True if the given expression has a value that would be converted to True according to the rules described in %perl-bool-eval. More...

## Detailed Description

Methods in this pseudo-class can be executed on binary values.

## Member Function Documentation

bool <binary>::empty | ( |  | ) |

Returns True if the binary object is empty (size = 0), False if not.

The opposite of <binary>::val()

Returns
  True if the binary object is empty (size = 0), False if not

Code Flags:
  CONSTANT

Example:
  my bool $b = $bin.empty();

int <binary>::size | ( |  | ) |

Returns the number of bytes in the binary object.

Returns
  the number of bytes in the binary object

Code Flags:
  CONSTANT

Example:
  my int $len = $b.size();

See Also
  <binary>::sizep()

bool <binary>::sizep | ( |  | ) |

Returns True since binary objects can return a non-zero size.

Code Flags:
  CONSTANT

Returns
  True since binary objects can return a non-zero size

See Also
  <binary>::size()

Since
  Qore 0.8.9

list <binary>::split | ( | binary | sep | ) |

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

  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:
  my list $l = $bin.split($sep);

Note
  equivalent to split(binary, binary)

Since
  Qore 0.8.5

binary <binary>::substr | ( | softint | start | ) |

Returns a portion of the binary data starting from an integer offset.

Arguments can be negative, giving offsets from the end of the data.

Code Flags:
  CONSTANT

Parameters

  start | The starting byte for the portion of the data 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 data starting from an integer bte offset; the rest of the data is returned after this offset

Example:
  # get the last 10 bytes of a binary object
  my binary $b1 = $b0.substr(-10);

Note
  equivalent to Qore::substr(binary, softint)

Since
  Qore 0.8.8

binary <binary>::substr | ( | softint | start,
|  | softint | len
| ) |  |

Returns a portion of the binary data starting from an integer offset.

Arguments can be negative, giving offsets from the end of the data.

Code Flags:
  CONSTANT

Parameters

  start | The starting byte for the portion of the data 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 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 portion of the data starting from an integer bte offset; the rest of the data is returned after this offset

Example:
  # get the last 5 bytes of the last 10 bytes of a binary object
  my binary $b1 = $b0.substr(-10, 5);

Note
  equivalent to Qore::substr(binary, softint, softint)

Since
  Qore 0.8.8

string <binary>::toBase64 | ( | softint | maxlinelen = `-1` | ) |

Returns the base64-encoded representation of the binary object.

Code Flags:
  CONSTANT

Example:
  my string $base64 = $bin.toBase64(64);

Implementation based on RFC-1421 and RFC-2045

Parameters

  maxlinelen | the maximum length of a line in the resulting output string in bytes; if this value is > 0 then output lines will be separated by CRLF characters

Returns
  the base64-encoded string of the data passed

Since
  Qore 0.8.8

See Also
  - <string>::toBase64()
  - makeBase64String(binary)

string <binary>::toHex | ( |  | ) |

returns a string of hexadecimal digits corresponding to the contents of the binary object

Code Flags:
  CONSTANT

Example:
  my string $str = $b.toHex();

Returns
  a string of hexadecimal digits corresponding to the contents of the binary object

Since
  Qore 0.8.8

See Also
  - <string>::toHex()
  - Qore::makeHexString(binary)

string <binary>::toMD5 | ( |  | ) |

Returns the MD5 message digest of the binary data as a hex string.

The trailing null character is not included in the digest returned.

Returns
  a hex string of the digest (ex: `"5d41402abc4b2a76b9719d911017c592"`)

Code Flags:
  RET_VALUE_ONLY

Example:
  my string $str = binary("hello").toMD5(); # returns "5d41402abc4b2a76b9719d911017c592"

Exceptions

  MD5-DIGEST-ERROR | error calculating digest (should not normally happen)

Note
  - equivalent to MD5()
  - the MD5 algorithm is not collision-resistant; it's recommended to use another hash algorithm (like SHA-256) if cryptographic security is important

See Also
  - MD5_bin()
  - <string>::toMD5()

Since
  Qore 0.8.5

string <binary>::toSHA1 | ( |  | ) |

Returns the SHA1 message digest of the binary data as a hex string.

The trailing null character is not included in the digest returned.

Returns
  a hex string of the digest (ex: `"aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"`)

Code Flags:
  RET_VALUE_ONLY

Example:
  my string $str = binary("hello").toSHA1(); # returns "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"

Exceptions

  SHA1-DIGEST-ERROR | error calculating digest (should not normally happen)

Note
  equivalent to SHA1()

See Also
  - SHA1_bin()
  - <string>::toSHA1()

Since
  Qore 0.8.5

string <binary>::toSHA224 | ( |  | ) |

Returns the SHA-224 message digest (a variant of SHA-2) of the binary data as a hex string.

The trailing null character is not included in the digest returned.

Platform Availability:
  Qore::Option::HAVE_SHA224

Code Flags:
  RET_VALUE_ONLY

Returns
  a hex string of the digest (ex: `"ea09ae9cc6768c50fcee903ed054556e5bfc8347907f12598aa24193"`)

Example:
  my string $str = binary("hello").toSHA224("hello"); # returns "ea09ae9cc6768c50fcee903ed054556e5bfc8347907f12598aa24193"

Exceptions

  SHA224-DIGEST-ERROR | error calculating digest (should not normally happen)

Note
  equivalent to SHA224()

See Also
  - SHA224_bin()
  - <string>::toSHA224()

Since
  Qore 0.8.5

string <binary>::toSHA256 | ( |  | ) |

Returns the SHA-256 message digest (a variant of SHA-2) of the binary data as a hex string.

The trailing null character is not included in the digest returned.

Platform Availability:
  Qore::Option::HAVE_SHA256

Code Flags:
  RET_VALUE_ONLY

Returns
  a hex string of the digest (ex: `"2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"`)

Example:
  my string $str = binary("hello").toSHA256(); # returns "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

Exceptions

  SHA256-DIGEST-ERROR | error calculating digest (should not normally happen)

Note
  equivalent to SHA256()

See Also
  - SHA256_bin()
  - <string>::toSHA256()

Since
  Qore 0.8.5

string <binary>::toSHA384 | ( |  | ) |

Returns the SHA-384 message digest (a variant of SHA-2) of the binary data as a hex string.

The trailing null character is not included in the digest returned.

Platform Availability:
  Qore::Option::HAVE_SHA384

Code Flags:
  RET_VALUE_ONLY

Returns
  a hex string of the digest (ex: `"59e1748777448c69de6b800d7a33bbfb9ff1b463e44354c3553bcdb9c666fa90125a3c79f90397bdf5f6a13de828684f"`)

Example:
  my string $str = binary("hello").toSHA384(); # returns "59e1748777448c69de6b800d7a33bbfb9ff1b463e44354c3553bcdb9c666fa90125a3c79f90397bdf5f6a13de828684f"

Exceptions

  SHA384-DIGEST-ERROR | error calculating digest (should not normally happen)

Note
  equivalent to SHA384()

See Also
  - SHA384_bin()
  - <string>::toSHA384()

Since
  Qore 0.8.5

string <binary>::toSHA512 | ( |  | ) |

Returns the SHA-512 message digest (a variant of SHA-2) of the binary data as a hex string.

The trailing null character is not included in the digest returned.

Platform Availability:
  Qore::Option::HAVE_SHA512

Code Flags:
  RET_VALUE_ONLY

Returns
  a hex string of the digest (ex: `"9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043"`)

Example:
  my string $str = binary("hello").toSHA512(); # returns "9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043"

Exceptions

  SHA512-DIGEST-ERROR | error calculating digest (should not normally happen)

Note
  equivalent to SHA512()

See Also
  - SHA512_bin()
  - <string>::toSHA512()

Since
  Qore 0.8.5

string <binary>::toString | ( | *string | encoding | ) |

Returns a string created from the binary data, taking an optional second argument giving the string encoding; if no second argument is passed then the default character encoding is assumed.

Code Flags:
  CONSTANT

Parameters

  encoding | the character encoding tag for the string return value; if not present, the default character encoding is assumed

Returns
  a string created from the binary data passed

Example:
  my string $str = $b.toString($b, "iso-8859-1");

Since
  Qore 0.8.8

int <binary>::typeCode | ( |  | ) |

Returns Qore::NT_BINARY.

Returns
  Qore::NT_BINARY

Code Flags:
  CONSTANT

Example:
  switch ($b.typeCode()) {
  case NT_BINARY:
  printf("%y: is a binary\n", $b);
  break;
  }

bool <binary>::val | ( |  | ) |

Returns False if the binary object is empty (size = 0), True if not.

The opposite of <binary>::empty()

Returns
  False if the binary object is empty (size = 0), True if not

Code Flags:
  CONSTANT

Example:
  my bool $b = $bin.val();

See Also
  - %perl-bool-eval
  - %strict-bool-eval