src/HashMap/EPTF_CLL_HashMapStr2Int_Functions.ttcn

///////////////////////////////////////////////////////////////////////////////
//                                                                           //
// Copyright (c) 2000-2019 Ericsson Telecom AB                               //
//                                                                           //
// All rights reserved. This program and the accompanying materials          //
// are made available under the terms of the Eclipse Public License v2.0     //
// which accompanies this distribution, and is available at                  //
// https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.html                                 //
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////  Detailed Comments:
//    Str2Int HashMap is a representation of the HashMap for charstring keys and integer data.
//    Supported hashmap type in this module(key/data): charstring -> integer
//    Most of the functions if the str2int HashMap are implemented as external functions.
//
//    Public functions:
//      <f_EPTF_str2int_HashMap_DumpByID> - Dump the content of a hash table by ID.
//      <f_EPTF_str2int_HashMap_Dump> - Dump the content of a hash table.
//      <f_EPTF_str2int_HashMap_DumpAll> - Dump the content of every hash table.
//      <f_EPTF_str2int_HashMap_New> - Creates a new hashmap.
//      <f_EPTF_str2int_HashMap_GetID> - To get the ID of the hashmap from the name.
//      <f_EPTF_str2int_HashMap_Delete> - Deletes the hashmap.
//      <f_EPTF_str2int_HashMap_DeleteById> - Deletes the hashmap by ID.
//      <f_EPTF_str2int_HashMap_Assign> - Assignment of one hashmap to another.
//      <f_EPTF_str2int_HashMap_Insert> - Inserts an element to hashmap.
//      <f_EPTF_str2int_HashMap_Update> - Updates an element in hashmap.
//      <f_EPTF_str2int_HashMap_Find> - Finds an element in hashmap.
//      <f_EPTF_str2int_HashMap_Erase> - Erases an element from hashmap.
//      <f_EPTF_str2int_HashMap_Clear> - Clear all elements from hashmap.
//      <f_EPTF_str2int_HashMap_Size> - Returns the size of hashmap. Size = the used buckets
//      <f_EPTF_str2int_HashMap_MaxSize> - Returns the maximum size of hashmap(largest possible size).
//      <f_EPTF_str2int_HashMap_CallHashFunc> - Calls the hash function of a given hashmap.
//      <f_EPTF_str2int_HashMap_Empty> - Check whether the hashmap is empty. true if the hash_map's size is 
//      <f_EPTF_str2int_HashMap_BucketCount> - Returns the number of buckets used by the hash_map.
//      <f_EPTF_str2int_HashMap_Begin> - To get the first element of hashmap. 
//      <f_EPTF_str2int_HashMap_Next> - To get the next element of hashmap.
//
//   Deprecated functions:
//      <f_EPTF_str2int_HashMap_Init> - Initializes the hash table. DEPRECATED!!! Use <f_EPTF_HashMap_init_CT> instead!
//      <f_EPTF_str2int_HashMap_Cleanup> - Deletes all hashmaps. KEPT FOR BACKWARD COMPATIBILITY. DO NOT USE IT!
//      <f_EPTF_str2int_HashMap_Resize> - Increases the bucket count to at least pl_hashsize. KEPT FOR BACKWARD COMPATIBILITY. DO NOT USE IT!
//
/////////////////////////////////////////////////////////////
module EPTF_CLL_HashMapStr2Int_Functions {

import from EPTF_CLL_HashMap_Definitions all;
import from EPTF_CLL_HashMap_Functions all;
import from EPTF_CLL_Common_Functions all;
import from EPTF_CLL_Base_Functions all;

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_DumpByID
// 
// Purpose:
//   External function call to dump the content of a specific hashmap.
// 
// Parameters:
//   pl_id - *in* *integer* - the id of the hashmap
// 
// Return Value:
//   -
//
//  Errors:
//   If HashMap ID (pl_id) is not valid.
///////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_DumpByID (
  in integer pl_id );

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_Dump
// 
// Purpose:
//   External function call to dump the content of a specific hashmap.
// 
// Parameters:
//   pl_name - *in* *charstring* - the name of the hashmap
// 
// Return Value:
//   -
//
//  Errors:
//   -
///////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_Dump (
  in charstring pl_name );

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_DumpAll
// 
// Purpose:
//   External function call to dump the content of all existing hashmap.
// 
// Parameters:
//   -
// 
// Return Value:
//   -
//
//  Errors:
//   -
///////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_DumpAll ();

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_Init
// 
// Purpose:
//   Function call to initialize the hash table.
//   This function is DEPRECATED! Will be removed after this release!
// 
// Parameters:
//   -
// Return Value:
//   -
//
//  Errors:
//   -
///////////////////////////////////////////////////////////
public function f_EPTF_str2int_HashMap_Init (in charstring pl_selfName := "") runs on EPTF_HashMap_CT {
  if (pl_selfName == "" and not f_EPTF_Base_cleanupIsInProgress()) {
    f_EPTF_Common_error(%definitionId&": Error: f_EPTF_Base_init_CT should be called before this function or use f_EPTF_HashMap_init_CT");
    f_EPTF_Base_stopAll(none);
  }
  f_EPTF_HashMap_init_CT(pl_selfName);
}

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_Cleanup
// 
// Purpose:
//   External function for deleting ALL hashmaps.
//   DEPRECATED! Do not use it!
// 
// Parameters:
//   -
// Return Value:
//   -
//
//  Errors:
//   -
///////////////////////////////////////////////////////////

public function f_EPTF_str2int_HashMap_Cleanup(){
//do not need to do anything
};

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_New
// 
// Purpose:
//   External function call to create a new hashmap.
// 
// Parameters:
//   pl_name - *in* *charstring* - the name of the hashmap
// 
// Return Value:
//   integer - the ID of the hashmap
//
//  Errors:
//   -
///////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_New (
  in charstring pl_name ) return integer;

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_GetID
// 
// Purpose:
//   External function call to get the ID of the hashmap from the name.
// 
// Parameters:
//   pl_name - *in* *charstring* - the name of the hashmap
//   pl_id - *out* *integer* - the ID of the hashmap
// 
// Return Value:
//   boolean - true if ID found
//
//  Errors:
//   -
///////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_GetID (
  in charstring pl_name,
  out integer pl_id) return boolean;

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_Delete
// 
// Purpose:
//   External function call to delete the hashmap.
// 
// Parameters:
//   pl_name - *in* *charstring* - the name of the hashmap
// 
// Return Value:
//   -
//
//  Errors:
//   -
///////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_Delete (
  in charstring pl_name );

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_DeleteById
// 
// Purpose:
//   External function call to delete the hashmap by Id.
// 
// Parameters:
//   pl_id - *in* *integer* - the id of the hashmap returned by
//      <f_EPTF_str2int_HashMap_New>, or <f_EPTF_str2int_HashMap_GetID>
// 
// Return Value:
//   -
//
//  Errors:
//   -
///////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_DeleteById (
  in integer pl_id );

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_Assign
// 
// Purpose:
//   External function call for assignment of one hashmap to another.
//   pl_id1 := pl_id2. 
// 
// Parameters:
//   pl_id1 - *in* *integer* - the ID of the hashmap1
//   pl_id2 - *in* *integer* - the ID of the hashmap2
// 
// Return Value:
//   -
//
//  Errors:
//   If HashMap ID (pl_id) is not valid.
///////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_Assign (
  in integer pl_id1,
  in integer pl_id2 );

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_Insert
// 
// Purpose:
//   External function call to insert an element to hashmap.
// 
// Parameters:
//   pl_id - *in* *integer* - the ID of the hashmap
//   pl_key - *in* *charstring* - the key of the hashmap
//   pl_data - *in* *integer* - the data to be inserted
// 
// Return Value:
//   -
//
//  Errors:
//   If HashMap ID (pl_id) is not valid.
///////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_Insert (
  in integer pl_id,
  in charstring pl_key,
  in integer pl_data );

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_Update
// 
// Purpose:
//   External function call for Updating an element in HashMap. Checks whether the key is exists.
//   If the key not exists insert the <key,data> pair. If exists updates the data to
//   the new value.
// 
// Parameters:
//   pl_id - *in* *integer* - the ID of the hashmap
//   pl_key - *in* *charstring* - the key of the hashmap
//   pl_data - *in* *integer* - the data to be inserted
// 
// Return Value:
//   -
//
//  Errors:
//   If HashMap ID (pl_id) is not valid.
///////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_Update (
  in integer pl_id,
  in charstring pl_key,
  in integer pl_data );

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_Find
// 
// Purpose:
//   External function call to find an element in hashmap.
// 
// Parameters:
//   pl_id - *in* *integer* - the ID of the hashmap
//   pl_key - *in* *charstring* - the key of the hashmap
//   pl_data - *out* *integer* - the searched data
// 
// Return Value:
//   boolean - if we found the data
//
//  Errors:
//   If HashMap ID (pl_id) is not valid.
///////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_Find (
  in integer pl_id,
  in charstring pl_key,
  out integer pl_data ) return boolean;

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_Erase
// 
// Purpose:
//   External function call to erase an element from hashmap.
// 
// Parameters:
//   pl_id - *in* *integer* - the ID of the hashmap
//   pl_key - *in* *charstring* - the key of the hashmap
// 
// Return Value:
//   -
//
//  Errors:
//   If HashMap ID (pl_id) is not valid.
////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_Erase (
  in integer pl_id,
  in charstring pl_key );

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_Clear
// 
// Purpose:
//   External function call to clear all elements from hashmap.
// 
// Parameters:
//   pl_id - *in* *integer* - the ID of the hashmap
// 
// Return Value:
//   -
//
//  Errors:
//   If HashMap ID (pl_id) is not valid.
/////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_Clear (
  in integer pl_id );

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_Size
// 
// Purpose:
//   External function call to return the size of hashmap. 
//   Size = the used buckets.
// 
// Parameters:
//   pl_id - *in* *integer* - the ID of the hashmap
// 
// Return Value:
//   integer - the size of hashmap
//
//  Errors:
//   If HashMap ID (pl_id) is not valid.
//////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_Size (
  in integer pl_id ) return integer;

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_MaxSize
// 
// Purpose:
//   External function call to return the maximum size of hashmap. 
// 
// Parameters:
//   pl_id - *in* *integer* - the ID of the hashmap
// 
// Return Value:
//   float - the maximum size of hashmap
//
//  Errors:
//   If HashMap ID (pl_id) is not valid.
//////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_MaxSize (
  in integer pl_id ) return float;

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_CallHashFunc
// 
// Purpose:
//   External function call to call the hash function of a given hashmap. 
// 
// Parameters:
//   pl_id - *in* *integer* - the ID of the hashmap, which hashfunction we use
//   pl_key - *in* *charstring* - the key of the hashmap
// 
// Return Value:
//   integer - the hashvalue of key
//
//  Errors:
//   If HashMap ID (pl_id) is not valid.
//////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_CallHashFunc (
  in integer pl_id,
  in charstring pl_key ) return integer;

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_Empty
// 
// Purpose:
//   External function call to check whether the hashmap is empty. 
//   true if the hash_map's size is 0.
// 
// Parameters:
//   pl_id - *in* *integer* - the ID of the hashmap
// 
// Return Value:
//   boolean - true if the hash_map's size is 0.
//
//  Errors:
//   If HashMap ID (pl_id) is not valid.
//////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_Empty (
  in integer pl_id ) return boolean;

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_Resize
// 
// Purpose:
//   External function call to increase the bucket count to at least pl_hashsize.
// 
// Parameters:
//   pl_id - *in* *integer* - the ID of the hashmap
//   pl_hashsize - *in* *integer* - the new bucketsize 
// 
// Return Value:
//   -
//
//  Errors:
//   If HashMap ID (pl_id) is not valid.
/////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_Resize (
  in integer pl_id,
  in integer pl_hashsize );

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_BucketCount
// 
// Purpose:
//   External function call to return the number of buckets used by the hash_map. 
//   This is the booked size.
//   It contains empty buckets also.
// 
// Parameters:
//   pl_id - *in* *integer* - the ID of the hashmap 
// 
// Return Value:
//   integer - the bucketsize
//
//  Errors:
//   If HashMap ID (pl_id) is not valid.
//////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_BucketCount (
  in integer pl_id ) return integer;

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_Begin
// 
// Purpose:
//   External function call to get the first element of hashmap. 
//   In TTCN we can't use iterators, so we get back the first key element.
// 
// Parameters:
//   pl_id - *in* *integer* - the ID of the hashmap
//   pl_key - *out* *integer* - the first key in hashmap
// 
// Return Value:
//   boolean - false if the hashmap is empty
//
//  Errors:
//   If HashMap ID (pl_id) is not valid.
//////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_Begin (
  in integer pl_id,
  out charstring pl_key) return boolean;

///////////////////////////////////////////////////////////
// Function: f_EPTF_str2int_HashMap_Next
// 
// Purpose:
//   External function call to get the next element of hashmap. 
//   In TTCN we can't use iterators, so we get back a key element's next key element.
// 
// Parameters:
//   pl_id - *in* *integer* - the ID of the hashmap
//   pl_iter - *inout* *charstring* - in = the iterator of the hashmap (iterator = key)
//                                    out = the next key in hashmap
// 
// Return Value:
//   boolean - false if no next key in hashmap
//
//  Errors:
//   If HashMap ID (pl_id) is not valid.
//////////////////////////////////////////////////////////
public external function f_EPTF_str2int_HashMap_Next (
  in integer pl_id,
  inout charstring pl_iter) return boolean;


} // end of module EPTF_CLL_HashMapStr2Int_Functions