module mysql.protocol.packet_helpers;

import std.algorithm;
import std.conv;
import std.datetime;
import std.digest.sha;
import std.exception;
import std.range;
import std.socket;
import std.stdio;
import std.string;
import std.traits;
import std.variant;

import mysql.common;
import mysql.protocol.constants;
import mysql.protocol.extra_types;

/**
 * Function to extract a time difference from a binary encoded row.
 *
 * Time/date structures are packed by the server into a byte sub-packet
 * with a leading length byte, and a minimal number of bytes to embody the data.
 *
 * Params: a = slice of a protocol packet beginning at the length byte for a chunk of time data
 *
 * Returns: A populated or default initialized TimeDiff struct.
 */
TimeDiff toTimeDiff(in ubyte[] a) pure
{
    enforceEx!MYXProtocol(a.length, "Supplied byte array is zero length");
    TimeDiff td;
    uint l = a[0];
    enforceEx!MYXProtocol(l == 0 || l == 5 || l == 8 || l == 12, "Bad Time length in binary row.");
    if (l >= 5)
    {
        td.negative = (a[1]  != 0);
        td.days     = (a[5] << 24) + (a[4] << 16) + (a[3] << 8) + a[2];
    }
    if (l >= 8)
    {
        td.hours    = a[6];
        td.minutes  = a[7];
        td.seconds  = a[8];
    }
    // Note that the fractional seconds part is not stored by MySQL
    return td;
}

/**
 * Function to extract a time difference from a text encoded column value.
 *
 * Text representations of a time difference are like -750:12:02 - 750 hours
 * 12 minutes and two seconds ago.
 *
 * Params: s = A string representation of the time difference.
 * Returns: A populated or default initialized TimeDiff struct.
 */
TimeDiff toTimeDiff(string s)
{
    TimeDiff td;
    int t = parse!int(s);
    if (t < 0)
    {
        td.negative = true;
        t = -t;
    }
    td.hours    = cast(ubyte) t%24;
    td.days     = cast(ubyte) t/24;
    munch(s, ":");
    td.minutes  = parse!ubyte(s);
    munch(s, ":");
    td.seconds  = parse!ubyte(s);
    return td;
}

/**
 * Function to extract a TimeOfDay from a binary encoded row.
 *
 * Time/date structures are packed by the server into a byte sub-packet
 * with a leading length byte, and a minimal number of bytes to embody the data.
 *
 * Params: a = slice of a protocol packet beginning at the length byte for a
 *             chunk of time data.
 * Returns: A populated or default initialized std.datetime.TimeOfDay struct.
 */
TimeOfDay toTimeOfDay(in ubyte[] a) pure
{
    enforceEx!MYXProtocol(a.length, "Supplied byte array is zero length");
    uint l = a[0];
    enforceEx!MYXProtocol(l == 0 || l == 5 || l == 8 || l == 12, "Bad Time length in binary row.");
    enforceEx!MYXProtocol(l >= 8, "Time column value is not in a time-of-day format");

    TimeOfDay tod;
    tod.hour    = a[6];
    tod.minute  = a[7];
    tod.second  = a[8];
    return tod;
}

/**
 * Function to extract a TimeOfDay from a text encoded column value.
 *
 * Text representations of a time of day are as in 14:22:02
 *
 * Params: s = A string representation of the time.
 * Returns: A populated or default initialized std.datetime.TimeOfDay struct.
 */
TimeOfDay toTimeOfDay(string s)
{
    TimeOfDay tod;
    tod.hour = parse!int(s);
    enforceEx!MYXProtocol(tod.hour <= 24 && tod.hour >= 0, "Time column value is in time difference form");
    munch(s, ":");
    tod.minute = parse!ubyte(s);
    munch(s, ":");
    tod.second = parse!ubyte(s);
    return tod;
}

/**
 * Function to pack a TimeOfDay into a binary encoding for transmission to the server.
 *
 * Time/date structures are packed into a string of bytes with a leading length
 * byte, and a minimal number of bytes to embody the data.
 *
 * Params: tod = TimeOfDay struct.
 * Returns: Packed ubyte[].
 */
ubyte[] pack(in TimeOfDay tod) pure nothrow
{
    ubyte[] rv;
    if (tod == TimeOfDay.init)
    {
        rv.length = 1;
        rv[0] = 0;
    }
    else
    {
        rv.length = 9;
        rv[0] = 8;
        rv[6] = tod.hour;
        rv[7] = tod.minute;
        rv[8] = tod.second;
    }
    return rv;
}

/**
 * Function to extract a Date from a binary encoded row.
 *
 * Time/date structures are packed by the server into a byte sub-packet
 * with a leading length byte, and a minimal number of bytes to embody the data.
 *
 * Params: a = slice of a protocol packet beginning at the length byte for a
 *             chunk of Date data.
 * Returns: A populated or default initialized std.datetime.Date struct.
 */
Date toDate(in ubyte[] a) pure
{
    enforceEx!MYXProtocol(a.length, "Supplied byte array is zero length");
    if (a[0] == 0)
        return Date(0,0,0);

    enforceEx!MYXProtocol(a[0] >= 4, "Binary date representation is too short");
    int year    = (a[2]  << 8) + a[1];
    int month   = cast(int) a[3];
    int day     = cast(int) a[4];
    return Date(year, month, day);
}

/**
 * Function to extract a Date from a text encoded column value.
 *
 * Text representations of a Date are as in 2011-11-11
 *
 * Params: s = A string representation of the time difference.
 * Returns: A populated or default initialized std.datetime.Date struct.
 */
Date toDate(string s)
{
    int year = parse!(ushort)(s);
    munch(s, "-");
    int month = parse!(ubyte)(s);
    munch(s, "-");
    int day = parse!(ubyte)(s);
    return Date(year, month, day);
}

/**
 * Function to pack a Date into a binary encoding for transmission to the server.
 *
 * Time/date structures are packed into a string of bytes with a leading length
 * byte, and a minimal number of bytes to embody the data.
 *
 * Params: dt = std.datetime.Date struct.
 * Returns: Packed ubyte[].
 */
ubyte[] pack(in Date dt) pure nothrow
{
    ubyte[] rv;
    if (dt.year < 0)
    {
        rv.length = 1;
        rv[0] = 0;
    }
    else
    {
        rv.length = 5;
        rv[0] = 4;
        rv[1] = cast(ubyte) ( dt.year       & 0xff);
        rv[2] = cast(ubyte) ((dt.year >> 8) & 0xff);
        rv[3] = cast(ubyte)   dt.month;
        rv[4] = cast(ubyte)   dt.day;
    }
    return rv;
}

/**
 * Function to extract a DateTime from a binary encoded row.
 *
 * Time/date structures are packed by the server into a byte sub-packet
 * with a leading length byte, and a minimal number of bytes to embody the data.
 *
 * Params: a = slice of a protocol packet beginning at the length byte for a
 *             chunk of DateTime data
 * Returns: A populated or default initialized std.datetime.DateTime struct.
 */
DateTime toDateTime(in ubyte[] a) pure
{
    enforceEx!MYXProtocol(a.length, "Supplied byte array is zero length");
    if (a[0] == 0)
        return DateTime();

    enforceEx!MYXProtocol(a[0] >= 4, "Supplied ubyte[] is not long enough");
    int year    = (a[2] << 8) + a[1];
    int month   =  a[3];
    int day     =  a[4];
    DateTime dt;
    if (a[0] == 4)
    {
        dt = DateTime(year, month, day);
    }
    else
    {
        enforceEx!MYXProtocol(a[0] >= 7, "Supplied ubyte[] is not long enough");
        int hour    = a[5];
        int minute  = a[6];
        int second  = a[7];
        dt = DateTime(year, month, day, hour, minute, second);
    }
    return dt;
}

/**
 * Function to extract a DateTime from a text encoded column value.
 *
 * Text representations of a DateTime are as in 2011-11-11 12:20:02
 *
 * Params: s = A string representation of the time difference.
 * Returns: A populated or default initialized std.datetime.DateTime struct.
 */
DateTime toDateTime(string s)
{
    int year = parse!(ushort)(s);
    munch(s, "-");
    int month = parse!(ubyte)(s);
    munch(s, "-");
    int day = parse!(ubyte)(s);
    munch(s, " ");
    int hour = parse!(ubyte)(s);
    munch(s, ":");
    int minute = parse!(ubyte)(s);
    munch(s, ":");
    int second = parse!(ubyte)(s);
    return DateTime(year, month, day, hour, minute, second);
}

/**
 * Function to extract a DateTime from a ulong.
 *
 * This is used to support the TimeStamp  struct.
 *
 * Params: x = A ulong e.g. 20111111122002UL.
 * Returns: A populated std.datetime.DateTime struct.
 */
DateTime toDateTime(ulong x) pure
{
    int second = cast(int) x%100;
    x /= 100;
    int minute = cast(int) x%100;
    x /= 100;
    int hour   = cast(int) x%100;
    x /= 100;
    int day    = cast(int) x%100;
    x /= 100;
    int month  = cast(int) x%100;
    x /= 100;
    int year   = cast(int) x%10000;
    // 2038-01-19 03:14:07
    enforceEx!MYXProtocol(year >= 1970 &&  year < 2039, "Date/time out of range for 2 bit timestamp");
    enforceEx!MYXProtocol(year == 2038 && (month > 1 || day > 19 || hour > 3 || minute > 14 || second > 7),
            "Date/time out of range for 2 bit timestamp");
    return DateTime(year, month, day, hour, minute, second);
}

/**
 * Function to pack a DateTime into a binary encoding for transmission to the server.
 *
 * Time/date structures are packed into a string of bytes with a leading length byte,
 * and a minimal number of bytes to embody the data.
 *
 * Params: dt = std.datetime.DateTime struct.
 * Returns: Packed ubyte[].
 */
ubyte[] pack(in DateTime dt) pure nothrow
{
    uint len = 1;
    if (dt.year || dt.month || dt.day) len = 5;
    if (dt.hour || dt.minute|| dt.second) len = 8;
    ubyte[] rv;
    rv.length = len;
    rv[0] =  cast(ubyte)(rv.length - 1); // num bytes
    if(len >= 5)
    {
        rv[1] = cast(ubyte) ( dt.year       & 0xff);
        rv[2] = cast(ubyte) ((dt.year >> 8) & 0xff);
        rv[3] = cast(ubyte)   dt.month;
        rv[4] = cast(ubyte)   dt.day;
    }
    if(len == 8)
    {
        rv[5] = cast(ubyte) dt.hour;
        rv[6] = cast(ubyte) dt.minute;
        rv[7] = cast(ubyte) dt.second;
    }
    return rv;
}


T consume(T)(MySQLSocket conn) pure {
    ubyte[T.sizeof] buffer;
    conn.read(buffer);
    ubyte[] rng = buffer;
    return consume!T(rng);
}

string consume(T:string, ubyte N=T.sizeof)(ref ubyte[] packet) pure
{
    return packet.consume!string(N);
}

string consume(T:string)(ref ubyte[] packet, size_t N) pure
in
{
    assert(packet.length >= N);
}
body
{
    return cast(string)packet.consume(N);
}

/// Returns N number of bytes from the packet and advances the array
ubyte[] consume()(ref ubyte[] packet, size_t N) pure nothrow
in
{
    assert(packet.length >= N);
}
body
{
    auto result = packet[0..N];
    packet = packet[N..$];
    return result;
}

T decode(T:ulong)(in ubyte[] packet, size_t n) pure nothrow
{
    switch(n)
    {
        case 8: return packet.decode!(T, 8)();
        case 4: return packet.decode!(T, 4)();
        case 3: return packet.decode!(T, 3)();
        case 2: return packet.decode!(T, 2)();
        case 1: return packet.decode!(T, 1)();
        default: assert(0);
    }
}

T consume(T)(ref ubyte[] packet, int n) pure nothrow
if(isIntegral!T)
{
    switch(n)
    {
        case 8: return packet.consume!(T, 8)();
        case 4: return packet.consume!(T, 4)();
        case 3: return packet.consume!(T, 3)();
        case 2: return packet.consume!(T, 2)();
        case 1: return packet.consume!(T, 1)();
        default: assert(0);
    }
}

TimeOfDay consume(T:TimeOfDay, ubyte N=T.sizeof)(ref ubyte[] packet) pure
in
{
    static assert(N == T.sizeof);
}
body
{
    enforceEx!MYXProtocol(packet.length, "Supplied byte array is zero length");
    uint length = packet.front;
    enforceEx!MYXProtocol(length == 0 || length == 5 || length == 8 || length == 12, "Bad Time length in binary row.");
    enforceEx!MYXProtocol(length >= 8, "Time column value is not in a time-of-day format");

    packet.popFront(); // length
    auto bytes = packet.consume(length);

    // TODO: What are the fields in between!?! Blank Date?
    TimeOfDay tod;
    tod.hour    = bytes[5];
    tod.minute  = bytes[6];
    tod.second  = bytes[7];
    return tod;
}

Date consume(T:Date, ubyte N=T.sizeof)(ref ubyte[] packet) pure
in
{
    static assert(N == T.sizeof);
}
body
{
    return toDate(packet.consume(5));
}

DateTime consume(T:DateTime, ubyte N=T.sizeof)(ref ubyte[] packet) pure
in
{
    assert(packet.length);
    assert(N == T.sizeof);
}
body
{
    auto numBytes = packet.consume!ubyte();
    if(numBytes == 0)
        return DateTime();

    enforceEx!MYXProtocol(numBytes >= 4, "Supplied packet is not large enough to store DateTime");

    int year    = packet.consume!ushort();
    int month   = packet.consume!ubyte();
    int day     = packet.consume!ubyte();
    int hour    = 0;
    int minute  = 0;
    int second  = 0;
    if(numBytes > 4)
    {
        enforceEx!MYXProtocol(numBytes >= 7, "Supplied packet is not large enough to store a DateTime with TimeOfDay");
        hour    = packet.consume!ubyte();
        minute  = packet.consume!ubyte();
        second  = packet.consume!ubyte();
    }
    return DateTime(year, month, day, hour, minute, second);
}


@property bool hasEnoughBytes(T, ubyte N=T.sizeof)(in ubyte[] packet) pure
in
{
    static assert(T.sizeof >= N, T.stringof~" not large enough to store "~to!string(N)~" bytes");
}
body
{
    return packet.length >= N;
}

T decode(T, ubyte N=T.sizeof)(in ubyte[] packet) pure nothrow
if(isIntegral!T)
in
{
    static assert(N == 1 || N == 2 || N == 3 || N == 4 || N == 8, "Cannot decode integral value. Invalid size: "~N.stringof);
    static assert(T.sizeof >= N, T.stringof~" not large enough to store "~to!string(N)~" bytes");
    assert(packet.hasEnoughBytes!(T,N), "packet not long enough to contain all bytes needed for "~T.stringof);
}
body
{
    T value = 0;
    static if(N == 8) // 64 bit
    {
        value |= cast(T)(packet[7]) << (8*7);
        value |= cast(T)(packet[6]) << (8*6);
        value |= cast(T)(packet[5]) << (8*5);
        value |= cast(T)(packet[4]) << (8*4);
    }
    static if(N >= 4) // 32 bit
    {
        value |= cast(T)(packet[3]) << (8*3);
    }
    static if(N >= 3) // 24 bit
    {
        value |= cast(T)(packet[2]) << (8*2);
    }
    static if(N >= 2) // 16 bit
    {
        value |= cast(T)(packet[1]) << (8*1);
    }
    static if(N >= 1) // 8 bit
    {
        value |= cast(T)(packet[0]) << (8*0);
    }
    return value;
}

T consume(T, ubyte N=T.sizeof)(ref ubyte[] packet) pure nothrow
if(isIntegral!T)
in
{
    static assert(N == 1 || N == 2 || N == 3 || N == 4 || N == 8, "Cannot consume integral value. Invalid size: "~N.stringof);
    static assert(T.sizeof >= N, T.stringof~" not large enough to store "~to!string(N)~" bytes");
    assert(packet.hasEnoughBytes!(T,N), "packet not long enough to contain all bytes needed for "~T.stringof);
}
body
{
    // The uncommented line triggers a template deduction error,
    // so we need to store a temporary first
    // could the problem be method chaining?
    //return packet.consume(N).decode!(T, N)();
    auto bytes = packet.consume(N);
    return bytes.decode!(T, N)();
}


T myto(T)(string value)
{
    static if(is(T == DateTime))
        return toDateTime(value);
    else static if(is(T == Date))
        return toDate(value);
    else static if(is(T == TimeOfDay))
        return toTimeOfDay(value);
    else
        return to!T(value);
}

T decode(T, ubyte N=T.sizeof)(in ubyte[] packet) pure nothrow
if(isFloatingPoint!T)
in
{
    static assert((is(T == float) && N == float.sizeof)
            || is(T == double) && N == double.sizeof);
}
body
{
    T result = 0;
    (cast(ubyte*)&result)[0..T.sizeof] = packet[0..T.sizeof];
    return result;
}

T consume(T, ubyte N=T.sizeof)(ref ubyte[] packet) pure nothrow
if(isFloatingPoint!T)
in
{
    static assert((is(T == float) && N == float.sizeof)
            || is(T == double) && N == double.sizeof);
}
body
{
    return packet.consume(T.sizeof).decode!T();
}


SQLValue consumeBinaryValueIfComplete(T, int N=T.sizeof)(ref ubyte[] packet, bool unsigned)
{
    SQLValue result;
    
    // Length of DateTime packet is NOT DateTime.sizeof, it can be 1, 5 or 8 bytes
    static if(is(T==DateTime))
        result.isIncomplete = packet.length < 1;
    else
        result.isIncomplete = packet.length < N;

    // isNull should have been handled by the caller as the binary format uses a
    // null bitmap, and we don't have access to that information at this point
    assert(!result.isNull);
    if(!result.isIncomplete)
    {
        // only integral types is unsigned
        static if(isIntegral!T)
        {
            if(unsigned)
                result.value = packet.consume!(Unsigned!T)();
            else
                result.value = packet.consume!(Signed!T)();
        }
        else
        {
            // TODO: DateTime values etc might be incomplete!
            result.value = packet.consume!(T, N)();
        }
    }
    return result;
}

SQLValue consumeNonBinaryValueIfComplete(T)(ref ubyte[] packet, bool unsigned)
{
    SQLValue result;
    auto lcb = packet.decode!LCB();
    result.isIncomplete = lcb.isIncomplete || packet.length < (lcb.value+lcb.totalBytes);
    result.isNull = lcb.isNull;
    if(!result.isIncomplete)
    {
        // The packet has all the data we need, so we'll remove the LCB
        // and convert the data
        packet.skip(lcb.totalBytes);
        assert(packet.length >= lcb.value);
        auto value = cast(string) packet.consume(cast(size_t)lcb.value);

        if(!result.isNull)
        {
            assert(!result.isIncomplete);
            assert(!result.isNull);
            static if(isIntegral!T)
            {
                if(unsigned)
                    result.value = to!(Unsigned!T)(value);
                else
                    result.value = to!(Signed!T)(value);
            }
            else
            {
                static if(isArray!T)
                {
                    // to!() crashes when trying to convert empty strings
                    // to arrays, so we have this hack to just store any
                    // empty array in those cases
                    if(!value.length)
                        result.value = T.init;
                    else
                        result.value = cast(T)value.dup;

                }
                else
                {
                    // TODO: DateTime values etc might be incomplete!
                    result.value = myto!T(value);
                }
            }
        }
    }
    return result;
}

SQLValue consumeIfComplete(T, int N=T.sizeof)(ref ubyte[] packet, bool binary, bool unsigned)
{
    return binary
        ? packet.consumeBinaryValueIfComplete!(T, N)(unsigned)
        : packet.consumeNonBinaryValueIfComplete!T(unsigned);
}

SQLValue consumeIfComplete()(ref ubyte[] packet, SQLType sqlType, bool binary, bool unsigned, ushort charSet)
{
    switch(sqlType)
    {
        default: assert(false, "Unsupported SQL type "~to!string(sqlType));
        case SQLType.NULL:
            SQLValue result;
            result.isIncomplete = false;
            result.isNull = true;
            return result;
        case SQLType.TINY:
            return packet.consumeIfComplete!byte(binary, unsigned);
        case SQLType.SHORT:
            return packet.consumeIfComplete!short(binary, unsigned);
        case SQLType.INT24:
            return packet.consumeIfComplete!(int, 3)(binary, unsigned);
        case SQLType.INT:
            return packet.consumeIfComplete!int(binary, unsigned);
        case SQLType.LONGLONG:
            return packet.consumeIfComplete!long(binary, unsigned);
        case SQLType.FLOAT:
            return packet.consumeIfComplete!float(binary, unsigned);
        case SQLType.DOUBLE:
        case SQLType.NEWDECIMAL:
            return packet.consumeIfComplete!double(binary, unsigned);
        case SQLType.TIMESTAMP:
            return packet.consumeIfComplete!DateTime(binary, unsigned);
        case SQLType.TIME:
            return packet.consumeIfComplete!TimeOfDay(binary, unsigned);
        case SQLType.YEAR:
            return packet.consumeIfComplete!ushort(binary, unsigned);
        case SQLType.DATE:
            return packet.consumeIfComplete!Date(binary, unsigned);
        case SQLType.DATETIME:
            return packet.consumeIfComplete!DateTime(binary, unsigned);
        case SQLType.VARCHAR:
        case SQLType.ENUM:
        case SQLType.SET:
        case SQLType.VARSTRING:
        case SQLType.STRING:
            return packet.consumeIfComplete!string(false, unsigned);
        case SQLType.TINYBLOB:
        case SQLType.MEDIUMBLOB:
        case SQLType.BLOB:
        case SQLType.LONGBLOB:
        case SQLType.BIT:  // Yes, BIT. See note below.

            // TODO: This line should work. Why doesn't it?
            //return packet.consumeIfComplete!(ubyte[])(binary, unsigned);

            auto lcb = packet.consumeIfComplete!LCB();
            assert(!lcb.isIncomplete);
            SQLValue result;
            result.isIncomplete = false;
            result.isNull = lcb.isNull;
            if(result.isNull)
            {
                // TODO: consumeIfComplete!LCB should be adjusted to do
                //       this itself, but not until I'm certain that nothing
                //       is reliant on the current behavior.
                packet.popFront(); // LCB length
            }
            else
            {
                auto data = packet.consume(cast(size_t)lcb.value);
                if(charSet == 0x3F) // CharacterSet == binary
                    result.value = data; // BLOB-ish
                else
                    result.value = cast(string)data; // TEXT-ish
            }
            
            // Type BIT is treated as a length coded binary (like a BLOB or VARCHAR),
            // not like an integral type. So convert the binary data to a bool.
            // See: http://dev.mysql.com/doc/internals/en/binary-protocol-value.html
            if(sqlType == SQLType.BIT)
            {
                enforceEx!MYXProtocol(result.value.length == 1,
                    "Expected BIT to arrive as an LCB with length 1, but got length "~to!string(result.value.length));
                
                result.value = result.value[0] == 1;
            }
            
            return result;
    }
}

/**
 * Extract number of bytes used for this LCB
 *
 * Returns the number of bytes required to store this LCB
 *
 * See_Also: http://forge.mysql.com/wiki/MySQL_Internals_ClientServer_Protocol#Elements
 *
 * Returns: 0 if it's a null value, or number of bytes in other cases
 * */
byte getNumLCBBytes(in ubyte lcbHeader) pure nothrow
{
    switch(lcbHeader)
    {
        case 251: return 0; // null
        case 0: .. case 250: return 1; // 8-bit
        case 252: return 2;  // 16-bit
        case 253: return 3;  // 24-bit
        case 254: return 8;  // 64-bit

        case 255:
        default:
            assert(0);
    }
    assert(0);
}


/**
 * Decodes a Length Coded Binary from a packet
 *
 * See_Also: struct LCB
 *
 * Parameters:
 *  packet = A packet that starts with a LCB. The bytes is popped off
 *           iff the packet is complete. See LCB.
 *
 * Returns: A decoded LCB value
 * */
T consumeIfComplete(T:LCB)(ref ubyte[] packet) pure nothrow
in
{
    assert(packet.length >= 1, "packet has to include at least the LCB length byte");
}
body
{
    auto lcb = packet.decodeLCBHeader();
    if(lcb.isNull || lcb.isIncomplete)
        return lcb;

    if(lcb.numBytes > 1)
    {
        // We know it's complete, so we have to start consuming the LCB
        // Single byte values doesn't have a length
        packet.popFront(); // LCB length
    }

    assert(packet.length >= lcb.numBytes);

    lcb.value = packet.consume!ulong(lcb.numBytes);
    return lcb;
}

LCB decodeLCBHeader(in ubyte[] packet) pure nothrow
in
{
    assert(packet.length >= 1, "packet has to include at least the LCB length byte");
}
body
{
    LCB lcb;
    lcb.numBytes = getNumLCBBytes(packet.front);
    if(lcb.numBytes == 0)
    {
        lcb.isNull = true;
        return lcb;
    }

    assert(!lcb.isNull);
    // -1 for LCB length as we haven't popped it off yet
    lcb.isIncomplete = (lcb.numBytes > 1) && (packet.length-1 < lcb.numBytes);
    if(lcb.isIncomplete)
    {
        // Not enough bytes to store data. We don't remove any data, and expect
        // the caller to check isIncomplete and take action to fetch more data
        // and call this method at a later time
        return lcb;
    }

    assert(!lcb.isIncomplete);
    return lcb;
}

/**
 * Decodes a Length Coded Binary from a packet
 *
 * See_Also: struct LCB
 *
 * Parameters:
 *  packet = A packet that starts with a LCB. See LCB.
 *
 * Returns: A decoded LCB value
 * */
LCB decode(T:LCB)(in ubyte[] packet) pure nothrow
in
{
    assert(packet.length >= 1, "packet has to include at least the LCB length byte");
}
body
{
    auto lcb = packet.decodeLCBHeader();
    if(lcb.isNull || lcb.isIncomplete)
        return lcb;
    assert(packet.length >= lcb.totalBytes);

    if(lcb.numBytes == 0)
        lcb.value = 0;
    else if(lcb.numBytes == 1)
        lcb.value = packet.decode!ulong(lcb.numBytes);
    else
    {
        // Skip the throwaway byte that indicated "at least 2 more bytes coming"
        lcb.value = packet[1..$].decode!ulong(lcb.numBytes);
    }

    return lcb;
}

/** Parse Length Coded String
 *
 * See_Also: http://forge.mysql.com/wiki/MySQL_Internals_ClientServer_Protocol#Elements
 * */
string consume(T:LCS)(ref ubyte[] packet) pure
in
{
    assert(packet.length >= 1, "LCS packet needs to store at least the LCB header");
}
body
{
    auto lcb = packet.consumeIfComplete!LCB();
    assert(!lcb.isIncomplete);
    if(lcb.isNull)
        return null;
    enforceEx!MYXProtocol(lcb.value <= uint.max, "Protocol Length Coded String is too long");
    return cast(string)packet.consume(cast(size_t)lcb.value).idup;
}

/**
 * Skips over n items, advances the array, and return the newly advanced array
 * to allow method chaining.
 * */
T[] skip(T)(ref T[] array, size_t n) pure nothrow
in
{
    assert(n <= array.length);
}
body
{
    array = array[n..$];
    return array;
}

/**
 * Converts a value into a sequence of bytes and fills the supplied array
 *
 * Parameters:
 * IsInt24 = If only the most significant 3 bytes from the value should be used
 * value = The value to add to array
 * array = The array we should add the values for. It has to be large enough,
 *         and the values are packed starting index 0
 */
void packInto(T, bool IsInt24 = false)(T value, ubyte[] array) pure nothrow
in
{
    static if(IsInt24)
        assert(array.length >= 3);
    else
        assert(array.length >= T.sizeof, "Not enough space to unpack "~T.stringof);
}
body
{
    static if(T.sizeof >= 1)
    {
        array[0] = cast(ubyte) (value >> 8*0) & 0xff;
    }
    static if(T.sizeof >= 2)
    {
        array[1] = cast(ubyte) (value >> 8*1) & 0xff;
    }
    static if(!IsInt24)
    {
        static if(T.sizeof >= 4)
        {
            array[2] = cast(ubyte) (value >> 8*2) & 0xff;
            array[3] = cast(ubyte) (value >> 8*3) & 0xff;
        }
        static if(T.sizeof >= 8)
        {
            array[4] = cast(ubyte) (value >> 8*4) & 0xff;
            array[5] = cast(ubyte) (value >> 8*5) & 0xff;
            array[6] = cast(ubyte) (value >> 8*6) & 0xff;
            array[7] = cast(ubyte) (value >> 8*7) & 0xff;
        }
    }
    else
    {
        array[2] = cast(ubyte) (value >> 8*2) & 0xff;
    }
}

ubyte[] packLength(size_t l, out size_t offset) pure nothrow
out(result)
{
    assert(result.length >= 1);
}
body
{
    ubyte[] t;
    if (!l)
    {
        t.length = 1;
        t[0] = 0;
    }
    else if (l <= 250)
    {
        t.length = 1+l;
        t[0] = cast(ubyte) l;
        offset = 1;
    }
    else if (l <= 0xffff) // 16-bit
    {
        t.length = 3+l;
        t[0] = 252;
        packInto(cast(ushort)l, t[1..3]);
        offset = 3;
    }
    else if (l < 0xffffff) // 24-bit
    {
        t.length = 4+l;
        t[0] = 253;
        packInto!(uint, true)(cast(uint)l, t[1..4]);
        offset = 4;
    }
    else // 64-bit
    {
        ulong u = cast(ulong) l;
        t.length = 9+l;
        t[0] = 254;
        u.packInto(t[1..9]);
        offset = 9;
    }
    return t;
}

ubyte[] packLCS(void[] a) pure nothrow
{
    size_t offset;
    ubyte[] t = packLength(a.length, offset);
    if (t[0])
        t[offset..$] = (cast(ubyte[]) a)[0..$];
    return t;
}


debug(MYSQL_INTEGRATION_TESTS)
unittest
{
    static void testLCB(string parseLCBFunc)(bool shouldConsume)
    {
        ubyte[] buf = [ 0xde, 0xcc, 0xbb, 0xaa, 0x99, 0x88, 0x77, 0x66, 0x55, 0x01, 0x00 ];
        ubyte[] bufCopy;
        
        bufCopy = buf;
        LCB lcb = mixin(parseLCBFunc~"!LCB(bufCopy)");
        assert(lcb.value == 0xde && !lcb.isNull && lcb.totalBytes == 1);
        assert(bufCopy.length == buf.length - (shouldConsume? lcb.totalBytes : 0));

        buf[0] = 251;
        bufCopy = buf;
        lcb = mixin(parseLCBFunc~"!LCB(bufCopy)");
        assert(lcb.value == 0 && lcb.isNull && lcb.totalBytes == 1);
        //TODO: This test seems to fail for consumeIfComplete, need to investigate.
        //      Don't know if fixing it might cause a problem, or if I simple misunderstood
        //      the function's intent.
        if(parseLCBFunc != "consumeIfComplete")
            assert(bufCopy.length == buf.length - (shouldConsume? lcb.totalBytes : 0));

        buf[0] = 252;
        bufCopy = buf;
        lcb = mixin(parseLCBFunc~"!LCB(bufCopy)");
        assert(lcb.value == 0xbbcc && !lcb.isNull && lcb.totalBytes == 3);
        assert(bufCopy.length == buf.length - (shouldConsume? lcb.totalBytes : 0));

        buf[0] = 253;
        bufCopy = buf;
        lcb = mixin(parseLCBFunc~"!LCB(bufCopy)");
        assert(lcb.value == 0xaabbcc && !lcb.isNull && lcb.totalBytes == 4);
        assert(bufCopy.length == buf.length - (shouldConsume? lcb.totalBytes : 0));

        buf[0] = 254;
        bufCopy = buf;
        lcb = mixin(parseLCBFunc~"!LCB(bufCopy)");
        assert(lcb.value == 0x5566778899aabbcc && !lcb.isNull && lcb.totalBytes == 9);
        assert(bufCopy.length == buf.length - (shouldConsume? lcb.totalBytes : 0));
    }
    
    //TODO: Merge 'consumeIfComplete(T:LCB)' and 'decode(T:LCB)', they do
    //      basically the same thing, only one consumes input and the other
    //      doesn't. Just want a better idea of where/how/why they're both
    //      used, and maybe more tests, before I go messing with them.
    testLCB!"consumeIfComplete"(true);
    testLCB!"decode"(false);
}

debug(MYSQL_INTEGRATION_TESTS)
unittest
{
    ubyte[] buf;
    ubyte[] bufCopy;

    buf.length = 0x2000200;
    buf[] = '\x01';
    buf[0] = 250;
    buf[1] = '<';
    buf[249] = '!';
    buf[250] = '>';
    bufCopy = buf;
    string x = consume!LCS(bufCopy);
    assert(x.length == 250 && x[0] == '<' && x[249] == '>');

    buf[] = '\x01';
    buf[0] = 252;
    buf[1] = 0xff;
    buf[2] = 0xff;
    buf[3] = '<';
    buf[0x10000] = '*';
    buf[0x10001] = '>';
    bufCopy = buf;
    x = consume!LCS(bufCopy);
    assert(x.length == 0xffff && x[0] == '<' && x[0xfffe] == '>');

    buf[] = '\x01';
    buf[0] = 253;
    buf[1] = 0xff;
    buf[2] = 0xff;
    buf[3] = 0xff;
    buf[4] = '<';
    buf[0x1000001] = '*';
    buf[0x1000002] = '>';
    bufCopy = buf;
    x = consume!LCS(bufCopy);
    assert(x.length == 0xffffff && x[0] == '<' && x[0xfffffe] == '>');

    buf[] = '\x01';
    buf[0] = 254;
    buf[1] = 0xff;
    buf[2] = 0x00;
    buf[3] = 0x00;
    buf[4] = 0x02;
    buf[5] = 0x00;
    buf[6] = 0x00;
    buf[7] = 0x00;
    buf[8] = 0x00;
    buf[9] = '<';
    buf[0x2000106] = '!';
    buf[0x2000107] = '>';
    bufCopy = buf;
    x = consume!LCS(bufCopy);
    assert(x.length == 0x20000ff && x[0] == '<' && x[0x20000fe] == '>');
}

/// Set packet length and number. It's important that the length of packet has
/// already been set to the final state as its length is used
void setPacketHeader(ref ubyte[] packet, ubyte packetNumber) pure nothrow
in
{
    // packet should include header, and possibly data
    assert(packet.length >= 4);
}
body
{
    auto dataLength = packet.length - 4; // don't include header in calculated size
    assert(dataLength <= uint.max);
    packet.setPacketHeader(packetNumber, cast(uint)dataLength);
}

void setPacketHeader(ref ubyte[] packet, ubyte packetNumber, uint dataLength) pure nothrow
in
{
    // packet should include header
    assert(packet.length >= 4);
    // Length is always a 24-bit int
    assert(dataLength <= 0xffff_ffff_ffff);
}
body
{
    dataLength.packInto!(uint, true)(packet);
    packet[3] = packetNumber;
}