// Licensed to the Apache Software Foundation (ASF) under one

// or more contributor license agreements.  See the NOTICE file

// distributed with this work for additional information

// regarding copyright ownership.  The ASF licenses this file

// to you under the Apache License, Version 2.0 (the

// "License"); you may not use this file except in compliance

// with the License.  You may obtain a copy of the License at

//

//   http://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing,

// software distributed under the License is distributed on an

// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

// KIND, either express or implied.  See the License for the

// specific language governing permissions and limitations

// under the License.

// Date: Mon. Apr. 18 19:52:34 CST 2011

// Iteratively split a string by one or multiple separators.

#ifndef BUTIL_STRING_SPLITTER_H

#define BUTIL_STRING_SPLITTER_H

#include <stdlib.h>

#include <stdint.h>

#include "butil/strings/string_piece.h"

// It's common to encode data into strings separated by special characters

// and decode them back, but functions such as `split_string' has to modify

// the input string, which is bad. If we parse the string from scratch, the

// code will be filled with pointer operations and obscure to understand.

//

// What we want is:

// - Scan the string once: just do simple things efficiently.

// - Do not modify input string: Changing input is bad, it may bring hidden

//   bugs, concurrency issues and non-const propagations.

// - Split the string in-place without additional buffer/array.

//

// StringSplitter does meet these requirements.

// Usage:

//     const char* the_string_to_split = ...;

//     for (StringSplitter s(the_string_to_split, '\t'); s; ++s) {

//         printf("%*s\n", s.length(), s.field());    

//     }

// 

// "s" behaves as an iterator and evaluates to true before ending.

// "s.field()" and "s.length()" are address and length of current field

// respectively. Notice that "s.field()" may not end with '\0' because

// we don't modify input. You can copy the field to a dedicated buffer

// or apply a function supporting length.

namespace butil {

enum EmptyFieldAction {

    SKIP_EMPTY_FIELD,

    ALLOW_EMPTY_FIELD

};

// Split a string with one character

class StringSplitter {

public:

    // Split `input' with `separator'. If `action' is SKIP_EMPTY_FIELD, zero-

    // length() field() will be skipped.

    inline StringSplitter(const char* input, char separator,

                          EmptyFieldAction action = SKIP_EMPTY_FIELD);

    // Allows containing embedded '\0' characters and separator can be '\0',

    // if str_end is not NULL.

    inline StringSplitter(const char* str_begin, const char* str_end,

                          char separator,

                          EmptyFieldAction action = SKIP_EMPTY_FIELD);

    // Allows containing embedded '\0' characters and separator can be '\0',

    inline StringSplitter(const StringPiece& input, char separator,

                          EmptyFieldAction action = SKIP_EMPTY_FIELD);

    // Move splitter forward.

    inline StringSplitter& operator++();

    inline StringSplitter operator++(int);

    // True iff field() is valid.

    inline operator const void*() const;

    // Beginning address and length of the field. *(field() + length()) may

    // not be '\0' because we don't modify `input'.

    inline const char* field() const;

    inline size_t length() const;

    inline StringPiece field_sp() const;

    // Cast field to specific type, and write the value into `pv'.

    // Returns 0 on success, -1 otherwise.

    // NOTE: If separator is a digit, casting functions always return -1.

    inline int to_int8(int8_t *pv) const;

    inline int to_uint8(uint8_t *pv) const;

    inline int to_int(int *pv) const;

    inline int to_uint(unsigned int *pv) const;

    inline int to_long(long *pv) const;

    inline int to_ulong(unsigned long *pv) const;

    inline int to_longlong(long long *pv) const;

    inline int to_ulonglong(unsigned long long *pv) const;

    inline int to_float(float *pv) const;

    inline int to_double(double *pv) const;

private:

    inline bool not_end(const char* p) const;

    inline void init();

    const char* _head;

    const char* _tail;

    const char* _str_tail;

    const char _sep;

    const EmptyFieldAction _empty_field_action;

};

// Split a string with one of the separators

class StringMultiSplitter {

public:

    // Split `input' with one character of `separators'. If `action' is

    // SKIP_EMPTY_FIELD, zero-length() field() will be skipped.

    // NOTE: This utility stores pointer of `separators' directly rather than

    //       copying the content because this utility is intended to be used

    //       in ad-hoc manner where lifetime of `separators' is generally

    //       longer than this utility.

    inline StringMultiSplitter(const char* input, const char* separators,

                               EmptyFieldAction action = SKIP_EMPTY_FIELD);

    // Allows containing embedded '\0' characters if str_end is not NULL.

    // NOTE: `separators` cannot contain embedded '\0' character.

    inline StringMultiSplitter(const char* str_begin, const char* str_end,

                               const char* separators,

                               EmptyFieldAction action = SKIP_EMPTY_FIELD);

    // Move splitter forward.

    inline StringMultiSplitter& operator++();

    inline StringMultiSplitter operator++(int);

    // True iff field() is valid.

    inline operator const void*() const;

    // Beginning address and length of the field. *(field() + length()) may

    // not be '\0' because we don't modify `input'.

    inline const char* field() const;

    inline size_t length() const;

    inline StringPiece field_sp() const;

    // Cast field to specific type, and write the value into `pv'.

    // Returns 0 on success, -1 otherwise.

    // NOTE: If separators contains digit, casting functions always return -1.

    inline int to_int8(int8_t *pv) const;

    inline int to_uint8(uint8_t *pv) const;

    inline int to_int(int *pv) const;

    inline int to_uint(unsigned int *pv) const;

    inline int to_long(long *pv) const;

    inline int to_ulong(unsigned long *pv) const;

    inline int to_longlong(long long *pv) const;

    inline int to_ulonglong(unsigned long long *pv) const;

    inline int to_float(float *pv) const;

    inline int to_double(double *pv) const;

private:

    inline bool is_sep(char c) const;

    inline bool not_end(const char* p) const;

    inline void init();

    const char* _head;

    const char* _tail;

    const char* _str_tail;

    const char* const _seps;

    const EmptyFieldAction _empty_field_action;

};

// Split query in the format according to the given delimiters.

// This class can also handle some exceptional cases.

// 1. consecutive pair_delimiter are omitted, for example,

//    suppose key_value_delimiter is '=' and pair_delimiter

//    is '&', then 'k1=v1&&&k2=v2' is normalized to 'k1=k2&k2=v2'.

// 2. key or value can be empty or both can be empty.

// 3. consecutive key_value_delimiter are not omitted, for example,

//    suppose input is 'k1===v2' and key_value_delimiter is '=', then

//    key() returns 'k1', value() returns '==v2'.

class KeyValuePairsSplitter {

public:

    inline KeyValuePairsSplitter(const char* str_begin,

                                 const char* str_end,

                                 char pair_delimiter,

                                 char key_value_delimiter)

        : _sp(str_begin, str_end, pair_delimiter)

        , _delim_pos(StringPiece::npos)

        , _key_value_delim(key_value_delimiter) {

        UpdateDelimiterPosition();

    }

    inline KeyValuePairsSplitter(const char* str_begin,

                                 char pair_delimiter,

                                 char key_value_delimiter)

        : KeyValuePairsSplitter(str_begin, NULL,

                pair_delimiter, key_value_delimiter) {}

    inline KeyValuePairsSplitter(const StringPiece &sp,

                                 char pair_delimiter,

                                 char key_value_delimiter)

        : KeyValuePairsSplitter(sp.begin(), sp.end(),

                pair_delimiter, key_value_delimiter) {}

    inline StringPiece key() {

        return key_and_value().substr(0, _delim_pos);

    }

    inline StringPiece value() {

        return key_and_value().substr(_delim_pos + 1);

    }

    // Get the current value of key and value

    // in the format of "key=value"

    inline StringPiece key_and_value() {

        return StringPiece(_sp.field(), _sp.length());

    }

    // Move splitter forward.

    inline KeyValuePairsSplitter& operator++() {

        ++_sp;

        UpdateDelimiterPosition();

        return *this;

    }

    inline KeyValuePairsSplitter operator++(int) {

        KeyValuePairsSplitter tmp = *this;

        operator++();

        return tmp;

    }

    inline operator const void*() const { return _sp; }

private:

    inline void UpdateDelimiterPosition();

private:

    StringSplitter _sp;

    StringPiece::size_type _delim_pos;

    const char _key_value_delim;

};

}  // namespace butil

#include "butil/string_splitter_inl.h"

#endif  // BUTIL_STRING_SPLITTER_H