Package core :: Module buffer

[hide private]
[frames] | no frames]

# Source Code for Module core.buffer

      1  # Copyright 2011-2012 the original author or authors.
      2  #
      3  # Licensed under the Apache License, Version 2.0 (the "License");
      4  # you may not use this file except in compliance with the License.
      5  # You may obtain a copy of the License at
      6  #
      7  #      http://www.apache.org/licenses/LICENSE-2.0
      8  #
      9  # Unless required by applicable law or agreed to in writing, software
     10  # distributed under the License is distributed on an "AS IS" BASIS,
     11  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     12  # See the License for the specific language governing permissions and
     13  # limitations under the License.
     14
     15  """
     16  This module adds the buffer support to the python vert.x platform
     17  """
     18
     19  import org.vertx.java.core.buffer.Buffer
     20
     21  __author__ = "Scott Horn"
     22  __email__ = "scott@hornmicro.com"
     23  __credits__ = "Based entirely on work by Tim Fox http://tfox.org"
     24
     25 -class Buffer(object):
     26      """A Buffer represents a sequence of zero or more bytes that can be written to or read from, and which expands
     27      as necessary to accomodate any bytes written to it.
     28
     29      Buffers are used in many places in vert.x, for example to read/write data to/from NetSocket, AsyncFile,
     30      WebSocket, HttpClientRequest, HttpClientResponse, HttpServerRequest, HttpServerResponse etc.
     31
     32      There are two ways to write data to a Buffer: The first method involves methods that take the form set_XXX.
     33      These methods write data into the buffer starting at the specified position. The position does not have to be inside data that
     34      has already been written to the buffer; the buffer will automatically expand to encompass the position plus any data that needs
     35      to be written. All positions are measured in bytes and start with zero.
     36
     37      The second method involves methods that take the form append-XXX; these methods append data at the end of the buffer.
     38      Methods exist to both set and append all primitive types, String and  other instances of Buffer.
     39
     40      Data can be read from a buffer by invoking methods which take the form get_XXX. These methods take a parameter
     41      representing the position in the Buffer from where to read data.
     42      """
     43 -    def __init__(self, buffer):
     44          self.buffer = buffer
     45
     46 -    def __repr__( self):
     47          """ String representation of buffer """
     48          return self.buffer.toString("UTF-8")
     49
     50 -    def to_string(self, enc="UTF-8"):
     51          """ Buffer in enc encoding """
     52          return self.buffer.toString(enc)
     53
     54      @staticmethod
     55 -    def create_from_str(str, enc="UTF-8"):
     56          """ Create a buffer from a string in the enc encoding """
     57          return Buffer(org.vertx.java.core.buffer.Buffer(str, enc))
     58
     59      @staticmethod
     60 -    def create(initial_size_hint = 0):
     61          """ Creates a new empty buffer. initial_size_hint is a hint to the system for how much memory to initially allocate."""
     62          return Buffer(org.vertx.java.core.buffer.Buffer(initial_size_hint))
     63
     64 -    def get_byte(self, pos):
     65          """ Get the byte at position pos in the buffer. """
     66          return self.buffer.getByte(pos)
     67
     68 -    def get_fixnum(self, pos, bytes):
     69          """ Get the fixnum represented by a sequence of bytes starting at position pos in the buffer. """
     70          if bytes == 1:
     71            return self.buffer.getByte(pos)
     72          elif bytes ==  2:
     73            return self.buffer.getShort(pos)
     74          elif bytes ==  4:
     75            return self.buffer.getInt(pos)
     76          elif bytes ==  8:
     77            return self.buffer.getLong(pos)
     78          else:
     79            raise Exception("bytes must be 1, 2, 4, or 8")
     80
     81 -    def get_float(self, pos, bytes):
     82          """ Get the float represented by a sequence of bytes starting at position pos in the buffer. """
     83          if bytes == 4:
     84            return self.buffer.getFloat(pos)
     85          elif bytes == 8:
     86            return self.buffer.getDouble(pos)
     87          else:
     88            raise Exception("bytes must be 4 or 8")
     89
     90 -    def get_string(self, pos, end_pos, enc='UTF-8'):
     91          """ Return bytes from the buffer interpreted as a String """
     92          return self.buffer.getString(pos, end_pos, enc)
     93
     94 -    def get_buffer(self, pos, end_pos):
     95          """ Return bytes in the buffer as a Buffer """
     96          return Buffer(self.buffer.getBuffer(pos, end_pos))
     97
     98 -    def append_buffer(self, buff):
     99          """ Appends a buffer to the end of this buffer. The buffer will expand as necessary to accomodate any bytes written. """
    100          self.buffer.appendBuffer(buff._to_java_buffer())
    101          return self
    102
    103 -    def append_fixnum(self, num, bytes):
    104          """ Appends a fixnum to the end of this buffer. The buffer will expand as necessary to accomodate any bytes written. """
    105          if bytes == 1:
    106              self.buffer.appendByte(num)
    107          elif bytes == 2:
    108              self.buffer.appendShort(num)
    109          elif bytes ==  4:
    110              self.buffer.appendInt(num)
    111          elif bytes ==  8:
    112              self.buffer.appendLong(num)
    113          else:
    114            raise Exception("bytes must be 1, 2, 4, or 8")
    115          return self
    116
    117 -    def append_float(self, num, bytes):
    118          """ Appends a float to the end of this buffer. The buffer will expand as necessary to accomodate any bytes written. """
    119          if bytes == 4:
    120            self.buffer.appendFloat(num)
    121          elif bytes == 8:
    122            self.buffer.appendDouble(num)
    123          else:
    124            raise Exception("bytes must be 4 or 8")
    125
    126 -    def append_str(self, str, enc="UTF-8"):
    127          """ Appends a string to the end of this buffer. The buffer will expand as necessary to accomodate any bytes written. """
    128          self.buffer.appendString(str, enc)
    129          return self
    130
    131 -    def set_fixnum(self, pos, num, bytes):
    132          """ Sets bytes in the buffer to a representation of a fixnum. The buffer will expand as necessary to accomodate any bytes written. """
    133          if bytes == 1:
    134              self.buffer.setByte(pos, num)
    135          elif bytes == 2:
    136              self.buffer.setShort(pos, num)
    137          elif bytes == 4:
    138              self.buffer.setInt(pos, num)
    139          elif bytes == 8:
    140              self.buffer.setLong(pos, num)
    141          else:
    142            raise Exception("bytes must be 1, 2, 4, or 8")
    143          return self
    144
    145 -    def set_float(self, pos, num, bytes):
    146          """ Sets bytes in the buffer to a representation of a float. The buffer will expand as necessary to accomodate any bytes written. """
    147          if bytes == 4:
    148              self.buffer.setFloat(pos, num)
    149          elif bytes == 8:
    150              self.buffer.setDouble(pos, num)
    151          else:
    152              raise Exception("bytes must be 4 or 8")
    153          return self
    154
    155 -    def set_buffer(self, pos, buff):
    156          """ Sets bytes in this buffer to the bytes of the specified buffer. The buffer will expand as necessary to accomodate any bytes written. """
    157          self.buffer.setBytes(pos, buff._to_java_buffer)
    158          return self
    159
    160 -    def set_string(self, pos, str, enc="UTF-8"):
    161          """ Set bytes in the buffer to the string encoding in the specified encoding """
    162          self.buffer.setString(pos, str, enc)
    163          return self
    164
    165      @property
    166 -    def length(self):
    167          """ The length of this buffer, in bytes. """
    168          return self.buffer.length()
    169
    170 -    def copy(self):
    171          """ Get a copy of the entire buffer. """
    172          return Buffer(self.buffer.copy())
    173
    174 -    def _to_java_buffer(self):
    175          """ private """
    176          return self.buffer
    177