/**
 * A handle to a weakref of a list of key / value pairs; any write operations on this handle will affect the resulting map entity string.
 * If the entry in the EntityLump is removed, the handle will error on all operations.  (The handle will still need to be deleted.)
 */
methodmap EntityLumpEntry < Handle {
	/**
	 * Copies the key / value at the given index into buffers.
	 *
	 * @error Index is out of bounds.
	 */
	native void Get(int index, char[] keybuf = "", int keylen = 0, char[] valbuf = "", int vallen = 0);
	
	/**
	 * Updates the key / value pair at the given index.
	 * NULL_STRING may be used to preserve the existing value.
	 *
	 * @error Index is out of bounds or entity lump is read-only.
	 */
	native void Update(int index, const char[] key = NULL_STRING, const char[] value = NULL_STRING);
	
	/**
	 * Inserts a new key / value pair at the given index, shifting the existing entry and ones past it up.
	 * If EntityLumpEntry.Length is passed in, this is an append operation.
	 *
	 * @error Index is out of bounds or entity lump is read-only.
	 */
	native void Insert(int index, const char[] key, const char[] value);
	
	/**
	 * Removes the key / value pair at the given index, shifting all entries past it down.
	 *
	 * @error Index is out of bounds or entity lump is read-only.
	 */
	native void Erase(int index);
	
	/**
	 * Inserts a new key / value pair at the end.
	 *
	 * @error Index is out of bounds or entity lump is read-only.
	 */
	native void Append(const char[] key, const char[] value);
	
	/**
	 * Returns the next index with the matching key, or -1 if not found.
	 *
	 * NOTE: Just a convenience function; probably fine to omit in favor of .Get()
	 */
	native int FindKey(const char[] key, int start = -1);
	
	/**
	 * Returns the number of key / value pairs in the list.
	 */
	property Length {
		native int get();
	};
};

/**
 * A group of natives for a singleton entity lump.
 * EntityLumpEntry instances are only available for writing during OnMapInit().
 */
methodmap EntityLump {
	/**
	 * Returns the EntityLumpEntry at the given index.
	 * This handle should be freed by the calling plugin.]
	 *
	 * @error Index is out of bounds.
	 */
	static native EntityLumpEntry Get(int index);
	
	/**
	 * Erases an EntityLumpEntry at the given index.
	 * Any handles referencing that EntityLumpEntry are invalidated.
	 *
	 * @error Index is out of bounds or entity lump is read-only.
	 */
	static native void Erase(int index);
	
	/**
	 * Inserts an empty EntityLumpEntry at the given index.
	 *
	 * @error Index is out of bounds or entity lump is read-only.
	 */
	static native void Insert(int index);
	
	/**
	 * Creates an empty EntityLumpEntry, returning its index.
	 *
	 * @error Entity lump is read-only.
	 */
	static native int Append();
	
	/**
	 * Returns the number of entities currently in the lump.
	 */
	static native int Length();
};