loned

Layout in 1D

Abstracts handling linear layout of items that can be measured in 1 dimension

Are you:

• laying out UI elements
• handling memory layout
• dealing with file formats

If so, please, for the sake of all that is good, find a more robust and reliable solution.

However, I will be using it for toy projects dabbling in these things, and you are welcome to join me.

In its current state, it is considerably more low-level than future releases will be - later on, you won't have to eg keep track of your own indices when modifying the layout, among other annoyances

install

npm install @nrkn/loned

usage

import { 
  loned, relayout, 
  
  queryLayout, 

  splitLayoutAt, combineSplitLayout,

  insertItem, appendItem, prependItem, overwrite, takeStart, takeEnd, 
  removeStart, removeEnd, takeSlice, removeSlice
} from '@nrkn/loned'

const myData = [
  { text: 'UwU', fg: 10, bg: 4 },
  { text: ' ', fg: 7, bg: 0 },
  { text: 'OwO', fg: 4, bg: 10 }
]

const mySizes = new BigUint64Array(
  myData.map(({ text }) => BigInt(text.length))
)

const layout = loned(mySizes)

const res = queryLayout(layout, 5n )

console.log( res.type ) 
/*  
  will be 'inside', could have also been: 
  'before' - the query is before the start of the layout
  'after' - the query is after the end of the layout
  'head' - the query is exactly at the start of the layout
  'tail' - the query is exactly at the end of the layout
  'boundary' - the query is on the boundary between two items

  res also contains information about the items that are involved in the query,
  if any
*/

// updating - we want to give it the new id
const newData = { text: ' uWu', fg: 2, bg: 8 }
const newSize = BigInt(newData.text.length)

const dataLookup = [
  ...myData,
  newData
]

const nextId = dataLookup.length - 1

// insert after the first UwU
// note we pass it the layout we created earlier, without the newData in it
// - when modifying, you need a way to keep track of the new items
const nextLayout = insertItem(layout, nextId, newSize, 3n)

// now use the layout data to create a new array 

const result = []

for( const item of newLayout.items ){
  if( item.type === 'segment' ){
    result.push( dataLookup[item.oid] )
  } else if( item.type === 'slice' ){
    const data = dataLookup[item.oid]

    data.text = data.text.slice(
      Number(item.sliceStart), 
      Number(item.sliceStart + item.sliceSize)
    )

    result.push(sliced)
  }
}

console.log( result ) // back in our original format, but with new uWu

API

• loned(sizes: BigUint64Array): Layout1D create a layout given the sizes of the items

• relayout(items: LayoutItem1D[] ): Layout1D relayout items from one or more other layouts

• queryLayout(layout: Layout1D, pos: bigint): QueryResult find out what's at the position - is it inside an item, between items, which items and so forth

• splitLayoutAt(layout: Layout1D, pos: bigint): SplitLayout split a layout into a head and tail of LayoutItem1D, potentially splitting inside an item, along with a lot of other information about the split (eg the query result)

• combineSplitLayout(split: SplitLayout): Layout1D combine a split layout back into a single layout

• insertItem(layout: Layout1D, oid: number, size: bigint, pos: bigint): Layout1D insert a new item into the layout, splitting an existing item if necessary

• appendItem(layout: Layout1D, oid: number, size: bigint): Layout1D appends an item to end of layout

• prependItem(layout: Layout1D, oid: number, size: bigint): Layout1D prepends an item to start of layout

• overwrite(layout: Layout1D, oid: number, size: bigint, pos: bigint): Layout1D overwrite any items that overlap with the new item, splitting them if only partial

• takeStart(layout: Layout1D, size: bigint): Layout1D take the start of the layout, up to the given size

• takeEnd(layout: Layout1D, size: bigint): Layout1D take the end of the layout, up to the given size

• removeStart(layout: Layout1D, size: bigint): Layout1D remove the start of the layout, up to the given size

• removeEnd(layout: Layout1D, size: bigint): Layout1D remove the end of the layout, up to the given size

• takeSlice(layout: Layout1D, start: bigint, size: bigint): Layout1D take a slice of the layout, splitting items at the bounds if necessary

• removeSlice(layout: Layout1D, start: bigint, size: bigint): Layout1D remove a slice of the layout, splitting items at the bounds if necessary

future

Wrap everything in a factory function that abstracts away annoying low level details like having to pass in a BigUint64Array for sizes, and having to manage your own indices when inserting etc

You will just need to bring your own:

• measure(item: T): bigint
• slice(item: T, slicedata ): T[]

We will provide an implementation for plain strings

nb

Early stages, API likely to change frequently. More detailed documentation may one day be written. Here be dragons, use at your own peril.

license

MIT License

Copyright (c) 2023 Nik Coughlin

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.