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
//---------------------------------------------------------



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

static text_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;
	tBuffer->errorStatus = TBE_NO_ERROR;
}

// 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.

				If this function fails, it sets the text
				buffer's error status to 
				TBE_CANT_ALLOCATE_BUFFER, which indicates 
				that there is not enough memory to copy 
				the characters from the string into 
				the specified row.
				
*/

void TextBufferSetRow(text_buffer *tBuffer,
					  int rowNumber,
					  text_string textString)
{
	text_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)
		{
			tBuffer->errorStatus = TBE_CANT_ALLOCATE_BUFFER;
		}
	}
	// Else there are not that many rows in the buffer...
	else
	{
		// Allocate memory for the new row.
		tBuffer->errorStatus = AllocateRows(tBuffer,rowNumber+1);

		// If the memory could be allocated...
		if (tBuffer->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)
			{
				tBuffer->errorStatus = 
					TBE_CANT_ALLOCATE_BUFFER;
			}
		}
	}
}

// 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 retrieved from.
	Out:		textString - Upon return, will contain the 
					text_string in the specified row.
	In/Out:		None.
Return Values:	None.
Comments:		This function retrieves the text_string
				contained in the specified row number. It
				does not create an additional instace of 
				the string. Nor does it copy any characters.
*/

void TextBufferGetRow(const text_buffer * const tBuffer,
					  int rowNumber,
					  text_string *textString)
{
	assert((rowNumber >= 0) && (rowNumber < tBuffer->totalRows));
	assert(textString != NULL);
	assert(tBuffer != NULL);

	*textString = tBuffer->allRows[rowNumber];
}
// 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(text_buffer *tBuffer,
						int linesToScroll)
{
	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.
*/

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

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

}

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



//---------------------------------------------------------
/* 
Function Name:	TextBufferScrollToBeginning
Parameters:
	In:			None.
	Out:		None.
	In/Out:		tBuffer - Contains the address of the 
					buffer to be scrolled.
Return Values:	None.
Comments:		This function scrolls the buffer to its first
				row of text.
*/	

void TextBufferScrollToBeginning(text_buffer *textBuffer)
{
	assert(textBuffer != NULL);

	textBuffer->topLine=0;
}

// End TextBufferScrollToBeginning
//---------------------------------------------------------



//---------------------------------------------------------
/* 
Function Name:	TextBufferScrollToEnd
Parameters:
	In:			None.
	Out:		None.
	In/Out:		tBuffer - Contains the address of the 
					buffer to be scrolled.
Return Values:	None.
Comments:		This function scrolls the buffer to its 
				last row of text.
*/	

void TextBufferScrollToEnd(text_buffer *textBuffer)
{
	assert(textBuffer != NULL);

	// If there is text in the buffer...
	if (textBuffer->totalRows > 0)
	{
		// Set the top row equal to the last row.
		textBuffer->topLine = textBuffer->totalRows - 1;
	}
	// Else there is no text in the buffer...
	else
	{
		textBuffer->topLine = 0;
	}
}

// End TextBufferScrollToEnd
//---------------------------------------------------------



//---------------------------------------------------------
/* 
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:	TextBufferSaveToFile
Parameters:
	In:			tBuffer - Contains a pointer to the text 
					buffer.
				fileName - Specifies the name of the file
					where the text will be saved.
	Out:		None.
	In/Out:		None.
Return Values:	None.
Comments:		Applications invoke the TextBufferSaveToFile()
				function to save the contents of a text buffer
				to a file. The file can be on any accessible
				storage medium to which the user has write 
				permission. All path names must be in a form 
				that is acceptable to the operating system 
				being used. 

				If this function fails, it sets the text
				buffer's error status to one of the 
				following values:
				TBE_CANT_WRITE_TO_FILE - The file could not