Binary

A Binary object represents a sequence of bytes and it can be created from a String in Base64 format, a verbatim String, or an Array containing byte values. A Binary can also be created from a Hash containing the value to convert to a Binary.

Binary algebra

  • A Binary can only be assigned a Binary value
  • A Binary has no type parameters

Binary.new

The signatures are:

type ByteInteger = Integer[0,255]
type Base64Format = Enum["%b", "%u", "%B", "%s"]
type StringHash = Struct[{value => String, "format" => Optional[Base64Format]}]
type ArrayHash = Struct[{value => Array[ByteInteger]}]
type BinaryArgsHash = Variant[StringHash, ArrayHash]

function Binary.new(
  String $base64_str,
  Optional[Base64Format] $format
)


function Binary.new(
  Array[ByteInteger] $byte_array
}

 # Same as for String, or for Array, but where arguments are given in a Hash.
 function Binary.new(BinaryArgsHash $hash_args)

The format codes represent the following data encoding formats:

Format Explanation
%b The data is in base64 encoding. Padding required by base64 strict encoding is added by default.
%u The data is in URL-safe base64 encoding.
%B The data is in base64 strict encoding.
%s The data is a Puppet string. If the string is not valid UTF-8 or convertible to UTF-8, Puppet raises an error.
%r The data is raw Ruby. The byte sequence in the given string is used verbatim irrespective of possible encoding errors.
  • The default format code is %B.
  • Avoid using the raw Ruby format %r. It exists for backward compatibility when a string received from some function should be treated as Binary. Such code should be changed to return a Binary instead of a String. This format will be deprecated in a future version of the specification when enough time has been given to migrate existing use of Ruby "binary strings", or Ruby strings that do not report accurate encoding.

Example: Creating Binary-typed content

# create the binary content "abc" from base64 encoded string
$a = Binary('YWJj')

# create the binary content from content in a module's file
$b = binary_file('mymodule/mypicture.jpg')