SBuf.h

Go to the documentation of this file.

/*
 * Copyright (C) 1996-2025 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
 */
 
/* DEBUG: section 24    SBuf */
 
#ifndef SQUID_SRC_SBUF_SBUF_H
#define SQUID_SRC_SBUF_SBUF_H
 
#include "base/InstanceId.h"
#include "base/TextException.h"
#include "debug/Stream.h"
#include "globals.h"
#include "sbuf/forward.h"
#include "sbuf/MemBlob.h"
#include "sbuf/Stats.h"
 
#include <climits>
#include <iosfwd>
#include <iterator>
#if HAVE_UNISTD_H
#include <unistd.h>
#endif
 
/* SBuf placeholder for printf */
#ifndef SQUIDSBUFPH
#define SQUIDSBUFPH "%.*s"
#define SQUIDSBUFPRINT(s) (s).plength(),(s).rawContent()
#endif /* SQUIDSBUFPH */
 
// TODO: move within SBuf and rename
typedef enum {
    caseSensitive,
    caseInsensitive
} SBufCaseSensitive;
 
class CharacterSet;
 
class SBufIterator
{
public:
    // iterator traits
    using iterator_category = std::input_iterator_tag;
    using value_type = char;
    using difference_type = std::ptrdiff_t;
    using pointer = char*;
    using reference = char&;
 
    friend class SBuf;
    typedef MemBlob::size_type size_type;
    bool operator==(const SBufIterator &s) const;
    bool operator!=(const SBufIterator &s) const;
 
    const char &operator*() const { return *iter; }
    SBufIterator& operator++() { ++iter; return *this; }
 
protected:
    SBufIterator(const SBuf &, size_type);
 
    const char *iter = nullptr;
};
 
class SBufReverseIterator : public SBufIterator
{
    friend class SBuf;
public:
    SBufReverseIterator& operator++() { --iter; return *this;}
    const char &operator*() const { return *(iter-1); }
protected:
    SBufReverseIterator(const SBuf &s, size_type sz) : SBufIterator(s,sz) {}
};
 
class SBuf
{
public:
    typedef MemBlob::size_type size_type;
    typedef SBufIterator const_iterator;
    typedef SBufReverseIterator const_reverse_iterator;
    using value_type = char;
    static const size_type npos = 0xffffffff; // max(uint32_t)
 
    static const size_type maxSize = 0xfffffff;
 
    SBuf();
    SBuf(const SBuf &S);
    SBuf(SBuf&& S) : store_(std::move(S.store_)), off_(S.off_), len_(S.len_) {
        ++stats.moves;
        S.store_ = nullptr; //RefCount supports nullptr, and S is about to be destructed
        S.off_ = S.len_ = 0;
    }
 
    explicit SBuf(const char *S, size_type n);
    explicit SBuf(const char *S);
 
    explicit SBuf(const std::string &s);
 
    ~SBuf();
 
    SBuf& assign(const SBuf &S);
 
    SBuf& operator =(const SBuf & S) {return assign(S);}
    SBuf& operator =(SBuf &&S) {
        ++stats.moves;
        if (this != &S) {
            store_ = std::move(S.store_);
            off_ = S.off_;
            len_ = S.len_;
            S.store_ = nullptr; //RefCount supports NULL, and S is about to be destructed
            S.off_ = 0;
            S.len_ = 0;
        }
        return *this;
    }
 
    // XXX: assign(s,n)/append(s,n) calls do not assign or append a c-string as
    // documented -- they do not stop at the first NUL character! They assign or
    // append the entire raw memory area, including any embedded NUL characters.
 
    SBuf& assign(const char *S, size_type n);
    SBuf& assign(const char *S) {return assign(S,npos);}
 
    SBuf& operator =(const char *S) {return assign(S);}
 
    void clear();
 
    SBuf& append(const SBuf & S);
 
    SBuf& append(const char c) { push_back(c); return *this; }
 
    void push_back(char);
 
    SBuf& append(const char * S, size_type Ssize);
    SBuf& append(const char * S) { return append(S,npos); }
 
    SBuf& Printf(const char *fmt, ...) PRINTF_FORMAT_ARG2;
 
    SBuf& appendf(const char *fmt, ...)  PRINTF_FORMAT_ARG2;
 
    SBuf& vappendf(const char *fmt, va_list vargs);
 
    std::ostream& print(std::ostream &os) const;
 
    std::ostream& dump(std::ostream &os) const;
 
    char operator [](size_type pos) const {++stats.getChar; return store_->mem[off_+pos];}
 
    char at(size_type pos) const {checkAccessBounds(pos); return operator[](pos);}
 
    void setAt(size_type pos, char toset);
 
    int compare(const SBuf &S, const SBufCaseSensitive isCaseSensitive, const size_type n) const;
    int compare(const SBuf &S, const SBufCaseSensitive isCaseSensitive) const {
        return compare(S, isCaseSensitive, npos);
    }
 
    inline int cmp(const SBuf &S, const size_type n) const {
        return compare(S,caseSensitive,n);
    }
    inline int cmp(const SBuf &S) const {
        return compare(S,caseSensitive,npos);
    }
 
    inline int caseCmp(const SBuf &S, const size_type n) const {
        return compare(S,caseInsensitive,n);
    }
    inline int caseCmp(const SBuf &S) const {
        return compare(S,caseInsensitive,npos);
    }
 
    int compare(const char *s, const SBufCaseSensitive isCaseSensitive, const size_type n) const;
    int compare(const char *s, const SBufCaseSensitive isCaseSensitive) const {
        return compare(s,isCaseSensitive,npos);
    }
 
    inline int cmp(const char *S, const size_type n) const {
        return compare(S,caseSensitive,n);
    }
    inline int cmp(const char *S) const {
        return compare(S,caseSensitive,npos);
    }
 
    inline int caseCmp(const char *S, const size_type n) const {
        return compare(S,caseInsensitive,n);
    }
    inline int caseCmp(const char *S) const {
        return compare(S,caseInsensitive,npos);
    }
 
    bool startsWith(const SBuf &S, const SBufCaseSensitive isCaseSensitive = caseSensitive) const;
 
    bool operator ==(const SBuf & S) const;
    bool operator !=(const SBuf & S) const;
    bool operator <(const SBuf &S) const {return (cmp(S) < 0);}
    bool operator >(const SBuf &S) const {return (cmp(S) > 0);}
    bool operator <=(const SBuf &S) const {return (cmp(S) <= 0);}
    bool operator >=(const SBuf &S) const {return (cmp(S) >= 0);}
 
    SBuf consume(size_type n = npos);
 
    static const SBufStats& GetStats();
 
    size_type copy(char *dest, size_type n) const;
 
    const char* rawContent() const;
 
    char *rawAppendStart(size_type anticipatedSize);
 
    void rawAppendFinish(const char *start, size_type actualSize);
 
    size_type spaceSize() const { return store_->spaceSize(); }
 
    const char* c_str();
 
    size_type length() const {return len_;}
 
    int plength() const {
        Must(length() <= INT_MAX);
        return static_cast<int>(length());
    }
 
    bool isEmpty() const {return (len_==0);}
 
    void reserveSpace(size_type minSpace) {
        Must(minSpace <= maxSize);
        Must(length() <= maxSize - minSpace);
        reserveCapacity(length()+minSpace);
    }
 
    void reserveCapacity(size_type minCapacity);
 
    size_type reserve(const SBufReservationRequirements &requirements);
 
    SBuf& chop(size_type pos, size_type n = npos);
 
    SBuf& trim(const SBuf &toRemove, bool atBeginning = true, bool atEnd = true);
 
    SBuf substr(size_type pos, size_type n = npos) const;
 
    size_type find(char c, size_type startPos = 0) const;
 
    size_type find(const SBuf & str, size_type startPos = 0) const;
 
    size_type rfind(char c, size_type endPos = npos) const;
 
    size_type rfind(const SBuf &str, size_type endPos = npos) const;
 
    size_type findFirstOf(const CharacterSet &set, size_type startPos = 0) const;
 
    size_type findLastOf(const CharacterSet &set, size_type endPos = npos) const;
 
    size_type findFirstNotOf(const CharacterSet &set, size_type startPos = 0) const;
 
    size_type findLastNotOf(const CharacterSet &set, size_type endPos = npos) const;
 
    void toLower();
 
    void toUpper();
 
    std::string toStdString() const { return std::string(buf(),length()); }
 
    const_iterator begin() const {
        return const_iterator(*this, 0);
    }
 
    const_iterator end() const {
        return const_iterator(*this, length());
    }
 
    const_reverse_iterator rbegin() const {
        return const_reverse_iterator(*this, length());
    }
 
    const_reverse_iterator rend() const {
        return const_reverse_iterator(*this, 0);
    }
 
    // TODO: possibly implement erase() similar to std::string's erase
    // TODO: possibly implement a replace() call
 
    const InstanceId<SBuf> id;
 
private:
 
    class Locker
    {
    public:
        Locker(SBuf *parent, const char *otherBuffer) {
            // lock if otherBuffer intersects the parents buffer area
            const MemBlob *blob = parent->store_.getRaw();
            if (blob->mem <= otherBuffer && otherBuffer < (blob->mem + blob->capacity))
                locket = blob;
        }
    private:
        MemBlob::Pointer locket;
    };
    friend class Locker;
 
    MemBlob::Pointer store_; 
    size_type off_ = 0; 
    size_type len_ = 0; 
    static SBufStats stats; 
 
    static MemBlob::Pointer GetStorePrototype();
 
    char * buf() const {return (store_->mem+off_);}
 
    char * bufEnd() const {return (store_->mem+off_+len_);}
 
    size_type estimateCapacity(size_type desired) const {return (2*desired);}
 
    void reAlloc(size_type newsize);
 
    void cow(size_type minsize = npos);
 
    void checkAccessBounds(const size_type pos) const { Must(pos < length()); }
 
    char *rawSpace(size_type minSize);
 
    SBuf& lowAppend(const char * memArea, size_type areaSize);
};
 
class SBufReservationRequirements
{
public:
    typedef SBuf::size_type size_type;
 
    /*
     * Parameters are listed in the reverse order of importance: Satisfaction of
     * the lower-listed requirements may violate the higher-listed requirements.
     * For example, idealSpace has no effect unless it exceeds minSpace.
     */
    size_type idealSpace = 0; 
    size_type minSpace = 0; 
    size_type maxCapacity = SBuf::maxSize; 
    bool allowShared = true; 
};
 
inline std::ostream &
operator <<(std::ostream& os, const SBuf& S)
{
    return S.print(os);
}
 
inline SBuf
ToUpper(SBuf buf)
{
    buf.toUpper();
    return buf;
}
 
inline SBuf
ToLower(SBuf buf)
{
    buf.toLower();
    return buf;
}
 
inline void
SBufToCstring(char *d, const SBuf &s)
{
    s.copy(d, s.length());
    d[s.length()] = '\0'; // 0-terminate the destination
    debugs(1, DBG_DATA, "built c-string '" << d << "' from " << s);
}
 
inline char *
SBufToCstring(const SBuf &s)
{
    char *d = static_cast<char*>(xmalloc(s.length()+1));
    SBufToCstring(d, s);
    return d;
}
 
inline
SBufIterator::SBufIterator(const SBuf &s, size_type pos)
    : iter(s.rawContent()+pos)
{}
 
inline bool
SBufIterator::operator==(const SBufIterator &s) const
{
    // note: maybe the sbuf comparison is unnecessary?
    return iter == s.iter;
}
 
inline bool
SBufIterator::operator!=(const SBufIterator &s) const
{
    // note: maybe the sbuf comparison is unnecessary?
    return iter != s.iter;
}
 
#endif /* SQUID_SRC_SBUF_SBUF_H */