Reference Manual

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members

# Inti::G::Dir Class Reference

A GDir C++ wrapper interface. More...

`#include <inti/glib/fileutils.h>`

Inheritance diagram for Inti::G::Dir:

List of all members.

## Public Member Functions

Constructors

- Dir ()
    Constructs an empty directory object.
- Dir (const char *path, G::Error *error)
    Constructs a directory object and opens the directory path.
- Dir (const std::string &path, G::Error *error)
    Constructs a directory object and opens the directory path.
- ~Dir ()
    Destructor; Closes the directory if it's open.

Accessors

- bool is_open () const
    Determines whether the directory is open.

Methods

- bool open (const char *path, G::Error *error)
    Opens a directory for reading.
- const char * read_name ()
    Retrieves the name of the next entry in the directory (the '.' and '..' entries are omitted).
- int read_names (std::vector< String > &names)
    Gets a list of the names of all the entries in the directory (the '.' and '..' entries are omitted).
- void rewind ()
    Resets the given directory so that the next call to read_name() will return the first entry again.
- void close ()
    Closes the directory and deallocates all related resources.

## Detailed Description

A GDir C++ wrapper interface.

Dir is an object that represents a file directory. Dir is a StackObject, that is it must created on the stack. You can't allocate Dir dynamically.

Example 1: You can construct an empty directory object using the default constructor and then call open().

        G::Dir dir;
        std::string dirname("/home");
        if (dir.open(dirname))
        {
            // read directory
        }
        dir.close();

Example 2: Alternatively you can construct and open a directory object in one step by calling one of the parameterized constructors.

        std::string dirname;
        G::Error error;
        G::Dir dir(dirname, &error);
        if (dir.is_open())
        {
            // read directory
        }
        dir.close();

You don't have to explicitly call Dir::close() as above, unless you want to. When a directory object goes out of scope its destructor will check for an open directory and close it.

For convenience the entries in a directory can be read individually by calling read_name() or at once by calling read_names(). The latter method fills a user-supplied 'std::vector of String' with the entry names.

## Constructor & Destructor Documentation

Inti::G::Dir::Dir | ( | const char * | path,
|  | G::Error * | error
| ) |

Constructs a directory object and opens the directory path.

Parameters:

  path | The path to the directory you are interested in.
  error | The return location for a G::Error, or null.

If the directory path is successfully opened is_open() returns true. If an error occurs is_open() returns false and error will contain information about the error.

Inti::G::Dir::Dir | ( | const std::string & | path,
|  | G::Error * | error
| ) |

Constructs a directory object and opens the directory path.

Parameters:

  path | The path to the directory you are interested in.
  error | The return location for a G::Error, or null.

If the directory path is successfully opened is_open() returns true. If an error occurs is_open() returns false and error will contain information about the error.

## Member Function Documentation

bool Inti::G::Dir::is_open | ( |  | ) | const

Determines whether the directory is open.

Returns:
  true if the directory is open.

bool Inti::G::Dir::open | ( | const char * | path,
|  | G::Error * | error
| ) |

Opens a directory for reading.

Parameters:

  path | The path to the directory you are interested in.
  error | The return location for a G::Error, or null.

Returns:
  true if this method is successful, false otherwise.

The names of the files in the directory can then be retrieved using read_name(). If error is non-null, an error will be set if and only if this method fails. If successful you can either explicitly call close() or let the dir object call close() when it goes out of scope.

const char* Inti::G::Dir::read_name | ( |  | ) |

Retrieves the name of the next entry in the directory (the '.' and '..' entries are omitted).

Returns:
  The entry's name or null if there are no more entries.

The return value is owned by GLib and must not be modified or freed.

int Inti::G::Dir::read_names | ( | std::vector< String > & | names | ) |

Gets a list of the names of all the entries in the directory (the '.' and '..' entries are omitted).

Parameters:

  names | A reference to a vector of String to hold the names.

Returns:
  -1 on failure, otherwise an integer value indicating the degree of success.

This method retrieves the name of each entry and calls String::from_filename() to convert the string from the encoding used for filenames into a UTF-8 String. If this method successfully converts all entry names the return value is 0. If any entry names couldn't be converted the return value is the number of failed conversions. If you want to know the entry names of all failed conversions you should call read_name() instead.

The documentation for this class was generated from the following file:

- fileutils.h

Main Page - Footer