// //------------------ DOK FILE -------------------------------------------------- +Header bufferLib =pkg bios =title Buffers =short variable length strings =desc Contrary to strings, string buffers have a variable length. // // //------------------ PROTO ----------------------------------------------------- Buffer +Proto Buffer =type Buffer =mode type =pkg bios =impl native =link =desc [[Buffer]] is a native type in Minimacy. The usual lifecycle is: creation, appending data, export the resulting content into a string. // // //------------------ PROTO ----------------------------------------------------- bufferAppend +Proto bufferAppend =type fun Buffer a1 -> Buffer =mode function =pkg bios =impl native =link =desc This function appends content to a [[Buffer]]. Basically it iterates through the data and appends a string from each element. - a string is printed as it is - an integer or a float are printed in decimal - [[true]] or [[false]] are printed 'true' or 'false' - nil is not printed at all - members of a tuple, an array or a list are printed in their natural order It is similar to [[strBuild]], except it prints the content into a [[Buffer]]. The [[bufferAppendJoin]] function is almost the same except it adds a separator between each printable element. // +arg buffer =type Buffer =desc A buffer // +arg data =type a1 =desc Any type // +arg result =type Buffer =desc The buffer // // //------------------ PROTO ----------------------------------------------------- bufferAppendJoin +Proto bufferAppendJoin =type fun Buffer Str a1 -> Buffer =mode function =pkg bios =impl native =link =desc This function appends content to a [[Buffer]]. Basically it iterates through the data and appends a string from each element, inserting the separator between each printable element. - a string is printed as it is - an integer or a float are printed in decimal - [[true]] or [[false]] are printed 'true' or 'false' - nil is not printed at all It is similar to [[strJoin]], except it prints the content into a [[Buffer]]. The [[bufferAppend]] function is almost the same but without the separator. // +arg buffer =type Buffer =desc A buffer // +arg separator =type Str =desc A string // +arg data =type a1 =desc Any type // +arg result =type Buffer =desc The buffer // // //------------------ PROTO ----------------------------------------------------- bufferCreate +Proto bufferCreate =type fun -> Buffer =mode function =pkg bios =impl native =link =desc This function creates a new empty [[Buffer]]. // +arg result =type Buffer =desc A new Buffer // // //------------------ PROTO ----------------------------------------------------- bufferCreateWithSize +Proto bufferCreateWithSize =type fun Int -> Buffer =mode function =pkg bios =impl native =link =desc This function creates a new empty [[Buffer]], with a specific size. On the implementation side, a buffer is the combination of a block of memory and an index. The index is the position of the next byte to write, and is initialized to 0. Each time a byte is appended, the index is incremented. When the block of memory is full, the VM allocates a larger new block and copies the data from the previous block, which could be slow. If you know the size you actually need for this buffer, it would be better to start with a block of at least this size. The default initial size is 128 bytes, and is doubled each time the block is full, until 2Mo, then it is incremented by steps of 1Mo. The [[bufferCreateWithSize]] function is used to specify a different initial size. // +arg size =type Int =desc A positive integer // +arg result =type Buffer =desc A new Buffer // // //------------------ PROTO ----------------------------------------------------- bufferLength +Proto bufferLength =type fun Buffer -> Int =mode function =pkg bios =impl native =link =desc This function returns the number of bytes in the buffer. // +arg buffer =type Buffer =desc A buffer // +arg result =type Int =desc The number of bytes currently in the buffer. // // //------------------ PROTO ----------------------------------------------------- bufferReset +Proto bufferReset =type fun Buffer -> Buffer =mode function =pkg bios =impl native =link =desc This function erases the data in the buffer, and restart with an empty buffer. On the implementation side, a buffer is the combination of a block of memory and an index. The index is the position of the next byte to write, and is initialized to 0. Each time a byte is appended, the index is incremented. The [[bufferReset]] function simply sets index to 0. // +arg buffer =type Buffer =desc A buffer // +arg result =type Buffer =desc The same buffer // // //------------------ PROTO ----------------------------------------------------- bytesFromBuffer +Proto bytesFromBuffer =type fun Buffer -> Bytes =mode function =pkg bios =impl native =link =desc This function exports the current content of a buffer into a new byte array. Subsequent modifications of the buffer will not affect the exported byte array. // +arg buffer =type Buffer =desc A buffer // +arg result =type Bytes =desc A byte array // // //------------------ PROTO ----------------------------------------------------- strFromBuffer +Proto strFromBuffer =type fun Buffer -> Str =mode function =pkg bios =impl native =link =desc This function exports the current content of a buffer into a new string. Subsequent modifications of the buffer will not affect the exported string. // +arg buffer =type Buffer =desc A buffer // +arg result =type Str =desc A string // // //------------------ PROTO ----------------------------------------------------- bufferAppendChar +Proto bufferAppendChar =type fun Buffer Int -> Buffer =mode function =pkg bios =impl native =link =desc This function appends a byte to the buffer. // +arg buffer =type Buffer =desc A buffer // +arg B =type Int =desc An integer between 0 and 255 // +arg result =type Buffer =desc The same buffer // // //------------------ PROTO ----------------------------------------------------- bufferGet +Proto bufferGet =type fun Buffer Int -> Int =mode function =pkg bios =impl native =link =desc This function returns the byte value located at the position index in the buffer, or nil when the position is outside the range of the buffer. When the index is negative it is counted from the end of the buffer. // +arg buffer =type Buffer =desc A buffer // +arg index =type Int =desc An integer // +arg result =type Int =desc An integer between 0 and 255, or nil // // //------------------ PROTO ----------------------------------------------------- bufferSliceOfStr +Proto bufferSliceOfStr =type fun Buffer Int Int -> Str =mode function =pkg bios =impl native =link =desc This function extracts a substring from the buffer src. // +arg src =type Buffer =desc // +arg offset =type Int =desc An integer // +arg len =type Int =desc Another integer // +arg result =type Str =desc A substring of src // // //------------------ PROTO ----------------------------------------------------- bufferSliceOfBytes +Proto bufferSliceOfBytes =type fun Buffer Int Int -> Bytes =mode function =pkg bios =impl native =link =desc This function is the same as [[bufferSliceOfStr]], except it returns an array of bytes. // +arg src =type Buffer =desc // +arg offset =type Int =desc An integer // +arg len =type Int =desc Another integer // +arg result =type Bytes =desc A substring of src as an array of bytes