Module bufflib
A library for string buffers in Lua.
The buffer code in this library is largely adapted from Lua 5.2's luaL_Buffer code. The main difference is that Buffers store their contents in the registry instead of the stack when their length exceeds LUAL_BUFFERSIZE. This prevents the C char array holding the current contents from being garbage collected until a larger array is required or the Buffer is reset or garbage collected. You don't need to know any of this to use the library, it's just extra information for people curious about the implementation.
Just like regular strings in Lua, string buffers can contain embedded nulls (\0).
Similar to Lua's string library, most Buffer methods can be called as buff:method(...) or bufflib.method(buff, ...) (where buff is a Buffer).
Note that not all methods use the same name in the Buffer metatable and the bufflib table.
The primary examples of this are the metamethods, which use the required metamethod names in the metatable and more descriptive names in the bufflib table (e.g. the __len metamethod is the same as bufflib.length).
In addition to the functions shown here, you can call any method from the global string table (not just functions from the string library) on a Buffer (either as a method or a function from the bufflib table) by prefixing the name with s_.
When you call a Buffer method with the s_ prefix, it calls the equivalent string function with the Buffer's contents as the first argument followed by any other arguments supplied to the method. None of these methods modify the original Buffer.
For example, bufflib.s_gsub(buff, ...) and buff:s_gsub(...) are both equivalent to str:gsub(...) (where buff is a Buffer and str is the Buffer's contents as a string).
Buffers define metamethods for equality (==), length (#), concatenation (..) and tostring(). See the documentation of each metamethod for details.
Class Buffer
| Buffer:add (...) | Add some strings to the Buffer. |
| Buffer:addsep (sep, ...) | Add some strings to the Buffer, each separated by the specified separator string. |
| Buffer:reset () | Reset the Buffer to its initial (empty) state. |
| Buffer:__tostring () | Converts the Buffer to a string representing its current conents. |
| Buffer:__len () | Metamethod for the # (length) operation. |
| Buffer:__concat (B) | Metamethod for the .. (concatenation) operation. |
| Buffer:__eq (buff2) | Metamethod for the == (equality) operation. |
Buffer Manipulation
| newbuffer ( [...]) | Creates a new Buffer object, optionally adding some strings to the new Buffer. |
| isbuffer (arg) | Tests whether or not the argument is a Buffer. |
| add (buff, ...) | Equivalent to buff:add(...). |
| addsep (buff, sep, ...) | Equivalent to buff:addsep(sep, ...). |
| reset (buff) | Equivalent to buff:reset(). |
| tostring (buff) | Equivalent to tostring(buff) or buff:\_\_tostring(). |
| length (buff) | Equivalent to #buff or buff:\_\_len(). |
| concat (buff1, buff2) | Equivalent to `buff1 .. |
| equal (buff1, buff2) | Equivalent to buff1 == buff2 or buff1:\_\_eq(buff2). |
Class Buffer
A class representing a string buffer.- Buffer:add (...)
-
Add some strings to the Buffer.
All non-string arguments are converted to strings following the same rules as the
tostring()function.Parameters:
- ... Some values to add to the Buffer.
Returns:
-
Buffer
The Buffer object.
- Buffer:addsep (sep, ...)
-
Add some strings to the Buffer, each separated by the specified separator string.
All non-string arguments are converted to strings following the same rules as the
tostring()function.Parameters:
- sep string The string to use as a separator.
- ... Some values to add to the Buffer.
Returns:
-
Buffer
The Buffer object.
- Buffer:reset ()
-
Reset the Buffer to its initial (empty) state.
If the Buffer was storing its contents in the registry, this is removed so it can be garbage collected.
Returns:
-
Buffer
The Buffer object.
- Buffer:__tostring ()
-
Converts the Buffer to a string representing its current conents.
The Buffer remains unchanged.
Returns:
-
string
The contents of the Buffer
- Buffer:__len ()
-
Metamethod for the
#(length) operation. Returns the length of the Buffer's current contents.Returns:
-
int
length
- Buffer:__concat (B)
-
Metamethod for the
..(concatenation) operation. If both arguments are Buffers, creates a new Buffer from their joined contents. Otherwise adds a value to the Buffer, converting it to a string following the same rules as thetostring()function.Parameters:
- B A Buffer to concatenate with this one or some value to to add to it.
Returns:
-
Buffer
Either the new Buffer created from the two Buffer arguments or the Buffer that the non-Buffer argument was added to.
- Buffer:__eq (buff2)
-
Metamethod for the
==(equality) operation. Returns true if the Buffers hold the same contents, false if they don't. The contents of each Buffer are converted to Lua strings and then the two strings are compared to obtain the result.Parameters:
- buff2 Buffer The Buffer to compare with this one.
Returns:
-
bool
equal Do the Buffers hold the same contents?
Buffer Manipulation
Buffer Manipulation.The functions in this section are available in the bufflib table, returned from require"bufflib".
- newbuffer ( [...])
-
Creates a new Buffer object, optionally adding some strings to the new Buffer.
All non-string arguments are converted to strings following the same rules as the
tostring()function.Parameters:
- ... Some values to add to the new Buffer.
Returns:
-
Buffer
The new Buffer object.
- isbuffer (arg)
-
Tests whether or not the argument is a Buffer.
Parameters:
- arg The value to check.
Returns:
-
bool
Is this a Buffer?
- add (buff, ...)
-
Equivalent to
buff:add(...).Parameters:
- buff Buffer The Buffer to add the values to.
- ... Some values to add to the Buffer.
Returns:
-
Buffer
The Buffer object.
- addsep (buff, sep, ...)
-
Equivalent to
buff:addsep(sep, ...).Parameters:
- buff Buffer The Buffer to add the values to.
- sep string The string to use as a separator.
- ... Some values to add to the Buffer.
Returns:
-
Buffer
The Buffer object.
- reset (buff)
-
Equivalent to
buff:reset().Parameters:
- buff Buffer The Buffer to reset.
Returns:
-
Buffer
The emptied Buffer object.
- tostring (buff)
-
Equivalent to
tostring(buff)orbuff:\_\_tostring().Parameters:
- buff Buffer The Buffer to convert to a string.
Returns:
-
string
The Buffer's contents as a string.
- length (buff)
-
Equivalent to
#bufforbuff:\_\_len().Parameters:
- buff Buffer The Buffer to get the length of.
Returns:
-
int
length
- concat (buff1, buff2)
-
Equivalent to
buff1 .. buff2orbuff1:\_\_concat(buff2).Parameters:
- buff1 A Buffer or some other value.
- buff2 A Buffer or some other value.
Returns:
-
Buffer
Either the new Buffer created from the Buffer arguments or the Buffer that the non-Buffer argument was added to.
- equal (buff1, buff2)
-
Equivalent to
buff1 == buff2orbuff1:\_\_eq(buff2).Parameters:
Returns:
-
bool
Do the Buffers hold the same contents?