.TH "FBB::Glob" "3bobcat" "2005\-2024" "libbobcat\-dev_6\&.06\&.02" "Files matching a pattern"

.PP 
.SH "NAME"
FBB::Glob \- Wrapper around \fBglob\fP(3) to find files matching a pattern
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/glob>\fP
.br 
Linking option: \fI\-lbobcat\fP
.PP 
.SH "DESCRIPTION"
The \fBFBB::Glob\fP class is a wrapper around the \fBC\fP function
\fBglob\fP(3)\&. It returns a list of files matching a certain pattern provided to
\fBFBB::Glob\fP\(cq\&s constructors or members\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
\-
.PP 
.SH "ENUMERATIONS"

.PP 
\fBGlob::Type\fP: 
.br 
This enumeration, which is identical to the \fBstat\fP(3bobcat) \fIType\fP
enumeration, defines the following values:
.IP o 
\fBBLOCK_DEVICE\fP (0060000): the object is a block device;
.IP o 
\fBCHARACTER_DEVICE\fP (0020000): the object is a character
device;
.IP o 
\fBDIRECTORY\fP (0040000): the object is a directory;
.IP o 
\fBFIFO\fP (0010000): the object is a named pipe (a queue);
.IP o 
\fBREGULAR_FILE\fP (0100000): the object is a regular file;
.IP o 
\fBSOCKET\fP (0140000): the object is a socket;
.IP o 
\fBSYMBOLIC_LINK\fP (0120000): the object is a symbolic link;
.IP o 
\fBANY\fP: any of the above types\&.

.PP 
These values are also used by \fBstat\fP(2) and \fBlstat\fP(2)\&. Although they
can be combined using the \fIbitor\fP operator, they are not uniquely
recognizable when combined\&. E\&.g\&., the value of \fICHARACTER_DEVICE |
DIRECTORY\fP is equal to the value of \fIBLOCK_DEVICE\fP\&. It\(cq\&s also possible
to combine \fIType\fP values in a \fIstd::unordered_set\fP, which avoids the
confusion that may result from using the \fIbitor\fP operator\&.
.PP 
\fBGlob::Flags\fP:
.IP o 
\fINO_FLAG\fP:   Equals 0, and can be used to avoid having to specify 0\&. It
has no further use\&.
.IP o 
\fIERR\fP: Return on read errors;
.IP o 
\fIMARK\fP: Append a slash to each name\&.
.IP o 
\fINOSORT\fP: Don\(cq\&t sort the names\&.
.IP o 
\fINOESCAPE\fP: Backslashes don\(cq\&t quote metacharacters\&.
.IP o 
\fIPERIOD\fP: Leading \fI\&.\fP\-characters can be matched by metachars (i\&.e\&.,
\fI*\fP and \fI?\fP)\&.
.IP o 
\fINOMATCH\fP: When specified the constructors won\(cq\&t throw exceptions when
no files matching their glob\-patterns could be found\&. Instead they
will return normally, and \fIGlob\(cq\&s size()\fP member (see below) will
return 0\&.

.PP 
\fBGlob::Dots\fP:
.IP o 
\fIFIRST\fP: Filenames starting with a dot will be listed first\&. Within
this set and in the leftover\-set the relative ordering is maintained\&.
.IP o 
\fIDEFAULT\fP: Return filenames as they appear in the globbing process\&.

.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBGlob(std::string const &pattern = \(dq\&*\(dq\&, int flags = PERIOD,
Dots dots = FIRST)\fP:
.br 
This constructor (which can also be used as the default constructor)
determines all elements matching \fIpattern\fP\&.
.IP 
An \fIException\fP exception is thrown if the constructor could not
properly complete it tasks\&.
.IP 
Multiple flags may be specified, separated by the \fIbitor\fP operator\&.
.IP 
This constructor properly completes its task if only defined \fBFlag\fP
values were specified and if the \fBglob\fP(3) function returned without
errors;
.IP 
.IP o 
\fBGlob(Type type, std::string const &pattern = \(dq\&*\(dq\&, int flags = PERIOD,
Dots dots = FIRST)\fP:
.br 
This constructor determines all elements of \fIpattern\fP when their
types `\fIelementType\fP\(cq\& are equal to the value of \fIelementType &
type\fP\&. The specified \fItype\fP value may consist of any \fIbitor\fP\-ed
combination of enum values defined by the \fIType\fP enum\&. Note that
this may produce confusing results\&. E\&.g\&., when specifying
\fIDIRECTORY\fP, elements that are \fIBLOCK_DEVICEs\fP or \fISOCKETs\fP are
also accepted\&. The next constructor can be used to avoid this
confusion;
.IP 
.IP o 
\fBGlob(std::unordered_set<Type> const &typeSet,
std::string const &pattern = \(dq\&*\(dq\&, int flags = PERIOD,
Dots dots = FIRST)\fP:
.br 
This constructor determines all elements of \fIpattern\fP when their
types are found in \fItypeSet\fP\&. Different from the previous
constructor, for an element to be accepted its type must exactly match
a type value in the \fItypeSet\fP set\&.

.PP 
Copy and move constructors (and assignment operators) are available\&.
.PP 
.SH "OVERLOADED OPERATORS"
.IP o 
\fBchar const *operator[](size_t idx) const\fP:
.br 
The element at index position \fIidx\fP is returns as a \fBC\fP string\&. It
returns an empty string if \fIidx\fP is or exceeds \fBsize()\fP\&.

.PP 
.SH "MEMBER FUNCTIONS"
.IP o 
\fBsize_t size() const\fP:
.br 
Returns the number of elements that were detected;
.IP o 
\fBchar const *const *begin() const\fP:
.br 
Returns a pointer to the first element that was detected\&. This pointer
can be used in generic algorithms as an output\-iterator supporting
pointer arithmetic;
.IP o 
\fBchar const *const *end() const\fP:
.br 
Returns a pointer beyond the last element that was detected\&. This
pointer can be used in generic algorithms as an output\-iterator
supporting pointer arithmetic;
.IP o 
\fBvoid swap(Glob &other)\fP:
.br 
Swaps the content of the other object with the current object\&.

.PP 
.SH "EXAMPLES"
.nf 

    int main(int argc, char **argv)
    {
        if (argc == 1)
        {
            cout << \(dq\&Provide glob\-expression as 1st arg\en\(dq\&;
            return 1;
        }

        cout << \(dq\&General:\en\(dq\&;

        Glob general;

        for (size_t idx = 0; idx < general\&.size(); idx++)
            cout << idx << \(dq\&: \(dq\& << general[idx] << endl;

        cout << \(dq\&Pattern: \(dq\& << argv[1] << \(dq\&\en\(dq\&;

        Glob pattern(argv[1], Glob::PERIOD, Glob::DEFAULT);

        for (size_t idx = 0; idx < pattern\&.size(); idx++)
            cout << idx << \(dq\&: \(dq\& << pattern[idx] << endl;
    }
        
.fi 

.PP 
.SH "FILES"
\fIbobcat/glob\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBstat\fP(3bobcat), \fBglob\fP(3)
.PP 
.SH "BUGS"
No Reported Bugs\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_6\&.06\&.02\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.06\&.02\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.06\&.02\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.06\&.02\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.06\&.02\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP