bin2raw               package:caTools               R Documentation

_C_o_n_v_e_r_t _R _v_e_c_t_o_r_s _t_o/_f_r_o_m _t_h_e _r_a_w _b_i_n_a_r_y _f_o_r_m_a_t

_D_e_s_c_r_i_p_t_i_o_n:

     Convert R vectors of any type to and from the raw binary format,
     stored as  vector of type "raw".

_U_s_a_g_e:

       r = bin2raw(x, size=NA, endian=.Platform$endian)
       x = raw2bin(r, what, size=NA, signed = TRUE, endian=.Platform$endian)

_A_r_g_u_m_e_n_t_s:

       x: vector or any structure that can be converted to a vector by 
           'as.vector' function. Strings are also allowed.

       r: vector of type "raw"

    what: Either an object whose mode will give the mode of the vector
          to be created, or a character vector of length one describing
          the mode: one of '"numeric", "double", "integer", "int",
          "logical", "complex", "character", "raw". Same as variable 
          'what' in 'readBin' and 'base64decode' functions. 

    size: integer.  The number of bytes per element in the byte stream 
          stored in 'r'. The default, ''NA'', uses the natural size.
          See  details. 

  signed: logical. Only used for integers of sizes 1 and 2, when it
          determines if the quantity stored as raw should be regarded
          as a signed or unsigned integer.

  endian: If provided, can be used to swap endian-ness. Using '"swap"' 
          will force swapping of byte order. Use '"big"' (big-endian,
          aka IEEE,  aka "network") or '"little"' (little-endian,
          format used on PC/Intel  machines) to indicate type of data
          encoded in "raw" format.

_D_e_t_a_i_l_s:

     Quoting from 'readBin' documentation:

     "If 'size' is specified and not the natural size of the object,
     each element of the vector is coerced to an appropriate type
     before being written or as it is read.  Possible sizes are 1, 2, 4
     and possibly 8 for integer or logical vectors, and 4, 8 and
     possibly 12/16 for numeric vectors.  (Note that coercion occurs as
     signed types except if 'signed = FALSE' when reading integers of
     sizes 1 and 2.) Changing sizes is unlikely to preserve 'NA's, and
     the extended precision sizes are unlikely to be portable across
     platforms."

     Default 'size's for different types: 'logical' - 4,  'integer' -
     4, 'double' - 8 , 'complex' - 16,  'character' - 2, 'raw' - 1.

_V_a_l_u_e:

     Function 'bin2raw' returns vector of raw values (see 'r'  above),
     where each 1-byte raw value correspond to 1-byte of 1-byte of the 
     binary form of other types. Length of the vector is going to be
     "number of  bytes of a  single element in array 'x'" times
     'length(x)'.

     Function 'raw2bin' returns vector of appropriate mode  and length
     (see 'x' above), where each 1-byte raw value correspond to  1-byte
     of the binary form of other types. Length of the vector is going
     to  be number of bytes per element in array 'x' times 'length(x)'.
      If parameter 'what' is equal to "character" than a string (of
     length 1) is returned instead of vector f characters.

_N_o_t_e:

     At the moment those two functions use calls to 'writeBin'  and
     'readBin' functions to do the job. I hope to change it in  the
     future by writing a C code.

_A_u_t_h_o_r(_s):

     Jarek Tuszynski (SAIC) jaroslaw.w.tuszynski@saic.com

_S_e_e _A_l_s_o:

     'readBin', 'writeBin'

_E_x_a_m_p_l_e_s:

        x = (10*runif(10)>5) # logical
        for (i in c(NA, 1, 2, 4)) {
          y = bin2raw(x, size=i)
          z = raw2bin(y,typeof(x), size=i)
          stopifnot(x==z)
        }
        print("Checked bin2raw and raw2bin conversion for logical type")
        
        x = as.integer(1:10) # integer
        for (i in c(NA, 1, 2, 4)) {
          y = bin2raw(x, size=i)
          z = raw2bin(y,typeof(x), size=i)
          stopifnot(x==z)
        }
        print("Checked bin2raw and raw2bin conversion for integer type")
       
        x = (1:10)*pi        # double
        for (i in c(NA, 4, 8)) {
          y = bin2raw(x, size=i)
          z = raw2bin(y,typeof(x), size=i)
          stopifnot(mean(abs(x-z))<1e-5)
        }
        print("Checked bin2raw and raw2bin conversion for double type")
        
        x = log(as.complex(-(1:10)*pi))        # complex
        y = bin2raw(x)
        z = raw2bin(y,typeof(x))
        stopifnot(x==z)
        print("Checked bin2raw and raw2bin conversion for complex type")
        
        x = "Chance favors the prepared mind" # character
        y = bin2raw(x)
        z = raw2bin(y,typeof(x))
        stopifnot(x==z)
        print("Checked bin2raw and raw2bin conversion for character type")

