Qore Programming Language Reference Manual  1.7.0
<binary> Class Reference

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

Inheritance diagram for Qore::<binary>:

Public Member Methods

bool empty ()
 Returns True if the binary object is empty (size = 0), False if not. More...
 
int find (data bin, softint byte_pos=0)
 Retrieves the byte position of a sequence of bytes within a binary object. More...
 
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. 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< binarysplit (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. 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; hex characters are always in lower case 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 Methods 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 complexType ()
 returns True if the value has a complex type, False if not More...
 
bool empty ()
 Returns True; this method will be reimplemented in container types where it may return False. More...
 
string fullType (*bool with_namespaces)
 returns the full type name which differs from the simple type name in case of complex types and objects 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 non-empty value. More...
 

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);
}
string printf(string fmt,...)
Outputs the string passed to standard output, using the first argument as a format string; does not e...
Parameters
binthe byte sequence to find in the binary object
byte_posthe 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
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
binthe byte sequence to find in the binary object
byte_posthe 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
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
septhe 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
startThe 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
startThe 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
lenThe 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
maxlinelenthe 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

◆ 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

◆ 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"
binary binary()
Always returns an empty binary object (of zero length)
Exceptions
MD5-DIGEST-ERRORerror 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
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-ERRORerror calculating digest (should not normally happen)
Note
equivalent to SHA1()
See also
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-ERRORerror calculating digest (should not normally happen)
Note
equivalent to SHA224()
See also
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-ERRORerror calculating digest (should not normally happen)
Note
equivalent to SHA256()
See also
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-ERRORerror calculating digest (should not normally happen)
Note
equivalent to SHA384()
See also
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-ERRORerror calculating digest (should not normally happen)
Note
equivalent to SHA512()
See also
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
encodingthe 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