OpenEuphoria: Euphoria v4.1

# OpenEuphoria Manual

## Euphoria v4.1

routine or constant name search

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.16 Sequence Manipulation | Up: 8 API Reference | 8.18 Sorting > | 9 Release Notes >>

## 8.17 Serialization of Euphoria Objects

### 8.17.1 Routines

#### 8.17.1.1 deserialize

    include std/serialize.e
    namespace serialize
    public function deserialize(object sdata, integer pos = 1)

converts a serialized object in to a standard Euphoria object.

##### Parameters:

1. `sdata` : either a sequence containing one or more concatenated serialized objects or an open file handle. If this is a file handle, the current position in the file is assumed to be at a serialized object in the file.
2. `pos` : optional index into `sdata`. If omitted 1 is assumed. The index must point to the start of a serialized object.

##### Returns:

The return value, depends on the input type.

- If `sdata` is a file handle then this function returns a Euphoria object that had been stored in the file, and moves the current file to the first byte after the stored object.
- If `sdata` is a sequence then this returns a two-element sequence. The first element is the Euphoria object that corresponds to the serialized object that begins at index `pos`, and the second element is the index position in the input parameter just after the serialized object.

##### Comments:

A serialized object is one that has been returned from the serialize function.

##### Example 1:

    sequence objcache
     objcache = serialize(FirstName) &
                serialize(LastName) &
                serialize(PhoneNumber) &
                serialize(Address)

     sequence res
     integer pos = 1
     res = deserialize( objcache , pos)
     FirstName = res[1] pos = res[2]
     res = deserialize( objcache , pos)
     LastName = res[1] pos = res[2]
     res = deserialize( objcache , pos)
     PhoneNumber = res[1] pos = res[2]
     res = deserialize( objcache , pos)
     Address = res[1] pos = res[2]

##### Example 2:

    sequence objcache
     objcache = serialize({FirstName,
                          LastName,
                          PhoneNumber,
                          Address})

     sequence res
     res = deserialize( objcache )
     FirstName = res[1][1]
     LastName = res[1][2]
     PhoneNumber = res[1][3]
     Address = res[1][4]

##### Example 3:

    integer fh
     fh = open("cust.dat", "wb")
     puts(fh, serialize(FirstName))
     puts(fh, serialize(LastName))
     puts(fh, serialize(PhoneNumber))
     puts(fh, serialize(Address))
     close(fh)

     fh = open("cust.dat", "rb")
     FirstName = deserialize(fh)
     LastName = deserialize(fh)
     PhoneNumber = deserialize(fh)
     Address = deserialize(fh)
     close(fh)

##### Example 4:

    integer fh
     fh = open("cust.dat", "wb")
     puts(fh, serialize({FirstName,
                         LastName,
                         PhoneNumber,
                         Address}))
     close(fh)

     sequence res
     fh = open("cust.dat", "rb")
     res = deserialize(fh)
     close(fh)
     FirstName = res[1]
     LastName = res[2]
     PhoneNumber = res[3]
     Address = res[4]

#### 8.17.1.2 serialize

    include std/serialize.e
    namespace serialize
    public function serialize(object x)

converts a standard Euphoria object in to a serialized version of it.

##### Parameters:

1. `euobj` : any Euphoria object.

##### Returns:

A sequence, this is the serialized version of the input object.

##### Comments:

A serialized object is one that has been converted to a set of byte values. This can then by written directly out to a file for storage.

You can use the deserialize function to convert it back into a standard Euphoria object.

##### Example 1:

    integer fh
     fh = open("cust.dat", "wb")
     puts(fh, serialize(FirstName))
     puts(fh, serialize(LastName))
     puts(fh, serialize(PhoneNumber))
     puts(fh, serialize(Address))
     close(fh)

     fh = open("cust.dat", "rb")
     FirstName = deserialize(fh)
     LastName = deserialize(fh)
     PhoneNumber = deserialize(fh)
     Address = deserialize(fh)
     close(fh)

##### Example 2:

    integer fh
     fh = open("cust.dat", "wb")
     puts(fh, serialize({FirstName,
                         LastName,
                         PhoneNumber,
                         Address}))
     close(fh)

     sequence res
     fh = open("cust.dat", "rb")
     res = deserialize(fh)
     close(fh)
     FirstName = res[1]
     LastName = res[2]
     PhoneNumber = res[3]
     Address = res[4]

#### 8.17.1.3 dump

    include std/serialize.e
    namespace serialize
    public function dump(sequence data, sequence filename)

saves a Euphoria object to disk in a binary format.

##### Parameters:

1. `data` : any Euphoria object.
2. `filename` : the name of the file to save it to.

##### Returns:

An integer, 0 if the function fails, otherwise the number of bytes in the created file.

##### Comments:

If the named file does not exist it is created, otherwise it is overwritten.

You can use the load function to recover the data from the file.

##### Example 1:

    include std/serialize.e
    integer size = dump(myData, theFileName)
    if size = 0 then
        puts(1, "Failed to save data to file\n")
    else
        printf(1, "Saved file is %d bytes long\n", size)
    end if

#### 8.17.1.4 load

    include std/serialize.e
    namespace serialize
    public function load(sequence filename)

restores a Euphoria object that has been saved to disk by dump.

##### Parameters:

1. `filename` : the name of the file to restore it from.

##### Returns:

A sequence, the first element is the result code. If the result code is 0 then it means that the function failed, otherwise the restored data is in the second element.

##### Comments:

This is used to load back data from a file created by the dump function.

##### Example 1:

    include std/serialize.e
    sequence mydata = load(theFileName)
    if mydata[1] = 0 then
        puts(1, "Failed to load data from file\n")
    else
        mydata = mydata[2] -- Restored data is in second element.
    end if

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.16 Sequence Manipulation | Up: 8 API Reference | 8.18 Sorting > | 9 Release Notes >>