tbuffer.c

Software Development in C: A Practical Approach to Programming and Design 软件开发：编程与设计（C））——国外经典教材·计

//---------------------------------------------------------
/*
File Name:	TBuffer.c
Comments:	This file contains the functions which 
			implement all of the valid operations on the 
			text_buffer type.
*/
//---------------------------------------------------------




//---------------------------------------------------------
// Include files

#include <string.h>
#include <assert.h>
#include <stdlib.h>
#include "TBuffer.h"

// End Include files
//---------------------------------------------------------




//---------------------------------------------------------
// Constants

const int DEFAULT_ROW_ALLOCATION = 10;

// End Constants
//---------------------------------------------------------




//---------------------------------------------------------
// Prototypes

buffer_error AllocateRows(text_buffer *tBuffer,
						  int totalRows);

// End prototypes
//---------------------------------------------------------




//---------------------------------------------------------
/* 
Function Name:	TextBufferInitialize
Parameters:
	In:			None
	Out:		tBuffer - Contains the address of the 
					text buffer to initialize.
	In/Out:		None
Return Values:	None.
Comments:		This function sets the text buffer into a
				known state. If this function is not called
				before the text_buffer is used, it is 
				likely that there will be a program error.
*/

void TextBufferInitialize(text_buffer *tBuffer)
{
	assert(tBuffer!=NULL);

	// Initialize the first row to zero.
	tBuffer->topLine = 0;
	tBuffer->allRows = NULL;
	tBuffer->totalRows = 0;
}

// TextBufferInitialize
//---------------------------------------------------------




//---------------------------------------------------------
/* 
Function Name:	TextBufferSetRow
Parameters:
	In:			rowNumber - Specifies the index number of 
					the row to set.
				textString - Contains a string of 
					characters that will be copied into 
					the specified row.
	Out:		None.
	In/Out:		tBuffer - Contains the address of the 
					text buffer that the text string
					will be copied into.
Return Values:	None.
Comments:		Use this function to copy a string of 
				characters into a row in the text buffer.
*/

buffer_error TextBufferSetRow(
					int rowNumber,
					const text_string * const textString,
					text_buffer *tBuffer)
{
	buffer_error errorStatus = TBE_NO_ERROR;

	assert(tBuffer!=NULL);
	assert(rowNumber >= 0);

	// If the row is in range...
	if (rowNumber<tBuffer->totalRows)
	{
		/* If the the characters from the text string can't 
		be copied to the specified row... */
		if (TextStringSetFromTextString(
				&tBuffer->allRows[rowNumber],
				textString) == TSE_CANT_ALLOCATE_STRING)
		{
			errorStatus = TBE_CANT_ALLOCATE_BUFFER;
		}
	}
	// Else there are not that many rows in the buffer...
	else
	{
		// Allocate memory for the new row.
		errorStatus = AllocateRows(tBuffer,rowNumber+1);

		// If the memory could be allocated...
		if (errorStatus==TBE_NO_ERROR)
		{
			/* If the the characters from the text string can't 
			be copied to the specified row... */
			if (TextStringSetFromTextString(
					&tBuffer->allRows[rowNumber],
					textString) == TSE_CANT_ALLOCATE_STRING)
			{
				errorStatus = TBE_CANT_ALLOCATE_BUFFER;
			}
		}
	}
	return (errorStatus);
}

// End TextBufferSetRow
//---------------------------------------------------------




//---------------------------------------------------------
/* 
Function Name:	TextBufferGetRow
Parameters:
	In:			rowNumber - Specifies the index number of 
					the row to get.
				tBuffer - Contains the address of the 
					text buffer that the text string
					will be copied from.
	Out:		textString - Contains a string of 
					characters that the specified row will 
					be copied into.
	In/Out:		None.
Return Values:	None.
Comments:		Applications use this function to copy 
				the specified row from the text buffer
				into a string of characters.
*/

buffer_error TextBufferGetRow(
					  int rowNumber,
					  text_string *textString,
					  const text_buffer * const tBuffer)
{
	buffer_error errorStatus = TBE_NO_ERROR;

	assert((rowNumber>=0) && (rowNumber<tBuffer->totalRows));
	assert(textString!=NULL);
	assert(tBuffer!=NULL);

	// If the source string is not empty...
	if (TextStringGetLength(&tBuffer->allRows[rowNumber]) > 0)
	{
		/* If the the characters from the text string can't 
		be copied to the specified row... */
		if (TextStringSetFromTextString(
				textString,
				&tBuffer->allRows[rowNumber]) != TSE_NO_ERROR)
		{
			errorStatus = TBE_CANT_ALLOCATE_BUFFER;
		}
	}
	// Else the row of text is empty...
	else
	{
		errorStatus = TextStringSetFromCharArray(textString,"");
	}

	return (errorStatus);
}
// End TextBufferGetRow
//---------------------------------------------------------




//---------------------------------------------------------
/* 
Function Name:	TextBufferScrollUp
Parameters:
	In:			linesToScroll - Contains the number of 
					lines to scroll up.
	Out:		None.
	In/Out:		tBuffer - Contains the address of the 
					buffer to be scrolled.
Return Values:	None.
Comments:		This function scrolls the buffer up by 
				the number of lines specified in the 
				linestoScroll parameter. Scrolling the
				buffer up means moving the displayable
				area toward the beginning of the buffer.
				This is done by setting the top row of 
				the buffer.

				If scrolling the buffer results in the 
				top row of the buffer taking on a value
				that is less than zero, the top row is
				set to zero. 
*/

void TextBufferScrollUp(int linesToScroll,
					    text_buffer *tBuffer)
{
	assert(tBuffer!=NULL);
	assert(linesToScroll>0);

	// Move the top row up.
	tBuffer->topLine-=linesToScroll;

	// If the top row is less than zero...
	if (tBuffer->topLine < 0)
	{
		// Set the top row to zero.
		tBuffer->topLine=0;
	}
}

// End TextBufferScrollUp
//---------------------------------------------------------




//---------------------------------------------------------
/* 
Function Name:	TextBufferScrollDown
Parameters:
	In:			linesToScroll - Contains the number of 
					lines to scroll down.
				displayAreaHeight - Specifies the number of
					rows of text contained in the on-screen
					display area.
	Out:		None.
	In/Out:		tBuffer - Contains the address of the 
					buffer to be scrolled.
Return Values:	None.
Comments:		This function scrolls the buffer down by 
				the number of lines specified in the 
				linestoScroll parameter. Scrolling the
				buffer down means moving the displayable
				area toward the end of the buffer.
				This is done by setting the top row of 
				the buffer.

				If scrolling the buffer results in the 
				top row of the buffer taking on a value
				that is greater than the last line of 
				the buffer minus the number of rows in
				the displayable area, the top row is set
				to the last line of the buffer minus the 
				number of rows in the displayable area,
*/

void TextBufferScrollDown(int linesToScroll,
						  int displayAreaHeight,
						  text_buffer *tBuffer)
{
	assert(tBuffer!=NULL);
	assert(linesToScroll>0);
	assert(displayAreaHeight>0);

	// Move the top row down.
	tBuffer->topLine+=linesToScroll;

	/* If the top row is greater than the last line of the
	buffer minus the number of rows in the displayable 
	area... */
	if (tBuffer->topLine > 
		tBuffer->totalRows-displayAreaHeight)
	{
		/* Set the top row to the last line of the buffer 
		minus the number of rows in the displayable area. */
		tBuffer->topLine = 
			tBuffer->totalRows-displayAreaHeight;
	}

	/* If the current buffer size is less than the number
	of lines in one screenful of text, it is possible for
	this function to set the top line to a number less 
	than 0. Check for this and adjust it. */
	if (tBuffer->topLine < 0)
	{
		tBuffer->topLine = 0;
	}
}

// End TextBufferScrollDown
//---------------------------------------------------------




//---------------------------------------------------------
/* 
Function Name:	TextBufferGetTopLine
Parameters:
	In:			tBuffer - Contains a pointer to the text 
					buffer.
	Out:		None.
	In/Out:		None.
Return Values:	This function returns the current top row
				number.
Comments:		See Return Values.
*/

int TextBufferGetTopLine(const text_buffer * const tBuffer)
{
	assert(tBuffer!=NULL);

	// Return the top row number.
	return (tBuffer->topLine);
}

// End TextBufferGetTopLine
//---------------------------------------------------------




//---------------------------------------------------------
/* 
Function Name:	TextBufferGetBufferLength
Parameters:
	In:			tBuffer - Contains a pointer to the text 
					buffer.
	Out:		None.
	In/Out:		None.
Return Values:	This function returns the number of rows
				currently allocated to the text buffer.
Comments:		See Return Values.
*/

int TextBufferGetBufferLength(
		const text_buffer * const tBuffer)
{
	assert(tBuffer!=NULL);

	return(tBuffer->totalRows);
}

// End TextBufferGetBufferLength
//---------------------------------------------------------




//---------------------------------------------------------
/* 
Function Name:	TextBufferFree
Parameters:
	In:			None.
	Out:		None.
	In/Out:		tBuffer - Contains a pointer to the text 
					buffer.
Return Values:	This function does not return a value.
Comments:		Applications use this function to free the
				memory associated with a text_buffer. If 
				this function is not called whenever a 
				text_buffer goes out of scope, there may 
				be a memory leak.
*/

void TextBufferFree(text_buffer *tBuffer)
{
	int i;

	assert(tBuffer!=NULL);

	// Free each row.
	for (i=0;i<tBuffer->totalRows;i++)
	{
		TextStringFree(&tBuffer->allRows[i]);
	}

	// Free the array of rows.
	if (tBuffer->allRows != NULL)
	{
		free(tBuffer->allRows);
		tBuffer->allRows = NULL;
		tBuffer->topLine = 0;
		tBuffer->totalRows = 0;
	}

	assert(tBuffer->totalRows==0);
}

// TextBufferFree
//---------------------------------------------------------




//---------------------------------------------------------
/* 
Function Name:	AllocateRows
Parameters:
	In:			totalRows - Specifies the minimum number 
					of rows to allocate.
	Out:		None.
	In/Out:		tBuffer - Contains a pointer to the text 
					buffer.
Return Values:	This function returns the number of rows
				currently allocated to the text buffer.
Comments:		The AllocateRows() function is used only 
				by functions in this file. It increases the
				number of rows allocated to the array of 
				text strings in the buffer.

				To decrease the number of allocations,
				this function allocates increases the
				number of rows in the buffer by a 
				fixed-size block. Whenever more rows are
				requested than the buffer currently 
				contains, it increments the allocation size
				by the constant DEFAULT_ROW_ALLOCATION 
				until the buffer length is greater than or 
				equal to the number of rows requested.
				
*/

buffer_error AllocateRows(text_buffer *tBuffer,
						  int totalRows)
{
	int i;
	text_string *tempBuffer=NULL;
	int bufferSize = tBuffer->totalRows;
	buffer_error errorStatus = TBE_NO_ERROR;

	assert(tBuffer!=NULL);
	assert(totalRows>0);

	/* Increase the allocation size until it is greater 
	than the requested number of rows. */
	for (bufferSize = tBuffer->totalRows;
		 bufferSize<totalRows;
		 bufferSize+=DEFAULT_ROW_ALLOCATION);

	tempBuffer = realloc(tBuffer->allRows,
						 bufferSize*sizeof(text_string));
	if (tempBuffer)
	{
		// Initialze the new rows.
		for (i=tBuffer->totalRows;i<bufferSize;i++)
		{
			TextStringInitString(&tempBuffer[i]);
		}

		// Save a pointer to the new buffer.
		tBuffer->allRows = tempBuffer;

		// Save the new buffer size.
		tBuffer->totalRows=bufferSize;
	}
	else
	{
		errorStatus = TBE_CANT_ALLOCATE_BUFFER;
	}
	return (errorStatus);
}

// End AllocateRows
//---------------------------------------------------------




// End TBuffer.c
//---------------------------------------------------------