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         // Versions have sections - and packages can have different versions with different sections
 164         // so this interface is broken by design. Run as fast as you can to Version.Section().
 165         APT_DEPRECATED inline const char *Section() const {return S->Section == 0?0:Owner->StrP + S->Section;}
 166         inline bool Purge() const {return S->CurrentState == pkgCache::State::Purge ||
 167                 (S->CurrentVer == 0 && S->CurrentState == pkgCache::State::NotInstalled);}
 168         inline const char *Arch() const {return S->Arch == 0?0:Owner->StrP + S->Arch;}
 169         inline APT_PURE GrpIterator Group() const { return GrpIterator(*Owner, Owner->GrpP + S->Group);}
 170
 171         inline VerIterator VersionList() const APT_PURE;
 172         inline VerIterator CurrentVer() const APT_PURE;
 173         inline DepIterator RevDependsList() const APT_PURE;
 174         inline PrvIterator ProvidesList() const APT_PURE;
 175         OkState State() const APT_PURE;
 176         const char *CandVersion() const APT_PURE;
 177         const char *CurVersion() const APT_PURE;
 178
 179         //Nice printable representation
 180         friend std::ostream& operator <<(std::ostream& out, PkgIterator i);
 181         std::string FullName(bool const &Pretty = false) const;
 182
 183         // Constructors
 184         inline PkgIterator(pkgCache &Owner,Package *Trg) : Iterator<Package, PkgIterator>(Owner, Trg), HashIndex(0) {
 185                 if (S == 0)
 186                         S = OwnerPointer();
 187         }
 188         inline PkgIterator() : Iterator<Package, PkgIterator>(), HashIndex(0) {}
 189 };
 190                                                                         /*}}}*/
 191 // Version Iterator                                                     /*{{{*/
 192 class pkgCache::VerIterator : public Iterator<Version, VerIterator> {
 193         protected:
 194         inline Version* OwnerPointer() const {
 195                 return (Owner != 0) ? Owner->VerP : 0;
 196         }
 197
 198         public:
 199         // Iteration
 200         void operator ++(int) {if (S != Owner->VerP) S = Owner->VerP + S->NextVer;}
 201         inline void operator ++() {operator ++(0);}
 202
 203         // Comparison
 204         int CompareVer(const VerIterator &B) const;
 205         /** \brief compares two version and returns if they are similar
 206
 207             This method should be used to identify if two pseudo versions are
 208             referring to the same "real" version */
 209         inline bool SimilarVer(const VerIterator &B) const {
 210                 return (B.end() == false && S->Hash == B->Hash && strcmp(VerStr(), B.VerStr()) == 0);
 211         }
 212
 213         // Accessors
 214         inline const char *VerStr() const {return S->VerStr == 0?0:Owner->StrP + S->VerStr;}
 215         inline const char *Section() const {return S->Section == 0?0:Owner->StrP + S->Section;}
 216         inline const char *Arch() const {
 217                 if ((S->MultiArch & pkgCache::Version::All) == pkgCache::Version::All)
 218                         return "all";
 219                 return S->ParentPkg == 0?0:Owner->StrP + ParentPkg()->Arch;
 220         }
 221         inline PkgIterator ParentPkg() const {return PkgIterator(*Owner,Owner->PkgP + S->ParentPkg);}
 222
 223         inline DescIterator DescriptionList() const;
 224         DescIterator TranslatedDescription() const;
 225         inline DepIterator DependsList() const;
 226         inline PrvIterator ProvidesList() const;
 227         inline VerFileIterator FileList() const;
 228         bool Downloadable() const;
 229         inline const char *PriorityType() const {return Owner->Priority(S->Priority);}
 230         const char *MultiArchType() const APT_PURE;
 231         std::string RelStr() const;
 232
 233         bool Automatic() const;
 234         VerFileIterator NewestFile() const;
 235
 236         inline VerIterator(pkgCache &Owner,Version *Trg = 0) : Iterator<Version, VerIterator>(Owner, Trg) {
 237                 if (S == 0)
 238                         S = OwnerPointer();
 239         }
 240         inline VerIterator() : Iterator<Version, VerIterator>() {}
 241 };
 242                                                                         /*}}}*/
 243 // Description Iterator                                                 /*{{{*/
 244 class pkgCache::DescIterator : public Iterator<Description, DescIterator> {
 245         protected:
 246         inline Description* OwnerPointer() const {
 247                 return (Owner != 0) ? Owner->DescP : 0;
 248         }
 249
 250         public:
 251         // Iteration
 252         void operator ++(int) {if (S != Owner->DescP) S = Owner->DescP + S->NextDesc;}
 253         inline void operator ++() {operator ++(0);}
 254
 255         // Comparison
 256         int CompareDesc(const DescIterator &B) const;
 257
 258         // Accessors
 259         inline const char *LanguageCode() const {return Owner->StrP + S->language_code;}
 260         inline const char *md5() const {return Owner->StrP + S->md5sum;}
 261         inline DescFileIterator FileList() const;
 262
 263         inline DescIterator() : Iterator<Description, DescIterator>() {}
 264         inline DescIterator(pkgCache &Owner,Description *Trg = 0) : Iterator<Description, DescIterator>(Owner, Trg) {
 265                 if (S == 0)
 266                         S = Owner.DescP;
 267         }
 268 };
 269                                                                         /*}}}*/
 270 // Dependency iterator                                                  /*{{{*/
 271 class pkgCache::DepIterator : public Iterator<Dependency, DepIterator> {
 272         enum {DepVer, DepRev} Type;
 273
 274         protected:
 275         inline Dependency* OwnerPointer() const {
 276                 return (Owner != 0) ? Owner->DepP : 0;
 277         }
 278
 279         public:
 280         // Iteration
 281         void operator ++(int) {if (S != Owner->DepP) S = Owner->DepP +
 282                 (Type == DepVer ? S->NextDepends : S->NextRevDepends);}
 283         inline void operator ++() {operator ++(0);}
 284
 285         // Accessors
 286         inline const char *TargetVer() const {return S->Version == 0?0:Owner->StrP + S->Version;}
 287         inline PkgIterator TargetPkg() const {return PkgIterator(*Owner,Owner->PkgP + S->Package);}
 288         inline PkgIterator SmartTargetPkg() const {PkgIterator R(*Owner,0);SmartTargetPkg(R);return R;}
 289         inline VerIterator ParentVer() const {return VerIterator(*Owner,Owner->VerP + S->ParentVer);}
 290         inline PkgIterator ParentPkg() const {return PkgIterator(*Owner,Owner->PkgP + Owner->VerP[S->ParentVer].ParentPkg);}
 291         inline bool Reverse() const {return Type == DepRev;}
 292         bool IsCritical() const APT_PURE;
 293         bool IsNegative() const APT_PURE;
 294         bool IsIgnorable(PrvIterator const &Prv) const APT_PURE;
 295         bool IsIgnorable(PkgIterator const &Pkg) const APT_PURE;
 296         bool IsMultiArchImplicit() const APT_PURE;
 297         bool IsSatisfied(VerIterator const &Ver) const APT_PURE;
 298         bool IsSatisfied(PrvIterator const &Prv) const APT_PURE;
 299         void GlobOr(DepIterator &Start,DepIterator &End);
 300         Version **AllTargets() const;
 301         bool SmartTargetPkg(PkgIterator &Result) const;
 302         inline const char *CompType() const {return Owner->CompType(S->CompareOp);}
 303         inline const char *DepType() const {return Owner->DepType(S->Type);}
 304
 305         //Nice printable representation
 306         friend std::ostream& operator <<(std::ostream& out, DepIterator D);
 307
 308         inline DepIterator(pkgCache &Owner, Dependency *Trg, Version* = 0) :
 309                 Iterator<Dependency, DepIterator>(Owner, Trg), Type(DepVer) {
 310                 if (S == 0)
 311                         S = Owner.DepP;
 312         }
 313         inline DepIterator(pkgCache &Owner, Dependency *Trg, Package*) :
 314                 Iterator<Dependency, DepIterator>(Owner, Trg), Type(DepRev) {
 315                 if (S == 0)
 316                         S = Owner.DepP;
 317         }
 318         inline DepIterator() : Iterator<Dependency, DepIterator>(), Type(DepVer) {}
 319 };
 320                                                                         /*}}}*/
 321 // Provides iterator                                                    /*{{{*/
 322 class pkgCache::PrvIterator : public Iterator<Provides, PrvIterator> {
 323         enum {PrvVer, PrvPkg} Type;
 324
 325         protected:
 326         inline Provides* OwnerPointer() const {
 327                 return (Owner != 0) ? Owner->ProvideP : 0;
 328         }
 329
 330         public:
 331         // Iteration
 332         void operator ++(int) {if (S != Owner->ProvideP) S = Owner->ProvideP +
 333                 (Type == PrvVer?S->NextPkgProv:S->NextProvides);}
 334         inline void operator ++() {operator ++(0);}
 335
 336         // Accessors
 337         inline const char *Name() const {return Owner->StrP + Owner->PkgP[S->ParentPkg].Name;}
 338         inline const char *ProvideVersion() const {return S->ProvideVersion == 0?0:Owner->StrP + S->ProvideVersion;}
 339         inline PkgIterator ParentPkg() const {return PkgIterator(*Owner,Owner->PkgP + S->ParentPkg);}
 340         inline VerIterator OwnerVer() const {return VerIterator(*Owner,Owner->VerP + S->Version);}
 341         inline PkgIterator OwnerPkg() const {return PkgIterator(*Owner,Owner->PkgP + Owner->VerP[S->Version].ParentPkg);}
 342
 343         bool IsMultiArchImplicit() const APT_PURE;
 344
 345         inline PrvIterator() : Iterator<Provides, PrvIterator>(), Type(PrvVer) {}
 346         inline PrvIterator(pkgCache &Owner, Provides *Trg, Version*) :
 347                 Iterator<Provides, PrvIterator>(Owner, Trg), Type(PrvVer) {
 348                 if (S == 0)
 349                         S = Owner.ProvideP;
 350         }
 351         inline PrvIterator(pkgCache &Owner, Provides *Trg, Package*) :
 352                 Iterator<Provides, PrvIterator>(Owner, Trg), Type(PrvPkg) {
 353                 if (S == 0)
 354                         S = Owner.ProvideP;
 355         }
 356 };
 357                                                                         /*}}}*/
 358 // Package file                                                         /*{{{*/
 359 class pkgCache::PkgFileIterator : public Iterator<PackageFile, PkgFileIterator> {
 360         protected:
 361         inline PackageFile* OwnerPointer() const {
 362                 return (Owner != 0) ? Owner->PkgFileP : 0;
 363         }
 364
 365         public:
 366         // Iteration
 367         void operator ++(int) {if (S != Owner->PkgFileP) S = Owner->PkgFileP + S->NextFile;}
 368         inline void operator ++() {operator ++(0);}
 369
 370         // Accessors
 371         inline const char *FileName() const {return S->FileName == 0?0:Owner->StrP + S->FileName;}
 372         inline const char *Archive() const {return S->Archive == 0?0:Owner->StrP + S->Archive;}
 373         inline const char *Component() const {return S->Component == 0?0:Owner->StrP + S->Component;}
 374         inline const char *Version() const {return S->Version == 0?0:Owner->StrP + S->Version;}
 375         inline const char *Origin() const {return S->Origin == 0?0:Owner->StrP + S->Origin;}
 376         inline const char *Codename() const {return S->Codename ==0?0:Owner->StrP + S->Codename;}
 377         inline const char *Label() const {return S->Label == 0?0:Owner->StrP + S->Label;}
 378         inline const char *Site() const {return S->Site == 0?0:Owner->StrP + S->Site;}
 379         inline const char *Architecture() const {return S->Architecture == 0?0:Owner->StrP + S->Architecture;}
 380         inline const char *IndexType() const {return S->IndexType == 0?0:Owner->StrP + S->IndexType;}
 381
 382         bool IsOk();
 383         std::string RelStr();
 384
 385         // Constructors
 386         inline PkgFileIterator() : Iterator<PackageFile, PkgFileIterator>() {}
 387         inline PkgFileIterator(pkgCache &Owner) : Iterator<PackageFile, PkgFileIterator>(Owner, Owner.PkgFileP) {}
 388         inline PkgFileIterator(pkgCache &Owner,PackageFile *Trg) : Iterator<PackageFile, PkgFileIterator>(Owner, Trg) {}
 389 };
 390                                                                         /*}}}*/
 391 // Version File                                                         /*{{{*/
 392 class pkgCache::VerFileIterator : public pkgCache::Iterator<VerFile, VerFileIterator> {
 393         protected:
 394         inline VerFile* OwnerPointer() const {
 395                 return (Owner != 0) ? Owner->VerFileP : 0;
 396         }
 397
 398         public:
 399         // Iteration
 400         void operator ++(int) {if (S != Owner->VerFileP) S = Owner->VerFileP + S->NextFile;}
 401         inline void operator ++() {operator ++(0);}
 402
 403         // Accessors
 404         inline PkgFileIterator File() const {return PkgFileIterator(*Owner,S->File + Owner->PkgFileP);}
 405
 406         inline VerFileIterator() : Iterator<VerFile, VerFileIterator>() {}
 407         inline VerFileIterator(pkgCache &Owner,VerFile *Trg) : Iterator<VerFile, VerFileIterator>(Owner, Trg) {}
 408 };
 409                                                                         /*}}}*/
 410 // Description File                                                     /*{{{*/
 411 class pkgCache::DescFileIterator : public Iterator<DescFile, DescFileIterator> {
 412         protected:
 413         inline DescFile* OwnerPointer() const {
 414                 return (Owner != 0) ? Owner->DescFileP : 0;
 415         }
 416
 417         public:
 418         // Iteration
 419         void operator ++(int) {if (S != Owner->DescFileP) S = Owner->DescFileP + S->NextFile;}
 420         inline void operator ++() {operator ++(0);}
 421
 422         // Accessors
 423         inline PkgFileIterator File() const {return PkgFileIterator(*Owner,S->File + Owner->PkgFileP);}
 424
 425         inline DescFileIterator() : Iterator<DescFile, DescFileIterator>() {}
 426         inline DescFileIterator(pkgCache &Owner,DescFile *Trg) : Iterator<DescFile, DescFileIterator>(Owner, Trg) {}
 427 };
 428                                                                         /*}}}*/
 429 // Inlined Begin functions can't be in the class because of order problems /*{{{*/
 430 inline pkgCache::PkgIterator pkgCache::GrpIterator::PackageList() const
 431        {return PkgIterator(*Owner,Owner->PkgP + S->FirstPackage);}
 432 inline pkgCache::VerIterator pkgCache::PkgIterator::VersionList() const
 433        {return VerIterator(*Owner,Owner->VerP + S->VersionList);}
 434 inline pkgCache::VerIterator pkgCache::PkgIterator::CurrentVer() const
 435        {return VerIterator(*Owner,Owner->VerP + S->CurrentVer);}
 436 inline pkgCache::DepIterator pkgCache::PkgIterator::RevDependsList() const
 437        {return DepIterator(*Owner,Owner->DepP + S->RevDepends,S);}
 438 inline pkgCache::PrvIterator pkgCache::PkgIterator::ProvidesList() const
 439        {return PrvIterator(*Owner,Owner->ProvideP + S->ProvidesList,S);}
 440 inline pkgCache::DescIterator pkgCache::VerIterator::DescriptionList() const
 441        {return DescIterator(*Owner,Owner->DescP + S->DescriptionList);}
 442 inline pkgCache::PrvIterator pkgCache::VerIterator::ProvidesList() const
 443        {return PrvIterator(*Owner,Owner->ProvideP + S->ProvidesList,S);}
 444 inline pkgCache::DepIterator pkgCache::VerIterator::DependsList() const
 445        {return DepIterator(*Owner,Owner->DepP + S->DependsList,S);}
 446 inline pkgCache::VerFileIterator pkgCache::VerIterator::FileList() const
 447        {return VerFileIterator(*Owner,Owner->VerFileP + S->FileList);}
 448 inline pkgCache::DescFileIterator pkgCache::DescIterator::FileList() const
 449        {return DescFileIterator(*Owner,Owner->DescFileP + S->FileList);}
 450                                                                         /*}}}*/
 451 #endif