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