"""Buffers used to hold null-terminated strings."""


from bgenBuffer import FixedOutputBufferType
from bgenStackBuffer import StackOutputBufferType
from bgenHeapBuffer import HeapOutputBufferType


class StringBufferMixIn:

	"""Mix-in class to create various string buffer types.

	Strings are character arrays terminated by a null byte.
	(For input, this is also covered by stringptr.)
	For output, there are again three variants:
	- Fixed: size is a constant given in the documentation; or
	- Stack: size is passed to the C function but we decide on a size at
	  code generation time so we can still allocate on the heap); or
	- Heap: size is passed to the C function and we let the Python caller
	  pass a size.
	(Note that this doesn't cover output parameters in which a string
	pointer is returned.  These are actually easier (no allocation) but far
	less common.  I'll write the classes when there is demand.)
	"""
	
	def declareSize(self, name):
		pass
	
	def getargsFormat(self):
		return "s"
	
	def getargsArgs(self, name):
		return "&%s__in__" % name

	def mkvalueFormat(self):
		return "s"

	def mkvalueArgs(self, name):
		return "%s__out__" % name


class FixedOutputStringType(StringBufferMixIn, FixedOutputBufferType):

	"""Null-terminated output string -- passed without size.

	Instantiate with buffer size as parameter.
	"""


class StackOutputStringType(StringBufferMixIn, StackOutputBufferType):

	"""Null-terminated output string -- passed as (buffer, size).

	Instantiate with buffer size as parameter.
	"""


class HeapOutputStringType(StringBufferMixIn, HeapOutputBufferType):

	"""Null-terminated output string -- passed as (buffer, size).

	Instantiate without parameters.
	Call from Python with buffer size.
	"""