class LUSI::API::Calendar::Year

Represents an academic year in the LUSI API

Attributes

full_year[RW]

@!attribute [rw] full_year

@return [String, nil] the full text description of the academic year
lookup[RW]

@!attribute [rw] lookup

@return [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution

Public Class Methods

get_current_academic_year(api = nil, lookup = nil) { |obj| ... } click to toggle source

Returns a Year instance for the current academic year @param api [LUSI::API::Core::API] the LUSI API instance @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution @return [LUSI::API::Calendar::Year] the current academic year @yield [obj] Passes the Year instance to the block @yieldparam obj [LUSI::API::Calendar::Year] the Year instance

# File lib/lusi_api/calendar.rb, line 111
def self.get_current_academic_year(api = nil, lookup = nil)
  xml = api.call('LUSIReference', 'General.asmx', 'GetCurrentAcademicYear')
  obj = new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:Year'), lookup)
  yield(obj) if block_given?
  obj
end
get_instance(api = nil, lookup = nil, *years, use_lookup: true, **kwargs) click to toggle source

Returns selected or all defined year instances @param api [LUSI::API::Core::API] the LUSI API instance @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution Remaining positional parameters are years or year identities of the required years @param use_lookup [Boolean] if true, use the lookup service to identify instances before trying the API @return [Array<LUSI::API::Calendar::Year>, nil] the defined year instances @yield [obj] Passes the Year instance to the block @yieldparam obj [LUSI::API::Calendar::Year] the Year instance

Calls superclass method LUSI::API::Core::Code::get_instance
# File lib/lusi_api/calendar.rb, line 126
def self.get_instance(api = nil, lookup = nil, *years, use_lookup: true, **kwargs)
  results = nil
  # Search the lookup service if required
  if lookup && use_lookup
    year_lookup = lookup.service(:year)
    results = year_lookup.values if year_lookup
  end
  # Search the API if required
  results = super(api, lookup, 'LUSIReference', 'General.asmx', 'GetYears', 'xmlns:Year') if results.nil?
  # Return the results
  if results.nil? || years.nil? || years.empty?
    # No results or no filtering required
    results
  else
    # Return the year instances for the specified years
    years = years.map { |year| lusi_year_identity(year) }
    results.select { |result| years.include?(result.identity) }
  end
end
new(xml = nil, lookup = nil, full_year: nil, **kwargs) click to toggle source

Initialises a new Year instance @param (see LUSI::API::Core::Code#initialize) @param full_year [String, nil] the full text description of the academic year @return [void]

Calls superclass method LUSI::API::Core::BasicCode::new
# File lib/lusi_api/calendar.rb, line 150
def initialize(xml = nil, lookup = nil, full_year: nil, **kwargs)
  super(xml, lookup, **kwargs)
  self.full_year = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:FullYear', full_year)
  # Store the lookup service for year arithmetic operations
  self.lookup = lookup
end

Protected Class Methods

get_instance_params(**kwargs) click to toggle source

Returns an empty parameter hash for the LUSI API call

# File lib/lusi_api/calendar.rb, line 225
def self.get_instance_params(**kwargs)
  {}
end

Public Instance Methods

+(years = 0) click to toggle source

Returns the year instance n years after this one @param years [Integer] the number of years to add to the instance's year @return [LUSI::API::Calendar::Year] the year instance

# File lib/lusi_api/calendar.rb, line 160
def +(years = 0)
  self.offset(years)
end
-(years = 0) click to toggle source

Returns the year instance n years before this one @param years [Integer] the number of years to subtract from the instance's year @return [LUSI::API::Calendar::Year] the year instance

# File lib/lusi_api/calendar.rb, line 167
def -(years = 0)
  self.offset(-years)
end
next(count = 1) click to toggle source

Returns the year instance immediately following this one @return [LUSI::API::Calendar::Year] the year instance

# File lib/lusi_api/calendar.rb, line 173
def next(count = 1)
  count = count.to_i
  if count == 1
    self.offset(1)
  else
    result = []
    (1..count).each { |offset| result.push(self.offset(offset)) }
    result
  end
end
offset(years = 0) click to toggle source

Returns the year instance n years after/before this one @param years [Integer] the number of years to add to the instance's year @return [LUSI::API::Calendar::Year] the year instance

# File lib/lusi_api/calendar.rb, line 187
def offset(years = 0)
  return self if years == 0
  year = self.class.lusi_year(self, self.lookup, as_instance: true, offset: years)
end
previous(count = 1) click to toggle source

Returns the year instance immediately preceding this one @return [LUSI::API::Calendar::Year] the year instance

# File lib/lusi_api/calendar.rb, line 194
def previous(count = 1)
  count = count.to_i
  if count == 1
    self.offset(-1)
  else
    result = []
    (1..count).each { |offset| result.push(self.offset(-offset)) }
    result
  end
end
range(from = nil, to = nil) click to toggle source

Returns a list of year instances around (immediately preceding and following) this one @param from [Integer, Range] the starting offset relative to the current year @param to [Integer] the ending offset relative to the current year @return [Array<LUSI::API::Calendar::Year>] the year instances

# File lib/lusi_api/calendar.rb, line 209
def range(from = nil, to = nil)
  from = (from..to) unless from.is_a?(Range)
  result = []
  from.each { |offset| result.push(self.offset(offset)) }
  result
end
to_s() click to toggle source

Returns a string representation of the Year instance @return [String] the string representation of the Year instance

# File lib/lusi_api/calendar.rb, line 218
def to_s
  self.full_year
end