# rank.icn: Taxonomic level object for nomo.icn.
#--

$define  RANK_REVISION      "$Revision: 1.5 $"
$define  RANK_DATE          "$Date: 1996/10/30 23:52:26 $"

#================================================================
# Class Rank: Each instance describes one level of a
# taxonomic hierarchy, that is, one rank such as Order or Genus.
#----------------------------------------------------------------
# METHODS
#----------------------------------------------------------------
# Rank_New ( rankCode, optional, keyLen, name, depth )
#   [ if the arguments satisfy the corresponding invariants ->
#       return a Rank object representing those values
#   ]
#--
# Rank_Hier ( self )
#   [ return the Hier object containing self
#   ]
#--
# Rank_Code ( self )
#   [ return self's rank code as a string of length Hier_Rank_Code()
#   ]
#--
# Rank_Is_Optional ( self )
#   [ if self is an optional rank -> return &null
#   | else -> fail
#   ]
#--
# Rank_Key_Len ( self )
#   [ return self's key length
#   ]
#--
# Rank_Name ( self )
#   [ return self's name
#   ]
#--
# Rank_Depth ( self )
#   [ return self's depth
#   ]
#--
# Rank_Show ( self )
#   [ return a string that displays the rank code, optional,
#     key length, name, and depth fields
#   ]
#----------------------------------------------------------------
# STATE
#----------------------------------------------------------------
  record rankTag (      # State for one Rank object
    rankCode,   # Rank code, e.g., "-f" for subfamily
    optional,   # 1 if optional, else &null
    keyLen,     # Number of digits in this rank's part of a txKey
    name,       # This rank's name as a string, e.g., "Species"
    depth )     # Depth: root=1, child of root=2, etc.
#----------------------------------------------------------------
# INVARIANTS
#----------------------------------------------------------------
# .rankCode == the code for this rank, a left-justified, blank-
#   filled string of length Hier_Rank_Code_Len()
# .optional ==
#     if this rank is optional -> a non-&null value
#     else -> &null
# .keyLen == the number of digits required to hold the largest number
#     of these ranks that will ever occur in the next highest rank,
#     as an integer >= 1 (example: if there are between 10 and 99
#     families in an order, this value should be 2 for the family rank)
# .name == the name of this rank as a string, trimmed both ends
#----------------------------------------------------------------


# - - -   R a n k _ N e w   - - -

#-- 1996-07-12: verified, A. Stavely

procedure Rank_New ( rankCode, optional, keyLen, name, depth )
  local self

  self           :=  rankTag ( );
  self.rankCode  :=  rankCode;
  self.optional  :=  optional;
  self.keyLen    :=  keyLen;
  self.name      :=  name;
  self.depth     :=  depth;

  return self;
end # --- Rank_New ---


# - - -   R a n k _ C o d e   - - -

#-- 1996-07-12: verified, A. Stavely

procedure Rank_Code ( self )
  return self.rankCode;
end


# - - -   R a n k _ I s _ O p t i o n a l   - - -

#-- 1996-07-12: verified, A. Stavely

procedure Rank_Is_Optional ( self )
  if  \ self.optional then
    return &null
  else
    fail;
end


# - - -   R a n k _ K e y _ L e n   - - -

#-- 1996-07-12: verified, A. Stavely

procedure Rank_Key_Len ( self )
  return self.keyLen;
end


# - - -   R a n k _ N a m e   - - -

#-- 1996-07-12: verified, A. Stavely

procedure Rank_Name ( self )
  return self.name;
end


# - - -   R a n k _ D e p t h   - - -

#-- 1996-07-12: verified, A. Stavely

procedure Rank_Depth ( self )
  return self.depth;
end


# - - -   R a n k _ S h o w   - - -

#-- 1996-07-12: verified, A. Stavely

procedure Rank_Show ( self )
#--
# Format of the output:
#   "<name> (<rankCode>, depth <depth>, keylen <keylen>[, optional])"
#--
  local result
  result  :=  self.name || " (" || trim ( self.rankCode ) ||
    ", depth " || self.depth || ", keylen " || self.keyLen;

  if  \ self.optional  then
    result  ||:=  ", optional";

  result  ||:=  ")";

  return result;
end # --- Rank_Show ---