records(3)

💖 records — bestie edition 💖

okay so this is records(3), and yes, that's section 3 of the Erlang Module Definition manual, and it's literally about to become your new fave. 🎀

---

✨ NAME ✨

records — native records processing functions. that's the whole name, short and slay. 💅

🌸 DESCRIPTION 🌸

bestie, listen up. this module is a lil toolbox of functions for creating and inspecting native records. 🦋

⚠️ WARNING, and I'm not being dramatic: the main purpose of the functions in this module is for debugging, implementing library functions (such as printing of native records), and implementing tools (such as the Debugger). Use with care in production code. like... with CARE. in PRODUCTION code. no cap. 😭

🎀 DATA TYPES 🎀

create_options() :: #{is_exported := boolean()}.

options that can be used when creating a native record. ✨

• the value for the is_exported key should be a boolean indicating whether this record value is exported.

Consumed by:

• records:create/4

---

👑 FUNCTIONS 👑

💜 create/4

create(Module :: module(),
       RecordName :: atom(),
       Fields :: [{atom(), term()}],
       Options :: create_options()) ->
          record().

takes Fields and creates a native record Record with module Module and name RecordName. 🫶

the native record definition does not have to exist in the given module, and if it exists, it will not be used in any way. truly ignores it. iconic. 💀

⚠️ WARNING: because this function can create records that are inconsistent with the record definition in module Module, it can cause very subtle bugs; therefore, its use in applications is strongly discouraged. pls don't do it bestie, I'm begging. 🙈

the call can fail in the following ways:

• with a {badrecord,Record} exception if Module or RecordName are not atoms.
• with a {badmap, OptionsMap} exception if OptionsMap is not a map.
• with a {badfield, Field} exception if a field name in Fields is not an atom.
• with a badarg exception if Options does not have the is_exported key.
• with a badarg exception for other invalid arguments, such as a field name being repeated in Fields.

💫 Examples

1> R = records:create(test, a, [{z,3}, {x,1}, {y,2}], #{is_exported => true}).
#test:a{z = 3,x = 1,y = 2}
2> records:is_exported(R).
true
3> records:create(test, a, [{42,1}], #{is_exported => true}).
** exception error: bad field name: 42 in #test:a{}
     in function  records:create/4
        called as records:create(test,a,[{42,1}],#{is_exported => true})
4> records:create(test, a, [{x,1}, {x,2}], #{is_exported => true}).
** exception error: bad argument
     in function  records:create/4
        called as records:create(test,a,[{x,1},{x,2}],#{is_exported => true})

🦋 get/2

get(Key, Record) -> dynamic()
             when Key :: atom(), Record :: record().

returns value Value associated with Key if native record Record contains Key. giving lookup energy. ✨

this call fails with a badarg exception if Record is not a native record or if Key does not exist in Record.

💫 Examples

1> R = records:create(test, a, [{x,1}], #{is_exported=>false}).
#test:a{x = 1}
2> records:get(x, R).
1
3> records:get(y, R).
** exception error: bad argument
     in function  records:get/2
        called as records:get(y,#test:a{x = 1})

🌈 get_definition/2

get_definition(Module :: module(), RecordName :: atom()) ->
                       {create_options(),
                        [{FieldName :: atom(), Default :: dynamic()} |
                         (FieldName :: atom())]}.

retrieves the definition for native record Name in module Module. that's the whole vibe, no notes. 💜

🧚 get_field_names/1

get_field_names(Record) -> [Name]
                         when Record :: record(), Name :: atom().

returns a complete list of field names (keys) in native record Record, in the order of declaration. order matters bestie, it's not a random shuffle. 👑

this call fails with a {badrecord,Record} exception if Record is not a native record.

💫 Examples

1> R = records:create(test, a, [{x,1}], #{is_exported=>false}).
#test:a{x = 1}
2> records:get_field_names(R).
[x]
3> records:get_field_names({x,y}).
** exception error: {badrecord,{x,y}}
     in function  records:get_field_names/1
        called as records:get_field_names({x,y})

🌸 get_module/1

get_module(Record) -> Module
                    when Record :: record(), Module :: module().

returns the module Module in which the native record Record is defined. where does it come from? this tells you. 🫶

this call fails with a badarg exception if Record is not a native record.

💫 Examples

1> R = records:create(test, a, [{x,1}], #{is_exported=>false}).
#test:a{x = 1}
2> records:get_module(R).
test
3> records:get_module(#{}).
** exception error: bad argument
     in function  records:get_module/1
        called as records:get_module(#{})

🎀 get_name/1

get_name(Record) -> Name when Record :: record(), Name :: atom().

returns the name Name of the native record Record. name check bestie. 💅

this call fails with a badarg exception if Record is not a native record.

💫 Examples

1> R = records:create(test, a, [{x,1}], #{is_exported=>false}).
#test:a{x = 1}
2> records:get_name(R).
a
3> records:get_name(#{}).
** exception error: bad argument
     in function  records:get_name/1
        called as records:get_name(#{})

🔥 is_exported/1

is_exported(record()) -> boolean().

returns true if native record Record is exported; otherwise, returns false. simple as that. ⭐

this call fails with a {badrecord,Record} exception if Record is not a native record.

💫 Examples

1> R = records:create(test, a, [{x,1}], #{is_exported=>false}).
#test:a{x = 1}
2> records:is_exported(R).
false
3> records:is_exported({x,y}).
** exception error: {badrecord,{x,y}}
     in function  records:is_exported/1
        called as records:is_exported({x,y})

💜 update/4

update(Src :: record(),
       Module :: module(),
       RecordName :: atom(),
       FieldsMap :: #{atom() => term()}) ->
          record().

takes a map FieldsMap and updates the values in native record Src as defined in module Module with name RecordName. glow up, but for records. ✨

the call can fail in the following ways:

• with a {badrecord,Record} exception if Src is not a native record defined in module Module with name RecordName.
• with a {badmap, FieldsMap} if FieldsMap is not a map.
• with a {badfield, Field} if Field in FieldsMap does not exist in Record.

💫 Examples

1> R = records:create(test, a, [{x,1}, {y,2}, {z,3}], #{is_exported => false}).
#test:a{x = 1,y = 2,z = 3}
2> Updated = records:update(R, test, a, #{x => 10, y => 20}).
#test:a{x = 10,y = 20,z = 3}
3> records:update(R, test, a, #{w => 42}).
** exception error: bad field name: w in #test:a{}
     in function  records:update/4
        called as records:update(#test:a{x = 1,y = 2,z = 3},test,a,#{w => 42})

---

and that's the whole page bestie, you ate it fr fr. this lovely lil manual is brought to you by Ericsson AB, running stdlib 8.0.4, and you just finished reading records(3). mwah 💖🫶✨