efl/src/lib/efl/interfaces/efl_io_buffer.eo

class @beta Efl.Io.Buffer extends Efl.Object
                          implements Efl.Io.Reader, Efl.Io.Writer, Efl.Io.Closer, Efl.Io.Sizer, Efl.Io.Positioner {
    [[Generic In-memory buffer of data to be used as I/O.

      This class offers both input and output, which can be used at
      the same time since @Efl.Io.Reader.read and @Efl.Io.Writer.write
      use different offsets/position internally.

      One can get temporary direct access to internal buffer with
      @.slice or steal the buffer with @.binbuf_steal.

      A fixed sized buffer can be implemented by setting @.limit
      followed by @.preallocate
    ]]

    methods {
        preallocate {
            [[Immediately pre-allocate a buffer of at least a given size.]]
            params {
                @in size: size; [[Amount of bytes to pre-allocate.]]
            }
        }

        adopt_readonly {
            [[Adopt a read-only slice as buffer's backing store.

              The slice memory will not be copied and must remain
              alive during the buffer's lifetime. Usually this is
              guaranteed by some global static-const memory or some
              parent object and this buffer being a view of that -- be
              aware of parent memory remaining alive, such as
              "slice,changed" events.
            ]]
            params {
                @in slice: const(Eina.Slice); [[Slice to adopt as read-only]]
            }
        }

        adopt_readwrite {
            [[Adopt a read-write slice as buffer's backing store.

              The slice memory will not be copied and must remain
              alive during the buffer's lifetime. Usually this is
              guaranteed by some global static memory or some
              parent object and this buffer being a view of that -- be
              aware of parent memory remaining alive, such as
              "slice,changed" events.

              The memory will be disposed using free() and reallocated
              using realloc().
            ]]
            params {
                @in slice: Eina.Rw_Slice; [[Slice to adopt as read-write]]
            }
        }

        @property limit {
            [[Limit how big the buffer can grow.

              This affects both @.preallocate and how buffer grows
              when @Efl.Io.Writer.write is called.

              If you want a buffer of an exact size always set the
              limit before any further calls that can expand it.
            ]]
            get { }
            set {
                [[Constructor-only property to set buffer limit. 0 is unlimited]]
            }
            values {
                size: size; [[Defines a maximum buffer size, or 0 to allow unlimited amount of bytes]]
            }
        }

        @property position_read {
            [[The position used by @Efl.Io.Reader.read.

             Note that @Efl.Io.Positioner.seek or
             @Efl.Io.Positioner.position.set will affect this property
             and @.position_write.

             @Efl.Io.Positioner.position.get will return the greatest
             of @.position_read and @.position_write.
            ]]
            get { }
            set {
                return: bool (false); [[$true if setting the position succeeded, $false otherwise]]
            }
            values {
                position: uint64; [[Position in buffer]]
            }
        }

        @property position_write {
            [[The position used by @Efl.Io.Writer.write.

             Note that @Efl.Io.Positioner.seek or
             @Efl.Io.Positioner.position.set will affect this property
             and @.position_read.

             @Efl.Io.Positioner.position.get will return the greatest
             of @.position_read and @.position_write.
            ]]
            get { }
            set {
                return: bool (false); [[$true if setting the position succeeded, $false otherwise]]
            }
            values {
                position: uint64; [[Position in buffer]]
            }
        }

        @property slice {
            [[Get a temporary access to buffer's internal memory.

              The memory pointed by slice may be changed by other
              methods of this class. The event "reallocated" will be
              called in those situations.
            ]]
            get { }
            values {
                slice: Eina.Slice; [[Slice of the current buffer, may be invalidated if @Efl.Io.Writer.write,
                                     @Efl.Io.Closer.close or @Efl.Io.Sizer.resize are called.
                                     It is the full slice, not a partial one starting at current position.]]
            }
        }

        binbuf_steal {
            [[Steals the internal buffer memory and returns it as a binbuf.

              The returned memory must be freed with eina_binbuf_free().

              On failure, for example a read-only backing store was
              adopted with @.adopt_readonly, NULL is returned.
            ]]
            return: ptr(Eina.Binbuf) @move @no_unused; [[Binbuf]]
        }
    }

    events {
       position_read,changed: void; [[Notifies @.position_read changed]]
       position_write,changed: void; [[Notifies @.position_write changed]]
       reallocated: void; [[Notifies the internal buffer was reallocated, thus whatever was returned by @.slice
                            becomes invalid.]]
    }

    implements {
        Efl.Object.finalize;
        Efl.Object.destructor;
        Efl.Io.Reader.read;
        Efl.Io.Reader.can_read { get; set; }
        Efl.Io.Reader.eos { get; set; }
        Efl.Io.Writer.write;
        Efl.Io.Writer.can_write { get; set; }
        Efl.Io.Closer.close;
        Efl.Io.Closer.closed { get; }
        Efl.Io.Closer.close_on_exec { get; set; }
        Efl.Io.Closer.close_on_invalidate { get; set; }
        Efl.Io.Sizer.resize;
        Efl.Io.Sizer.size { get; }
        Efl.Io.Positioner.seek;
        Efl.Io.Positioner.position { get; }
    }
}