xref: /external/astl/include/string

/* -*- c++ -*- */
/*
 * Copyright (C) 2009 The Android Open Source Project
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *  * Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *  * Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 */

#ifndef ANDROID_ASTL_STRING__
#define ANDROID_ASTL_STRING__

#include <cstddef>

namespace std {

// Simple string implementation. Its purpose is to be able to compile code that
// uses the STL and requires std::string.
//
// IMPORTANT:
// . This class it is not fully STL compliant. Some constructors/methods maybe
// missing, they will be added on demand.
// . We don't provide a std::basic_string template that std::string extends
// because we use only char (wchar is not supported on Android).
// . The memory allocation scheme uses the heap. Since Android has the concept
// of SharedBuffer, we may, in the future, templatize this class and add an
// allocation parameter.
// . The implementation is not optimized in any way (no copy on write support),
// temporary instance may be expensive.
// . Currently there is no support for iterators.
//
// TODO: use size_type instead of size_t to be consistent.

class string
{
  public:
    typedef size_t size_type;
    typedef char   value_type;

    static const size_t  npos = static_cast<size_t>(-1);

    // Constructors
    string();

    string(const string& str);

    // Construct a string from a source's substring.
    // @param str The source string.
    // @param idx The index of the character to start the copy at.
    // @param num The number of characters to copy. Use string::npos for the
    // remainder.
    string(const string& str, size_t idx, size_t num);

    // Same as above but implicitely copy from idx to the end of the str.
    string(const string& str, size_t idx);

    // Construct a string from a C string.
    // @param str The source string, must be '\0' terminated.
    string(const char *str);

    // Construct a string from a char array.
    // @param str The source C string. '\0' are ignored.
    // @param num The number of characters to copy.
    string(const char *str, size_t num);

    // Construct a string from a repetition of a character.
    // @param num The number of characters.
    // @param c The character to use.
    string(size_t num, char c);

    // Construct a string from a char array.
    // @param begin The start of the source C string. '\0' are ignored.
    // @param end The end of source C string. Points just pass the last
    // character.
    string(const char *begin, const char *end);

    ~string();

    // @return The number of characters in the string, not including any
    // null-termination.
    const size_t length() const { return mLength; }
    const size_t size() const { return mLength; }

    // @return A pointer to null-terminated contents.
    const char *c_str() const { return mData; }
    const char *data() const { return mData; }

    // Clear the string. Empty on return.
    void clear();

    // @return true if the string is empty.
    bool empty() const { return this->size() == 0; }

    // @param str The string to be append.
    // @return A reference to this string.
    string& operator+=(const string& str) { return this->append(str); }

    // @param str The C string to be append.
    // @return A reference to this string.
    string& operator+=(const char *str) { return this->append(str); }

    // @param c A character to be append.
    // @return A reference to this string.
    string& operator+=(const char c) { this->push_back(c); return *this; }

    // @param c A character to be append.
    void push_back(const char c);

    // no-op if str is NULL.
    string& append(const char *str);
    // no-op if str is NULL. len must be >= 0.
    string& append(const char *str, size_t len);
    // no-op if str is NULL. idx and len must be >= 0.
    string& append(const char *str, size_t idx, size_t len);
    string& append(const string& str);

    // Comparaison.
    // @return 0 if this==other, < 0 if this < other and > 0 if this > other.
    // Don't assume the values are -1, 0, 1
    int compare(const string& other) const;
    int compare(const char *other) const;

    friend bool operator==(const string& left, const string& right);
    friend bool operator==(const string& left, const char *right);
    friend bool operator==(const char *left, const string& right) { return right == left; }
    friend bool operator!=(const string& left, const string& right) { return !(left == right); }
    friend bool operator!=(const string& left, const char* right) { return !(left == right); }
    friend bool operator!=(const char *left, const string& right) { return !(left == right); }

    // @return Number of elements for which memory has been allocated. capacity >= size().
    size_t capacity() const { return mCapacity; }

    // Change the capacity to new_size. No effect if new_size < size().
    // 0 means Shrink to fit.
    // @param new_size number of character to be allocated.
    void reserve(size_t new_size = 0);

    // Exchange the content of this with the content of other.
    // @param other Instance to swap this one with.
    void swap(string& other);

    // Accessors.
    // @param idx of the char. No boundary, signed checks are done.
    // @return a const reference to the char.
    const char& operator[](const size_t idx) const;
    // @param idx of the char. No boundary, signed checks are done.
    // @return a reference to the char.
    char& operator[](const size_t idx);

    // Assignments.
    string& operator=(const string& str) { return assign(str); }
    string& operator=(const char* str) { return assign(str); }
    string& operator=(char c);

    string& assign(const string& str);
    // Assign a substring of the original.
    // @param str Original string.
    // @param pos Index of the start of the copy.
    // @param len Number of character to be copied.
    string& assign(const string& str, size_t pos, size_t len);
    string& assign(const char *str);
    // Assign a non terminated array of chars.
    // @param array Of chars non-null terminated.
    // @param len Length of the array.
    string& assign(const char *array, size_t len);

    // Concat. Prefer using += or append.
    // Uses unamed object for return value optimization.
    friend string operator+(const string& left, const string& right) {
        return string(left).append(right);
    }
    friend string operator+(const string& left, const char *right) {
        return string(left).append(right);
    }
    friend string operator+(const char *left, const string& right) {
        return string(left).append(right);
    }
    friend string operator+(const string& left, char right) {
        return string(left).operator+=(right);
    }
    friend string operator+(char left, const string& right) {
        return string(&left, 1).append(right);
    }

    // Find the position of a sub-string. The empty string is always
    // found at the requested position except when it's beyond the
    // string's end.
    // @param str String to locate.
    // @param pos Index of the character to search from. Default to 0.
    // @return Index of start of the first occurence of the
    // string. string::npos if no occurence of str was found from the
    // starting position.
    size_type find(const string& str, size_type pos = 0) const {
    return find(str.mData, pos);
    }

    // Find the position of a C sub-string. The empty string is always
    // found at the requested position except when it's beyond the
    // string's end.
    // @param str C string to locate.
    // @param pos Index of the character to search from. Default to 0.
    // @return Index of start of the first occurence of the
    // string. string::npos if no occurence of str was found from the
    // starting position.
    size_type find(const char *str, size_type pos = 0) const;

  private:
    bool SafeMalloc(size_t num);
    void SafeRealloc(size_t num);
    void SafeFree(char *str);
    void ResetTo(char *str);
    void ConstructEmptyString();
    void Constructor(const char *str, size_t num);
    void Constructor(const char *str, size_t pos, size_t num);
    void Constructor(size_t num, char c);
    void DeleteSafe();
    void Append(const char *str, size_t len);

    char *mData;  // pointer to the buffer
    size_t mCapacity;  // size of the buffer.
    size_t mLength;  // len of the string excl. null-terminator.
};

}  // namespace std

#endif  // ANDROID_ASTL_STRING__