GAP (Semigroups) - Chapter 17: IO

Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax on]

17 IO
17.1 Reading and writing elements to a file
17.1-1 ReadGenerators
17.1-2 WriteGenerators
17.1-3 IteratorFromGeneratorsFile
17.2 Reading and writing multiplication tables to a file
17.2-1 ReadMultiplicationTable
17.2-2 WriteMultiplicationTable
17.2-3 IteratorFromMultiplicationTableFile

### 17 IO

#### 17.1 Reading and writing elements to a file

The functions `ReadGenerators` (17.1-1) and `WriteGenerators` (17.1-2) can be used to read or write, respectively, elements of a semigroup to a file.

##### 17.1-1 ReadGenerators

`‣ ReadGenerators`( filename[, nr] ) | ( function )

Returns: A list of lists of semigroup elements.

If filename is an IO package file object or is the name of a file created using `WriteGenerators` (17.1-2), then `ReadGenerators` returns the contents of this file as a list of lists of elements of a semigroup.

If the optional second argument nr is present, then `ReadGenerators` returns the elements stored in the nrth line of filename.

    gap> file := Concatenation(SEMIGROUPS.PackageDir,
    > "/data/tst/testdata");;
    gap> ReadGenerators(file, 13);
    [ <identity partial perm on [ 2, 3, 4, 5, 6 ]>,
      <identity partial perm on [ 2, 3, 5, 6 ]>, [1,2](5)(6) ]

##### 17.1-2 WriteGenerators

`‣ WriteGenerators`( filename, list[, append][, function] ) | ( function )

Returns: `IO_OK` or `IO_ERROR`.

This function provides a method for writing collections of elements of a semigroup to a file. The resulting file can be further compressed using `gzip` or `xz`.

The argument list should be a list of lists of elements, or semigroups.

The argument filename should be a string containing the name of a file or an IO package file object where the entries in list will be written; see `IO_File` (IO: IO_File mode) and `IO_CompressedFile` (IO: IO_CompressedFile).

If the optional third argument append is not present or is given and equals `"w"`, then the previous content of the file is deleted and overwritten. If the third argument is `"a"`, then `list` is appended to the file.

If any element of list is a semigroup, then the generators of that semigroup are written to filename. More specifically, the list returned by `GeneratorsOfSemigroup` (Reference: GeneratorsOfSemigroup) is written to the file.

This function returns `IO_OK` (IO: IO_OK) if everything went well or `IO_ERROR` (IO: IO_Error) if something went wrong.

The file produced by `WriteGenerators` can be read using `ReadGenerators` (17.1-1).

From Version 3.0.0 onwards the Semigroups package used the IO package pickling functionality; see IO: Pickling and unpickling for more details. This approach is used because it is more general and more robust than the methods used by earlier versions of Semigroups, although the performance is somewhat worse, and the resulting files are somewhat larger.

##### 17.1-3 IteratorFromGeneratorsFile

`‣ IteratorFromGeneratorsFile`( filename ) | ( function )

Returns: An iterator.

If filename is a file or a string containing the name of a file created using `WriteGenerators` (17.1-2), then `IteratorFromGeneratorsFile` returns an iterator `iter` such that `NextIterator(iter)` returns the next collection of generators stored in the file filename.

This function is a convenient way of, for example, looping over a collection of generators in a file without loading every object in the file into memory. This might be useful if the file contains more information than there is available memory.

If you want to get an iterator for a file written using `WriteGenerators` from a version of Semigroups before version 3.0.0, then you can use `IteratorFromOldGeneratorsFile`.

#### 17.2 Reading and writing multiplication tables to a file

The functions `ReadMultiplicationTable` (17.2-1) and `WriteMultiplicationTable` (17.2-2) can be used to read or write, respectively, multiplication tables to a file.

##### 17.2-1 ReadMultiplicationTable

`‣ ReadMultiplicationTable`( filename[, nr] ) | ( function )

Returns: A list of multiplication tables.

If filename is a file or is the name of a file created using `WriteMultiplicationTable` (17.2-2), then `ReadMultiplicationTable` returns the contents of this file as a list of multiplication tables.

If the optional second argument nr is present, then `ReadMultiplicationTable` returns the multiplication table stored in the nrth line of filename.

    gap> file := Concatenation(SEMIGROUPS.PackageDir,
    > "/data/tst/tables.gz");;
    gap> tab := ReadMultiplicationTable(file, 12);
    [ [ 1, 1, 3, 4, 5, 6, 7, 8, 9, 6 ], [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ],
      [ 3, 3, 1, 5, 4, 7, 6, 9, 8, 7 ], [ 4, 4, 9, 6, 3, 8, 5, 1, 7, 8 ],
      [ 5, 5, 8, 7, 1, 9, 4, 3, 6, 9 ], [ 6, 6, 7, 8, 9, 1, 3, 4, 5, 1 ],
      [ 7, 7, 6, 9, 8, 3, 1, 5, 4, 3 ], [ 8, 8, 5, 1, 7, 4, 9, 6, 3, 4 ],
      [ 9, 9, 4, 3, 6, 5, 8, 7, 1, 5 ], [ 6, 10, 7, 8, 9, 1, 3, 4, 5, 2 ]
     ]

##### 17.2-2 WriteMultiplicationTable

`‣ WriteMultiplicationTable`( filename, list[, append] ) | ( function )

Returns: `IO_OK` or `IO_ERROR`.

This function provides a method for writing collections of multiplication tables to a file. The resulting file can be further compressed using `gzip` or `xz`. This function applies to square arrays with a maximum of 255 rows where the entries are integers from `[1, 2, .., n]` (where `n` is the number of rows in the array.

The argument list should be a list of multiplication tables.

The argument filename should be a file or a string containing the name of a file where the entries in list will be written or an IO package file object; see `IO_File` (IO: IO_File mode) and `IO_CompressedFile` (IO: IO_CompressedFile).

If the optional third argument append is not present or is given and equals `"w"`, then the previous content of the file is deleted and overwritten. If the third argument is given and equals `"a"` then `list` is appended to the file. This function returns `IO_OK` (IO: IO_OK) if everything went well or `IO_ERROR` (IO: IO_Error) if something went wrong.

The multiplication tables saved in filename can be recovered from the file using `ReadMultiplicationTable` (17.2-1).

##### 17.2-3 IteratorFromMultiplicationTableFile

`‣ IteratorFromMultiplicationTableFile`( filename ) | ( function )

Returns: An iterator.

If filename is a file or a string containing the name of a file created using `WriteMultiplicationTable` (17.2-2), then `IteratorFromMultiplicationTableFile` returns an iterator `iter` such that `NextIterator(iter)` returns the next multiplication table stored in the file filename.

This function is a convenient way of, for example, looping over a collection of multiplication tables in a file without loading every object in the file into memory. This might be useful if the file contains more information than there is available memory.

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 Bib Ind

generated by GAPDoc2HTML