## NAME

ACE_Read_Buffer - Efficiently reads an artibrarily large buffer from an input stream up to and including a termination character. Also performs search/replace on single occurrences a character in the buffer using the principles of Integrated Layer Processing.

## SYNOPSIS

    #include <ace/Read_Buffer.h>

    class ACE_Read_Buffer
    {
      public:
        ACE_Read_Buffer (
            FILE *fp,
            int close_on_delete = 0,
            ACE_Allocator * = 0
            );
        ACE_Read_Buffer (
            ACE_HANDLE handle,
            int close_on_delete = 0,
            ACE_Allocator * = 0
            );
        ~ACE_Read_Buffer (void);
        char *read (
            int terminator = EOF,
            int search = '\n',
            int replace = '  '
            );
        size_t replaced (void) const;
        size_t size (void) const;
        ACE_Allocator *alloc (void) const;
        void dump (void) const;
      private:
        char *rec_read (int term, int search, int replace);
        size_t size_;
        size_t occurrences_;
        FILE *stream_;
        int close_on_delete_;
        ACE_Allocator *allocator_;
        inline ACE_UNIMPLEMENTED_FUNC (
            void operator= (const ACE_Read_Buffer &)
            );
    };

## DESCRIPTION

This implementation is optimized to do a single dynamic allocation and make only one copy of the data. It uses recursion and the run-time stack to accomplish this efficiently.

## Initialization and termination methods.

    ACE_Read_Buffer (
        FILE *fp,
        int close_on_delete = 0,
        ACE_Allocator * = 0
        );

Read from a FILE *.

    ACE_Read_Buffer (
        ACE_HANDLE handle,
        int close_on_delete = 0,
        ACE_Allocator * = 0
        );

Read from an open HANDLE.

    ~ACE_Read_Buffer (void);

Closes the FILE *.

    char *read (
        int terminator = EOF,
        int search = '\n',
        int replace = '  '
        );

Returns a pointer dynamically allocated with `ACE_Allocator::malloc` to data from the input stream up to (and including) the `terminator`. If `search` is = 0 then all occurrences of the `search` value are substituted with the `replace` value. The last of the byte of data is a 0, so that `strlen` can be used on it. The caller is responsible for freeing the pointer returned from this method using the `ACE_Allocator::free`.

    size_t replaced (void) const;

Returns the number of characters replaced during a `read`.

    size_t size (void) const;

Returns the size of the allocated buffer obtained during a `read`, not including the null terminator.

    ACE_Allocator *alloc (void) const;

Returns a pointer to its allocator.

    void dump (void) const;

Dump the state of the object.

## Disallow copying and assignment...

    inline ACE_UNIMPLEMENTED_FUNC (
        void operator= (const ACE_Read_Buffer &)
        );

## AUTHOR

Doug Schmidt and Seth Widoff

## LIBRARY

ace