string.hh

Click is a modular router toolkit. To use it you ll need to know how to compile and install the sof

     * Return the index of the leftmost occurence of @a c, starting at index
     * @a start and working up to the end of the string.  Returns -1 if @a c
     * is not found. */
    int find_left(char c, int start = 0) const;

    /** @brief Search for a substring in a string.
     * @param x substring to search for
     * @param start initial search position
     *
     * Return the index of the leftmost occurence of the substring @a str,
     * starting at index @a start and working up to the end of the string.
     * Returns -1 if @a str is not found. */
    int find_left(const String &x, int start = 0) const;

    /** @brief Search for a character in a string.
     * @param c character to search for
     * @param start initial search position
     *
     * Return the index of the rightmost occurence of the character @a c,
     * starting at index @a start and working back to the beginning of the
     * string.  Returns -1 if @a c is not found.  @a start may start beyond
     * the end of the string. */
    int find_right(char c, int start = 0x7FFFFFFF) const;

    /** @brief Return true iff this string begins with prefix @a x.
     *
     * Same as String::starts_with(@a x.data(), @a x.length()). */
    inline bool starts_with(const String &x) const {
	return starts_with(x._r.data, x._r.length);
    }

    /** @brief Return true iff this string begins with the data in @a s.
     * @param s string data to compare to
     * @param len length of @a s
     *
     * If @a len @< 0, then treats @a s as a null-terminated C string.
     *
     * @sa String::compare(const String &a, const String &b) */
    bool starts_with(const char *s, int len) const;


    /** @brief Return a lowercased version of this string.
     *
     * Translates the ASCII characters 'A' through 'Z' into their lowercase
     * equivalents. */
    String lower() const;

    /** @brief Return an uppercased version of this string.
     *
     * Translates the ASCII characters 'a' through 'z' into their uppercase
     * equivalents. */
    String upper() const;

    /** @brief Return a "printable" version of this string.
     *
     * Translates control characters 0-31 into "control" sequences, such as
     * "^@" for the null character, and characters 127-255 into octal escape
     * sequences, such as "\377" for 255. */
    String printable() const;

    /** @brief Return a substring with spaces trimmed from the end. */
    String trim_space() const;

    /** @brief Return a hex-quoted version of the string.
     *
     * For example, the string "Abcd" would convert to "\<41626364>". */
    String quoted_hex() const;


    /** @brief Assign this string to @a x. */
    inline String &operator=(const String &x) {
	if (likely(&x != this)) {
	    deref();
	    assign(x);
	}
	return *this;
    }

    /** @brief Assign this string to the C string @a cstr. */
    inline String &operator=(const char *cstr) {
	assign(cstr, -1, true);
	return *this;
    }


    /** @brief Append the first @a len characters of @a s to this string.
     * @param s data to append
     * @param len length of data
     *
     * If @a len @< 0, treats @a s as a null-terminated C string. */
    void append(const char *s, int len);

    /** @brief Appends the data from @a begin to @a end to the end of this
     * string.
     *
     * Does nothing if @a begin @>= @a end. */
    inline void append(const char *begin, const char *end) {
	if (begin < end)
	    append(begin, end - begin);
    }

    /** @brief Append @a len copies of character @a c to this string. */
    void append_fill(int c, int len);

    /** @brief Append @a len unknown characters to this string.
     * @return Modifiable pointer to the appended characters.
     *
     * The caller may safely modify the returned memory.  Null is returned if
     * the string becomes out-of-memory. */
    char *append_garbage(int len);


    /** @brief Append a copy of @a x to the end of this string.
     *
     * Returns the result. */
    inline String &operator+=(const String &x) {
	append(x._r.data, x._r.length);
	return *this;
    }

    /** @brief Append a copy of the C string @a cstr to the end of this string.
     *
     * Returns the result. */
    inline String &operator+=(const char *cstr) {
	append(cstr, -1);
	return *this;
    }

    /** @brief Append the character @a c to the end of this string.
     *
     * Returns the result. */
    inline String &operator+=(char c) {
	append(&c, 1);
	return *this;
    }


    // String operator+(String, const String &);
    // String operator+(String, const char *);
    // String operator+(const char *, const String &);
    // String operator+(String, PermString);
    // String operator+(PermString, const String &);
    // String operator+(PermString, const char *);
    // String operator+(const char *, PermString);
    // String operator+(PermString, PermString);
    // String operator+(String, char);


    /** @brief Return true iff the String's data is shared or immutable. */
    inline bool data_shared() const {
	return !_r.memo->capacity || _r.memo->refcount != 1;
    }

    /** @brief Ensure the string's data is unshared and return a mutable
     * pointer to it. */
    char *mutable_data();

    /** @brief Null-terminate the string and return a mutable pointer to its
     * data.
     * @sa String::c_str */
    char *mutable_c_str();


    /** @brief Return true iff this is an out-of-memory string. */
    inline bool out_of_memory() const {
	return _r.data == &oom_string_data;
    }

    /** @brief Return a const reference to an out-of-memory String. */
    static inline const String &make_out_of_memory() {
	return reinterpret_cast<const String &>(oom_string_rep);
    }

    /** @brief Return the data pointer used for out-of-memory strings.
     *
     * The returned value may be dereferenced; it points to a null
     * character. */
    static inline const char *out_of_memory_data() {
	return &oom_string_data;
    }

  private:

    /** @cond never */
    struct memo_t {
	volatile uint32_t refcount;
	uint32_t capacity;
	volatile uint32_t dirty;
	char *real_data;
    };

    struct rep_t {
	const char *data;
	int length;
	memo_t *memo;
    };
    /** @endcond never */

    mutable rep_t _r;		// mutable for c_str()

    inline String(const char *data, int length, memo_t *memo) {
	_r.data = data;
	_r.length = length;
	_r.memo = memo;
	atomic_uint32_t::inc(memo->refcount);
    }

    inline void assign(const String &x) const {
	_r.data = x._r.data;
	_r.length = x._r.length;
	_r.memo = x._r.memo;
	atomic_uint32_t::inc(_r.memo->refcount);
    }

    inline void deref() const {
	if (atomic_uint32_t::dec_and_test(_r.memo->refcount))
	    delete_memo(_r.memo);
    }

    void assign(const char *cstr, int len, bool need_deref);
    void assign_out_of_memory();
    static memo_t *create_memo(char *data, int dirty, int capacity);
    static void delete_memo(memo_t *memo);

    static const char null_string_data;
    static const char oom_string_data;
    static const char bool_data[11];
    static memo_t null_memo;
    static memo_t permanent_memo;
    static memo_t oom_memo;
    static const rep_t null_string_rep;
    static const rep_t oom_string_rep;

    static String make_claim(char *, int, int); // claim memory

    friend class rep_t;
    friend class StringAccum;

};


/** @brief Return a const reference to an empty String.
 * @deprecated Use make_empty() instead. */
inline const String &String::empty_string() {
    return make_empty();
}

/** @brief Return a String containing @a len unknown characters.
 * @deprecated Use make_garbage() instead. */
inline String String::garbage_string(int len) {
    return make_garbage(len);
}

/** @brief Return a String that directly references the first @a len
 * characters of @a s.
 * @deprecated Use make_stable() instead. */
inline String String::stable_string(const char *s, int len) {
    return make_stable(s, len);
}

/** @brief Return a String that directly references the character data in
 * [@a begin, @a end).
 * @deprecated Use make_stable() instead. */
inline String String::stable_string(const char *begin, const char *end) {
    return make_stable(begin, end);
}

/** @brief Create and return a string representation of @a x.
 * @deprecated Use make_numeric() instead. */
inline String String::numeric_string(int_large_t x, int base, bool uppercase) {
    return make_numeric(x, base, uppercase);
}

/** @overload */
inline String String::numeric_string(uint_large_t x, int base, bool uppercase) {
    return make_numeric(x, base, uppercase);
}


/** @relates String
 * @brief Compares two strings for equality.
 *
 * Returns true iff the two operands have the same lengths and the same
 * characters in the same order.  At most one of the operands can be a
 * null-terminated C string.
 * @sa String::compare
 */
inline bool operator==(const String &a, const String &b) {
    return a.equals(b.data(), b.length());
}

/** @relates String */
inline bool operator==(const char *a, const String &b) {
    return b.equals(a, -1);
}

/** @relates String */
inline bool operator==(const String &a, const char *b) {
    return a.equals(b, -1);
}

/** @relates String
 * @brief Compare two Strings for inequality.
 *
 * Returns true iff !(@a a == @a b).  At most one of the operands can be a
 * null-terminated C string. */
inline bool operator!=(const String &a, const String &b) {
    return !a.equals(b.data(), b.length());
}

/** @relates String */
inline bool operator!=(const char *a, const String &b) {
    return !b.equals(a, -1);
}

/** @relates String */
inline bool operator!=(const String &a, const char *b) {
    return !a.equals(b, -1);
}

/** @relates String
 * @brief Compare two Strings.
 *
 * Returns true iff @a a @< @a b in lexicographic order.
 * @sa String::compare
 */
inline bool operator<(const String &a, const String &b) {
    return a.compare(b.data(), b.length()) < 0;
}

/** @relates String
 * @brief Compare two Strings.
 *
 * Returns true iff @a a @<= @a b in lexicographic order.
 * @sa String::compare
 */
inline bool operator<=(const String &a, const String &b) {
    return a.compare(b.data(), b.length()) <= 0;
}

/** @relates String
 * @brief Compare two Strings.
 *
 * Returns true iff @a a @> @a b in lexicographic order.
 * @sa String::compare
 */
inline bool operator>(const String &a, const String &b) {
    return a.compare(b.data(), b.length()) > 0;
}

/** @relates String
 * @brief Compare two Strings.
 *
 * Returns true iff @a a @>= @a b in lexicographic order.
 * @sa String::compare
 */
inline bool operator>=(const String &a, const String &b) {
    return a.compare(b.data(), b.length()) >= 0;
}

/** @relates String
 * @brief Concatenate the operands and return the result.
 *
 * At most one of the two operands can be a null-terminated C string. */
inline String operator+(String a, const String &b) {
    a += b;
    return a;
}

/** @relates String */
inline String operator+(String a, const char *b) {
    a.append(b, -1);
    return a;
}

/** @relates String */
inline String operator+(const char *a, const String &b) {
    String s1(a);
    s1 += b;
    return s1;
}

/** @relates String
 * @brief Concatenate the operands and return the result.
 *
 * The second operand is a single character. */
inline String operator+(String a, char b) {
    a.append(&b, 1);
    return a;
}

// find methods

inline const char *rfind(const char *begin, const char *end, char c) {
    for (const char *bb = end - 1; bb >= begin; bb--)
	if (*bb == c)
	    return bb;
    return end;
}

inline const char *find(const String &s, char c) {
    return find(s.begin(), s.end(), c);
}

// sort methods

template <typename T> int click_compare(const void *, const void *);

template <> inline int click_compare<String>(const void *a, const void *b) {
    const String *ta = reinterpret_cast<const String *>(a);
    const String *tb = reinterpret_cast<const String *>(b);
    return String::compare(*ta, *tb);
}

CLICK_ENDDECLS
#endif