apt-pkg/cacheiterators.h

   1 // -*- mode: cpp; mode: fold -*-
   2 // Description                                                          /*{{{*/
   3 /* ######################################################################
   4
   5    Cache Iterators - Iterators for navigating the cache structure
   6
   7    The iterators all provides ++,==,!=,->,* and end for their type.
   8    The end function can be used to tell if the list has been fully
   9    traversed.
  10
  11    Unlike STL iterators these contain helper functions to access the data
  12    that is being iterated over. This is because the data structures can't
  13    be formed in a manner that is intuitive to use and also mmapable.
  14
  15    For each variable in the target structure that would need a translation
  16    to be accessed correctly a translating function of the same name is
  17    present in the iterator. If applicable the translating function will
  18    return an iterator.
  19
  20    The DepIterator can iterate over two lists, a list of 'version depends'
  21    or a list of 'package reverse depends'. The type is determined by the
  22    structure passed to the constructor, which should be the structure
  23    that has the depends pointer as a member. The provide iterator has the
  24    same system.
  25
  26    This header is not user includable, please use apt-pkg/pkgcache.h
  27
  28    ##################################################################### */
  29                                                                         /*}}}*/
  30 #ifndef PKGLIB_CACHEITERATORS_H
  31 #define PKGLIB_CACHEITERATORS_H
  32 #include<apt-pkg/pkgcache.h>
  33 #include<apt-pkg/macros.h>
  34
  35 #include<iterator>
  36 #include <iosfwd>
  37 #include <string>
  38
  39 #include<string.h>
  40
  41 // abstract Iterator template                                           /*{{{*/
  42 /* This template provides the very basic iterator methods we
  43    need to have for doing some walk-over-the-cache magic */
  44 template<typename Str, typename Itr> class pkgCache::Iterator :
  45                         public std::iterator<std::forward_iterator_tag, Str> {
  46         protected:
  47         Str *S;
  48         pkgCache *Owner;
  49
  50         /** \brief Returns the Pointer for this struct in the owner
  51          *  The implementation of this method should be pretty short
  52          *  as it will only return the Pointer into the mmap stored
  53          *  in the owner but the name of this pointer is different for
  54          *  each structure and we want to abstract here at least for the
  55          *  basic methods from the actual structure.
  56          *  \return Pointer to the first structure of this type
  57          */
  58         virtual Str* OwnerPointer() const = 0;
  59
  60         public:
  61         // Iteration
  62         virtual void operator ++(int) = 0;
  63         virtual void operator ++() = 0; // Should be {operator ++(0);}
  64         inline bool end() const {return Owner == 0 || S == OwnerPointer();}
  65
  66         // Comparison
  67         inline bool operator ==(const Itr &B) const {return S == B.S;}
  68         inline bool operator !=(const Itr &B) const {return S != B.S;}
  69
  70         // Accessors
  71         inline Str *operator ->() {return S;}
  72         inline Str const *operator ->() const {return S;}
  73         inline operator Str *() {return S == OwnerPointer() ? 0 : S;}
  74         inline operator Str const *() const {return S == OwnerPointer() ? 0 : S;}
  75         inline Str &operator *() {return *S;}
  76         inline Str const &operator *() const {return *S;}
  77         inline pkgCache *Cache() const {return Owner;}
  78
  79         // Mixed stuff
  80         inline void operator =(const Itr &B) {S = B.S; Owner = B.Owner;}
  81         inline bool IsGood() const { return S && Owner && ! end();}
  82         inline unsigned long Index() const {return S - OwnerPointer();}
  83
  84         void ReMap(void const * const oldMap, void const * const newMap) {
  85                 if (Owner == 0 || S == 0)
  86                         return;
  87                 S += (Str const * const)(newMap) - (Str const * const)(oldMap);
  88         }
  89
  90         // Constructors - look out for the variable assigning
  91         inline Iterator() : S(0), Owner(0) {}
  92         inline Iterator(pkgCache &Owner,Str *T = 0) : S(T), Owner(&Owner) {}
  93 };
  94                                                                         /*}}}*/
  95 // Group Iterator                                                       /*{{{*/
  96 /* Packages with the same name are collected in a Group so someone only
  97    interest in package names can iterate easily over the names, so the
  98    different architectures can be treated as of the "same" package
  99    (apt internally treat them as totally different packages) */
 100 class pkgCache::GrpIterator: public Iterator<Group, GrpIterator> {
 101         long HashIndex;
 102
 103         protected:
 104         inline Group* OwnerPointer() const {
 105                 return (Owner != 0) ? Owner->GrpP : 0;
 106         }
 107
 108         public:
 109         // This constructor is the 'begin' constructor, never use it.
 110         inline GrpIterator(pkgCache &Owner) : Iterator<Group, GrpIterator>(Owner), HashIndex(-1) {
 111                 S = OwnerPointer();
 112                 operator ++(0);
 113         }
 114
 115         virtual void operator ++(int);
 116         virtual void operator ++() {operator ++(0);}
 117
 118         inline const char *Name() const {return S->Name == 0?0:Owner->StrP + S->Name;}
 119         inline PkgIterator PackageList() const;
 120         PkgIterator FindPkg(std::string Arch = "any") const;
 121         /** \brief find the package with the "best" architecture
 122
 123             The best architecture is either the "native" or the first
 124             in the list of Architectures which is not an end-Pointer
 125
 126             \param PreferNonVirtual tries to respond with a non-virtual package
 127                    and only if this fails returns the best virtual package */
 128         PkgIterator FindPreferredPkg(bool const &PreferNonVirtual = true) const;
 129         PkgIterator NextPkg(PkgIterator const &Pkg) const;
 130
 131         // Constructors
 132         inline GrpIterator(pkgCache &Owner, Group *Trg) : Iterator<Group, GrpIterator>(Owner, Trg), HashIndex(0) {
 133                 if (S == 0)
 134                         S = OwnerPointer();
 135         }
 136         inline GrpIterator() : Iterator<Group, GrpIterator>(), HashIndex(0) {}
 137
 138 };
 139                                                                         /*}}}*/
 140 // Package Iterator                                                     /*{{{*/
 141 class pkgCache::PkgIterator: public Iterator<Package, PkgIterator> {
 142         long HashIndex;
 143
 144         protected:
 145         inline Package* OwnerPointer() const {
 146                 return (Owner != 0) ? Owner->PkgP : 0;
 147         }
 148
 149         public:
 150         // This constructor is the 'begin' constructor, never use it.
 151         inline PkgIterator(pkgCache &Owner) : Iterator<Package, PkgIterator>(Owner), HashIndex(-1) {
 152                 S = OwnerPointer();
 153                 operator ++(0);
 154         }
 155
 156         virtual void operator ++(int);
 157         virtual void operator ++() {operator ++(0);}
 158
 159         enum OkState {NeedsNothing,NeedsUnpack,NeedsConfigure};
 160
 161         // Accessors
 162         inline const char *Name() const {return S->Name == 0?0:Owner->StrP + S->Name;}
 163         inline const char *Section() const {return S->Section == 0?0:Owner->StrP + S->Section;}
 164         inline bool Purge() const {return S->CurrentState == pkgCache::State::Purge ||
 165                 (S->CurrentVer == 0 && S->CurrentState == pkgCache::State::NotInstalled);}
 166         inline const char *Arch() const {return S->Arch == 0?0:Owner->StrP + S->Arch;}
 167         inline APT_PURE GrpIterator Group() const { return GrpIterator(*Owner, Owner->GrpP + S->Group);}
 168
 169         inline VerIterator VersionList() const APT_PURE;
 170         inline VerIterator CurrentVer() const APT_PURE;
 171         inline DepIterator RevDependsList() const APT_PURE;
 172         inline PrvIterator ProvidesList() const APT_PURE;
 173         OkState State() const APT_PURE;
 174         const char *CandVersion() const APT_PURE;
 175         const char *CurVersion() const APT_PURE;
 176
 177         //Nice printable representation
 178         friend std::ostream& operator <<(std::ostream& out, PkgIterator i);
 179         std::string FullName(bool const &Pretty = false) const;
 180
 181         // Constructors
 182         inline PkgIterator(pkgCache &Owner,Package *Trg) : Iterator<Package, PkgIterator>(Owner, Trg), HashIndex(0) {
 183                 if (S == 0)
 184                         S = OwnerPointer();
 185         }
 186         inline PkgIterator() : Iterator<Package, PkgIterator>(), HashIndex(0) {}
 187 };
 188                                                                         /*}}}*/
 189 // Version Iterator                                                     /*{{{*/
 190 class pkgCache::VerIterator : public Iterator<Version, VerIterator> {
 191         protected:
 192         inline Version* OwnerPointer() const {
 193                 return (Owner != 0) ? Owner->VerP : 0;
 194         }
 195
 196         public:
 197         // Iteration
 198         void operator ++(int) {if (S != Owner->VerP) S = Owner->VerP + S->NextVer;}
 199         inline void operator ++() {operator ++(0);}
 200
 201         // Comparison
 202         int CompareVer(const VerIterator &B) const;
 203         /** \brief compares two version and returns if they are similar
 204
 205             This method should be used to identify if two pseudo versions are
 206             referring to the same "real" version */
 207         inline bool SimilarVer(const VerIterator &B) const {
 208                 return (B.end() == false && S->Hash == B->Hash && strcmp(VerStr(), B.VerStr()) == 0);
 209         }
 210
 211         // Accessors
 212         inline const char *VerStr() const {return S->VerStr == 0?0:Owner->StrP + S->VerStr;}
 213         inline const char *Section() const {return S->Section == 0?0:Owner->StrP + S->Section;}
 214         inline const char *Arch() const {
 215                 if ((S->MultiArch & pkgCache::Version::All) == pkgCache::Version::All)
 216                         return "all";
 217                 return S->ParentPkg == 0?0:Owner->StrP + ParentPkg()->Arch;
 218         }
 219         inline PkgIterator ParentPkg() const {return PkgIterator(*Owner,Owner->PkgP + S->ParentPkg);}
 220
 221         inline DescIterator DescriptionList() const;
 222         DescIterator TranslatedDescription() const;
 223         inline DepIterator DependsList() const;
 224         inline PrvIterator ProvidesList() const;
 225         inline VerFileIterator FileList() const;
 226         bool Downloadable() const;
 227         inline const char *PriorityType() const {return Owner->Priority(S->Priority);}
 228         const char *MultiArchType() const APT_PURE;
 229         std::string RelStr() const;
 230
 231         bool Automatic() const;
 232         VerFileIterator NewestFile() const;
 233
 234         inline VerIterator(pkgCache &Owner,Version *Trg = 0) : Iterator<Version, VerIterator>(Owner, Trg) {
 235                 if (S == 0)
 236                         S = OwnerPointer();
 237         }
 238         inline VerIterator() : Iterator<Version, VerIterator>() {}
 239 };
 240                                                                         /*}}}*/
 241 // Description Iterator                                                 /*{{{*/
 242 class pkgCache::DescIterator : public Iterator<Description, DescIterator> {
 243         protected:
 244         inline Description* OwnerPointer() const {
 245                 return (Owner != 0) ? Owner->DescP : 0;
 246         }
 247
 248         public:
 249         // Iteration
 250         void operator ++(int) {if (S != Owner->DescP) S = Owner->DescP + S->NextDesc;}
 251         inline void operator ++() {operator ++(0);}
 252
 253         // Comparison
 254         int CompareDesc(const DescIterator &B) const;
 255
 256         // Accessors
 257         inline const char *LanguageCode() const {return Owner->StrP + S->language_code;}
 258         inline const char *md5() const {return Owner->StrP + S->md5sum;}
 259         inline DescFileIterator FileList() const;
 260
 261         inline DescIterator() : Iterator<Description, DescIterator>() {}
 262         inline DescIterator(pkgCache &Owner,Description *Trg = 0) : Iterator<Description, DescIterator>(Owner, Trg) {
 263                 if (S == 0)
 264                         S = Owner.DescP;
 265         }
 266 };
 267                                                                         /*}}}*/
 268 // Dependency iterator                                                  /*{{{*/
 269 class pkgCache::DepIterator : public Iterator<Dependency, DepIterator> {
 270         enum {DepVer, DepRev} Type;
 271
 272         protected:
 273         inline Dependency* OwnerPointer() const {
 274                 return (Owner != 0) ? Owner->DepP : 0;
 275         }
 276
 277         public:
 278         // Iteration
 279         void operator ++(int) {if (S != Owner->DepP) S = Owner->DepP +
 280                 (Type == DepVer ? S->NextDepends : S->NextRevDepends);}
 281         inline void operator ++() {operator ++(0);}
 282
 283         // Accessors
 284         inline const char *TargetVer() const {return S->Version == 0?0:Owner->StrP + S->Version;}
 285         inline PkgIterator TargetPkg() const {return PkgIterator(*Owner,Owner->PkgP + S->Package);}
 286         inline PkgIterator SmartTargetPkg() const {PkgIterator R(*Owner,0);SmartTargetPkg(R);return R;}
 287         inline VerIterator ParentVer() const {return VerIterator(*Owner,Owner->VerP + S->ParentVer);}
 288         inline PkgIterator ParentPkg() const {return PkgIterator(*Owner,Owner->PkgP + Owner->VerP[S->ParentVer].ParentPkg);}
 289         inline bool Reverse() const {return Type == DepRev;}
 290         bool IsCritical() const APT_PURE;
 291         bool IsNegative() const APT_PURE;
 292         bool IsIgnorable(PrvIterator const &Prv) const APT_PURE;
 293         bool IsIgnorable(PkgIterator const &Pkg) const APT_PURE;
 294         bool IsMultiArchImplicit() const APT_PURE;
 295         bool IsSatisfied(VerIterator const &Ver) const APT_PURE;
 296         bool IsSatisfied(PrvIterator const &Prv) const APT_PURE;
 297         void GlobOr(DepIterator &Start,DepIterator &End);
 298         Version **AllTargets() const;
 299         bool SmartTargetPkg(PkgIterator &Result) const;
 300         inline const char *CompType() const {return Owner->CompType(S->CompareOp);}
 301         inline const char *DepType() const {return Owner->DepType(S->Type);}
 302
 303         //Nice printable representation
 304         friend std::ostream& operator <<(std::ostream& out, DepIterator D);
 305
 306         inline DepIterator(pkgCache &Owner, Dependency *Trg, Version* = 0) :
 307                 Iterator<Dependency, DepIterator>(Owner, Trg), Type(DepVer) {
 308                 if (S == 0)
 309                         S = Owner.DepP;
 310         }
 311         inline DepIterator(pkgCache &Owner, Dependency *Trg, Package*) :
 312                 Iterator<Dependency, DepIterator>(Owner, Trg), Type(DepRev) {
 313                 if (S == 0)
 314                         S = Owner.DepP;
 315         }
 316         inline DepIterator() : Iterator<Dependency, DepIterator>(), Type(DepVer) {}
 317 };
 318                                                                         /*}}}*/
 319 // Provides iterator                                                    /*{{{*/
 320 class pkgCache::PrvIterator : public Iterator<Provides, PrvIterator> {
 321         enum {PrvVer, PrvPkg} Type;
 322
 323         protected:
 324         inline Provides* OwnerPointer() const {
 325                 return (Owner != 0) ? Owner->ProvideP : 0;
 326         }
 327
 328         public:
 329         // Iteration
 330         void operator ++(int) {if (S != Owner->ProvideP) S = Owner->ProvideP +
 331                 (Type == PrvVer?S->NextPkgProv:S->NextProvides);}
 332         inline void operator ++() {operator ++(0);}
 333
 334         // Accessors
 335         inline const char *Name() const {return Owner->StrP + Owner->PkgP[S->ParentPkg].Name;}
 336         inline const char *ProvideVersion() const {return S->ProvideVersion == 0?0:Owner->StrP + S->ProvideVersion;}
 337         inline PkgIterator ParentPkg() const {return PkgIterator(*Owner,Owner->PkgP + S->ParentPkg);}
 338         inline VerIterator OwnerVer() const {return VerIterator(*Owner,Owner->VerP + S->Version);}
 339         inline PkgIterator OwnerPkg() const {return PkgIterator(*Owner,Owner->PkgP + Owner->VerP[S->Version].ParentPkg);}
 340
 341         bool IsMultiArchImplicit() const APT_PURE;
 342
 343         inline PrvIterator() : Iterator<Provides, PrvIterator>(), Type(PrvVer) {}
 344         inline PrvIterator(pkgCache &Owner, Provides *Trg, Version*) :
 345                 Iterator<Provides, PrvIterator>(Owner, Trg), Type(PrvVer) {
 346                 if (S == 0)
 347                         S = Owner.ProvideP;
 348         }
 349         inline PrvIterator(pkgCache &Owner, Provides *Trg, Package*) :
 350                 Iterator<Provides, PrvIterator>(Owner, Trg), Type(PrvPkg) {
 351                 if (S == 0)
 352                         S = Owner.ProvideP;
 353         }
 354 };
 355                                                                         /*}}}*/
 356 // Package file                                                         /*{{{*/
 357 class pkgCache::PkgFileIterator : public Iterator<PackageFile, PkgFileIterator> {
 358         protected:
 359         inline PackageFile* OwnerPointer() const {
 360                 return (Owner != 0) ? Owner->PkgFileP : 0;
 361         }
 362
 363         public:
 364         // Iteration
 365         void operator ++(int) {if (S != Owner->PkgFileP) S = Owner->PkgFileP + S->NextFile;}
 366         inline void operator ++() {operator ++(0);}
 367
 368         // Accessors
 369         inline const char *FileName() const {return S->FileName == 0?0:Owner->StrP + S->FileName;}
 370         inline const char *Archive() const {return S->Archive == 0?0:Owner->StrP + S->Archive;}
 371         inline const char *Component() const {return S->Component == 0?0:Owner->StrP + S->Component;}
 372         inline const char *Version() const {return S->Version == 0?0:Owner->StrP + S->Version;}
 373         inline const char *Origin() const {return S->Origin == 0?0:Owner->StrP + S->Origin;}
 374         inline const char *Codename() const {return S->Codename ==0?0:Owner->StrP + S->Codename;}
 375         inline const char *Label() const {return S->Label == 0?0:Owner->StrP + S->Label;}
 376         inline const char *Site() const {return S->Site == 0?0:Owner->StrP + S->Site;}
 377         inline const char *Architecture() const {return S->Architecture == 0?0:Owner->StrP + S->Architecture;}
 378         inline const char *IndexType() const {return S->IndexType == 0?0:Owner->StrP + S->IndexType;}
 379
 380         bool IsOk();
 381         std::string RelStr();
 382
 383         // Constructors
 384         inline PkgFileIterator() : Iterator<PackageFile, PkgFileIterator>() {}
 385         inline PkgFileIterator(pkgCache &Owner) : Iterator<PackageFile, PkgFileIterator>(Owner, Owner.PkgFileP) {}
 386         inline PkgFileIterator(pkgCache &Owner,PackageFile *Trg) : Iterator<PackageFile, PkgFileIterator>(Owner, Trg) {}
 387 };
 388                                                                         /*}}}*/
 389 // Version File                                                         /*{{{*/
 390 class pkgCache::VerFileIterator : public pkgCache::Iterator<VerFile, VerFileIterator> {
 391         protected:
 392         inline VerFile* OwnerPointer() const {
 393                 return (Owner != 0) ? Owner->VerFileP : 0;
 394         }
 395
 396         public:
 397         // Iteration
 398         void operator ++(int) {if (S != Owner->VerFileP) S = Owner->VerFileP + S->NextFile;}
 399         inline void operator ++() {operator ++(0);}
 400
 401         // Accessors
 402         inline PkgFileIterator File() const {return PkgFileIterator(*Owner,S->File + Owner->PkgFileP);}
 403
 404         inline VerFileIterator() : Iterator<VerFile, VerFileIterator>() {}
 405         inline VerFileIterator(pkgCache &Owner,VerFile *Trg) : Iterator<VerFile, VerFileIterator>(Owner, Trg) {}
 406 };
 407                                                                         /*}}}*/
 408 // Description File                                                     /*{{{*/
 409 class pkgCache::DescFileIterator : public Iterator<DescFile, DescFileIterator> {
 410         protected:
 411         inline DescFile* OwnerPointer() const {
 412                 return (Owner != 0) ? Owner->DescFileP : 0;
 413         }
 414
 415         public:
 416         // Iteration
 417         void operator ++(int) {if (S != Owner->DescFileP) S = Owner->DescFileP + S->NextFile;}
 418         inline void operator ++() {operator ++(0);}
 419
 420         // Accessors
 421         inline PkgFileIterator File() const {return PkgFileIterator(*Owner,S->File + Owner->PkgFileP);}
 422
 423         inline DescFileIterator() : Iterator<DescFile, DescFileIterator>() {}
 424         inline DescFileIterator(pkgCache &Owner,DescFile *Trg) : Iterator<DescFile, DescFileIterator>(Owner, Trg) {}
 425 };
 426                                                                         /*}}}*/
 427 // Inlined Begin functions can't be in the class because of order problems /*{{{*/
 428 inline pkgCache::PkgIterator pkgCache::GrpIterator::PackageList() const
 429        {return PkgIterator(*Owner,Owner->PkgP + S->FirstPackage);}
 430 inline pkgCache::VerIterator pkgCache::PkgIterator::VersionList() const
 431        {return VerIterator(*Owner,Owner->VerP + S->VersionList);}
 432 inline pkgCache::VerIterator pkgCache::PkgIterator::CurrentVer() const
 433        {return VerIterator(*Owner,Owner->VerP + S->CurrentVer);}
 434 inline pkgCache::DepIterator pkgCache::PkgIterator::RevDependsList() const
 435        {return DepIterator(*Owner,Owner->DepP + S->RevDepends,S);}
 436 inline pkgCache::PrvIterator pkgCache::PkgIterator::ProvidesList() const
 437        {return PrvIterator(*Owner,Owner->ProvideP + S->ProvidesList,S);}
 438 inline pkgCache::DescIterator pkgCache::VerIterator::DescriptionList() const
 439        {return DescIterator(*Owner,Owner->DescP + S->DescriptionList);}
 440 inline pkgCache::PrvIterator pkgCache::VerIterator::ProvidesList() const
 441        {return PrvIterator(*Owner,Owner->ProvideP + S->ProvidesList,S);}
 442 inline pkgCache::DepIterator pkgCache::VerIterator::DependsList() const
 443        {return DepIterator(*Owner,Owner->DepP + S->DependsList,S);}
 444 inline pkgCache::VerFileIterator pkgCache::VerIterator::FileList() const
 445        {return VerFileIterator(*Owner,Owner->VerFileP + S->FileList);}
 446 inline pkgCache::DescFileIterator pkgCache::DescIterator::FileList() const
 447        {return DescFileIterator(*Owner,Owner->DescFileP + S->FileList);}
 448                                                                         /*}}}*/
 449 #endif