ceph/src/arrow/python/pyarrow/builder.pxi

   1 # Licensed to the Apache Software Foundation (ASF) under one
   2 # or more contributor license agreements.  See the NOTICE file
   3 # distributed with this work for additional information
   4 # regarding copyright ownership.  The ASF licenses this file
   5 # to you under the Apache License, Version 2.0 (the
   6 # "License"); you may not use this file except in compliance
   7 # with the License.  You may obtain a copy of the License at
   8 #
   9 #   http://www.apache.org/licenses/LICENSE-2.0
  10 #
  11 # Unless required by applicable law or agreed to in writing,
  12 # software distributed under the License is distributed on an
  13 # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  14 # KIND, either express or implied.  See the License for the
  15 # specific language governing permissions and limitations
  16 # under the License.
  17
  18
  19 cdef class StringBuilder(_Weakrefable):
  20     """
  21     Builder class for UTF8 strings.
  22
  23     This class exposes facilities for incrementally adding string values and
  24     building the null bitmap for a pyarrow.Array (type='string').
  25     """
  26     cdef:
  27         unique_ptr[CStringBuilder] builder
  28
  29     def __cinit__(self, MemoryPool memory_pool=None):
  30         cdef CMemoryPool* pool = maybe_unbox_memory_pool(memory_pool)
  31         self.builder.reset(new CStringBuilder(pool))
  32
  33     def append(self, value):
  34         """
  35         Append a single value to the builder.
  36
  37         The value can either be a string/bytes object or a null value
  38         (np.nan or None).
  39
  40         Parameters
  41         ----------
  42         value : string/bytes or np.nan/None
  43             The value to append to the string array builder.
  44         """
  45         if value is None or value is np.nan:
  46             self.builder.get().AppendNull()
  47         elif isinstance(value, (bytes, str)):
  48             self.builder.get().Append(tobytes(value))
  49         else:
  50             raise TypeError('StringBuilder only accepts string objects')
  51
  52     def append_values(self, values):
  53         """
  54         Append all the values from an iterable.
  55
  56         Parameters
  57         ----------
  58         values : iterable of string/bytes or np.nan/None values
  59             The values to append to the string array builder.
  60         """
  61         for value in values:
  62             self.append(value)
  63
  64     def finish(self):
  65         """
  66         Return result of builder as an Array object; also resets the builder.
  67
  68         Returns
  69         -------
  70         array : pyarrow.Array
  71         """
  72         cdef shared_ptr[CArray] out
  73         with nogil:
  74             self.builder.get().Finish(&out)
  75         return pyarrow_wrap_array(out)
  76
  77     @property
  78     def null_count(self):
  79         return self.builder.get().null_count()
  80
  81     def __len__(self):
  82         return self.builder.get().length()