Loading...
Searching...
No Matches
<binary> Class Reference

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

`#include <Pseudo_QC_Binary.dox.h>`

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

## Public Member Functions

bool | empty ()
| Returns True if the binary object is empty (size = 0), False if not.
int | find (data bin, softint byte_pos=0)
| Retrieves the byte position of a sequence of bytes within a binary object.
int | rfind (data bin, softint byte_pos=-1)
| Retrieves the byte position of a sequence of bytes within a binary object searching from the end of the binary object.
int | size ()
| Returns the number of bytes in the binary object.
bool | sizep ()
| Returns True since binary objects can return a non-zero size.
list< binary > | split (data 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.
binary | substr (softint start)
| Returns a portion of the binary data starting from an integer offset.
binary | substr (softint start, softint len)
| Returns a portion of the binary data starting from an integer offset.
string | toBase64 (softint maxlinelen=-1)
| Returns the base64-encoded representation of the binary object.
string | toBase64Url (softint maxlinelen=-1)
| Returns the base64-url-encoded representation of the binary object.
string | toHex ()
| returns a string of hexadecimal digits corresponding to the contents of the binary object; hex characters are always in lower case
string | toMD5 ()
| Returns the MD5 message digest of the binary data as a hex string.
string | toSHA1 ()
| Returns the SHA1 message digest of the binary data as a hex string.
string | toSHA224 ()
| Returns the SHA-224 message digest (a variant of SHA-2) of the binary data as a hex string.
string | toSHA256 ()
| Returns the SHA-256 message digest (a variant of SHA-2) of the binary data as a hex string.
string | toSHA384 ()
| Returns the SHA-384 message digest (a variant of SHA-2) of the binary data as a hex string.
string | toSHA512 ()
| Returns the SHA-512 message digest (a variant of SHA-2) of the binary data as a hex string.
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.
int | typeCode ()
| Returns Qore::NT_BINARY.
bool | val ()
| Returns False if the binary object is empty (size = 0), True if not.
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)
bool | complexType ()
| returns True if the value has a complex type, False if not
bool | empty ()
| Returns True; this method will be reimplemented in container types where it may return False.
string | fullType (*bool with_namespaces)
| returns the full type name which differs from the simple type name in case of complex types and objects
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.
AbstractIterator | iterator ()
| Returns an iterator object for the value; the default iterator object returned is SingleValueIterator.
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.
int | size ()
| Returns zero; this method will be reimplemented in container types where it may return a non-zero value.
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)
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.
bool | toBool ()
| Returns the boolean representation of the value; the default is False.
float | toFloat ()
| Returns the floating-point representation of the value; the default is 0.0.
int | toInt ()
| Returns the integer representation of the value; the default is 0.
number | toNumber ()
| Returns the arbitrary-precision numeric representation of the value; the default is 0.
string | toString (*string encoding)
| Returns the string representation of the value; the default is an empty string.
string | type ()
| Returns the string type for the value.
int | typeCode ()
| Returns the type code for the value.
bool | val ()
| Returns False; this method is reimplemented in other types and will return True if the given expression has a non-empty value.

## Detailed Description

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

## Member Function Documentation

## empty()

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:
  bool b = bin.empty();

## find()

int <binary>::find | ( | data | bin,
|  | softint | byte_pos = 0 )

Retrieves the byte position of a sequence of bytes within a binary object.

Code Flags:
  RET_VALUE_ONLY

Example:
  int i = bin.find(bin2);
  if (i == -1) {
  printf("could not find %y in %y\n", bin2, bin);
  }

Parameters

  bin | the byte sequence to find in the binary object
  byte_pos | the starting byte position for the search; if negative, then specifies an offset from the end of the current binary object

Returns
  the byte position of a sequence of bytes within a binary object, -1 is returned if the byte sequence is not found or if byte_pos specifies a position beyond the end of the string

Note
  an empty bin argument always matches

See also
  - <binary>::rfind(data, softint)

Since
  Qore 0.9.1

## rfind()

int <binary>::rfind | ( | data | bin,
|  | softint | byte_pos = -1 )

Retrieves the byte position of a sequence of bytes within a binary object searching from the end of the binary object.

Code Flags:
  RET_VALUE_ONLY

Example:
  int i = bin.rfind(bin2);
  if (i == -1) {
  printf("could not find %y in %y\n", bin2, bin);
  }

Parameters

  bin | the byte sequence to find in the binary object
  byte_pos | the starting byte position for the search; if negative, then specifies an offset from the end of the current binary object; if byte_pos specifies a position beyond the end of the string, then the search starts from the end of the string

Returns
  the byte position of a sequence of bytes within a binary object, -1 is returned if the byte sequence is not found

Note
  an empty bin argument always matches

See also
  - <binary>::find(data, softint)

Since
  Qore 0.9.1

## size()

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:
  int len = b.size();

See also
  <binary>::sizep()

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

## split()

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

Note
  equivalent to split(data, binary)

Since
  Qore 0.8.5

## substr() [1/2]

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
  binary b1 = b0.substr(-10);

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

Since
  Qore 0.8.8

## substr() [2/2]

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
  binary b1 = b0.substr(-10, 5);

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

Since
  Qore 0.8.8

## toBase64()

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

Returns the base64-encoded representation of the binary object.

Code Flags:
  CONSTANT

Example:
  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()
  - make_base64_string(binary, softint)

## toBase64Url()

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

Returns the base64-url-encoded representation of the binary object.

Base64-URL encoding is defined by RFC-4648

Code Flags:
  CONSTANT

Example:
  string base64 = bin.toBase64Url();

Returns
  the base64-url-encoded string of the data passed

Since
  Qore 1.19.0

See also
  - <string>::toBase64Url()
  - make_base64_url_string(binary)

## toHex()

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

returns a string of hexadecimal digits corresponding to the contents of the binary object; hex characters are always in lower case

Code Flags:
  CONSTANT

Example:
  string str = b.toHex();

Returns
  a string of hexadecimal digits corresponding to the contents of the binary object; hex characters are always in lower case

Since
  Qore 0.8.8

See also
  - <string>::toHex()
  - Qore::make_hex_string(binary)

## toMD5()

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

## toSHA1()

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

## toSHA224()

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

## toSHA256()

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

## toSHA384()

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

## toSHA512()

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

## toString()

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:
  string str = b.toString("iso-8859-1");

Since
  Qore 0.8.8

## typeCode()

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;
  }

## val()

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:
  bool b = bin.val();

See also
  - %perl-bool-eval
  - %strict-bool-eval