Class: CAConstString

Inherits:
Object
  • Object
show all
Includes:
CArray::StringOperationMixin
Defined in:
lib/carray/const_string.rb

Overview

Read-only column of variable-length Strings: every element's bytes are packed into one shared buffer, with a (start, end) byte-range pair per element (the Arrow string layout).

Built through CArray.const_string. For a column with heavy duplication (categorical labels) prefer CACategorical, which stores each distinct value once.

Instance Method Summary collapse

Methods included from CArray::StringOperationMixin

#bytesize, #capitalize, #center, #chomp, #delete_prefix, #delete_suffix, #downcase, #encode, #end_with?, #extract, #force_encoding, #gsub, #in?, #include?, #ljust, #lstrip, #match?, #rindex, #rjust, #rstrip, #scrub, #start_with?, #str_index, #str_len, #strip, #swapcase, #to_const_string, #to_f, #to_fixlen_string, #to_i, #to_string, #upcase

Instance Method Details

#categorize(labels: nil, sort_labels: false) ⇒ CACategorical

Returns categories keyed on the strings.

Returns:



314
315
316
 
# File 'lib/carray/const_string.rb', line 314

def categorize (labels: nil, sort_labels: false)
  to_string.categorize(labels: labels, sort_labels: sort_labels)
end

#difference(other, sort: false) ⇒ CAConstString

Returns the distinct strings only self has.

Returns:



296
297
298
 
# File 'lib/carray/const_string.rb', line 296

def difference (other, sort: false)
  const_string_lift(to_string.difference(string_operand(other), sort: sort))
end

#intersection(other, sort: false) ⇒ CAConstString

Returns the distinct strings present in both.

Returns:



290
291
292
 
# File 'lib/carray/const_string.rb', line 290

def intersection (other, sort: false)
  const_string_lift(to_string.intersection(string_operand(other), sort: sort))
end

#is_in(values) ⇒ CArray

Returns boolean, true where the cell's string is in values.

Returns:

  • (CArray) —

    boolean, true where the cell's string is in values.



284
285
286
 
# File 'lib/carray/const_string.rb', line 284

def is_in (values)
  to_string.is_in(string_operand(values))
end

#is_mode(axis: nil) ⇒ CArray

Returns boolean, true where the cell holds a modal string.

Returns:

  • (CArray) —

    boolean, true where the cell holds a modal string.



272
273
274
 
# File 'lib/carray/const_string.rb', line 272

def is_mode (axis: nil)
  to_string.is_mode(axis: axis)
end

#locate_addr(ref) ⇒ CArray

Returns for each cell, its address in ref (UNDEF when absent).

Returns:

  • (CArray) —

    for each cell, its address in ref (UNDEF when absent).



308
309
310
 
# File 'lib/carray/const_string.rb', line 308

def locate_addr (ref)
  to_string.locate_addr(string_operand(ref))
end

#mask_duplicates(axis: nil) ⇒ CAConstString

Returns a copy with every repeat occurrence masked.

Returns:

  • (CAConstString) —

    a copy with every repeat occurrence masked.



278
279
280
 
# File 'lib/carray/const_string.rb', line 278

def mask_duplicates (axis: nil)
  const_string_lift(to_string.mask_duplicates(axis: axis))
end

#max(axis: nil, keep_axis: false) ⇒ String, CAConstString

Byte-largest counterpart of #min.

Returns:



173
174
175
176
 
# File 'lib/carray/const_string.rb', line 173

def max (*args, **kw)
  return __max_bytes__ || UNDEF if args.empty? && kw.empty?
  const_string_lift(to_string.max(*args, **kw))
end

#max_index(axis: nil) ⇒ Integer, CArray

Returns where the byte-largest string sits.

Returns:

  • (Integer, CArray) —

    where the byte-largest string sits.



193
194
195
 
# File 'lib/carray/const_string.rb', line 193

def max_index (*args, **kw)
  to_string.max_index(*args, **kw)
end

#min(axis: nil, keep_axis: false) ⇒ String, CAConstString

Returns the byte-smallest string, skipping masked cells; UNDEF when every cell is masked or the array is empty.

Returns:



165
166
167
168
 
# File 'lib/carray/const_string.rb', line 165

def min (*args, **kw)
  return __min_bytes__ || UNDEF if args.empty? && kw.empty?
  const_string_lift(to_string.min(*args, **kw))
end

#min_index(axis: nil) ⇒ Integer, CArray

Returns where the byte-smallest string sits.

Returns:

  • (Integer, CArray) —

    where the byte-smallest string sits.



187
188
189
 
# File 'lib/carray/const_string.rb', line 187

def min_index (*args, **kw)
  to_string.min_index(*args, **kw)
end

#minmax(axis: nil, keep_axis: false) ⇒ Array

Returns [min, max].

Returns:

  • (Array) —

    [min, max].



180
181
182
183
 
# File 'lib/carray/const_string.rb', line 180

def minmax (*args, **kw)
  return [min, max] if args.empty? && kw.empty?
  to_string.minmax(*args, **kw).map { |r| const_string_lift(r) }
end

#mode(axis: nil) ⇒ CAConstString, Array

Returns the most frequent string(s).

Returns:



265
266
267
268
 
# File 'lib/carray/const_string.rb', line 265

def mode (axis: nil)
  r = to_string.mode(axis: axis)
  r.is_a?(Array) ? r.map { |c| const_string_lift(c) } : const_string_lift(r)
end

#nunique(axis: nil, keep_axis: false) ⇒ Integer, CArray

Returns the number of distinct strings.

Returns:

  • (Integer, CArray) —

    the number of distinct strings.



259
260
261
 
# File 'lib/carray/const_string.rb', line 259

def nunique (axis: nil, keep_axis: false)
  to_string.nunique(axis: axis, keep_axis: keep_axis)
end

#order(*args) ⇒ CArray

Returns the ordering of the cells by string order.

Returns:

  • (CArray) —

    the ordering of the cells by string order.



157
158
159
 
# File 'lib/carray/const_string.rb', line 157

def order (*args, **kw)
  to_string.order(*args, **kw)
end

#partition_copy(kth, axis: nil) ⇒ CAConstString

Returns partitioned about the kth string in order.

Returns:



199
200
201
 
# File 'lib/carray/const_string.rb', line 199

def partition_copy (*args, **kw)
  const_string_lift(to_string.partition_copy(*args, **kw))
end

#partition_index(kth, axis: nil) ⇒ CArray

Returns the indices that partition about the kth string.

Returns:

  • (CArray) —

    the indices that partition about the kth string.



205
206
207
 
# File 'lib/carray/const_string.rb', line 205

def partition_index (*args, **kw)
  to_string.partition_index(*args, **kw)
end

#rank_index(axis: nil) ⇒ CArray

Returns each cell's rank in string order.

Returns:

  • (CArray) —

    each cell's rank in string order.



151
152
153
 
# File 'lib/carray/const_string.rb', line 151

def rank_index (*args, **kw)
  to_string.rank_index(*args, **kw)
end

#sort(axis: nil, kind: :quick, masked_position: :last) ⇒ CAConstString

Returns a sorted CAConstString view, gathered over the same buffer and offsets. With no axis: the array is flattened first, as CArray#sort does.

Returns:



119
120
121
122
 
# File 'lib/carray/const_string.rb', line 119

def sort (*args, **kw)
  addr = sort_addr(*args, **kw)
  kw[:axis].nil? ? self[addr.flatten] : self[addr]
end

#sort_addr(axis: nil, kind: :quick, masked_position: :last) ⇒ CArray

Returns the view-flat addresses that index a sort by string order.

Returns:

  • (CArray) —

    :int64 addresses.



135
136
137
138
139
140
 
# File 'lib/carray/const_string.rb', line 135

def sort_addr (*args, **kw)
  # The native scan has no notion of an incomparable sentinel, so a masked
  # column goes the same way a per-axis one does.
  return __sort_addr_bytes__ if args.empty? && kw.empty? && ! has_mask?
  to_string.sort_addr(*args, **kw)
end

#sort_copy(axis: nil, kind: :quick, masked_position: :last) ⇒ CAConstString

Returns an owned sorted CAConstString; the materialised counterpart to #sort.

Returns:



128
129
130
 
# File 'lib/carray/const_string.rb', line 128

def sort_copy (*args, **kw)
  sort(*args, **kw).copy
end

#sort_index(axis: nil, kind: :quick, masked_position: :last) ⇒ CArray

Returns the per-fiber indices that index a sort by string order.

Returns:

  • (CArray) —

    :int64 indices.



145
146
147
 
# File 'lib/carray/const_string.rb', line 145

def sort_index (*args, **kw)
  to_string.sort_index(*args, **kw)
end

#template(type = nil, **opts) ⇒ CArray

CAConstString is the one Face with three separate entities -- storage (int64 offset), surface (fixlen), and the length-prefixed buffer -- so it has no byte-compatible blank form (other Faces have surface == storage or a struct tail, which the core template lift handles). A same-class template would be an unusable shell, so override it: with an explicit type defer to the generic (plain) path; with no type return a plain same-shape object array (a fillable string container), honouring a block.

Returns:



218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/carray/const_string.rb', line 218

def template (*args, &block)
  return super unless args.empty?    # a type was given: generic plain path
  out = CArray.object(*shape)
  if block
    if block.arity == 0
      out[] = block.call
    else
      out.map_with_index! { |_, *idx| block.call(*idx) }
    end
  end
  out
end

#union(other, sort: false) ⇒ CAConstString

Returns the distinct strings of either side.

Returns:



302
303
304
 
# File 'lib/carray/const_string.rb', line 302

def union (other, sort: false)
  const_string_lift(to_string.union(string_operand(other), sort: sort))
end

#unique(sort: false) ⇒ CAConstString

Returns the distinct strings.

Returns:



246
247
248
 
# File 'lib/carray/const_string.rb', line 246

def unique (sort: false)
  const_string_lift(to_string.unique(sort: sort))
end

#value_counts(sort: false) ⇒ Array(CAConstString, CArray)

Returns [values, counts].

Returns:



252
253
254
255
 
# File 'lib/carray/const_string.rb', line 252

def value_counts (sort: false)
  values, counts = to_string.value_counts(sort: sort)
  [const_string_lift(values), counts]
end