core/btree: small refactoring + documentation tweaks

[jussisaurio]

small follow up to #539

contains:

• Variable renaming and comments to btreecursor.insert_into_cell()
• New utility methods pagecontent.header_size(), pagecontent.cell_pointer_array_size(), pagecontent.unallocated_region_start() and pagecontent.unallocated_region_size()
• Refactor of btreecursor.compute_free_space() (plus comments and variable renaming)
• Rename pagecontent.cell_get_raw_pointer_region() to pagecontent.cell_pointer_array_offset_and_size() and remove its usage in btreecursor.defragment_page()

[jussisaurio]

is this a bug? doesn't include offset for 1st page in db (which is 100 bytes, due to the database header)

[pereman2]

hmmm feels like it.

[jussisaurio]

actually this one in particular probably isn't, because PageContent generally tries to hide the existence of the potential 100 byte offset from the user -- all of the read/write functions e.g. read_u16() add the offset under the hood:

    pub fn read_u16(&self, pos: usize) -> u16 {
        let buf = self.as_ptr();
        u16::from_be_bytes([buf[self.offset + pos], buf[self.offset + pos + 1]])
    }

whereas this quoted code does the following:

let cell_pointer_array_start = (...does NOT include offset...)
let cell_pointer = cell_pointer_array_start + (idx * 2);
let cell_pointer = self.read_u16(cell_pointer) as usize; // <--key part, offset added implicitly by read_u16

so the offset actually MUST not be added here because then it would be double-added :)

there might be a way to refactor this to make it less footgun-y

[jussisaurio]

And I'm blindly guessing that your thought process when naming pub fn cell_get_raw_pointer_region() was that 'raw' means that it includes the offset

[jussisaurio]

I'm still thinking there is a 100-byte offset related error somewhere that is causing CREATE TABLE errors